Component: vulnhunter-agent/ — the headless runtime
Role. The automation layer. Runs
/vulnhuntunattended (CI, a scheduled job, a fleet worker, a container), then wires results into GitHub. Also drives the verifier.Kind. Config-driven Python runtime (~35 production modules, ~13.2k LOC + 48 test files). The
vulnhunterpackage is the thin CLI entry point around theagentpackage.
Part 1
The three skills describe how to hunt, fix, and verify. This runtime makes a scan happen without anyone sitting at a keyboard. Point it at a repository URL and it clones the code, runs the hunter, writes a machine-readable record of what happened, optionally copies the report to a separate place, and files one tidy GitHub issue per real finding (or a "clean scan" receipt if there are none). Everything specific to your environment — which model endpoint, which credentials, which GitHub host — comes from a config file and environment variables, so the same container image runs anywhere.
Explain-it-simply. A robot operator that boots the scanner on a schedule, does the paperwork, and files the tickets — configured entirely from the outside so you never rebuild it to move environments.
Data-flow (this component)
flowchart LR URL[(repo URL)] --> CFG[load_config] CFG --> TOK[make_token_manager] TOK --> CLONE[clone] --> RUN[run_vulnhunt<br/>Agent SDK] RUN --> MAN[(scan_manifest.json)] MAN --> PUB[publish?] --> ISS[issues?]
Part 2 — Technical detail
Auth is a single chokepoint
build_settings.py is the only place that renders the Claude Code settings JSON (environment +
sandbox) and knows how to authenticate. Three token managers share one get_valid_token():
auth_mode |
Transport | Set |
|---|---|---|
api_key (default) |
Direct Anthropic API | ANTHROPIC_API_KEY |
bedrock_oauth |
Bedrock proxy fronted by an OAuth2 client-credentials endpoint | [anthropic].bedrock_base_url + [oauth] block |
bedrock_sigv4 |
Amazon Bedrock directly via SigV4 (AWS credential chain) | [anthropic].aws_region (+ optional profile/endpoint) |
make_token_manager(config) returns the right one, so everything downstream is auth-mode
agnostic. Both the scan loop and the issues-LLM calls go through this chokepoint.
File map (selected)
| File | Purpose |
|---|---|
agent/__main__.py |
CLI entry (python -m agent <repo-url> [--no-publish] [--no-issues] [--mode=verify] …). |
agent/config.py |
Load TOML + overlay VULNHUNT_* env → AgentConfig (env wins). |
agent/auth.py, token_client.py, build_settings.py |
The auth chokepoint + token managers + settings/sandbox JSON. |
agent/clone.py |
Clone the target (token injected only when the host matches). |
agent/runner.py |
Drive the Claude Agent SDK: run /vulnhunt, stream events, retry on 429, autocompact/stall handling. |
agent/_stream_events.py, _transient.py |
Event streaming + transient-error classification. |
agent/manifest.py |
Write scan_manifest.json, validated against scan_manifest.schema.json. |
agent/publish.py |
Optionally push the results dir to a separate reports repo. |
agent/issues*.py |
issues_fetch/extract/dedup/render/remote_report — one deduplicated issue per finding; clean-scan receipt. |
agent/verify*.py |
--mode=verify: orchestrate /vulnhunt-fix-verify, extract/resolve refs, post verdicts. |
agent/audit.py, audit_extract.py |
Optional JSONL lifecycle + finding events. |
agent/repo_properties.py, _url.py, _github*.py |
Repo metadata, URL redaction, GitHub helpers. |
scan_manifest.schema.json, verify_disposition.schema.json |
The two validated contracts. |
agent/templates/ |
issue_body.md, clean_scan_body.md, clean_scan_comment.md. |
vulnhunter/app.pyis a placeholder stub (print("Hello, Python Project!")); the real entry point ispython -m agent(agent/__main__.py). The README describesvulnhunteras the thin CLI wrapper aroundagent.
Config sections (abridged)
[anthropic]/[oauth] (auth), [github] (scan_token, reports_token, or a
broker_token_dir), [publish] (destination repo/branch), [issues] (labels, dedup,
clean-scan, extraction/dedup models), [sandbox] (OS-level fs/net sandbox), [telemetry]
(optional OTLP), [scan] (clone dir, allowed tools — Bash stripped unless --enable-bash,
autocompact, stall timeout), [verify] (scratch dir, repo_aliases).
Deployment pattern
Use it as a base image you extend (FROM) with your own config/credentials/telemetry —
wrap, don't fork. Put org-specific orchestration in a thin parent process that shells out to
python -m agent … and reads the exit code + scan_manifest.json; the manifest is the stable
integration contract.
Part 3 — Inputs, outputs, model selection & deterministic calls
What happens here. The runtime is the deterministic shell around the LLM work: it clones, launches the scanner (an LLM process it does not itself reason inside), then does classic software-engineering plumbing — schema-validate, push, call GitHub APIs. The only LLM calls it makes directly are small ones in the issues stage.
Inputs. A repo URL (CLI arg); a TOML config (--config → $VULNHUNT_AGENT_CONFIG →
agent/config.toml) overlaid by VULNHUNT_* env vars (env wins); credentials for the chosen
auth mode; optional GitHub tokens (or a broker_token_dir).
Outputs. The scanner's *_VULNHUNT_RESULTS_* dir; a schema-validated scan_manifest.json
(the stable integration contract); optionally a published copy of the results in a separate repo;
and one deduplicated GitHub issue per finding (or a clean-scan receipt). In --mode=verify, a
posted per-finding verdict.
How the model version is chosen. Two separate decisions. (1) The scan model is a config
value: [anthropic].model (default claude-opus-4-8), overridable per run with --model or
VULNHUNT_ANTHROPIC_MODEL. (2) The issues stage uses its own small-model tiering — it tries
haiku_model (claude-haiku-4-5) first and falls back to sonnet_model (claude-sonnet-5) for
findings extraction and semantic dedup, with deterministic chunking math against
model_context_tokens (200 K) to size batches. Which token manager is used is also config-chosen:
auth_mode = api_key / bedrock_oauth / bedrock_sigv4.
Deterministic (non-LLM) calls. (1) Config load — TOML parse + env overlay → AgentConfig.
(2) Auth — token managers: OAuth2 client-credentials token fetch (HTTP), or SigV4 request
signing via the AWS credential chain (no LLM). (3) git clone of the target; token injected
only when the host matches. (4) GitHub API / gh — publish push, issue create/list, dedup pool
paging. (5) Schema validation (jsonschema) of scan_manifest.json and
verify_disposition.json before write. (6) 429 retry/backoff, autocompact at a % of the
context window, stall-timeout watchdog, and an optional OS sandbox for the CLI's tools.
(7) Optional JSONL audit append. The Agent SDK event stream is parsed deterministically
(_stream_events.py, _transient.py).