Metadata-Version: 2.4
Name: agentfort
Version: 0.1.4
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
```

## GitHub Actions

Add AgentFort to any CI pipeline with one step. The action installs `agentfort` from PyPI and runs a full scan — failing the build on critical findings by default.

```yaml
- name: AgentFort Security Scan
  uses: NeuronKnight/agentfort-action@v1
  with:
    repo-path: '.'           # directory to scan (default: .)
    min-severity: 'low'      # critical | high | medium | low (default: low)
    fail-on-critical: 'true' # fail build on critical findings (default: true)
    offline: 'false'         # skip OSV.dev live CVE lookup (default: false)
```

Full workflow example:

```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: NeuronKnight/agentfort-action@v1
        with:
          min-severity: high
          fail-on-critical: 'true'
```

> **Note:** `NeuronKnight/agentfort-action` is the planned standalone Action repo. Until it's published, use the local action from this repo: `uses: ./.github/actions/agentfort`.

## 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
```

## Ignoring paths

Create `.agentfortignore` in your repo root to exclude directories or files from scanning. Uses gitignore-style glob patterns:

```
# .agentfortignore

# Ignore generated code
generated/

# Ignore vendor directory
vendor/

# Ignore specific file pattern
*.pb.py
```

The scanner skips any file whose path matches a pattern. Useful for:
- Vendored code you don't control
- Test fixtures that intentionally contain vulnerable patterns
- Generated files with no manual security surface

## 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
```
