Metadata-Version: 2.4
Name: agentsentinel-cli
Version: 0.4.0
Summary: Security scanner and red-team CLI for AI agents — static probe, AI-driven red-teaming, MCP server auditing, and agent discovery
Project-URL: Homepage, https://github.com/jaydenaung/agentsentinel
Project-URL: Repository, https://github.com/jaydenaung/agentsentinel
License: Apache-2.0
Keywords: agent-security,ai-security,cli,devsecops,discovery,langchain,llm,mcp,openai,scanner
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: ai-probe
Requires-Dist: anthropic>=0.50.0; extra == 'ai-probe'
Requires-Dist: httpx>=0.24.0; extra == 'ai-probe'
Provides-Extra: all
Requires-Dist: anthropic>=0.50.0; extra == 'all'
Requires-Dist: httpx>=0.24.0; extra == 'all'
Requires-Dist: psutil>=5.9.0; extra == 'all'
Provides-Extra: connect
Requires-Dist: httpx>=0.24.0; extra == 'connect'
Provides-Extra: discover
Requires-Dist: httpx>=0.24.0; extra == 'discover'
Requires-Dist: psutil>=5.9.0; extra == 'discover'
Provides-Extra: mcp
Requires-Dist: httpx>=0.24.0; extra == 'mcp'
Provides-Extra: probe
Requires-Dist: httpx>=0.24.0; extra == 'probe'
Description-Content-Type: text/markdown

# agentsentinel-cli

One-command security scanner for AI agents and MCP servers. No server, no Docker, no setup.

```bash
pip install agentsentinel-cli
sentinel scan my_agent.py
sentinel mcp scan http://localhost:3000
```

---

## Install

```bash
pip install agentsentinel-cli

# With MCP server scanning (HTTP transport):
pip install "agentsentinel-cli[mcp]"

# With agent discovery (process + network scanning):
pip install "agentsentinel-cli[discover]"

# Everything:
pip install "agentsentinel-cli[all]"
```

---

## Commands

### `sentinel scan` — audit an agent file

Detects exfiltration paths, dangerous grants, hardcoded credentials, and more
from static analysis of Python agent files.

```bash
# Scan a single file
sentinel scan my_agent.py

# Scan a directory recursively
sentinel scan ./agents/

# Fail with exit code 1 if CRITICAL findings exist (for CI)
sentinel scan my_agent.py --fail-on CRITICAL

# Output JSON (for piping into other tools)
sentinel scan my_agent.py --format json

# Include live behavior data from a running AgentSentinel instance
sentinel scan my_agent.py --connect http://localhost:9000
```

**What it detects:**

| Rule | Severity | Description |
|------|----------|-------------|
| `EXFILTRATION_PATH` | CRITICAL | Agent holds internal-read AND external-write grants |
| `CODE_EXECUTION_GRANT` | CRITICAL | Agent holds bash/exec/shell grants |
| `HARDCODED_CREDENTIALS` | CRITICAL | API keys or secrets hardcoded in source |
| `SECRETS_ACCESS_GRANT` | HIGH | Agent holds runtime access to vaults or tokens |
| `PROMPT_INJECTION_VECTOR` | HIGH | Agent reads from web AND holds write grants |
| `LATERAL_MOVEMENT_PATH` | HIGH | Admin/IAM grants combined with infrastructure grants |
| `UNBOUNDED_FILE_ACCESS` | HIGH | Filesystem write grants with no scoped description |
| `PRIVILEGE_EXCESS` | HIGH | Write grants on a read-only described agent |
| `DANGEROUS_GRANTS` | HIGH | Agent holds dangerous tool grants |
| `TOOL_SPRAWL` | MEDIUM | Too many tools across too many categories |
| `UNDESCRIBED_WRITE_AGENT` | MEDIUM | Write grants with no agent description |
| `MISSING_RATE_LIMIT` | LOW | Dangerous grants without rate limit configuration |

---

### `sentinel mcp scan` — audit an MCP server

Connects to any MCP server, enumerates all exposed tools, and checks for
authentication gaps, exfiltration paths, code execution exposure, and input
validation weaknesses.

```bash
# Scan an HTTP MCP server
sentinel mcp scan http://localhost:3000

# Scan with authentication
sentinel mcp scan http://localhost:3000 --auth-header "Authorization: Bearer token"

# Scan a stdio-transport server (launch as subprocess)
sentinel mcp scan --stdio "python my_mcp_server.py"

# JSON output for CI pipelines
sentinel mcp scan http://localhost:3000 --format json

# Fail CI on CRITICAL findings
sentinel mcp scan http://localhost:3000 --fail-on CRITICAL
```

**What it detects:**

| Rule | Severity | Description |
|------|----------|-------------|
| `NO_AUTH` | CRITICAL | Server accepts tool enumeration with no credentials (HTTP) |
| `UNAUTH_DANGEROUS_EXEC` | CRITICAL | Dangerous tools callable without authentication (HTTP) |
| `EXFILTRATION_PATH` | CRITICAL | Server exposes internal-read AND external-write tools |
| `CODE_EXECUTION_TOOL` | CRITICAL | Server exposes code execution tools |
| `UNBOUNDED_INPUT` | HIGH | Tools accept unconstrained string inputs — injection surface |
| `TOOL_SPRAWL` | MEDIUM | Excessive tool count or category breadth |
| `VAGUE_TOOL_DESCRIPTIONS` | MEDIUM | Short/missing descriptions expand injection surface |
| `MISSING_RATE_LIMIT` | LOW | Dangerous tools present with no visible rate limiting |

See [`docs/mcp-scan-testing.md`](../docs/mcp-scan-testing.md) for test server examples
that trigger every finding.

---

### `sentinel discover` — find AI agents in your environment

```bash
sentinel discover                        # scan processes + network
sentinel discover --docker               # include Docker containers
sentinel discover --path ./agents        # scan a source directory
sentinel discover --subnet 10.0.0.0/24   # scan an internal subnet
sentinel discover --format json          # machine-readable output
```

---

## CI/CD integration

```yaml
# .github/workflows/security.yml
- name: Scan AI agents
  run: |
    pip install agentsentinel-cli
    sentinel scan ./agents/ --fail-on CRITICAL

- name: Scan MCP server
  run: |
    pip install "agentsentinel-cli[mcp]"
    sentinel mcp scan http://localhost:3000 --fail-on CRITICAL
```

---

## Tool detection (`sentinel scan`)

The scanner detects tools defined via:
- `@tool` decorator (LangChain)
- `@SentinelTool` decorator (AgentSentinel middleware)
- `BaseTool` / `StructuredTool` subclasses
- `Tool(name=...)` and `StructuredTool(name=...)` instantiations

---

## Requirements

- Python 3.10+
- No running server required for static scan or stdio MCP scan
- `httpx` required for HTTP MCP scanning: `pip install "agentsentinel-cli[mcp]"`
- `psutil` + `httpx` required for `sentinel discover`: `pip install "agentsentinel-cli[discover]"`
