Metadata-Version: 2.4
Name: agentfort
Version: 0.1.2
Summary: CVE-style advisory database and static scanner for AI agent security risks
Author-email: NeuronKnight <dev@neuronknight.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/NeuronKnight/agentfort
Project-URL: Source, https://github.com/NeuronKnight/agentfort
Project-URL: Issues, https://github.com/NeuronKnight/agentfort/issues
Keywords: security,ai,agents,mcp,llm,scanner,langchain,crewai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# AgentFort

Static security scanner for AI agent codebases. Analyzes repositories and MCP config files against a CVE-style advisory database — no live agent interaction required.

## What it does

- Scans Python repos for dangerous patterns: `eval()`, `exec()`, `shell=True`, hardcoded API keys
- Parses MCP config files (`claude_desktop_config.json`, `.mcp.json`) for shell execution tools, overly broad filesystem access, and unverified `npx`/`uvx` packages
- Detects agent framework imports (LangChain, CrewAI, AutoGen, OpenAI, Anthropic, etc.) and cross-references against known vulnerabilities
- **Queries OSV.dev live** for real CVEs against every detected package — findings stay current without any database updates
- Produces risk scores, terminal reports, Markdown, and JSON output
- Exits with code 1 on critical findings — CI pipeline friendly

## Install

```bash
# From repo root (inside a virtualenv)
pip install agentfort

# Or dev install from repo root
pip install -e .
```

## Usage

```bash
# Scan a repo
agentfort scan --repo /path/to/your/agent-project

# Scan just an MCP config file
agentfort scan --mcp-config ~/.config/claude/claude_desktop_config.json

# JSON output (clean stdout, progress on stderr)
agentfort scan --repo . --format json

# Markdown report to file
agentfort scan --repo . --format md --output report.md

# Only show high and above
agentfort scan --repo . --min-severity high

# Disable CI exit code
agentfort scan --repo . --no-fail-on-critical

# Skip OSV live lookup (air-gapped / CI without outbound)
agentfort scan --repo . --offline

# Browse advisories
agentfort advisories list
agentfort advisories list --severity critical
agentfort advisories show AGSA-001
```

## Live CVE lookup (OSV.dev)

Every scan queries [OSV.dev](https://osv.dev) in parallel for known CVEs against every package detected in the repo. No database to update — findings reflect OSV's current state on each run.

- Results are capped at 5 CVEs per package (highest severity first) to avoid noise from very old pinned versions
- Uses GHSA severity labels (`database_specific.severity`) for accurate critical/high/medium/low mapping
- Falls back silently if the network is unreachable — use `--offline` to skip the lookup entirely

```bash
# Scan with live CVEs (default)
agentfort scan --repo .

# Air-gapped / no outbound network
agentfort scan --repo . --offline
```

## Advisory database

14 static advisories covering structural/behavioral risks from the [OWASP Agentic Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/). Package CVEs are handled live by OSV.dev (see above).

| ID | Severity | Risk |
|---|---|---|
| AGSA-001 | Critical | LangChain ShellTool unrestricted shell execution |
| AGSA-002 | Critical | MCP server exposes shell execution tool |
| AGSA-003 | Critical | `eval()`/`exec()` in agent tool handler |
| AGSA-005 | Critical | AutoGen/CrewAI code execution without confirmation |
| AGSA-004 | High | Hardcoded API key or secret in MCP config |
| AGSA-006 | High | MCP filesystem server with overly broad path (`/`, `~`) |
| AGSA-007 | High | `subprocess` with `shell=True` or `os.system()` |
| AGSA-008 | High | Agent tool writes to arbitrary file paths |
| AGSA-010 | High | Prompt injection via unvalidated tool output |
| AGSA-013 | High | OpenAI Assistants `file_search`/`code_interpreter` without scope restriction |
| AGSA-009 | Medium | MCP server loaded via unverified `npx`/`uvx` package |
| AGSA-012 | Medium | Secrets exposed via `os.environ` in tool scope |
| AGSA-014 | Medium | Non-PyPI/non-npm dependency as framework component |
| AGSA-015 | Medium | System prompt in user-accessible config location |

## Risk score

`0–100`. Each finding adds: critical=40, high=15, medium=5, low=1. Capped at 100.

## Output formats

**Terminal** (default) — Rich panels with color-coded severity table and detail panels for critical/high findings.

**JSON** — Machine-readable. Progress messages go to stderr so stdout is clean for piping:
```bash
agentfort scan --repo . --format json 2>/dev/null | jq '.findings[] | select(.severity=="critical")'
```

**Markdown** — Full report with summary table and per-finding sections, suitable for GitHub issues or PR comments.

## Project structure

```
agentfort/                  # project root
├── agentfort/              # Python package
│   ├── cli.py              # Click CLI entry point
│   ├── models.py           # Finding, ScanResult dataclasses
│   ├── db/
│   │   ├── advisory.py     # Advisory loader and index
│   │   └── data/           # AGSA-001.yaml … AGSA-015.yaml
│   ├── scanner/
│   │   ├── frameworks.py   # requirements.txt / pyproject.toml / package.json
│   │   ├── mcp.py          # MCP config file scanner
│   │   ├── osv.py          # Live CVE lookup via OSV.dev API
│   │   ├── patterns.py     # Python source pattern scanner
│   │   └── secrets.py      # Hardcoded credential scanner
│   └── report/
│       └── formatter.py    # Terminal, Markdown, JSON renderers
└── pyproject.toml
```
