Component: vulnhunter-agent/ — headless runtime

Clone → scan → publish → file issues, unattended, with a single auth chokepoint.

Component: vulnhunter-agent/ — the headless runtime

Role. The automation layer. Runs /vulnhunt unattended (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 vulnhunter package is the thin CLI entry point around the agent package.


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.py is a placeholder stub (print("Hello, Python Project!")); the real entry point is python -m agent (agent/__main__.py). The README describes vulnhunter as the thin CLI wrapper around agent.

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).


See also: Scanner · Verifier · Harness · LLD §6.