Charon/docs/SUPPLY_CHAIN_VULNERABILITY_GUIDE.md

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:

   # For Go modules
   go get package-name@v1.25.5
   go mod tidy
   
   # For npm packages
   npm install package-name@1.25.5
   
   # For Alpine packages (in Dockerfile)
   RUN apk upgrade package-name
   

3. Test locally:

   make test-all
   docker build -t charon:local .
   

4. Push updates:

   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.

---

⏳ 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:

{
  "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:

# 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:

# Manually trigger workflow
gh workflow run supply-chain-verify.yml

Outdated Vulnerability Data

Symptom: Known-fixed vulnerability still shown

Solution:

# 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: https://github.com/anchore/grype-db
3. Report issue: https://github.com/anchore/grype/issues
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):

   FROM alpine:3.19  # Update to latest patch version
   

3. Batch dependency updates:

   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:

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:

- 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: https://github.com/anchore/grype
• CVE Database: https://cve.mitre.org/
• NVD: https://nvd.nist.gov/
• Go Security: https://go.dev/security/
• Alpine Security: https://alpinelinux.org/security/

Support Channels

• Project Issues: Create issue on this repository
• Security Team: security@yourcompany.com
• Grype Support: https://github.com/anchore/grype/discussions

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