Troubleshooting and FAQ

Find the symptom, then the fix. For any failed run, the agent's own error output is in ~/.secfoo/reports/<run-id>/stderr.log.

A run didn't succeed

StatusMeansFix
binary_not_foundThe agent's CLI isn't on PATH.Install it, or fix PATH in the shell you run secfoo from. secfoo agents shows what's found.
not_configuredThe api agent has no key.Set OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY.
timeoutThe agent ran past its limit (30 minutes; 15 for Cursor) and was stopped.Use --timeout 3600, --depth quick, or --exclude for folders that aren't in scope.
failedThe agent exited with an error.Read stderr.log. The usual causes are an expired login, a "trust this folder" prompt, or a provider quota. Log in to the agent outside secfoo and retry.

Other common problems

SymptomFix
Nothing new to scan. Use --rescan to scan this commit again.That commit was already scanned for those activities. Add --rescan, or commit your changes first.
The api agent fails with missing dependenciesInstall with pip install "secfoo[api]". The npm package, install scripts and Docker image don't include them.
Diagrams show as textRun secfoo vendor mermaid once, then restart secfoo serve.
The report says a Confluence page couldn't be readThe agent has no Confluence MCP connection. See Connecting agent CLIs (MCP).
Cloning a private repository failsFor HTTPS, set SECFOO_GITLAB_TOKEN or SECFOO_BITBUCKET_TOKEN; for SSH, check that git clone works on its own. See Repository targets.
Error in ~/.secfoo/config.tomlThe file has a TOML error, or an [[mcp_servers]] entry sets both or neither of command and url. Fix it, or move it aside and run secfoo config init.
Findings show as 0 but the report lists issuesThe agent didn't use the required ### [SEVERITY] ID: title headings, so nothing was counted. Rerun, or try another agent or model.
Cost shows a dash, or runs are "unpriced"That agent doesn't report spend (Cursor, Antigravity), or reports tokens only (Gemini, Codex). See where cost numbers come from.
secfoo serve says the port is in usesecfoo serve --port 9000
The dashboard isn't reachable from DockerPass serve --host 0.0.0.0 inside the container. See Docker.
A date option is rejectedDates are always YYYY-MM-DD.
Windows: Codex or Copilot runs failUpgrade secfoo; both were fixed for Windows in recent releases.

FAQ

Does secfoo send my code anywhere?

secfoo itself doesn't, but the agent doing the review sends what it reads to its model provider, as it does whenever you use it. The api agent sends source files in its prompt. See What leaves your machine.

Will two runs give the same report?

Not word for word: the agent is a model. The report's structure, severities and verdict options are fixed, which is what lets runs be compared. SAST, SCA and secret findings are matched across runs by the code they point at, so a reworded finding is recognised as the same one.

Are the findings always right?

No. Treat a report as a capable reviewer's first draft and check each finding before acting on it. Record what you decide; see Recording risk decisions and How far to trust it.

How much does a scan cost?

It depends on the agent, model, depth and repository size. With a subscription-based agent CLI there's no per-scan charge from secfoo. Where the agent reports spend, secfoo cost shows it by agent, skill or project, and --max-cost caps it. Start with quick depth.

Which agent should I use?

The one your organisation already approves for this code. secfoo gives each the same brief and the same report shape. See Choosing and setting up an agent.

Can I run it without internet access?

secfoo and the dashboard run locally, but the agent needs to reach its model provider. Copy mermaid.min.js into ~/.secfoo/vendor/ by hand for diagrams; SCA advisory lookups are skipped when OSV.dev can't be reached.

Can I add my own activity?

Yes, in a source install: an activity is a Markdown file in src/secfoo/skills/definitions/. The CLI choices, the dashboard's run form and its activity pages are all built from that folder. See the repository.

Reporting a bug

Open an issue on GitHub with your secfoo install method, the agent and its version, the command you ran, and stderr.log from the failed run. Report security vulnerabilities privately, as described in the repository's SECURITY.md, not in a public issue.

← Data and privacy