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:

Project nameThe name shown across the dashboard. Press Enter to accept the default (the repo or folder name).
Application ID (optional)The system's ID in your asset inventory or CMDB, if you have one. Press Enter to skip.

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.

Quick by default
Without --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:

ColumnWhat it tells you
SkillThe activity that ran.
Statussuccess, or why it didn't finish: failed, timeout, binary_not_found (agent not on PATH) or not_configured (no API key).
DurationHow long the agent took.
Findings (C/H/M/L)How many critical, high, medium and low findings the report contains.
CostAI spend, when the agent reports it. A dash means this agent doesn't report cost.
Run IDThe 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 --skill flags 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 init writes ~/.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 mermaid once 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.

← Introduction Installation →