Metadata-Version: 2.4
Name: agentsec-cli
Version: 1.0.0
Summary: Static security scanner for AI coding agents and MCP configurations
Author: locface
License-Expression: MIT
Project-URL: homepage, https://locface.github.io/AgentSec/
Project-URL: repository, https://github.com/locface/AgentSec
Project-URL: documentation, https://locface.github.io/AgentSec/docs/
Project-URL: changelog, https://github.com/locface/AgentSec/blob/main/CHANGELOG.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.0.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: toml<1,>=0.10.2
Requires-Dist: tomli<3,>=2.0.1; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/locface/AgentSec/main/docs/images/agentsec-dark.svg">
  <img alt="AgentSec" src="https://raw.githubusercontent.com/locface/AgentSec/main/docs/images/agentsec-light.svg">
</picture>

# AgentSec

**Static security scanner for AI coding agents and MCP configurations.**

[![PyPI](https://img.shields.io/pypi/v/agentsec-cli.svg)](https://pypi.org/project/agentsec-cli/)
[![Python](https://img.shields.io/pypi/pyversions/agentsec-cli.svg)](https://pypi.org/project/agentsec-cli/)
[![License](https://img.shields.io/github/license/locface/AgentSec)](LICENSE)
[![Tests](https://img.shields.io/github/actions/workflow/status/locface/AgentSec/agentsec.yml?label=tests)](https://github.com/locface/AgentSec/actions)
[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-1a1a2e)](https://github.com/astral-sh/ruff)

AgentSec inspects MCP server manifests, Claude Desktop configs, Cursor rules, Codex configurations, and agent instruction files for dangerous permissions, prompt injection risks, secret exposure, and unsafe tool access.

**No LLM dependencies.** Purely static analysis. Your configurations never leave your machine.

## Why AgentSec?

AI coding agents have access to your shell, filesystem, network, and secrets. Most agent configurations are never audited for security risks.

AgentSec helps you answer:

- Which MCP servers can execute shell commands?
- Which configs expose filesystem write access?
- Which agents have both network and file access (exfiltration risk)?
- Are there unpinned dependencies or OAuth scopes that are too broad?

It maps every finding to [OWASP Top 10 for LLM Applications](https://genai.owasp.org/) (LLM01–LLM10) and the [OWASP Agentic Security Top 10](https://owasp.org/) (AG01–AG10), so findings are immediately understandable to security professionals.

## Features

- **41 security rules** — shell execution, filesystem access, network exfiltration, OAuth scopes, prompt injection, container escape risks, browser automation, credential helper exposure
- **OWASP LLM + Agentic mapping** — every rule maps to industry-standard security frameworks
- **4 output formats** — terminal (human-readable), JSON (machine-parseable), Markdown (reports), SARIF v2.1.0 (GitHub CodeQL)
- **CI/CD gating** — `--fail-on` exits with code 1 when findings meet a severity threshold
- **Baseline comparison** — track new, changed, and removed findings across scans
- **Zero LLM dependencies** — purely static analysis, no data exfiltration risk
- **Automatic config detection** — scans JSON, YAML, TOML, and Markdown files for known patterns
- **NOSECHO license** — MIT

## Installation

```bash
pip install agentsec-cli
```

**Landing page:** [https://locface.github.io/AgentSec/](https://locface.github.io/AgentSec/)

**Documentation:** [https://locface.github.io/AgentSec/docs/](https://locface.github.io/AgentSec/docs/)

**PyPI:** [https://pypi.org/project/agentsec-cli/](https://pypi.org/project/agentsec-cli/)

<details>
<summary>Install from source</summary>

```bash
git clone https://github.com/locface/AgentSec.git
cd AgentSec
pip install -e .
```
</details>

## Quick Start

## Installation

```bash
pip install agentsec-cli
```

**Landing page:** [https://locface.github.io/AgentSec/](https://locface.github.io/AgentSec/)

**Documentation:** [https://locface.github.io/AgentSec/docs/](https://locface.github.io/AgentSec/docs/)

**PyPI:** [https://pypi.org/project/agentsec-cli/](https://pypi.org/project/agentsec-cli/)

```
 Scanning /home/user/dev/mcp-project...

[CRITICAL] MCP shell execution
  File: claude_desktop_config.json
  Server: shell-server
  Description: MCP server can execute shell commands
  Recommendation: Require explicit approval or remove shell access.

[CRITICAL] MCP filesystem write access
  File: claude_desktop_config.json
  Server: filesystem
  Description: MCP server has filesystem write access
  Recommendation: Restrict filesystem access to read-only or specific directories.

[CRITICAL] Network + filesystem access
  File: mcp.json
  Server: everything
  Description: MCP server has both network and filesystem access (exfiltration risk)
  Recommendation: Separate network and filesystem capabilities, or implement strict allowlists.

Total findings: 4 · Critical: 3 · High: 0 · Medium: 1 · Low: 0
```

## CLI Reference

```text
Usage: agentsec [OPTIONS] COMMAND [ARGS]...

  AgentSec — security scanner for AI agent configs.

Options:
  --help  Show this message and exit.

Commands:
  scan  Scan a directory for security risks in AI agent configurations.
```

### Scan Options

| Option | Description |
|--------|-------------|
| `PATH` | Directory to scan (default: current directory) |
| `-f, --format` | Output format: `terminal`, `json`, `markdown`, `sarif` |
| `--severity` | Minimum severity: `critical`, `high`, `medium`, `low`, `all` |
| `--fail-on` | Exit with code 1 if any finding ≥ this severity |
| `--include-hidden` | Include hidden files and directories |
| `--baseline FILE` | Path to baseline JSON for regression comparison |
| `--update-baseline FILE` | Save current findings as baseline JSON |
| `--show-owasp` | Display OWASP mapping IDs for each finding |

## Output Formats

### Terminal (default)

```text
[CRITICAL] LLM06, AG02 MCP shell execution
  File: claude_desktop_config.json
  Server: shell-server
  Description: MCP server can execute shell commands
  Recommendation: Require explicit approval or remove shell access.

Total findings: 4 · Critical: 3 · High: 0 · Medium: 1 · Low: 0
```

## Installation

```bash
pip install agentsec-cli
```

**Landing page:** [https://locface.github.io/AgentSec/](https://locface.github.io/AgentSec/)

**Documentation:** [https://locface.github.io/AgentSec/docs/](https://locface.github.io/AgentSec/docs/)

**PyPI:** [https://pypi.org/project/agentsec-cli/](https://pypi.org/project/agentsec-cli/)
[
  {
    "rule": "MCP shell execution",
    "severity": "critical",
    "file": "claude_desktop_config.json",
    "server": "shell-server",
    "description": "MCP server can execute shell commands",
    "recommendation": "Require explicit approval or remove shell access.",
    "owasp": "LLM06, AG02"
  }
]
```

## Installation

```bash
pip install agentsec-cli
```

**Landing page:** [https://locface.github.io/AgentSec/](https://locface.github.io/AgentSec/)

**Documentation:** [https://locface.github.io/AgentSec/docs/](https://locface.github.io/AgentSec/docs/)

**PyPI:** [https://pypi.org/project/agentsec-cli/](https://pypi.org/project/agentsec-cli/)

## Installation

```bash
pip install agentsec-cli
```

**Landing page:** [https://locface.github.io/AgentSec/](https://locface.github.io/AgentSec/)

**Documentation:** [https://locface.github.io/AgentSec/docs/](https://locface.github.io/AgentSec/docs/)

**PyPI:** [https://pypi.org/project/agentsec-cli/](https://pypi.org/project/agentsec-cli/)

Upload to GitHub:

```yaml
- name: Run AgentSec
  run: |
    pip install agentsec-cli
    agentsec scan . --format sarif > results.sarif
- name: Upload SARIF to GitHub
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
```

## OWASP Mapping

## Installation

```bash
pip install agentsec-cli
```

**Landing page:** [https://locface.github.io/AgentSec/](https://locface.github.io/AgentSec/)

**Documentation:** [https://locface.github.io/AgentSec/docs/](https://locface.github.io/AgentSec/docs/)

**PyPI:** [https://pypi.org/project/agentsec-cli/](https://pypi.org/project/agentsec-cli/)
|-----------|-----|----------|
| OWASP Top 10 for LLM Applications | LLM01–LLM10 | Rules mapped to injection, sensitive data exposure, etc. |
| OWASP Agentic Security Top 10 | AG01–AG10 | Rules mapped to agency overreach, unauthorized execution, etc. |

Example:

```text
[CRITICAL] LLM06, AG02 MCP shell execution
```

Where LLM06 = Code Injection, AG02 = Unauthorized Execution.

## Baseline / Lockfile

Track regressions across scans:

```bash
# Save a baseline (first run)
agentsec scan . --update-baseline baseline.json

# Compare against baseline (subsequent runs)
agentsec scan . --baseline baseline.json
```

Baseline comparison shows:
- **New findings** — issues that didn't exist before
- **Changed severity** — findings whose severity changed
- **Removed findings** — issues that were fixed

## Installation

```bash
pip install agentsec-cli
```

**Landing page:** [https://locface.github.io/AgentSec/](https://locface.github.io/AgentSec/)

**Documentation:** [https://locface.github.io/AgentSec/docs/](https://locface.github.io/AgentSec/docs/)

**PyPI:** [https://pypi.org/project/agentsec-cli/](https://pypi.org/project/agentsec-cli/)

```yaml
- name: Security scan
  run: agentsec scan . --fail-on high --format sarif > results.sarif
```

## Supported Config Files

AgentSec automatically detects and scans these file types:

| Category | Files |
|----------|-------|
| MCP Servers | `mcp.json`, `mcp.yaml`, `mcp.toml`, `mcp-config.json` |
| Claude Desktop | `claude_desktop_config.json` |
| Cursor | `.cursorrules`, `.cursor/rules/*` |
| Codex | `codex.toml` |
| Cline | `cline_mcp`, `.clinerules` |
| Agents | `AGENTS.md`, `CLAUDE.md` |
| Package | `package.json`, `requirements.txt` |
| Infrastructure | `Dockerfile`, `docker-compose.yml` |
| Settings | `settings.json` |

## Rule Categories

| Category | Severity | Example Rules |
|----------|----------|---------------|
| Shell Execution | CRITICAL | MCP shell exec, insecure default commands |
| Filesystem Access | CRITICAL | Write access, broad paths, Docker socket |
| Exfiltration | CRITICAL | Network + filesystem, read repo + network |
| Prompt Injection | HIGH | Instruction injection, role override |
| OAuth / Auth | MEDIUM | Broad scopes, excessive permissions |
| Policy | LOW | Missing policy file |
| Dependencies | MEDIUM | Unpinned packages, vulnerable versions |

Full rule list: [agentsec/rules/additional.py](agentsec/rules/additional.py).

## Architecture

```
┌──────────────────────────────────────────────────┐
│                   agentsec CLI                    │
│           agentsec scan [options] [path]          │
└──────────────────────┬───────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────┐
│                  Scanner                          │
│  • Walks directory tree                          │
│  • Filters by file name patterns                 │
│  • Handles .gitignore / --include-hidden         │
└──────┬─────────────────────────────┬─────────────┘
       │                             │
┌──────▼──────────┐    ┌────────────▼─────────────┐
│    Parsers       │    │         Rules             │
│  • JSON          │    │  • base.py (patterns)     │
│  • YAML          │    │  • additional.py (extras) │
│  • TOML          │    • 41 rules                  │
│  • Markdown      │    • OWASP mapping             │
└──────┬──────────┘    └────────────┬──────────────┘
       │                             │
┌──────▼─────────────────────────────▼─────────────┐
│               Output Formatters                    │
│  terminal │ json │ markdown │ SARIF                │
└──────────────────────────────────────────────────┘
```

## Roadmap

- [ ] GitHub Action for PR comments
- [ ] Policy file support (`.agentsec.yaml`)
- [ ] Expanded rule set (targeting 60+ rules)
- [ ] HTML report output
- [ ] VS Code extension
- [ ] Windows support
- [ ] Performance optimization for large repositories
- [ ] More framework mappings (MITRE ATLAS, NIST)

## FAQ

### Does AgentSec send my data anywhere?

No. AgentSec runs entirely on your machine. No telemetry, no API calls, no network requests.

### Does it use an LLM?

No. All checks are implemented as static analysis rules. No LLM dependency, no API key needed.

### How is this different from Bandit or Semgrep?

Bandit and Semgrep are general-purpose security scanners. AgentSec is purpose-built for AI coding agent and MCP configurations — it understands the semantics of MCP server manifests, Claude Desktop configs, Cursor rules, and related formats out of the box.

### Can I use this in CI/CD?

Yes. The `--fail-on` flag and `--baseline` comparison are designed for CI/CD pipelines. SARIF output integrates with GitHub CodeQL.

### What version of SARIF do you support?

SARIF v2.1.0, the standard supported by GitHub CodeQL and most enterprise security tools.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and pull request workflow.

## Security

Report vulnerabilities privately. See [SECURITY.md](SECURITY.md) for our disclosure policy.

## Code of Conduct

This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md) v2.1.

## License

MIT — see [LICENSE](LICENSE).
