Your first scan
From nothing installed to a finished security review in your browser. Plan on about ten minutes, most of it the agent doing the review.
What you need
- macOS, Linux or Windows.
- Something to do the review. Either a coding-agent CLI that's installed and already logged in (Claude Code is the default; Cursor, Codex, Copilot, Gemini CLI and others work too), or an OpenAI, Anthropic or Gemini API key.
- Something to review. A project directory on your machine, or the URL of a GitHub, GitLab or Bitbucket repository.
Step 1: Install secfoo
If you have Python 3.10 or newer, pip is the simplest route:
pip install secfoo
No Python? npm install -g @rakfortltd/secfoo or the install script works too. See Installation for every option. Check it worked:
secfoo --help
You should see the list of commands (run, serve, agents and so on). If your shell says command not found, see "command not found" after installing.
Step 2: Check your agent
secfoo doesn't review code itself. It briefs a coding agent and collects the agent's report. Ask secfoo which agents it can find:
secfoo agents
This lists every adapter and whether its CLI is on your PATH. It doesn't check that the agent is logged in, so do that yourself: open the agent once in a normal terminal and finish any login or "trust this folder" prompt. secfoo runs agents without a terminal attached, so a prompt it hits mid-run can't be answered and the run fails.
No agent CLI? Use an API key with the built-in api agent instead. It needs the pip install with extras:
pip install "secfoo[api]"
export OPENAI_API_KEY=sk-... # or ANTHROPIC_API_KEY / GEMINI_API_KEY
Then use --agent api wherever this page says --agent claude. With an Anthropic or Gemini key, also set SECFOO_API_MODEL to one of that provider's models, since the default is an OpenAI model. See Using an API key.
Step 3: Run a scan
Go to the project you want to review and run the SAST activity (static code analysis) against it:
cd ~/code/my-service
secfoo run --skill sast --agent claude
Or scan a repository by URL without cloning it yourself. secfoo makes a shallow clone and deletes it afterwards:
secfoo run --skill sast --agent claude --target https://github.com/org/repo
Before the scan starts, secfoo asks two questions:
These label the assessment (secfoo's case file) that the run is filed under. Pass --project-name and --app-id to skip the questions.
Then the agent works, with a progress line for each activity. A first scan typically takes a few minutes; large repositories take longer. Each activity is stopped after 30 minutes by default (15 for Cursor), which you can change with --timeout.
--depth, scans run at quick depth: the agent reports the 3 to 8 most important findings, favouring critical and high severity. Add --depth standard for a full review against the activity's whole checklist. It takes longer and costs more.Step 4: Read the result
When the scan finishes, secfoo prints a results table:
| Column | What it tells you |
|---|---|
| Skill | The activity that ran. |
| Status | success, or why it didn't finish: failed, timeout, binary_not_found (agent not on PATH) or not_configured (no API key). |
| Duration | How long the agent took. |
| Findings (C/H/M/L) | How many critical, high, medium and low findings the report contains. |
| Cost | AI spend, when the agent reports it. A dash means this agent doesn't report cost. |
| Run ID | The run's UUID, used by secfoo show. |
Read the full report in the terminal:
secfoo show <run-id> # the report, as Markdown
secfoo list # every run so far, newest first
Every report opens with a short summary and an overall risk rating, then lists each finding with its severity, location and a concrete fix. Reading a report explains each part.
Step 5: Open the dashboard
secfoo serve
Open http://127.0.0.1:8787 in your browser. The dashboard runs only on your machine and reads the same local store the CLI writes to. Stop it with Ctrl+C.
- Dashboard shows posture across everything you've scanned, with the top findings.
- Assessments lists your case files. Open yours to see the run and its report.
- Analysis → SAST lists your findings. Each stays open until a later scan no longer finds it.
See Using the dashboard for a tour of every page.
Where to go next
- Run more activities at once. Several
--skillflags run concurrently:secfoo run --skill threat-modeling --skill security-architecture-review --agent claude. The activity reference explains what each one does. - Stop typing the same flags.
secfoo config initwrites~/.secfoo/config.toml, where you can set a default agent, depth and exclusions. See Configuration. - See diagrams. Architecture and threat-modeling reports include a data-flow diagram. Run
secfoo vendor mermaidonce to render it as a picture. See Rendering architecture diagrams. - Scan on every pull request. See CI gates and SARIF export.
Everything secfoo stored is in ~/.secfoo/. Data and privacy explains what's there and what leaves your machine.