# CVE Differential (`cve-differential`)

A self-contained Gitea and GitHub Actions composite action that extracts multi-platform SBOM attestations from container images, runs vulnerability scans with [Trivy](https://github.com/aquasecurity/trivy), and produces a set-based CVE delta report between a head image and a target baseline image.

---

## ✨ Features

- **Multi-Platform Support**: Automatically detects and extracts SPDX SBOM attestations for multi arch images.
- **Fast Attestation Extraction**: Uses `docker buildx imagetools inspect` to extract SBOMs directly from registry manifest indices in seconds without downloading layer blobs.
- **Graceful Fallbacks**: If SBOM attestations or baseline images are missing, automatically falls back to generating SBOMs directly with Trivy. Using images that do contain an SBOM is highly recomended though!
- **Set-Based Differential Analysis**: Categorizes vulnerabilities into:
  - 🔴 **Introduced Vulnerabilities** (newly added in this branch / commit)
  - 🟢 **Fixed Vulnerabilities** (present in target baseline, resolved in this branch)
  - ⚪ **Unchanged Vulnerabilities** (pre-existing in target baseline)
- **Secure by Default**: Verified Trivy binary downloads against static SHA256 checksum lockfiles and single-step unified caching (binary + vulnerability database).

---

## 📥 Inputs

| Input | Description | Required | Default |
| :--- | :--- | :---: | :--- |
| `head-image` | Head container image reference to scan (e.g. `registry.example.com/repo:git-sha`) | **Yes** | — |
| `target-image` | Target baseline container image reference to compare against (e.g. `registry.example.com/repo:latest`) | **Yes** | — |
| `target-branch` | Target branch name for report headings | No | `main` |
| `trivy-version` | Trivy version to install and verify | No | `0.74.0` |
| `output-delta` | Output path for the CVE delta Markdown report | No | `cve-delta.md` |
| `output-summary` | Output path for the full vulnerability Markdown summary | No | `cve-summary.md` |
| `write-summary` | Whether to append the generated reports to the job summary (`$GITHUB_STEP_SUMMARY`) | No | `true` |

---

## 📤 Outputs

| Output | Description |
| :--- | :--- |
| `delta-report` | Path to the generated CVE delta Markdown report |
| `summary-report` | Path to the full vulnerability Markdown summary report |

---

## 🚀 Usage Example

```yaml
jobs:
  build-and-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build and Push Head Container Image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          sbom: true
          platforms: linux/amd64,linux/arm64
          tags: registry.example.com/my-app:git-${{ github.sha }}

      - name: Compare Vulnerabilities (Head vs Target)
        uses: https://git.horstenkamp.eu/Philipp/cve-differential@main
        with:
          head-image: registry.example.com/my-app:git-${{ github.sha }}
          target-image: registry.example.com/my-app:latest
          target-branch: ${{ github.base_ref || 'main' }}
```

---

## 📄 License

MIT