Choosing and setting up an agent

secfoo doesn't do the review itself. It hands a structured brief to a coding agent you already have, or to a model API, and collects a report in a fixed shape. Pick which one with --agent.

Before your first run

A CLI agent must be installed on your PATH and already logged in. secfoo runs it headless: there's no terminal for it to ask you a question, so a login or "trust this folder?" prompt can't be answered mid-run. Install and authenticate each tool using its own instructions, then check what secfoo can see:

secfoo agents      # every adapter, and whether its CLI is on PATH

secfoo agents checks that the binary exists, not that it's logged in.

The adapters

Agent IDRuns withWhat to know
claudeClaude CodeThe default. Subscription login works. Gets a read-only tool grant (read, search, git log/git diff). Only the MCP servers in your secfoo config load; servers from your global Claude config or the target's .mcp.json don't.
agentCursorCursor's headless mode can hang, so its default timeout is 900 seconds (others use 1800).
codexCodex CLIRuns in Codex's read-only sandbox, and works on Windows. A run fails if the sandbox rejects a command.
copilotGitHub Copilot CLICopilot auto-approves tools, including writes. Read-only behaviour relies on the review instructions, not a sandbox.
geminiGemini CLIRuns with --skip-trust and no write auto-approval. If you see IneligibleTierError, try --agent agy.
opencodeOpenCodeShell, edit and web-fetch permissions are denied for the run, and external plugins are disabled.
droidFactory DroidSet FACTORY_API_KEY; without it Droid reports Authentication failed. Droid defaults to read-only.
agyAntigravityHeadless mode denies tool calls that need approval. No model selection and no MCP support yet.
devinDevin CLIRun devin auth login first. No model selection.
apiA model API keyNo agent CLI at all. See below.

No agent CLI? Use an API key

The built-in api agent calls a model directly, which is handy in CI or on a machine where you can't install an agent CLI.

pip install "secfoo[api]"
export OPENAI_API_KEY=...        # or ANTHROPIC_API_KEY / GEMINI_API_KEY
secfoo run --skill sast --agent api --target https://github.com/org/repo
Source files go to the model provider
Unlike the CLI agents, which read files themselves, the api agent includes the target's source files in the prompt it sends. Use a provider and account your organisation has approved for that code.

The model is, in order: the one you select (below), then SECFOO_API_MODEL, then openai/gpt-4.1-mini. Set SECFOO_API_MODEL if your key isn't an OpenAI one. Cost comes from LiteLLM's pricing for that model.

Choosing a model

Pick a model for one run, or set a per-agent default once:

secfoo run --skill sast --agent claude --model <model-id>
# ~/.secfoo/config.toml
[agents.claude]
model = "<model-id>"

[agents.codex]
model = "<model-id>"

Use the registered agent ID as the table name (agent for Cursor, agy for Antigravity). --model wins over the config. Use a model ID your installed CLI accepts; an invalid one is reported by that CLI. Antigravity and Devin have no model flag, so secfoo warns and uses the CLI's default. With no model set, each CLI uses its own default.

Each run stores the model you requested. That's a label, not a provider-verified identity, and it's empty when you didn't pick one.

When a run fails

binary_not_foundThe CLI isn't on PATH. Install it, or fix PATH for the shell secfoo runs in.
Login or trust promptCan't be answered during a run. Log in to the CLI first, outside secfoo, then rerun.
timeoutsecfoo kills the agent's whole process tree. Raise it with --timeout or [defaults].timeout.
failedRead the error. If Antigravity returns empty output or "Agent execution terminated due to error", try another agent.
not_configuredThe api agent has no key. Set OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY.

The agent's own error output for any run is in ~/.secfoo/reports/<run-uuid>/stderr.log. Include it when you report a bug.

Next: wire a run into your pipeline with CI gates and SARIF export, or give agents extra context with MCP servers.