Introduction

Secfoo is a context-based security architectural assessment orchestrator. Pick one or more security activities, point them at a target, choose which coding-agent CLI runs them, and browse every assessment ever run in a local web dashboard.

What Secfoo does

  • Runs any of 8 activities — architecture review, threat modeling, SAST, SCA, secret scanning, prompt review, deployment readiness, Responsible AI compliance — concurrently against the same target, and reviews vendors' security documents for third-party risk.
  • Targets a local directory or a GitHub, GitLab or Bitbucket repository, plus optional Confluence pages for extra context.
  • Drives the agent that actually performs the review: Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Antigravity, Droid or Devin, or a model API key directly. See choosing an agent.
  • Stores every run locally and serves it from secfoo serve — a dashboard that never calls out to a CDN while you're reading a report.
  • Tracks SAST, SCA and secret findings open-to-closed across rescans, exports them as JSON Lines or SARIF, and gates CI on severity and AI spend. See CI gates and SARIF export.
Optional: render diagrams
Architecture review and threat modeling reports include a Mermaid data-flow diagram. Run secfoo vendor mermaid once (~3.5MB) to render it as a picture in the dashboard — without it, the diagram source still appears, just unrendered.

Start here

Installation

Pick whichever fits how you work — they're all the same tool underneath. To use the built-in api agent, install with pip. Installation covers checking, upgrading and uninstalling.

PyPI · Python 3.10+
pip install secfoo
npm · standalone binary
npm install -g @rakfortltd/secfoo
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/secfoo-com/secfoo/main/install.sh | sh
Windows PowerShell
irm https://raw.githubusercontent.com/secfoo-com/secfoo/main/install.ps1 | iex
Docker
docker run --rm ghcr.io/secfoo-com/secfoo --help
Contributing to secfoo
pip install -e ".[dev]"

Quickstart

# 1. Run a skill against the current directory
secfoo run --skill security-architecture-review --agent claude

# 2. List past runs
secfoo list

# 3. Launch the dashboard
secfoo serve

No agent CLI installed? Use a model API key instead:

pip install "secfoo[api]"
export OPENAI_API_KEY=...        # or ANTHROPIC_API_KEY / GEMINI_API_KEY
secfoo run --skill sast --agent api

On a real terminal, step 1 asks for a project name and application ID before it runs — that's what makes the case file it creates findable later on the Assessments page instead of just a bare run. Skip the prompt with --project-name/--app-id flags, or leave it non-interactive (CI, scripts) and it's skipped automatically. See the CLI reference for the full flag list, or follow Your first scan for a step-by-step walkthrough.

Configuration

Set a default agent, depth, timeout, exclusions, and MCP servers once in ~/.secfoo/config.toml, instead of passing flags on every secfoo run. The file is plain TOML, entirely optional — an empty or missing config is fine, secfoo just falls back to built-in defaults — and CLI flags always win over whatever it sets.

secfoo config init      # writes a starter ~/.secfoo/config.toml

[defaults]

Fallbacks for secfoo run's --agent, --depth, --timeout, --exclude, --fail-on and --max-cost flags.

KeyTypeDefaultNotes
agentstringclaudeclaude · agent (Cursor) · agy (Antigravity) · gemini · codex · copilot · opencode · droid · devin · api
depthstringquickquick (fast triage) or standard (full checklist)
timeoutintegeragent's own defaultPer-skill timeout, in seconds
excludearray of strings[]Additive on top of secfoo's built-ins (node_modules/, .git/, dist/, …) — never a replacement for them. --exclude on the command line adds further paths on top, for a single run.
fail_onstringunsetcritical · high · medium · low. Exit 2 when a finding at that severity or worse is reported. Unset means findings never fail the command.
max_cost_usdnumberunsetExit 3 when the summed reported AI spend for an invocation exceeds this.

[agents.<id>]

A default model per agent, so you don't have to pass --model on every run. The table name is the agent ID from --agent.

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

--model on the command line wins. Antigravity and Devin ignore model selection, with a warning. See choosing a model.

[[mcp_servers]]

Define MCP servers once here instead of wiring each agent CLI separately — e.g. an Atlassian/Confluence connector for --confluence context. Repeat the [[mcp_servers]] table for each server.

KeyRequiredNotes
nameYesUnique identifier — secfoo mcp list and secfoo mcp sync refer to servers by this.
commandExactly one of command / urlstdio transport — the binary secfoo runs, e.g. npx.
argsNoArray of arguments passed to command.
urlExactly one of command / urlsse/http transport — a remote MCP endpoint.
transportNoDefault stdio. Set to sse or http alongside url.
envNoKey-value environment variables passed to a stdio process.
headersNoKey-value HTTP headers for an sse/http server, e.g. an Authorization bearer token.
Exactly one of command or url
Setting both, or neither, on an [[mcp_servers]] entry fails config loading with mcp_servers.<name>: set exactly one of command (stdio) or url (sse/http).

How a configured server actually reaches an agent depends on that agent's own CLI:

claudePicked up automatically on every secfoo run (via --mcp-config, scoped to that invocation only — your global Claude config is never touched).
gemini, agent (Cursor)Run secfoo mcp sync --agent <agent> once to register persistently in that tool's own config. Re-run after adding new servers — already-registered ones are skipped.
codexNot wired up yet — Codex reads MCP servers from its own ~/.codex/config.toml.
agy (Antigravity)Not supported yet — its CLI has no MCP configuration mechanism as of this writing.

A complete example — one stdio server bridged through npx, one remote server reachable directly over HTTP:

[defaults]
agent = "claude"
depth = "quick"
# timeout = 1800
# exclude = ["vendor/", "third_party/", "some-cloned-repo/"]

# Atlassian (Confluence/Jira) via the official Rovo MCP server, bridged
# through the mcp-remote npm package (stdio transport: secfoo just needs
# a command + args to run).
[[mcp_servers]]
name = "Atlassian-Rovo-MCP"
command = "npx"
args = ["-y", "mcp-remote@latest", "https://mcp.atlassian.com/v1/mcp/authv2"]

# A plain remote MCP server reachable directly over HTTP/SSE (no bridge
# needed) -- use url + transport instead of command.
[[mcp_servers]]
name = "example-remote"
url = "https://example.com/mcp"
transport = "http"
headers = { Authorization = "Bearer YOUR_TOKEN" }

Check what's loaded with secfoo mcp list, then see the full mcp / config command reference →

CLI reference →