Draft VEX for scanner findings

# Decosa signed VEX triage: use the hosted API

You are wiring Decosa's VEX triage into this project (a CI pipeline, a release script or a security dashboard). It takes a
scanner report for one container image and returns draft VEX statements with their evidence, signed OpenVEX and CycloneDX
VEX documents, and a signed evidence record. Every model call has a signed receipt. Use only what is listed below; if you
need something else, stop and ask me.

Per finding the answer is one of:
- `not_affected`, with a CISA justification (`component_not_present`, `vulnerable_code_not_present`,
  `vulnerable_code_not_in_execute_path`; the other two are left to a person);
- `affected`, with an action;
- `fixed`;
- `under_investigation`.

`not_affected` is written only when a code check found positive evidence in the image or the advisory ranges. Everything
else stays under investigation.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- **The image never goes to the API.** You send the scanner report, optionally the SBOM, and the evidence bundle the
  collector writes on your machine (search hits, library loader chains, config excerpts with secret-looking lines
  redacted). Without the bundle nothing can be marked `not_affected`.
- This is a triage aid. Never publish the VEX without a security engineer's review, and never tell anyone an image is
  secure because of it.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in `DECOSA_API_KEY`, never in code.
   Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "vex-triage"}` returns `{"token", "expires_at", "budget"}`.
   The demo allows a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz) and a token allowance per session (the `budget` in the session response). Over a limit you get HTTP 429
   with `Retry-After`. A demo token runs one triage at a time (409 otherwise).
3. A run needs about 380 generated tokens per finding left in the budget before it starts (402 otherwise).

## 1. Scan and collect on your machine
```bash
grype <image> -o json > grype.json                      # or: trivy image --format json -o trivy.json <image>
syft <image> -o cyclonedx-json > sbom.cdx.json          # optional
pip install "decosa-api @ git+<decosa-api source: on request at https://decosa.ai/contact?topic=self-host>"   # publishing soon; the collector is stdlib + httpx
python -m decosa_api.verticals.vex.collect --image <image> --findings grype.json --out evidence.json
```
The collector unpacks the image with `crane export` or `docker export` into a temp directory, searches it, and deletes it.
It fetches advisory text from OSV.dev and NVD by vulnerability id (`--offline` to use only a local store).

## 2. Triage
- `POST /vex/triage` (token). Body: `{"findings": <Grype or Trivy JSON>, "sbom"?: <CycloneDX or SPDX JSON>, "evidence"?: <bundle>,
  "image"?: {"ref", "digest", "arch"}, "select"?: {"ids"?: [...], "packages"?: [...], "severity_min"?: "high", "limit"?: 1-60},
  "author"?: "Your PSIRT", "title"?, "stream"?}` or `{"sample_id": "nginx-1.20.0"}`.
  - The default selection is known-exploited findings first, then by severity and EPSS, 25 per run (at most 60). The rest
    come back in `not_triaged`; triage them in more runs with `select.ids`.
  - Limits: 16 MB of JSON per request.
  - The JSON response has `statements` (each with `status`, `justification`, `impact_statement`, `action_statement`,
    `status_notes`, `evidence`, `checks`, `advisories`, `model` and `gate_note`), `counts`, `openvex`, `cyclonedx`,
    `envelopes` (DSSE, Ed25519), `report_md`, `record`, `record_check`, `advisories` (every record used, with its sha256),
    `not_triaged`, `receipts` and `note`.
  - With `Accept: text/event-stream` (or `"stream": true`) the events are `ready`, `advisories`, a `receipt` per model call,
    a `finding` per statement, then `result`, `budget` and `done`.
- `POST /vex/verify` (no token) `{"envelope": {...}}` checks a DSSE envelope against this server's key.
- `POST /record/verify` (no token) `{"record": {...}}` re-checks the evidence record.
- `GET /vex/info`, `GET /vex/samples` and `GET /attest/signing-key` need no token.

## Example (Python, `pip install httpx`)
```python
import httpx, json, os
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
body = {"findings": json.load(open("grype.json")), "sbom": json.load(open("sbom.cdx.json")),
        "evidence": json.load(open("evidence.json")), "select": {"severity_min": "high", "limit": 40}, "author": "Example PSIRT"}
