Orchestrates CVE backporting with AI assistance. It runs cve-corrector as a
subprocess, and when the corrector exits with a recoverable code — conflict
(1), ptest failure (3), or build failure (4) — it starts a guarded AI session
to resolve the problem and retries.
Requires a sourced Yocto build environment (BBPATH must be set) and a working
AI backend.
cve-agent --cve-id CVE-2024-1234 --cve-info cve-metadata.json --trust
# Batch mode
cve-agent --cve-list cves.txt --cve-info cve-metadata.json --trustBackends are interchangeable and selected with --backend:
| Backend | --backend value |
Needs | Notes |
|---|---|---|---|
| Kiro CLI | kiro (default) |
kiro-cli installed | Default backend |
| Claude Code | claude |
Authenticated claude CLI on PATH (Anthropic API key, or Bedrock/Vertex) |
Pass --model sonnet|opus|haiku or a full model id |
| Native OpenAI-compatible | openai / openai-<profile> |
A tool-capable OpenAI-compatible endpoint, including local Ollama | Runs entirely in-process; no external agent CLI and no generic shell |
| Custom plugin | your own name | A file in extra/ implementing AIBackend |
See extra/README.md |
All backends run under the same file-scope guard, so the AI can only modify the files the upstream fix touches.
Before committing to a real backport run, confirm the selected backend is installed, authenticated, and actually responding:
cve-agent --backend claude --verify-backend--verify-backend runs a trivial, no-op round trip against the backend — no
file or git operations, no CVE workflow — and exits immediately: 0 if the
backend responded correctly, non-zero with a reason otherwise. It replaces
--cve-id/--cve-list for that invocation, so omit both.
The built-in openai backend calls a non-streaming /chat/completions endpoint
directly and runs the agent loop and closed typed tools inside this project —
no external agent CLI and no generic shell. It works against a local Ollama
instance as well as a remote provider, and openai-<profile> selects a named
profile holding a validated endpoint/model policy.
Everything about it lives in one place: the native OpenAI-compatible backend guide covers the Ollama quick start, the API contract, configuration and precedence, named profiles, capability probes and provider fallback, authentication and endpoint security, approvals and transcripts, and troubleshooting.
Committing a fix requires a Git author/committer identity, and this applies to
every backend. cve-agent seeds GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL,
GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL once at startup from your global
git config user.name / user.email — but only if none of the four are
already set. Explicit environment values always win and are never overwritten.
If you have no global Git identity either, the variables stay unset and the
commit fails with Git's own "identity unknown" error.
| Flag | Description |
|---|---|
--cve-id ID |
Single CVE identifier |
--cve-list PATH |
File with CVE IDs, one per line |
--verify-backend |
Check that --backend responds, then exit |
--cve-info PATH |
JSON metadata from cve-metadata-extractor |
--fix-url URL |
Fix commit or pull request URL, repeatable; forwarded unchanged to cve-corrector (see cve-corrector.md) |
--recipe NAME |
Recipe name; required with --fix-url when --cve-info is absent |
--skip-source SOURCE |
Ignore fix commits from this source (repeatable) |
--mainline-parent N |
Explicit 1-based direct parent for a selected merge fix commit |
--cve-id, --cve-list, and --verify-backend are mutually exclusive, and
exactly one is required.
| Flag | Default | Description |
|---|---|---|
--backend NAME |
kiro |
Backend to use, see above |
--model NAME |
backend-specific | Kiro and Claude default to claude-sonnet-5; plain openai requires this or CVE_AGENT_OPENAI_MODEL |
--max-retries N |
3 |
Maximum resolution attempts |
--session-timeout SECS |
600 |
Timeout per AI session |
--trust |
off | Skip human review (not recommended); cannot be combined with --sign-off |
--no-knowledge |
off | Disable the knowledge base for this run: no similar-pattern lookups, and no pattern saved on success |
--interactive, -i |
off | Human-in-the-loop; the native openai backend prompts before side effects |
--no-knowledge is useful for benchmarking a model's unaided performance.
| Flag | Default | Description |
|---|---|---|
--security-gate {verified,equivalent} |
equivalent |
Minimum trusted semantic status required for release success; equivalent also accepts verified |
--skip-ptest |
off | Skip ptest execution |
--skip-cve-applicability |
off | Skip the git-blame based applicability check |
--clean |
off | Clean the workspace before starting |
--meta-layer PATH |
— | Destination meta-layer for devtool finish |
--bbappend |
off | Create a bbappend instead of modifying the original recipe |
--mirror-dir PATH |
— | Directory with bare repository mirrors |
--sign-off |
off | Pass --sign-off through to cve-corrector |
cve-agent propagates the corrector's exit codes (see
cve-corrector.md) and adds three of its own:
| Code | Meaning |
|---|---|
| 13 | User declined trust mode |
| 14 | Internal agent error |
| 15 | AI session timed out |
Install patchutils to get
interdiff. When present, cve-agent enriches its review diff, console
output, and AI context with a concise upstream-vs-backport adaptation delta.
When absent, behavior is unchanged.
- Result schema — versioned workflow/build/security outcomes
- Agent artifacts — durable, redacted per-attempt directories
- Agent preflight — typed repository checks before a backend starts
- Semantic security validation — the gate a completed build must pass before release
- Agent progress and budgets — progress accounting and bounded terminal budgets for native model sessions
- Evaluation harness — reproducible backend/model benchmarking
Add a backend by dropping a .py file implementing AIBackend into extra/,
then select it by name with --backend. See
extra/README.md.
Run cve-agent --help for the complete flag list.