Metadata-Version: 2.5
Name: secfoo
Version: 0.3.0
Summary: Context-based security architectural assessment orchestrator: pick skills, targets, and an agent CLI to run them.
Author-email: RakFort <info@rakfort.com>
License-Expression: MIT
License-File: LICENSE
Keywords: compliance,llm-agent,owasp,security,stride,threat-modeling
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click<9,>=8.3.3
Requires-Dist: fastapi>=0.110
Requires-Dist: jinja2>=3.1
Requires-Dist: langgraph>=0.2
Requires-Dist: litellm>=1.40
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: pypdf>=4.0
Requires-Dist: python-docx>=1.1
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: python-pptx>=0.6.23
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: api
Requires-Dist: langgraph>=0.2; extra == 'api'
Requires-Dist: litellm>=1.40; extra == 'api'
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: bandit>=1.8; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: langgraph>=0.2; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Secfoo - Everyone's a security professional.

<p align="center">
  <a href="https://pypi.org/project/secfoo/"><img src="https://img.shields.io/pypi/v/secfoo" alt="PyPI"></a>
  <a href="https://pypi.org/project/secfoo/"><img src="https://img.shields.io/pypi/dm/secfoo" alt="PyPI downloads"></a>
  <a href="https://github.com/secfoo-com/secfoo/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/secfoo-com/secfoo/ci.yml" alt="CI"></a>
  <a href="https://github.com/secfoo-com/secfoo/blob/main/LICENSE"><img src="https://img.shields.io/github/license/secfoo-com/secfoo" alt="MIT license"></a>
</p>

<p align="center">
    Secfoo turns any AI coding agent into a disciplined security reviewer — same standards, same report, every run.
Context-based security architectural assessment orchestrator: pick skills, targets, and an agent CLI to run them.
</p>

<p align="center">
  <a href="https://secfoo.com">Website</a> ·
  <a href="https://secfoo.com/docs/index.html#install">Getting Started</a> ·
  <a href="https://secfoo.com/docs/cli.html">CLI Reference</a> ·
  <a href="https://secfoo.com/docs/index.html">Documentation</a>
</p>

Pick one or more security **activities** (see the catalog below), point them
at a **target** (a public GitHub URL, a local directory, plus optional
Confluence links for extra context), choose which coding-agent CLI runs them
(Claude Code, Cursor, Antigravity, Gemini CLI, or Codex CLI), and browse every
assessment ever run, across every project, in a local web dashboard.

> This repository is the open-source CLI and local dashboard. secfoo's
> enterprise portal (multi-tenant cloud sync, admin console) is closed-source
> and lives in a separate private repository — `secfoo cloud login` connects
> this CLI to it, but nothing about the portal itself is in this repo.

## Quick Start

