euvd-watch

EUVD-native software supply-chain vulnerability watch + EU Cyber Resilience Act (CRA) reporting toolkit.

⚠️ Status: work in progress. APIs and structure may change until 1.0.0. The Commands table below marks what is ✅ available today versus 🧪 beta versus 🚧 planned — milestones M0–M5 (scan, match, VEX, the CRA workflow, watch mode, Docker image, GitHub Action, GitLab template, PyPI releases) are implemented and tested. The dashboard (M6) is fully implemented — app, accessibility gate, and a tested deployment guide (docs/deploy.md) — and marked beta only because its surface may still change before the 1.1 GA.

euvd-watch connects software supply-chain transparency to Europe's own vulnerability infrastructure and to the concrete reporting duties of the EU Cyber Resilience Act.

It ingests your SBOM, continuously matches every component against the European Union Vulnerability Database (EUVD) operated by ENISA — including its actively exploited flag and EPSS scores — automatically drafts machine-readable VEX statements to cut false-positive noise, and, when a component is hit by an actively exploited vulnerability, drafts the CRA Article 14 notification and starts the 24-hour clock with a tamper-evident audit trail.

Why this exists

SBOM generation (Syft, cdxgen) and scanning against US sources (NVD, OSV) are mature. But:

• Nothing open is built around the EUVD — Europe's own vulnerability database, operated by ENISA.
• Nothing connects "exploited" status to the CRA's actual reporting workflow (the 24-hour early warning to ENISA/CSIRTs).
• VEX generation is still mostly manual, so teams drown in non-applicable findings.

euvd-watch fills that gap as a self-hostable building block that runs in CI/CD and on a schedule. It does not reinvent SBOM generators or scanners — it reuses them.

Pipeline

flowchart LR
    A[SBOM<br/>CycloneDX / SPDX] -->|ingest| B[Normalized<br/>components]
    B -->|match| C[EUVD<br/>exploited + EPSS + KEV]
    C --> D[OpenVEX<br/>statements]
    C -->|trigger| E[CRA Article 14<br/>draft + 24h clock + audit log]
    B -.->|CI/CD · CLI · watch| F[Dashboard]

Quickstart (everything below works today)

pip install euvd-watch
euvd-watch version

# 1. Generate an SBOM for your project (using Syft, or bring your own)
syft dir:. -o cyclonedx-json > sbom.cdx.json

# 2. See what's inside it
euvd-watch scan sbom.cdx.json

# 3. Match it against the EUVD — show only actively exploited vulnerabilities
euvd-watch match sbom.cdx.json --exploited-only

# 4. Generate OpenVEX statements (conservative by design)
euvd-watch vex generate sbom.cdx.json -o openvex.json

# 5. Check whether anything crossed your CRA reporting threshold
euvd-watch cra check sbom.cdx.json
euvd-watch cra status

# 6. Watch it on a schedule - notify only new/resolved/changed findings
euvd-watch watch sbom.cdx.json --interval 6h

Commands

All implemented commands support --output json|table and CI-friendly exit codes (0 clean, 1 findings, 2 error; cra check adds 3 indeterminate). Unimplemented commands exit 2 with a clear message.

--output is a global option, so it goes before the command, not after it:

euvd-watch --output json match sbom.cdx.json --exploited-only   # correct
euvd-watch match sbom.cdx.json --exploited-only --output json   # exits 2: "No such option"

In JSON mode stdout carries only the JSON document — summaries and warnings go to stderr — so euvd-watch --output json match sbom.cdx.json > findings.json is safe to pipe straight into jq.

Using it in CI

The GitHub Action (action.yml at the repo root), the GitLab include-template (templates/euvd-watch.gitlab-ci.yml) and the Docker image (docker/Dockerfile) are implemented, schema-linted, and dogfooded by this repository's own CI — see docs/integrations.md for the full reference.

GitHub Actions:

- uses: anchore/sbom-action@v0          # generate SBOM with Syft
  with: { format: cyclonedx-json, output-file: sbom.cdx.json }
- uses: caisarus/euvd@v0.4.1
  with:
    sbom-path: sbom.cdx.json
    fail-on: exploited

GitLab CI:

include:
  - remote: 'https://raw.githubusercontent.com/caisarus/euvd/main/templates/euvd-watch.gitlab-ci.yml'

euvd-watch:
  variables: { EUVDWATCH_SBOM: "sbom.cdx.json", EUVDWATCH_FAIL_ON: "exploited" }

Docker (ghcr.io/caisarus/euvd-watch, or build locally):

docker run --rm -v "$PWD:/work:ro" ghcr.io/caisarus/euvd-watch:latest match /work/sbom.cdx.json
# or build from a clone:
docker build -f docker/Dockerfile -t euvd-watch .

Configuration

euvd-watch.yaml (or --config, or EUVD_WATCH_* env vars):

cache_dir: ~/.cache/euvd-watch
epss_threshold: 0.5
min_confidence: medium
organization:
  name: "Example S.R.L."
  contact_email: security@example.com
  product_name: "Example Product"
cra_trigger:
  euvd_exploited: true
  cisa_kev: true
  epss_over_threshold: true

Design principles

• Reuse, don't reinvent — wrap Syft/cdxgen output, OpenVEX, EPSS, KEV; build only the missing glue.
• EUVD-first, with OSV/KEV/EPSS as supplements.
• Conservative VEX — never auto-suppress something that might be real risk.
• Human-in-the-loop reporting — euvd-watch drafts; a human confirms before anything is filed. The tool never submits anything automatically.
• Auditable — every decision carries a human-readable explanation and lands in a hash-chained audit log.
• Deterministic — same inputs produce byte-identical outputs.

What euvd-watch is NOT

• Not an SBOM generator (use Syft/cdxgen).
• Not a general-purpose scanner replacement (Grype/Trivy remain great for NVD/OSV coverage).
• Not legal advice, and not an automatic filing tool — CRA notifications are always reviewed and submitted by a human through official channels.

Architecture & docs

Start here

• ARCHITECTURE.md — how the pieces fit together, module by module
• README.simple.md — the same story, explained so a child can follow it
• GLOSSARY.md — every technical term (SBOM, VEX, CRA, EPSS…) in plain language

How each part behaves

• docs/matching.md — matching strategies & confidence scoring
• docs/cra.md — the CRA Article 14 workflow, deadline stages, and the audit log's honest threat model
• docs/euvd-api.md — the verified EUVD API surface this tool uses
• docs/watch.md — scheduled re-matching, diffing, and webhook delivery
• docs/web.md — the dashboard, its auth model, and its documented limits
• docs/storage.md — the state database, migrations, and backups

Running it somewhere

• docs/integrations.md — GitHub Action, GitLab template, Docker
• docs/deploy.md — self-hosting with Docker Compose and Caddy
• docs/accessibility.md — the WCAG 2.1 AA gate and how it is run
• docs/release.md — versioning policy and the release process

Contributing

Early contributors are very welcome — see CONTRIBUTING.md for the dev setup, how to run the tests, and the two governance rules that keep this tool honest: every wild bug becomes a truth-table row before its fix merges, and every alias-table entry cites a real EUVD record.

Reporting a vulnerability in euvd-watch itself: SECURITY.md.

License

EUPL-1.2. Documentation provided in English and Romanian — see README.ro.md and GLOSSARY.ro.md / vezi README.ro.md și GLOSSARY.ro.md.