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

   ```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: <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):

   ```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**: <https://github.com/anchore/grype>
- **CVE Database**: <https://cve.mitre.org/>
- **NVD**: <https://nvd.nist.gov/>
- **Go Security**: <https://go.dev/security/>
- **Debian Security**: <https://www.debian.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