# Supply Chain Vulnerability Report - User Guide ## Quick Start When you create a pull request, the supply chain security workflow automatically scans your Docker image for vulnerabilities and posts a comment with detailed findings. ## Reading the Report ### Summary Section At the top of the comment, you'll see a summary table: ``` | Severity | Count | |----------|-------| | 🔴 Critical | 2 | | 🟠 High | 5 | | 🟡 Medium | 12 | | 🔵 Low | 8 | ``` **Priority:** - 🔴 **Critical**: Fix immediately before merging - 🟠 **High**: Fix before next release - 🟡 **Medium**: Schedule for upcoming sprint - 🔵 **Low**: Address during regular maintenance ### Detailed Findings Expand the collapsible sections to see specific vulnerabilities: #### What Each Column Means | Column | Description | Example | |--------|-------------|---------| | **CVE** | Common Vulnerabilities and Exposures ID | CVE-2025-12345 | | **Package** | Affected software package | golang.org/x/net | | **Current Version** | Version in your image | 1.22.0 | | **Fixed Version** | Version that fixes the issue | 1.25.5 | | **Description** | Brief explanation of the vulnerability | Buffer overflow in HTTP/2 | #### Reading "No fix available" This means: - The vulnerability is acknowledged but unpatched - Consider: - Using an alternative package - Implementing workarounds - Accepting the risk (with documentation) - Waiting for upstream fix ## Taking Action ### For Critical/High Vulnerabilities 1. **Identify the fix:** - Check the "Fixed Version" column - Note if it says "No fix available" 2. **Update dependencies:** ```bash # For Go modules go get package-name@v1.25.5 go mod tidy # For npm packages npm install package-name@1.25.5 # For Debian packages (in Dockerfile) RUN apt-get update && apt-get upgrade -y package-name && rm -rf /var/lib/apt/lists/* ``` 3. **Test locally:** ```bash make test-all docker build -t charon:local . ``` 4. **Push updates:** ```bash git add go.mod go.sum # or package.json, Dockerfile, etc. git commit -m "fix: update package-name to v1.25.5 (CVE-2025-12345)" git push ``` 5. **Verify:** - Workflow will re-run automatically - Check that the vulnerability is no longer listed - Confirm counts decreased in summary table ### For Medium/Low Vulnerabilities - **Not blocking**: You can merge if critical/high are resolved - **Track separately**: Create follow-up issues - **Batch fixes**: Address multiple in one PR during maintenance windows ## Common Scenarios ### ✅ Scenario: No Vulnerabilities ``` ### ✅ Status: No Vulnerabilities Detected 🎉 Great news! No security vulnerabilities were found in this image. ``` **Action:** None needed. Safe to merge! --- ### ⚠️ Scenario: Critical Vulnerabilities ``` ### 🚨 Status: Critical Vulnerabilities Detected ⚠️ Action Required: 2 critical vulnerabilities require immediate attention! ``` **Action:** Must fix before merging. See [detailed findings](#detailed-findings). --- ### ⏳ Scenario: Waiting for Image ``` ### ⏳ Status: Waiting for Image The Docker image has not been built yet. This scan will run automatically once the docker-build workflow completes. ``` **Action:** Wait a few minutes. Comment will auto-update when scan completes. --- ### 🔧 Scenario: Scan Failed ``` ### ⚠️ Status: SBOM Validation Failed The Software Bill of Materials (SBOM) could not be validated. ``` **Action:** 1. Click the workflow run link 2. Check logs for error details 3. Fix the underlying issue (usually build-related) 4. Re-trigger the workflow ## Advanced Usage ### Downloading Full Reports For detailed analysis: 1. Navigate to Actions → Supply Chain Verification 2. Find your workflow run 3. Scroll to "Artifacts" section 4. Download `vulnerability-scan-{tag}.zip` 5. Extract and open `vuln-scan.json` **Use cases:** - Import to security dashboards - Generate compliance reports - Track trends over time - Deep dive analysis ### Understanding JSON Format The `vuln-scan.json` follows Grype's schema: ```json { "matches": [ { "vulnerability": { "id": "CVE-2025-12345", "severity": "Critical", "description": "Full vulnerability description...", "fix": { "versions": ["1.25.5"] } }, "artifact": { "name": "golang.org/x/net", "version": "1.22.0", "type": "go-module" } } ] } ``` ### Analyzing with jq Extract specific information: ```bash # List all Critical CVEs jq '.matches[] | select(.vulnerability.severity == "Critical") | .vulnerability.id' vuln-scan.json # Count by package jq '.matches | group_by(.artifact.name) | map({package: .[0].artifact.name, count: length})' vuln-scan.json # Find unfixed vulnerabilities jq '.matches[] | select(.vulnerability.fix.versions | length == 0)' vuln-scan.json # Export to CSV jq -r '.matches[] | [.vulnerability.id, .artifact.name, .artifact.version, .vulnerability.severity] | @csv' vuln-scan.json > vulns.csv ``` ## Best Practices ### ✅ Do's - ✅ Fix Critical/High before merging - ✅ Create issues for Medium/Low to track - ✅ Document decisions to accept risks - ✅ Test fixes thoroughly before pushing - ✅ Review Fixed Version availability - ✅ Keep dependencies up to date - ✅ Use dependabot for automation ### ❌ Don'ts - ❌ Don't ignore Critical/High vulnerabilities - ❌ Don't merge without scanning - ❌ Don't disable security checks - ❌ Don't use outdated base images - ❌ Don't skip testing after updates - ❌ Don't dismiss "No fix available" lightly ## Troubleshooting ### Comment Not Appearing **Possible causes:** - Docker build workflow hasn't completed - PR is from a fork (security restriction) - Workflow permissions issue **Solution:** ```bash # Manually trigger workflow gh workflow run supply-chain-verify.yml ``` ### Outdated Vulnerability Data **Symptom:** Known-fixed vulnerability still shown **Solution:** ```bash # Clear Grype cache grype db delete grype db update # Or wait for next workflow run (auto-updates) ``` ### False Positives **If you believe a vulnerability is incorrectly reported:** 1. Verify package version: `go list -m all | grep package-name` 2. Check Grype database: 3. Report issue: 4. Document in PR why accepted (with evidence) ### Too Many Vulnerabilities **If list is overwhelming (>100):** 1. Start with Critical only 2. Update base images first (biggest impact): ```dockerfile FROM debian:bookworm-slim # Debian slim for security and glibc compatibility ``` 3. Batch dependency updates: ```bash go get -u ./... # Update all Go dependencies ``` 4. Consider using a vulnerability triage tool ## Integration with Other Tools ### GitHub Security Tab Vulnerabilities also appear in: - **Security** → **Dependabot alerts** - **Security** → **Code scanning** Cross-reference between tools for complete picture. ### Dependabot Configure `.github/dependabot.yml` for automatic updates: ```yaml version: 2 updates: - package-ecosystem: "gomod" directory: "/backend" schedule: interval: "weekly" open-pull-requests-limit: 10 ``` ### Pre-commit Hooks Add to `.pre-commit-config.yaml`: ```yaml - repo: local hooks: - id: grype-scan name: Vulnerability scan entry: grype language: system args: [dir:., --fail-on=critical] pass_filenames: false ``` ## Getting Help ### Resources - **Grype Documentation**: - **CVE Database**: - **NVD**: - **Go Security**: - **Debian Security**: ### Support Channels - **Project Issues**: Create issue on this repository - **Security Team**: - **Grype Support**: ### Escalation For urgent security issues: 1. Do not merge PR 2. Contact security team immediately 3. Create private security advisory 4. Follow incident response procedures --- **Last Updated**: 2026-01-11 **Maintained By**: Security & DevOps Teams **Questions?** Create an issue or contact #security-alerts