agentsentinel-cli 0.4.0

Security scanner and red-team CLI for AI agents — static probe, AI-driven red-teaming, MCP server auditing, and agent discovery

agentsentinel-cli

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

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

---

Install

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.

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

# 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 for test server examples that trigger every finding.

---

sentinel discover — find AI agents in your environment

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

# .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]"