r = httpx.post(f"{API}/vex/triage", json=body, headers=H, timeout=900)
r.raise_for_status()
js = r.json()
for s in js["statements"]:
    print(f"{s['status']:>20}  {s['id']:<18} {s['package']['name']}  {s['justification'] or ''}")
json.dump(js["openvex"], open("draft.openvex.json", "w"), indent=2)      # a draft: review before publishing
json.dump(js["envelopes"], open("draft.vex.dsse.json", "w"))
json.dump(js["record"], open("vex-evidence-record.json", "w"))           # keep with the release
```
After review, `grype <image> --vex draft.openvex.json` hides the findings a not_affected or fixed statement covers
(tested with Grype 0.119; Trivy's `--vex` also reads OpenVEX but was not tested).

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa signed VEX triage: run it yourself (containers)

You are setting up Decosa's VEX triage on this machine, so images, SBOMs and scanner reports never leave it. For each
finding in a Grype or Trivy report it writes a draft VEX status with its evidence: checks run on the image (package,
version against the fix and the advisory ranges, the distro changelog, what loads the library, the advisory's programs
and settings, the platform) and one open-model judgment that code gates. `not_affected` needs positive evidence. The
output is signed OpenVEX and CycloneDX VEX drafts and a signed evidence record. Nothing is sent to Decosa's hosted API;
only vulnerability ids go to OSV.dev and NVD, and that can be switched off.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/vex-triage.zip (65 KB, 10 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py vex-triage` (the api image carries the same bundle under /app/rehearsal/vex-triage/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py vex-triage --bundle vex-triage.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "libwebp's known-exploited CVE-2023-4863 is not in the execute path (only an unloaded module loads it)", "and its status is not_affected", "OpenSSL's CVE-2022-0778 stays affected for both packages"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
   instructions for this distribution (docs.docker.com/engine/install). Install the NVIDIA container toolkit, then check
   `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. Keep the `llm` service (Qwen3.8-27B on vLLM) and the `api` service. On the `api` service:
   - set `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1` and `DECOSA_LLM_MODEL=qwen3.8-27b`;
   - set `DECOSA_VEX_OFFLINE=1` if this box must not reach the internet (then import OSV.dev's bulk export into the
     advisory store with `python -m decosa_api.verticals.vex.advisories import <zip>`);
   - keep its data on a named volume (the advisory store lives there);
   - bind every port to 127.0.0.1.
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check. The first start
   downloads about 20 GB of weights.
4. On the host, install Grype and Syft (Apache-2.0) and `crane` (or use Docker), and get the collector: it is
   `decosa_api/verticals/vex/collect.py` in the decosa-api source and needs Python 3.11+ and `httpx`.
5. Check: `curl -fsS http://127.0.0.1:<PORT>/vex/info` lists the statuses, the justifications, the checks and the limits.
   `GET /attest/signing-key` shows this box's public key: it is what others pin to verify my VEX documents.
6. Smoke test on the bundled public sample:
   - Get a token with `POST /demo/session {"vertical":"vex-triage"}`, then send
     `POST /vex/triage {"sample_id":"nginx-1.20.0","select":{"ids":["CVE-2023-4863","CVE-2021-37600","CVE-2022-0778"]}}`.
     Expect libwebp's CVE-2023-4863 `not_affected` / `vulnerable_code_not_in_execute_path`, CVE-2021-37600 `fixed`,
     CVE-2022-0778 `affected`, and every receipt `attested`.
   - `POST /vex/verify {"envelope": <envelopes.openvex>}` should give `valid_signature: true`;
     `POST /record/verify {"record": <record>}` should give `ok: true`.
7. Then one of my own images: `grype <image> -o json > grype.json`, `syft <image> -o cyclonedx-json > sbom.json`,
   `python -m decosa_api.verticals.vex.collect --image <image> --findings grype.json --out evidence.json`, and send the
   three files to `POST /vex/triage`. Save `openvex`, `envelopes` and `record` from the answer.
8. Report back: the public key and key id, the smoke-test results, and how long the triage took.

This is a triage aid: every statement is a draft that a security engineer reviews and signs off, and it never says an
image is secure. It sees the image as shipped, not configs mounted at run time.

Off by default. Joining as a provider serves other people's requests on this GPU. Don't do it on a box that holds
internal images or SBOMs. If I ask for it later, follow the Provide page instead of improvising.