Requires Python 3.10+ for `pip install` — or skip Python entirely with
npm, a standalone binary, or Docker (see [Install](#install) below).

```bash
pip install secfoo
secfoo run --skill security-architecture-review --agent claude
```

You'll need an agent CLI already installed and authenticated — Claude
Code, Cursor, Antigravity, Gemini CLI, or Codex CLI (`--agent claude|agent|agy|gemini|codex`)
— or just a model API key with the built-in `api` agent (below).
On a real terminal, that first run prompts for a project name and
application ID, then browse every result in the dashboard:

```bash
secfoo run --skill sast --skill threat-modeling \
  --target https://github.com/org/repo --agent claude
secfoo serve
```

### No agent CLI? Use an API key

The built-in `api` agent is a LangGraph workflow that sends the target's
source to OpenAI, Anthropic or Gemini through LiteLLM — no coding-agent
CLI needed, which suits CI. Keys are read from the environment only and
never stored:

```bash
pip install "secfoo[api]"
export OPENAI_API_KEY=...            # or ANTHROPIC_API_KEY / GEMINI_API_KEY
export SECFOO_API_MODEL=openai/gpt-4.1-mini   # optional; any LiteLLM model id
secfoo run --skill sast --agent api --target https://github.com/org/repo
```

It suits small and medium repositories: the whole target has to fit in one
request, and larger ones are rejected with a message suggesting `--exclude`.

### Tracking AI spend

Every run records tokens and cost where the agent reports them (`api`,
`claude`; `gemini` reports tokens only). See it per run in `secfoo run`,
`secfoo list` and the dashboard, or summarised:

```bash
secfoo cost                          # by agent
secfoo cost --by skill --since 2026-09-01
secfoo cost --project checkout
```

Secfoo also includes a built-in LangGraph agent whose model calls are routed
through LiteLLM. Configure the provider key and model in the environment;
credentials are never stored in the repository:

```powershell
$env:OPENAI_API_KEY = "your-key"
$env:SECFOO_MODEL = "openai/gpt-4o-mini"
secfoo run --skill security-architecture-review --agent secfoo
```

LiteLLM-reported spend is stored per run and can be reviewed from the
dashboard or queried from the CLI:

```bash
secfoo cost
secfoo cost --project "Checkout Service"
```

See [Getting Started](https://secfoo.com/docs/index.html#quickstart) or
the [CLI reference](https://secfoo.com/docs/cli.html) for more.

## What can you do with secfoo?

- **Review architecture and threat-model a system** against secure
  design principles, STRIDE/LINDDUN, and CSA CCM v4 domain conformance
- **Find code and dependency vulnerabilities** — SAST and SCA reachability
  triage, tracked as an Open/Closed Findings register across rescans, not
  just a one-off report
- **Catch exposed credentials** across source, config, git history, and
  linked Confluence pages
- **Review LLM prompts and agent tool definitions** for injection and
  over-permissioning risk
- **Track third-party/vendor risk** with AI-BOM inventories and a
  dedicated third-party review workflow
- **Run it in CI**, non-interactively, with the same commands you'd use
  locally
- **Browse every assessment across every project** in a local dashboard,
  or sync to your org's enterprise portal

## Why secfoo?

- **Agent-native, not another parser**: a skill is a structured prompt,
  not a bespoke rules engine — secfoo hands your existing coding-agent
  CLI a brief and a target and lets it actually read the code, the way
  a human reviewer would.
- **Local-first**: `secfoo serve` and every run stay on your machine
  unless you explicitly connect `secfoo cloud login` to your org's portal.
- **One case file per system**: assessments consolidate repeat runs
  under the same application ID instead of fragmenting into a new
  record every rescan.
- **Concurrent by default**: multiple `--skill` flags run at the same
  time, not one after another.
- **Bring your own agent**: Claude Code, Cursor, Antigravity, Gemini
  CLI, or Codex CLI — pick whichever you already use and trust.
- **Open source CLI**: MIT licensed.

## Activity catalog

| Activity | Skill ID |
|---|---|
| Security Architecture Review | `security-architecture-review` |
| Threat Modeling | `threat-modeling` |
| SAST — Static Code Analysis | `sast` |
| SCA — Reachability & Upgrade Triage | `sca-reachability` |
| Secret Scanning — Code, Confluence & Docs | `secret-scanning` |
| Prompt Review | `prompt-review` |
| Deployment Readiness | `deployment-readiness` |
| Responsible AI Compliance | `responsible-ai-compliance` |

Run one, or several together — multiple `--skill` flags execute
concurrently against the same target. Each has its own report shape and
program-level dashboard; see [docs/REFERENCE.md](docs/REFERENCE.md) for
what each one actually produces, plus assessments, configuration, and
install/distribution details.

## Install

```bash
pip install secfoo               # PyPI, needs Python 3.10+
npm install -g @rakfortltd/secfoo    # npm, no Python needed
docker run --rm ghcr.io/rakfortltd/secfoo --help
```

Also available via a universal install script (macOS/Linux/Windows) and
as standalone platform binaries — see
[docs/REFERENCE.md#install](docs/REFERENCE.md#install) for every channel.
Developing on this repo instead? `pip install -e ".[dev]"`.

## Learn More

- [docs/REFERENCE.md](docs/REFERENCE.md) — full activity catalog, dashboards, assessments, configuration, distribution
- [Getting Started](https://secfoo.com/docs/index.html#quickstart)
- [Full Documentation](https://secfoo.com/docs/index.html)
- [CLI Reference](https://secfoo.com/docs/cli.html)
- [Running an assessment](https://secfoo.com/docs/guide-running-an-assessment.html)
- [Excluding paths from a scan](https://secfoo.com/docs/guide-excluding-paths.html)
- [Rendering architecture diagrams](https://secfoo.com/docs/guide-architecture-diagrams.html)
- [Connecting agent CLIs (MCP)](https://secfoo.com/docs/guide-connecting-mcp.html)
- [Editions & pricing](https://secfoo.com/editions.html)

## Contributing

We welcome contributions — see [CONTRIBUTING.md](CONTRIBUTING.md) to get
started, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community
expectations. Found a security issue? See [SECURITY.md](SECURITY.md)
instead of opening a public issue.
