Security Scanning Guide¶
This document provides comprehensive guidance on the security scanning tools and processes implemented in the Open Resource Broker project.
Overview¶
The project implements a multi-layered security scanning approach that includes:
- Static Application Security Testing (SAST)
- Dependency Vulnerability Scanning
- Container Security Scanning
- Infrastructure as Code Security
- Software Bill of Materials (SBOM) Generation
- Secret Detection
Security Tools¶
1. Ruff (flake8-bandit rules) - Python Security Linter¶
Purpose: Static analysis of Python code for common security issues (hardcoded credentials, unsafe subprocess calls, SQL string construction, and similar patterns).
Usage:
# Run via Makefile (part of the Ruff quality gate)
make ci-quality-ruff
# Run directly
ruff check --select S --ignore S311 src/
Configuration: pyproject.toml ([tool.ruff.lint]). Findings are either
fixed or suppressed with a per-line # noqa: Sxxx comment carrying the
justification; tests/** carries a blanket suppression since assert and
dummy-credential patterns are normal test code.
Output Formats: - Text (CI job log and local terminal)
2. Safety - Dependency Vulnerability Scanner¶
Purpose: Check Python dependencies for known security vulnerabilities.
Usage:
# Check current environment
python -m safety check
# Generate JSON report
python -m safety check --json --output safety-report.json
Features: - CVE database integration - Severity scoring - Remediation suggestions
3. Trivy - Container Vulnerability Scanner¶
Purpose: Comprehensive container image security scanning.
Usage:
# Scan container image
make security-container
# Direct usage
trivy image --format sarif --output trivy-results.sarif myimage:latest
Scan Types: - OS package vulnerabilities - Language-specific vulnerabilities - Configuration issues - Secret detection
4. Hadolint - Dockerfile Security Linter¶
Purpose: Best practices and security analysis for Dockerfiles.
Usage:
Checks: - Security best practices - Performance optimizations - Maintainability issues
5. CodeQL - Semantic Code Analysis¶
Purpose: Deep semantic analysis of code for security vulnerabilities.
Configuration: .github/codeql/codeql-config.yml
Features: - Advanced dataflow analysis - Custom security queries - Integration with GitHub Security tab
6. Semgrep - Static Analysis¶
Purpose: Fast, customizable static analysis for security patterns.
Usage: Automated in CI/CD pipeline
Rule Sets: - Security audit rules - Secret detection - Python-specific security patterns
SARIF Integration¶
All security tools generate SARIF (Static Analysis Results Interchange Format) files for standardized reporting.
SARIF Files Generated¶
trivy-results.sarif- Container vulnerabilitieshadolint-results.sarif- Dockerfile issuessemgrep.sarif- Static analysis resultscodeql-results.sarif- CodeQL analysis
GitHub Security Tab¶
SARIF files are automatically uploaded to GitHub's Security tab, providing:
- Centralized vulnerability dashboard
- Issue tracking and management
- Integration with pull requests
- Historical trend analysis
Software Bill of Materials (SBOM)¶
SBOM Generation¶
The project generates comprehensive SBOMs in multiple formats:
SBOM Formats¶
SPDX (Software Package Data Exchange):
- python-sbom-spdx.json - Python dependencies
- project-sbom-spdx.json - Full project
- container-sbom-spdx.json - Container image
CycloneDX:
- python-sbom-cyclonedx.json - Python dependencies
- project-sbom-cyclonedx.json - Full project
- container-sbom-cyclonedx.json - Container image
SBOM Tools¶
- pip-audit: Python package SBOM generation
- Syft: Universal SBOM generator
- Docker Scout: Container SBOM analysis
CI/CD Integration¶
GitHub Actions Workflows¶
Security Workflow (.github/workflows/security.yml):
- Runs on push, PR, and weekly schedule
- Generates SARIF files
- Uploads to GitHub Security tab
CodeQL Workflow (.github/workflows/codeql.yml):
- Deep semantic analysis
- Weekly scheduled scans
- Custom query configuration
Container Security (.github/workflows/container-security.yml):
- Multi-tool container scanning
- Dockerfile security analysis
- SARIF integration
SBOM Generation (.github/workflows/sbom.yml):
- Automated SBOM creation
- Multiple format support
- Release artifact attachment
Pre-commit Hooks¶
Security checks integrated into pre-commit workflow:
# Security checks in .pre-commit-config.yaml
- id: ruff-check
- id: pip-audit
- id: secrets-detection
- id: dockerfile-security
Dependency Pinning¶
Tooling installed by CI workflows, container images and packaging scripts comes from
hash-locked requirements in .github/requirements/ (installed with
--require-hashes --no-deps) or from exact versions. Regenerate the locks with
dev-tools/ci/update_tool_locks.sh; Dependabot tracks the directory. The Java and Kotlin
SDKs use strict Gradle dependency locking and the C# SDK package uses a NuGet lock file
that CI restores in locked mode.
Trusted-context exceptions¶
These installs are intentionally not hash-pinned. Each runs the code under test, a reviewed repository file, or a tool on a developer machine that is already trusted:
- Wheel under test (
package-testing.yml,sdk.yml,sdk/java/Dockerfile.build,dev-tools/package/test_install.sh): the wheel built in the same workflow run is installed together with its dependency ranges. Pinning them would stop the job from testing what users get frompip install. - Project installs (
dev-tools/package/install_dev.sheditable install,dev-tools/ci/run_ui_smoke.shanddev-tools/package/build_ui.shinstalling.[ui]): these install the checked-out project, whose dependencies are locked inuv.lock. - Developer-machine installers (
dev-tools/setup/install_dev_tools.py): the Windows bun installer and the syft, actionlint and uvcurlinstallers download from the vendors' official endpoints, which publish no checksum for those scripts. They are not used by CI workflows. CI uses version-pinned actions and the hash-locked requirements above, and the UI package build verifies the SHA-256 of the pinned bun release archive. - Base image tags selected by build argument (
Dockerfile,Dockerfile.dev-tools): the Python version is a build argument, so one digest cannot be pinned.
Local Development¶
Running Security Scans¶
Quick Security Check:
Full Security Suite:
Comprehensive Report:
SARIF Validation¶
Validate SARIF files before upload:
Security Policies¶
Vulnerability Response¶
- Critical/High Severity: Address within 24-48 hours
- Medium Severity: Address within 1 week
- Low Severity: Address in next release cycle
Dependency Management¶
- Weekly automated dependency updates via Dependabot
- Security-focused dependency scanning
- Automated vulnerability alerts
Container Security¶
- Regular base image updates
- Multi-stage builds for minimal attack surface
- Non-root user execution
- Security scanning in CI/CD
Reporting and Monitoring¶
Security Dashboard¶
Access security information through:
- GitHub Security Tab: Centralized vulnerability view
- CI/CD Artifacts: Detailed scan reports
- Local Reports: Generated security summaries
Metrics and KPIs¶
- Vulnerability detection rate
- Mean time to remediation
- Security scan coverage
- False positive rate
Best Practices¶
Development¶
- Secure Coding: Follow OWASP guidelines
- Dependency Management: Regular updates and vulnerability monitoring
- Secret Management: No hardcoded secrets, use environment variables
- Input Validation: Sanitize all external inputs
- Error Handling: Avoid information disclosure
Infrastructure¶
- Container Security: Minimal base images, regular updates
- Network Security: Principle of least privilege
- Access Control: Role-based permissions
- Monitoring: Comprehensive logging and alerting
CI/CD¶
- Automated Scanning: Every commit and PR
- Quality Gates: Block deployments on critical issues
- SARIF Integration: Standardized reporting
- Artifact Security: Signed releases and SBOMs
Troubleshooting¶
Common Issues¶
Ruff Security Rule False Positives:
# Use a per-line # noqa comment with the rule code and a reason
password = get_password_from_env() # noqa: S105 # env lookup, not a literal credential
Safety Dependency Conflicts:
Container Scan Failures:
Getting Help¶
- Review security scan reports in CI/CD artifacts
- Check GitHub Security tab for detailed findings
- Consult tool-specific documentation
- Contact security team for critical issues