vulkro hunt

An optional local model DRIVES a hunt for vulnerabilities the deterministic scan may have missed, calling Vulkro's own deterministic checks (find sinks, read slices, taint, prove) as tools. A finding is CONFIRMED only when a deterministic oracle grounds it. Everything else is a labelled advisory lead.

Advisory only, opt-in, local by default

vulkro hunt is Free (capability ai-assist). It is advisory: enabling it changes NO deterministic result. Not a finding, a severity, the published benchmark, or the exit code. The exit code follows the deterministic scan only. A loopback model (http://127.0.0.1, http://localhost) is allowed under VULKRO_OFFLINE; a cloud url is refused offline. The default model is a local qwen2.5-coder:7b served by Ollama on your own machine, so nothing leaves the box.

Usage

vulkro hunt [OPTIONS] [PATH]

PATH is the project to hunt over and defaults to the current directory.

The default sweep enumerates each sink and forces a vulnerable / safe verdict on it, which is more reliable with small local models. Pass --free-form to use the ReAct agent loop instead, where the model chooses its own actions each turn.

Arguments

Argument	Description	Default
PATH	Project path to hunt over.	.

Flags

Flag	Description	Default
--class <CLASS>	Focus the hunt on one class: sql, command, path, ssrf, xxe, deserialization, ssti, ldap, xpath, open_redirect. Omit to hunt the full class set.	full set
--free-form	Use the free-form ReAct agent loop instead of the default per-sink adjudication sweep. The sweep forces a vulnerable / safe verdict on each enumerated sink; the free-form loop lets the model choose its own actions each turn.	false
--max-turns <N>	Cap the number of agent turns (model calls).	24
--ai-budget <TOKENS>	Cap the running token budget for the whole hunt.	60000
--verbose	Stream a live trace of the hunt to stderr (every phase, adjudication, verification, and refine step). The trace goes to stderr so it never pollutes --format json on stdout.	false
--log <FILE>	Write the structured hunt log as JSON Lines to this file (one event per line: phases, verdicts, verify results, refine steps).	none
--format <FORMAT>	Output format: table, json, or sarif.	table
--ai-model <MODEL>	AI model tag override (highest precedence). Overrides VULKRO_AI_MODEL, the saved vulkro ai use selection, and the smart default.	smart default
--ai-url <URL>	AI runtime base url override (OpenAI-compatible). A loopback url is allowed under VULKRO_OFFLINE; a cloud url is refused offline.	Ollama default
--no-ai	Disable the AI layer for this run. No hunt runs; the deterministic scan is unaffected.	false
--offline	Hard-disable every outbound network call for this run (sets VULKRO_OFFLINE=1). Blocks the CVE feed, the license heartbeat, the update check, webhooks, and any cloud AI endpoint. A loopback model is still allowed. Equivalent to exporting VULKRO_OFFLINE=1, and the flag wins when both are set.	false

Output formats

• table (default): the advisory banner plus confirmed findings and leads.
• json: the full AiAgentReport.
• sarif: the advisory SARIF lane. A separate vulkro-ai run with vulkro-ai-* ruleIds and note / warning-only levels, kept disjoint from the deterministic scan SARIF.

The advisory formats never change the exit code, which follows the deterministic scan only.

Exit codes

The exit code follows the deterministic scan ONLY. The advisory hunt never moves it.

• 0 scan clean (no deterministic findings).
• 1 the deterministic scan reported findings.
• 2 error: bad path or IO failure.

Examples

# Hunt the full class set over the current project.
vulkro hunt .

# Focus on SQL injection, with a live trace to stderr.
vulkro hunt --class sql --verbose

# Free-form loop, capped budget, structured log to a file.
vulkro hunt --free-form --max-turns 40 --ai-budget 120000 --log hunt.jsonl

Related

• vulkro ai - configure and drive the local-AI layer the hunt uses.
• vulkro scan - the deterministic scan the hunt builds on and defers to.
• vulkro prove - turn a confirmed finding into a runnable proof.

Command reference

Generated from vulkro help hunt on vulkro 0.26.0. This block is the authoritative flag, usage, and exit-code reference for this command; the prose above is the friendly explanation. Do not edit this block by hand; run npm run docs:cli after a release.

Let a local model hunt for bugs the scan may have missed, using Vulkro's own checks as tools.

AI-first agent hunt: an optional local model DRIVES a hunt for vulnerabilities the deterministic scan may have missed, calling Vulkro's deterministic checks (find sinks, read slices, taint, prove) as tools. A finding is CONFIRMED only when a deterministic oracle grounds it; everything else is a labelled advisory lead.

ADVISORY / opt-in / local-by-default. Enabling it changes NO deterministic result: not a finding, a severity, the benchmark, or the exit code. A loopback model is allowed under VULKRO_OFFLINE; a cloud url is refused offline.

Exit codes follow the deterministic scan ONLY: 0  scan clean (no deterministic findings). 1  the deterministic scan reported findings. 2  error (bad path, IO failure).

Usage: vulkro hunt [OPTIONS] [PATH]

Arguments:
  [PATH]
          Project path to hunt over. Defaults to the current directory
          
          [default: .]

Options:
      --class <CLASS>
          Focus the hunt on one class: sql | command | path | ssrf | xxe | deserialization | ssti | ldap | xpath | open_redirect. Omit to hunt the full class set

      --offline
          Hard-disable every outbound network call for this run (sets VULKRO_OFFLINE=1). Blocks the CVE feed, the license heartbeat, the update check, webhooks, and any cloud AI endpoint; a loopback model (http://127.0.0.1, http://localhost) is still allowed. Equivalent to exporting VULKRO_OFFLINE=1, and the flag wins when both are set

      --ai-model <MODEL>
          AI model tag override (highest precedence). Overrides VULKRO_AI_MODEL, the saved `vulkro ai use` selection, and the smart default

      --ai-url <URL>
          AI runtime base url override (OpenAI-compatible). A loopback url is allowed under VULKRO_OFFLINE; a cloud url is refused offline

      --no-ai
          Disable the AI layer for this run (no hunt runs; the deterministic scan is unaffected)

      --format <FORMAT>
          Output format: `table` (default; the advisory banner + confirmed findings and leads), `json` (the full AiAgentReport), or `sarif` (the advisory SARIF lane: a separate `vulkro-ai` run with `vulkro-ai-*` ruleIds and note/warning-only levels, kept disjoint from the deterministic scan SARIF). Advisory formats never change the exit code, which follows the deterministic scan only
          
          [default: table]

      --max-turns <N>
          Cap the number of agent turns (model calls). Defaults to the built-in budget (24)

      --ai-budget <TOKENS>
          Cap the running token budget for the whole hunt. Defaults to the built-in budget (60000)

      --free-form
          Use the free-form ReAct agent loop instead of the default per-sink adjudication sweep. The sweep forces a vulnerable/safe verdict on each enumerated sink (more reliable with small local models); the free-form loop lets the model choose its own actions each turn

      --verbose
          Stream a live trace of the hunt to stderr (every phase, adjudication, verification, and refine step). The trace goes to stderr so it never pollutes `--format json` on stdout

      --log <FILE>
          Write the structured hunt log as JSON Lines to this file (one event per line: phases, verdicts, verify results, refine steps)

  -h, --help
          Print help (see a summary with '-h')