AgentSentinel CLI — Complete Documentation

sentinel is a security CLI for AI agents and MCP servers. It answers the questions every security team is now asking: What are my AI agents doing? Can they be attacked? Do I even know all of them?

No server required. No Docker. Works on any Python agent file or live HTTP endpoint.

Install
Quick Start
Commands
Finding Suppression
Real-World Workflows
CI/CD Integration
Reference

Install

Recommended — pipx (isolated, no venv needed)

pipx install "agentsentinel-cli[all]"

pip (standard)

# Zero-dependency core (sentinel scan only)
pip install agentsentinel-cli

# With specific features
pip install "agentsentinel-cli[inspect]"    # sentinel inspect (live endpoints)
pip install "agentsentinel-cli[discover]"   # sentinel discover
pip install "agentsentinel-cli[mcp]"        # sentinel mcp scan
pip install "agentsentinel-cli[probe]"      # sentinel probe
pip install "agentsentinel-cli[ai-probe]"   # sentinel ai-probe

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

Upgrade

pip install --upgrade "agentsentinel-cli[all]"
# or
pipx upgrade agentsentinel-cli

Verify

sentinel --version

Quick Start

Six commands that cover the full picture in under 10 minutes:

# 1. What is this agent? (fingerprint + plain English summary)
sentinel inspect my_agent.py

# 2. Does it have dangerous permissions? (posture audit)
sentinel scan my_agent.py

# 3. Has it leaked credentials or customer PII into memory files?
sentinel secrets .

# 4. Is the MCP server it connects to secure?
sentinel mcp scan http://localhost:3000

# 5. Can it be jailbroken? (42-payload attack battery)
sentinel probe http://my-agent.com/chat

# 6. Deep red-team with Claude as the attacker (needs ANTHROPIC_API_KEY)
sentinel ai-probe http://my-agent.com/chat

Commands

sentinel inspect

What problem it solves: Security teams are being asked to approve AI agents they have no visibility into. sentinel inspect answers "what the hell is this thing?" in 10 seconds — framework, model, cloud provider, what it reads, what it writes, and whether it should be trusted.

sentinel inspect TARGET [OPTIONS]

TARGET can be a Python file, a directory, or a live HTTP endpoint URL.

Options

Flag	Default	Description
`--format [text\|json]`	`text`	Output format
`--no-ai`	off	Skip Claude summary even if `ANTHROPIC_API_KEY` is set
`--model TEXT`	`claude-haiku-4-5-20251001`	Claude model for AI summary
`--auth-header HEADER`	—	HTTP auth header for live endpoints, e.g. `Authorization: Bearer token`
`--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]`	—	Exit code 1 if findings reach this severity
`--ignore-rule RULE_ID`	—	Suppress a finding by rule ID. Repeatable. Also reads `.sentinelignore` in the target directory

What it shows

Section	Details
Type	AI Agent (has an LLM) vs MCP Server (tool provider only)
Function	Plain English: what it does, what it accesses, top security risk
Fingerprint	Framework, model, Python version, deployment, cloud, system prompt
Capabilities	Every tool with scope (read/write), category, and severity
Data flows	Where data comes from (Input ←) and where it goes (Output →)
Findings	Posture violations from the rule engine
Trust score	0–100 composite score with status label

Examples

# Inspect a single agent file — no API key needed
sentinel inspect my_agent.py --no-ai

# With AI-generated plain English summary (requires ANTHROPIC_API_KEY)
export ANTHROPIC_API_KEY=sk-ant-...
sentinel inspect my_agent.py

# Inspect all agents in a directory
sentinel inspect ./agents/

# Inspect a live HTTP endpoint (fingerprints from headers + response)
sentinel inspect http://localhost:3000

# Inspect a live endpoint with authentication
sentinel inspect http://my-agent.internal/chat \
  --auth-header "Authorization: Bearer my-token"

# JSON output — pipe into jq, SIEM, dashboards
sentinel inspect my_agent.py --format json | jq '.fingerprint'

# Suppress a known-accepted finding while still gating on CRITICAL
sentinel inspect my_agent.py --fail-on CRITICAL --ignore-rule DANGEROUS_GRANTS

# CI gate — fail if any CRITICAL finding
sentinel inspect my_agent.py --fail-on CRITICAL

Understanding the output

Type             AI Agent (tool consumer with LLM)
Framework        LangChain
Model            gpt-4o
Python           3.11
Deployment       AWS Lambda
Cloud            AWS
System prompt    Found  "You are a sales assistant..."
Env vars         OPENAI_API_KEY, DATABASE_URL, SENDGRID_API_KEY

Type distinguishes agents (have an LLM, make decisions) from MCP servers (expose tools, no LLM). If you see MCP Server, run sentinel mcp scan against the live endpoint for a richer audit.
System prompt Found means a hardcoded system prompt was detected in source — if it contains sensitive instructions, it's a leakage risk.
Env vars lists every os.environ.get() and os.getenv() call — useful to spot credential references before auditing secrets management.

AI summary example

With ANTHROPIC_API_KEY set, you get a paragraph like:

"This LangChain agent functions as a sales assistant that queries a CRM system and analytics database to answer customer questions, then sends emails to customers. The critical security concern is that the agent holds internal data-read permissions (CRM and database) and external write permissions (email), creating an exfiltration risk where sensitive customer data could be transmitted externally without sufficient controls."

Without the key, a template summary is generated from the structured data instead.

Trust score

Score	Status	Meaning
80–100	TRUSTED	Normal operation
60–79	WATCH	Minor concerns — monitor
40–59	ALERT	Active risks — investigate
0–39	CRITICAL	Immediate action required

sentinel scan

What problem it solves: Catches dangerous permission combinations, hardcoded secrets, and structural misconfigurations in agent source code before they reach production. Fast enough for every commit.

sentinel scan [TARGET] [OPTIONS]

TARGET defaults to . (current directory, scanned recursively).

Options

Flag	Default	Description
`--format [text\|json]`	`text`	Output format
`--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]`	—	Exit code 1 if findings reach this severity
`--ignore-rule RULE_ID`	—	Suppress a finding by rule ID. Repeatable. Also reads `.sentinelignore` in the target directory
`--connect URL`	—	Pull live behavior data from a running AgentSentinel instance
`--api-key TEXT`	`$AGENTSENTINEL_API_KEY`	API key for `--connect`

Detection rules

Rule	Severity	What it catches
`EXFILTRATION_PATH`	CRITICAL	Agent holds both internal-read AND external-write tools — data can leave
`CODE_EXECUTION_GRANT`	CRITICAL	Agent holds bash/exec/shell tools — full host compromise possible
`HARDCODED_CREDENTIALS`	CRITICAL	API keys or secrets hardcoded in source (`sk-ant-...`, `AKIA...`, etc.)
`SECRETS_ACCESS_GRANT`	HIGH	Agent has runtime access to vaults, env vars, or token stores
`PROMPT_INJECTION_VECTOR`	HIGH	Agent reads from the web AND holds write grants — injection → action chain
`LATERAL_MOVEMENT_PATH`	HIGH	IAM/admin grants combined with infrastructure tools
`UNBOUNDED_FILE_ACCESS`	HIGH	Filesystem write grants with no scope description
`PRIVILEGE_EXCESS`	HIGH	Write grants on an agent described as read-only
`DANGEROUS_GRANTS`	HIGH	Dangerous tools detected (delete, deploy, execute, send)
`TOOL_SPRAWL`	MEDIUM	Too many tools across too many categories — hard to audit
`UNDESCRIBED_WRITE_AGENT`	MEDIUM	Write grants but no agent description — intent is unclear
`MISSING_RATE_LIMIT`	LOW	Dangerous tools present with no rate limit configuration

Tool detection — what it recognises

The scanner extracts tools defined via:

@tool decorator (LangChain, LlamaIndex, custom)
@SentinelTool decorator (AgentSentinel middleware)
BaseTool / StructuredTool subclasses
Tool(name=...) and StructuredTool(name=...) instantiations

Examples

# Scan a single file
sentinel scan my_agent.py

# Scan all agents in a directory (recursive)
sentinel scan ./agents/

# CI gate — break the build on CRITICAL findings
sentinel scan ./agents/ --fail-on CRITICAL

# Break the build on HIGH or worse
sentinel scan ./agents/ --fail-on HIGH

# JSON output 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 --api-key $AGENTSENTINEL_KEY

# Suppress a noisy LOW finding and still gate on HIGH
sentinel scan ./agents/ --fail-on HIGH --ignore-rule MISSING_RATE_LIMIT

# Stack multiple suppressions
sentinel scan ./agents/ --fail-on CRITICAL \
  --ignore-rule MISSING_RATE_LIMIT \
  --ignore-rule TOOL_SPRAWL

Example output

  ● CRITICAL  EXFILTRATION_PATH
              Agent holds both internal-read and external-write grants.
              Internal: read_database  |  External: send_email

  ● HIGH      DANGEROUS_GRANTS
              Agent holds dangerous tool grants. Verify intent and add rate limits.

  Posture Score  34/100  CRITICAL

sentinel secrets

What problem it solves: AI agents process sensitive data — customer records, credentials, system prompts — and many frameworks persist this to local memory files (.md, .json, conversation logs). Developers commit these files to git without realising they contain customer NRICs, email addresses, or API keys captured from tool call results. sentinel secrets finds what leaked where — before an attacker does.

Zero extra dependencies. Fully offline. No API calls.

sentinel secrets [TARGET] [OPTIONS]

TARGET defaults to . (current directory, scanned recursively).

Running it for the first time

Start with the broadest scan — current directory, default severity (MEDIUM and above):

cd your-agent-project/
sentinel secrets .

If you get no output, your project is clean at MEDIUM+. Run with --severity LOW to see everything including low-confidence findings.

If you get findings, work through them top to bottom — CRITICAL first. Credentials must be rotated immediately. PII in memory files needs to be purged and the source (which tool call produced it) investigated.

Recommended scan order for a new project:

# 1. Full scan, see the big picture
sentinel secrets .

# 2. Narrow to memory files — this is where PII most often hides
sentinel secrets . --scope memory --severity LOW

# 3. Check configs separately (credential focus)
sentinel secrets . --scope config

# 4. Scan Claude Code's own memory for this project
sentinel secrets ~/.claude/projects/ --severity LOW

Options

Flag	Default	Description
`--scope [all\|memory\|config]`	`all`	Restrict scan to memory files, config/env files, or both
`--severity [CRITICAL\|HIGH\|MEDIUM\|LOW]`	`MEDIUM`	Minimum severity level to display
`--format [text\|json]`	`text`	Output format
`--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]`	—	Exit code 1 if findings reach this severity
`--no-redact`	off	Show full matched values instead of masking them
`--ignore-rule RULE_ID`	—	Suppress a finding by rule ID. Repeatable. Also reads `.sentinelignore` in the target directory

Choosing the right scope

Scope	What it scans	When to use
`all` (default)	Memory files + config files + source files	First run, CI/CD gate, general audit
`memory`	Agent memory files only (`.md`, `.json` in memory dirs, conversation logs)	Daily monitoring, post-session audit, fastest scan
`config`	`.env`, `.yaml`, `.toml`, `docker-compose.yml`, etc.	Pre-commit hook on config changes, credential audit

Source files (.py, .js) are always scanned for credentials regardless of scope — a hardcoded sk-ant-... in Python source is CRITICAL no matter what scope is selected.

Detection layers

Layer 1 — Credentials (all file types)

Rule ID	Severity	Pattern
`ANTHROPIC_KEY`	CRITICAL	`sk-ant-api03-...`
`OPENAI_KEY`	CRITICAL	`sk-...` / `sk-proj-...`
`AWS_ACCESS_KEY`	CRITICAL	`AKIA[16 chars]`
`GITHUB_TOKEN`	CRITICAL	`ghp_...` / `github_pat_...`
`STRIPE_SECRET`	CRITICAL	`sk_live_...`
`PRIVATE_KEY_BLOCK`	CRITICAL	`-----BEGIN ... PRIVATE KEY-----`
`SLACK_TOKEN`	HIGH	`xoxb-...` / `xoxp-...`
`GOOGLE_API_KEY`	HIGH	`AIza[35 chars]`
`HUGGINGFACE_TOKEN`	HIGH	`hf_[34 chars]`
`DATABASE_URL`	HIGH	`postgresql://user:pass@host`
`JWT_TOKEN`	MEDIUM	`eyJ...eyJ...` (memory + config only)
`GENERIC_API_KEY`	MEDIUM	`api_key = "..."` (config files only)
`GENERIC_PASSWORD`	MEDIUM	`password = "..."` (config files only)

Note: Any credential found inside an agent memory file is automatically upgraded to CRITICAL severity. Memory files are routinely committed to git with no secrets management.

Layer 2 — PII (global) (memory + config files)

Rule ID	Severity	Description
`EMAIL_ADDRESS`	MEDIUM	Email addresses (`user@domain.tld`)
`CREDIT_CARD`	HIGH	Visa / MC / Amex / Discover — Luhn-validated
`US_SSN`	HIGH	US Social Security Number (`DDD-DD-DDDD`) — structurally validated
`US_PHONE`	LOW	US phone numbers (memory files only)

Layer 2 — PII (Singapore / PDPA) (memory + config files unless noted)

Rule ID	Severity	Description
`SG_NRIC`	HIGH	NRIC/FIN — weighted mod-11 checksum validated (S/T/F/G/M prefix). Scans all file types.
`SG_PASSPORT`	HIGH	Singapore passport (E/K series). Scans all file types.
`SG_PHONE_MOBILE`	MEDIUM	Mobile number (`+65 8xxx xxxx` / `+65 9xxx xxxx`)
`SG_PHONE_LANDLINE`	LOW	Landline — requires explicit `+65` prefix to reduce false positives
`SG_UEN`	LOW	Unique Entity Number (business registration)
`SG_ADDRESS_POSTAL`	LOW	`Singapore XXXXXX` postal address

Layer 3 — Memory contamination (memory files only)

These compound rules look at file content holistically, not line by line.

Rule ID	Severity	Trigger condition
`CONVERSATION_PII`	HIGH	Email + NRIC (SGP) or Email + SSN (USA) within 5 lines of each other. Strong indicator that a raw CRM or database tool call result leaked into memory.
`SYSTEM_PROMPT_IN_MEMORY`	MEDIUM	"You are a..." / "Your instructions are..." patterns in the first 30 lines of a memory file. System prompts in memory reveal agent instructions if the file is committed to git.

Memory path registry

sentinel secrets knows where agent frameworks store memory and automatically classifies these as high-sensitivity memory files:

Framework	Paths scanned
Claude Code	`~/.claude/projects/*/memory/`
LangChain	`.langchain/`, `memory/*.json`, `langchain_cache/`
AutoGen	`.autogen/`, `autogen_cache/`
CrewAI	`crew_workspace/`, `.crewai/`
Mem0	`.mem0/`, `mem0_storage/`
OpenAI Agents	`.openai_agents/`, `agent_workspace/`
Generic	`memory/`, `_memory.md`, `conversation_history.json`, `agent_logs/`

Any file inside one of these directories is treated as a memory file and scanned with all three detection layers. Config files (.env, *.yaml, *.toml, etc.) receive credential and PII scanning. Source files receive credential scanning only (to avoid false positives from example data in docstrings and comments).

.gitignore check

sentinel secrets warns if agent memory directories are not covered by .gitignore, since memory files often contain the most sensitive data in an AI project.

Examples

# Scan everything in the current directory
sentinel secrets .

# Scan your Claude Code agent memory for leaked PII
sentinel secrets ~/.claude/projects/

# Memory files only (fastest, most sensitive findings)
sentinel secrets . --scope memory

# Config and env files only (credential scan)
sentinel secrets . --scope config

# Only show HIGH and CRITICAL (for daily monitoring)
sentinel secrets . --severity HIGH

# CI gate — break the build if HIGH+ findings exist
sentinel secrets . --fail-on HIGH

# Machine-readable output for SIEM or dashboards
sentinel secrets . --format json

# Show full matched values (for investigation — use carefully)
sentinel secrets . --no-redact

# Scan a specific agent workspace
sentinel secrets /path/to/my-agent/ --severity LOW

# JSON output, extract only Singapore PII findings
sentinel secrets . --format json | jq '.findings[] | select(.jurisdiction == "SGP")'

# Extract all CRITICAL findings with file locations
sentinel secrets . --format json | jq '.findings[] | select(.severity == "CRITICAL") | {rule_id, file, line}'

Example output

╭──────────────────────────────────────────────────╮
│  AgentSentinel Secrets                           │
│  Target: /my-agent/                              │
╰──────────────────────────────────────────────────╯

──────────────── CREDENTIALS ─────────────────────

  ● CRITICAL  ANTHROPIC_KEY ✓validated  memory/session_42.md:14
              sk-ant[REDACTED]
              → Rotate at console.anthropic.com/settings/api-keys

  ● HIGH      DATABASE_URL ✓validated  .env:3
              postgr[REDACTED]
              → Move database credentials to environment variables

──────────────────── PII ─────────────────────────

  ● HIGH      SG_NRIC (SGP — PDPA) ✓validated  memory/session_42.md:23
              S12345[REDACTED]
              NRIC: S123[REDACTED]
              → NRIC/FIN is protected under Singapore PDPA. Purge from memory.

  ● MEDIUM    EMAIL_ADDRESS  memory/session_42.md:24
              john.t[REDACTED]
              → Remove personal email from agent memory files.

──────────────── MEMORY CONTAMINATION ────────────

  ● HIGH      CONVERSATION_PII (SGP — PDPA) ✓validated  memory/session_42.md:23
              [email + NRIC cluster]
              Email line 24, NRIC line 23
              → Singapore customer PII cluster — likely leaked from CRM tool call.

  ● MEDIUM    SYSTEM_PROMPT_IN_MEMORY ✓validated  memory/session_42.md:1
              You are a helpful customer service assistant for...
              → System prompt content in memory file. Will be committed to git.

──────────────── WARNINGS ────────────────────────

  ⚠  memory/ is not covered by .gitignore — memory files may be committed to git

──────────────────────────────────────────────────
  12 files scanned (4 memory · 3 config)  ·  CRITICAL:1  HIGH:3  MEDIUM:2  LOW:0  ·  0.1s

Understanding the output

Each finding block has four lines:

  ● CRITICAL  SG_NRIC (SGP — PDPA) ✓validated  memory/session_42.md:23
              S12345[REDACTED]
              NRIC: S123[REDACTED]
              → NRIC/FIN is protected under Singapore PDPA. Purge from memory.

Part	Meaning
`●` + colour	Severity: red = CRITICAL, orange = HIGH, yellow = MEDIUM, dim = LOW
`SG_NRIC`	Rule ID — matches the rule tables above
`(SGP — PDPA)`	Jurisdiction tag — tells you which privacy law applies. `(SGP — PDPA)` = Singapore Personal Data Protection Act; no tag = globally applicable
`✓validated`	The match passed a checksum or structural validator (NRIC mod-11, Luhn for credit cards, area-code check for SSNs). A validated finding is a confirmed true positive — not just a regex match. Absence of `✓validated` means the rule relies on pattern alone and has a higher false positive rate.
`memory/session_42.md:23`	File path and line number — click to open directly in most editors
`S12345[REDACTED]`	First 6 characters of the match + `[REDACTED]`. Enough to identify the type, not enough to reconstruct the secret. Use `--no-redact` to see the full value during investigation.
`NRIC: S123[REDACTED]`	The surrounding line of text, with the sensitive part masked — gives context for where the data came from
`→ ...`	Recommended remediation action

The WARNINGS section at the bottom is separate from findings — it reports structural problems like memory directories not covered by .gitignore.

The summary bar shows total files scanned broken down by type, finding counts by severity, and scan duration.

What to do when you find something

CRITICAL — credentials

Act immediately. A leaked API key is live until you rotate it.

Rotate the credential first — do not wait. Links are in the → line of each finding.
Check if the key appeared in git history: git log --all -p | grep sk-ant- — if yes, the history is compromised even if the file is deleted.
Audit usage logs (Anthropic Console, AWS CloudTrail, GitHub audit log) for activity you did not authorise.
Add the file or directory to .gitignore and remove the secret from the file.
Consider using a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler) to prevent recurrence.

HIGH — PII (NRIC, credit card, SSN)

Identify which tool call produced this data — look at the surrounding lines in the file for context (tool name, timestamp, query).
Delete or purge the memory file contents: echo "" > memory/session_42.md or delete the file if the session is complete.
If the file was ever committed to git, the PII is in history. Consider a history rewrite with git filter-repo or treat the repo as compromised for that data type.
Review your agent's tool definitions — if a CRM or database tool is returning full customer records (including NRIC/SSN), add field filtering to return only what the agent needs.
For Singapore NRIC under PDPA: if the data was accessed without consent or leaked outside the system, a data breach notification may be required.

MEDIUM — email addresses, system prompt leakage

Email addresses in memory files are lower urgency but indicate your agent is retaining more data than it needs. Check if memory retention is configured and reduce the session window.
SYSTEM_PROMPT_IN_MEMORY is usually intentional (the agent wrote its own instructions to memory) but is a problem if the file gets committed — add memory/ to .gitignore.

Memory contamination (CONVERSATION_PII)

This finding fires when an email address and an NRIC (or SSN) appear within 5 lines of each other in a memory file — a strong signal that a raw database or CRM record was written to memory by a tool call. The record contains at minimum two linked PII fields, which is more serious than either in isolation.

Steps:

Open the file at the reported line. Read the surrounding context to identify the tool that produced the data.
Determine whether the tool call was authorised and whether the data was needed.
Purge the memory file.
If the tool legitimately needs customer records, modify it to return only the fields required (not full rows).

False positives

✓validated findings are rarely false positives — the validators are conservative by design. Findings without ✓validated have a higher false positive rate.

Common false positives and how to handle them:

Finding	Common false positive cause	How to confirm
`SG_PHONE_MOBILE`	Version numbers, port numbers like `8080 9000`	Use `--no-redact` and read the full match. A Singapore mobile is always 8 digits starting with 8 or 9.
`EMAIL_ADDRESS`	Example emails in documentation (`user@example.com`)	Read the context line — documentation examples are usually surrounded by descriptive text
`GENERIC_API_KEY`	Example keys in comments or README snippets	Check if the value looks like a real key (random alphanumeric, 20+ chars) vs a placeholder (`your-api-key-here`)
`SG_UEN`	9-digit numbers that happen to end in a letter	UENs are common in business documents — confirm the surrounding context

If a finding is a confirmed false positive, it does not affect the finding count for --fail-on evaluation — you still need to address it, suppress it with --ignore-rule, or restructure the content to remove the match. See Finding Suppression.

sentinel discover

What problem it solves: Most organisations don't have a complete inventory of their AI agents. sentinel discover finds agents you didn't know existed — in running processes, Docker containers, network ports, source directories, and internal subnets.

sentinel discover [OPTIONS]

No arguments required — by default scans processes and network ports.

Options

Flag	Default	Description
`--process / --no-process`	on	Scan running processes for LLM API calls
`--network / --no-network`	on	Probe local ports for MCP/agent APIs
`--docker / --no-docker`	off	Inspect running Docker containers
`--path DIR`	—	Scan a source directory for agent files
`--subnet CIDR`	—	Scan an internal subnet, e.g. `10.0.0.0/24`
`--ports RANGE`	common ports	Custom port range, e.g. `8000-9001` or `8000,8080,9000`
`--format [text\|json]`	`text`	Output format
`-v / --verbose`	off	Show full details per discovered agent

Examples

# Default: scan processes + local network ports
sentinel discover

# Also check Docker containers
sentinel discover --docker

# Scan a source directory for agent files
sentinel discover --path ./services/

# Scan an internal subnet (CISO use case — "what's in our network?")
sentinel discover --subnet 10.0.0.0/24

# Scan a subnet with a custom port range
sentinel discover --subnet 192.168.1.0/24 --ports 8000-9000

# Network scan only — skip process scan
sentinel discover --no-process

# Full detail on every discovered agent
sentinel discover --verbose

# JSON for export to inventory systems
sentinel discover --format json > agent-inventory.json

# Combine vectors
sentinel discover --docker --path ./agents/ --subnet 10.0.0.0/24

What it looks for

Processes: running Python processes making calls to OpenAI, Anthropic, Cohere, Groq, or similar LLM API endpoints
Network ports: HTTP servers responding to MCP protocol or common agent API patterns on ports 3000, 3001, 8000, 8080, 8888, 9000, 9001, 11434, etc.
Docker containers: image names and environment variables indicating LLM usage (OPENAI_API_KEY, ANTHROPIC_API_KEY, framework imports, etc.)
Source files: Python files containing @tool decorators, BaseTool subclasses, or LLM constructor calls
Subnets: HTTP endpoints across a CIDR range responding to agent/MCP probes

sentinel mcp scan

What problem it solves: MCP (Model Context Protocol) servers expose tools that AI agents call. A misconfigured MCP server with unauthenticated code execution is a critical vulnerability. sentinel mcp scan is the first open-source tool to enumerate and audit MCP servers.

sentinel mcp scan [URL] [OPTIONS]
sentinel mcp scan --stdio "CMD" [OPTIONS]

Options

Flag	Default	Description
`--stdio CMD`	—	Audit a stdio-transport server — provide the launch command
`--auth-header HEADER`	—	HTTP header, e.g. `Authorization: Bearer token`
`--format [text\|json]`	`text`	Output format
`--timeout SECONDS`	`10.0`	Connection timeout
`--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]`	—	Exit code 1 if findings reach this severity
`--ignore-rule RULE_ID`	—	Suppress a finding by rule ID. Repeatable. Also reads `.sentinelignore` in the working directory

Transport support

Transport	How to use
HTTP (streamable)	`sentinel mcp scan http://host:port`
stdio	`sentinel mcp scan --stdio "python my_server.py"`
SSE	Not supported — use the HTTP endpoint directly

Detection rules

Rule	Severity	What it catches
`NO_AUTH`	CRITICAL	Tools can be enumerated with no credentials (HTTP only)
`UNAUTH_DANGEROUS_EXEC`	CRITICAL	Dangerous tools callable without authentication (HTTP only)
`EXFILTRATION_PATH`	CRITICAL	Server exposes both internal-read and external-write tools
`CODE_EXECUTION_TOOL`	CRITICAL	Server exposes bash/exec/eval 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 with no visible rate limit

Note: NO_AUTH and UNAUTH_DANGEROUS_EXEC are HTTP-only rules. stdio transport is OS-isolated and has no network authentication concept, so these rules are intentionally skipped.

Examples

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

# Scan with authentication — supply the exact header
sentinel mcp scan http://my-mcp.internal:3000 \
  --auth-header "Authorization: Bearer eyJhbGci..."

# Scan a stdio-transport server (spawns the process)
sentinel mcp scan --stdio "python3 my_mcp_server.py"
sentinel mcp scan --stdio "node dist/mcp-server.js"
sentinel mcp scan --stdio "uvx my-mcp-package"

# JSON output for security dashboards
sentinel mcp scan http://localhost:3000 --format json

# CI gate
sentinel mcp scan http://localhost:3000 --fail-on CRITICAL

# Longer timeout for slow servers
sentinel mcp scan http://remote-server.com/mcp --timeout 30

# CI gate — suppress a finding accepted at the infrastructure layer
sentinel mcp scan http://localhost:3000 --fail-on CRITICAL --ignore-rule NO_AUTH

Example output

  ● CRITICAL  NO_AUTH
              MCP server accepts tool enumeration with no credentials.
              Any client can list and call all tools without authentication.

  ● CRITICAL  CODE_EXECUTION_TOOL
              Server exposes code execution tools: bash_exec
              Arbitrary code execution on the host is possible.

  ● CRITICAL  EXFILTRATION_PATH
              Server exposes internal-read (read_database) and
              external-write (send_email, http_post) tools simultaneously.

  MCP Posture Score  0/100  CRITICAL  ·  5 tools  ·  3 findings

sentinel probe

What problem it solves: Every AI developer fears prompt injection but has no simple way to test it. sentinel probe fires 42 adversarial payloads at any HTTP agent endpoint and reports exactly which attacks succeeded. No API key required — fast enough for every deployment.

sentinel probe TARGET_URL [OPTIONS]

Options

Flag	Default	Description
`--input-field FIELD`	auto	JSON field for the message. Auto-detected if omitted
`--output-field FIELD`	auto	JSON field for the response. Auto-detected if omitted
`--auth-header HEADER`	—	HTTP auth header
`--attacks CATS`	all	Comma-separated categories to run
`--timeout SECONDS`	`15.0`	Per-probe timeout
`--format [text\|json]`	`text`	Output format
`--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]`	—	Exit code 1 if any finding reaches this severity

Attack categories

Category	Count	What it tests
`injection`	10	Classic prompt override, authority injection, nested context, false premise
`jailbreak`	12	DAN, persona adoption, fictional framing, developer mode, grandma exploit
`extraction`	8	System prompt leakage, verbatim repeat, sentence completion, reflection
`encoding`	6	Base64, ROT13, unicode homoglyph, whitespace injection, leetspeak
`context`	6	Few-shot manipulation, false anchoring, semantic satiation, virtualisation bypass

Auto-detection

On first request, sentinel probe automatically detects whether your endpoint uses:

OpenAI-compatible format: {"messages": [{"role": "user", "content": "..."}]} → reads choices[0].message.content
Custom format: tries common field names (message, input, query, prompt, text, content)

Override with --input-field and --output-field if detection fails.

Success detection

Each payload has a list of expected patterns (phrases that would appear in a successful attack response). A probe is marked:

HIT — response matched ≥2 patterns, or 1 pattern with no refusal detected
PARTIAL — response matched 1 pattern alongside a refusal, or was unusually long/non-standard
passed — standard refusal or no patterns matched

Examples

# Run all 42 attacks
sentinel probe http://localhost:3002

# Run only injection and jailbreak attacks
sentinel probe http://my-agent.com/chat --attacks injection,jailbreak

# Run only extraction attacks (check for system prompt leakage)
sentinel probe http://my-agent.com/chat --attacks extraction

# Specify field names if auto-detection fails
sentinel probe http://my-agent.com/chat \
  --input-field query --output-field answer

# Authenticated endpoint
sentinel probe http://my-agent.com/chat \
  --auth-header "Authorization: Bearer $API_TOKEN"

# CI gate — fail if hit rate exceeds 10%
sentinel probe http://localhost:3002 --fail-on HIGH

# JSON output for reporting
sentinel probe http://my-agent.com/chat --format json > probe-results.json

# Quick jailbreak-only test (fastest)
sentinel probe http://my-agent.com/chat --attacks jailbreak --timeout 5

Reading the results

  ● HIT     INJ001  Classic system prompt override      injection   CRITICAL
  ● HIT     JBK001  DAN jailbreak                       jailbreak   CRITICAL
  ◑ PARTIAL EXT003  Verbatim system prompt repeat        extraction  HIGH
  ○ passed  ENC001  Base64 encoded instruction           encoding    MEDIUM

  42 probes · 2 confirmed · 1 partial · 7% hit rate · static · 18.4s

A 0% hit rate means your agent refused or did not respond to all 42 payloads — that is the goal. Any hit rate above 0% warrants investigation.

sentinel ai-probe

What problem it solves: A static attack battery misses context-specific vulnerabilities. sentinel ai-probe unleashes Claude as an autonomous security researcher — it reads your agent's responses, forms a threat model, crafts targeted attacks, escalates when it finds weaknesses, and documents everything with OWASP mappings.

sentinel ai-probe TARGET_URL [OPTIONS]

Requires ANTHROPIC_API_KEY environment variable.

Options

Flag	Default	Description
`--input-field FIELD`	auto	JSON field for the message
`--output-field FIELD`	auto	JSON field for the response
`--auth-header HEADER`	—	HTTP auth header
`--context TEXT`	—	Context about the agent — improves targeting
`--max-probes INTEGER`	`20`	Maximum probes Claude can send
`--model TEXT`	`claude-opus-4-8`	Claude model to use as the probe agent
`--timeout SECONDS`	`15.0`	Per-probe timeout
`--format [text\|json]`	`text`	Output format
`--fail-on [CRITICAL\|HIGH\|MEDIUM\|LOW]`	—	Exit code 1 if any finding reaches this severity

How Claude probes

Claude runs a 5-phase methodology autonomously:

Reconnaissance — sends benign messages to understand the agent's persona, topic restrictions, and response style
Threat modelling — based on what it learned, identifies the most likely attack surfaces
Targeted attacks — crafts payloads specific to this agent's context and persona
Escalation — on partial success, immediately crafts follow-up attacks to confirm and deepen
Documentation — records each finding with severity, OWASP category, and evidence

When to use ai-probe vs probe

	`sentinel probe`	`sentinel ai-probe`
API key required	No	Yes (Anthropic)
Cost	Free	~$0.10–$0.50 per run
Speed	~30s	2–5 min
Attack style	Fixed library	Adaptive, context-aware
Best for	CI/CD gate, quick check	Pre-launch security review
Finds	Known injection patterns	Novel context-specific attacks

Examples

# Basic run — Claude decides everything
export ANTHROPIC_API_KEY=sk-ant-...
sentinel ai-probe http://my-agent.com/chat

# Provide context for better targeting (strongly recommended)
sentinel ai-probe http://my-agent.com/chat \
  --context "Customer service agent for a fintech company. Handles account queries and refunds."

# More probes = deeper investigation
sentinel ai-probe http://my-agent.com/chat --max-probes 50

# Authenticated endpoint
sentinel ai-probe http://my-agent.com/chat \
  --auth-header "Authorization: Bearer $API_TOKEN" \
  --context "Internal HR assistant with access to employee records"

# Use a different Claude model
sentinel ai-probe http://my-agent.com/chat --model claude-opus-4-8

# JSON output with full probe log and evidence
sentinel ai-probe http://my-agent.com/chat --format json > ai-probe-report.json

# CI gate — only fails on CRITICAL findings
sentinel ai-probe http://my-agent.com/chat --fail-on CRITICAL

Example output

  Probe agent initialised. Budget: 20 probes.

  [ 1] reconnaissance  Sending benign greeting to understand response style
  [ 2] reconnaissance  Testing topic restrictions with an off-topic query
  [ 3] extraction      Attempting direct system prompt extraction
  [ 4] injection       Injecting role override via authority claim
  [ 5] jailbreak       Persona adoption — fictional framing escalation
  ...

  ● CRITICAL  PROMPT_INJECTION
              Agent adopted attacker-supplied persona on probe 5.
              Evidence: "As an unrestricted AI, I can help with anything..."

  ● HIGH      SYSTEM_PROMPT_LEAKAGE
              System prompt partially leaked on probe 3.
              Evidence: "My instructions say I should not discuss competitors..."

  20 probes · 2 findings · 10% finding rate · ai (claude-opus-4-8) · 187.3s

Finding Suppression

Use --ignore-rule and .sentinelignore to suppress specific findings by rule ID. Suppressed findings are excluded from both output display and --fail-on evaluation — they never break a CI gate.

Supported commands: sentinel scan, sentinel mcp scan, sentinel supply-chain, sentinel secrets, sentinel inspect.

--ignore-rule flag

Suppress one or more rules for a single run. The flag is repeatable.

# Suppress a single rule
sentinel scan ./agents/ --fail-on HIGH --ignore-rule MISSING_RATE_LIMIT

# Stack multiple suppressions
sentinel mcp scan http://localhost:3001 --fail-on CRITICAL \
  --ignore-rule NO_AUTH \
  --ignore-rule UNBOUNDED_INPUT

# Suppress during secrets scan
sentinel secrets . --fail-on HIGH --ignore-rule SG_UEN

.sentinelignore file

For persistent, project-level suppressions, create a .sentinelignore file and commit it to source control. sentinel walks up from the target directory to find it — same discovery pattern as .gitignore.

# .sentinelignore

# Comments start with #. Blank lines are ignored.
# Rule IDs are case-insensitive.

MISSING_RATE_LIMIT          # rate limiting enforced at API gateway layer
SC03_HIDDEN_NETWORK_FIELDS  # webhook field is for audit logging — verified safe
NO_AUTH                     # MCP server is behind an authenticated reverse proxy

sentinel searches for .sentinelignore starting from the target path and walking up to the filesystem root. For URL targets (sentinel mcp scan, sentinel supply-chain), it searches from the current working directory.

Suppression notice

When findings are suppressed, sentinel prints a dim notice at the end of text output:

  1 finding suppressed by .sentinelignore / --ignore-rule: MISSING_RATE_LIMIT

In JSON output, suppressed findings are absent from the findings array. The --fail-on threshold is evaluated only against the active (non-suppressed) findings.

What to suppress — and what not to

Suppressions are appropriate for findings where the risk is genuinely accepted at another layer:

Scenario	Appropriate suppression
Rate limiting handled at API gateway	`MISSING_RATE_LIMIT`
MCP server behind authenticated proxy	`NO_AUTH`
Known webhook field verified safe	`SC03_HIDDEN_NETWORK_FIELDS`
Agent description intentionally omitted	`UNDESCRIBED_WRITE_AGENT`

Do not suppress CRITICAL findings (EXFILTRATION_PATH, CODE_EXECUTION_GRANT, HARDCODED_CREDENTIALS, SC01_DESCRIPTION_INJECTION) without a very specific, documented reason. These represent confirmed active risk paths, not configuration preferences.

Incremental CI adoption

The .sentinelignore + --fail-on combination is the recommended way to adopt CI gates incrementally:

# Week 1 — gate only on CRITICAL, suppress anything that isn't actually critical
sentinel scan ./agents/ --fail-on CRITICAL

# Week 2 — raise threshold to HIGH, suppress accepted HIGH findings
echo "DANGEROUS_GRANTS" >> .sentinelignore
sentinel scan ./agents/ --fail-on HIGH

# Week 3 — full posture gate, suppressions document accepted risk
sentinel scan ./agents/ --fail-on MEDIUM

Real-World Workflows

Workflow 1: Unknown agent found in production

Your monitoring flagged an unfamiliar process making OpenAI API calls.

# Step 1 — find it
sentinel discover --process --verbose

# Step 2 — if you have the source file, understand it
sentinel inspect /path/to/the/agent.py

# Step 3 — check its permissions
sentinel scan /path/to/the/agent.py

# Step 4 — if it exposes an HTTP endpoint, probe it
sentinel probe http://10.0.1.42:8080/chat

# Step 5 — full red-team if it handles sensitive data
sentinel ai-probe http://10.0.1.42:8080/chat \
  --context "Found in production, unknown purpose, handles customer data"

Workflow 2: Security review before deploying a new agent

Agent is written, tests pass, about to go to staging.

# Step 1 — understand what you're shipping
sentinel inspect ./my_agent.py

# Step 2 — static posture check
sentinel scan ./my_agent.py --fail-on HIGH

# Step 3 — check for leaked secrets or PII in the workspace
sentinel secrets . --fail-on HIGH

# Step 4 — start the agent locally, probe it
sentinel probe http://localhost:8000/chat --attacks injection,jailbreak,extraction

# Step 5 — deep AI red-team
sentinel ai-probe http://localhost:8000/chat \
  --context "Customer-facing chatbot for e-commerce, handles order history and returns" \
  --max-probes 30

# Step 6 — if it has an MCP server, audit that too
sentinel mcp scan http://localhost:3000 --fail-on CRITICAL

Workflow 3: Audit an MCP server before connecting agents to it

You're about to connect your agents to a third-party or internal MCP server.

# HTTP transport
sentinel mcp scan http://mcp-server.internal:3000 \
  --auth-header "Authorization: Bearer $MCP_TOKEN"

# stdio transport
sentinel mcp scan --stdio "uvx my-mcp-package"

# Save the report
sentinel mcp scan http://mcp-server.internal:3000 --format json > mcp-audit.json

If you see NO_AUTH or CODE_EXECUTION_TOOL — do not connect your agents to this server until those findings are resolved.

Workflow 4: CISO asking "what AI agents do we have?"

# Discover everything on the internal network
sentinel discover \
  --subnet 10.0.0.0/16 \
  --docker \
  --process \
  --format json > agent-inventory.json

# Count and categorise
cat agent-inventory.json | jq '.agents | length'
cat agent-inventory.json | jq '.agents[] | select(.risk == "CRITICAL") | .name'

Workflow 5: Ongoing security monitoring

Run daily or on every deployment.

#!/bin/bash
# daily-security-check.sh

set -e

echo "=== Secrets and PII Scan ==="
sentinel secrets . --fail-on HIGH --format json >> reports/secrets-$(date +%Y%m%d).json

echo "=== Agent Posture Scan ==="
sentinel scan ./agents/ --fail-on CRITICAL --format json >> reports/scan-$(date +%Y%m%d).json

echo "=== MCP Server Audit ==="
sentinel mcp scan http://mcp-server.internal:3000 --fail-on HIGH

echo "=== Probe ==="
sentinel probe http://staging-agent.internal/chat \
  --attacks injection,jailbreak \
  --format json >> reports/probe-$(date +%Y%m%d).json

echo "Done."

Workflow 6: Singapore PDPA compliance check

Your agent processes customer data under Singapore's Personal Data Protection Act.

# Scan for any Singapore PII that leaked into agent memory or configs
sentinel secrets . --format json \
  | jq '.findings[] | select(.jurisdiction == "SGP")' \
  > pdpa-findings.json

# Count NRIC exposures specifically
sentinel secrets . --format json \
  | jq '[.findings[] | select(.rule_id == "SG_NRIC")] | length'

# Full audit — memory files only, all severity levels
sentinel secrets . --scope memory --severity LOW

# Fail CI if any Singapore PII found in memory files
sentinel secrets . --scope memory --fail-on MEDIUM

NRICs are validated using the official Singapore weighted mod-11 checksum algorithm before being reported — false positive rate is negligible. Any SG_NRIC finding with "validated": true in JSON output is a structurally valid identity number.

CI/CD Integration

GitHub Actions

# .github/workflows/agent-security.yml
name: AI Agent Security

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        # .sentinelignore in the repo root is picked up automatically

      - name: Install sentinel
        run: pip install "agentsentinel-cli[all]"

      - name: Inspect agents
        run: sentinel inspect ./agents/ --no-ai --format json

      - name: Secrets and PII scan — fail on HIGH
        run: sentinel secrets . --fail-on HIGH

      - name: Posture scan — fail on CRITICAL
        run: sentinel scan ./agents/ --fail-on CRITICAL

      - name: Start agent for live tests
        run: |
          python agents/my_agent.py &
          sleep 2

      - name: Probe — fail on HIGH findings
        run: sentinel probe http://localhost:8000/chat --fail-on HIGH

      - name: MCP scan
        run: sentinel mcp scan http://localhost:3000 --fail-on CRITICAL

Add a .sentinelignore at the repo root to suppress known-accepted findings without weakening the gate threshold:

# .sentinelignore — committed to source control
MISSING_RATE_LIMIT    # rate limiting handled at infra layer

GitLab CI

agent-security:
  image: python:3.11
  before_script:
    - pip install "agentsentinel-cli[all]"
  script:
    - sentinel secrets . --fail-on HIGH
    - sentinel scan ./agents/ --fail-on CRITICAL
    - sentinel mcp scan http://mcp-server:3000 --fail-on HIGH
  artifacts:
    reports:
      junit: sentinel-report.xml

Pre-commit hook

#!/bin/bash
# .git/hooks/pre-commit
sentinel secrets . --fail-on HIGH   # catch leaked keys/PII before they hit git history
sentinel scan . --fail-on CRITICAL

Reference

OWASP LLM Top 10 Coverage

OWASP LLM	Risk	sentinel command
LLM01 Prompt Injection	Attackers manipulate agent via crafted inputs	`sentinel probe`, `sentinel ai-probe`
LLM02 Sensitive Info Disclosure	Agent leaks credentials, PII, or customer data	`sentinel secrets`, `sentinel probe --attacks extraction`
LLM06 Excessive Agency	Agent has more permissions than needed	`sentinel scan`, `sentinel discover`
LLM07 System Prompt Leakage	System prompt extracted or persisted to memory	`sentinel secrets` (memory contamination), `sentinel probe --attacks extraction`
LLM08 Vector/Embedding Weaknesses	MCP servers expose vector DB tools unsafely	`sentinel mcp scan`

Trust Score

Trust Score = Posture × 0.45 + Behavior × 0.45 + Recency × 0.10

Score	Status	Action
80–100	TRUSTED	Normal operation
60–79	WATCH	Monitor — minor concerns
40–59	ALERT	Investigate — active risks
0–39	CRITICAL	Act immediately

Exit Codes

Code	Meaning
`0`	Success — no findings above `--fail-on` threshold
`1`	Findings found at or above `--fail-on` threshold
`1`	Connection error, missing dependency, or invalid arguments

Environment Variables

Variable	Used by	Description
`ANTHROPIC_API_KEY`	`sentinel ai-probe`, `sentinel inspect`	Claude API key for AI features
`AGENTSENTINEL_API_KEY`	`sentinel scan --connect`	API key for AgentSentinel platform

Output Formats

All commands support --format text (default, Rich terminal output) and --format json.

JSON output is designed for piping into other tools:

# Extract just the trust score
sentinel inspect my_agent.py --format json | jq '.trust_score'

# List all CRITICAL findings
sentinel scan ./agents/ --format json | jq '.[] | .findings[] | select(.severity == "CRITICAL")'

# Export probe results for a security report
sentinel probe http://my-agent.com/chat --format json \
  | jq '{target: .target, hit_rate: .jailbreak_rate, hits: [.findings[].name]}'

# Save MCP audit for compliance records
sentinel mcp scan http://mcp-server.internal:3000 --format json \
  > "mcp-audit-$(date +%Y%m%d).json"

Tool Category Reference

sentinel scan and sentinel inspect classify tools into these categories:

Category	Examples	Risk signal
`database`	`query_db`, `run_sql`, `search_postgres`	Internal read — watch for exfiltration
`storage`	`get_object`, `list_buckets`, `read_s3`	Cloud storage access
`filesystem`	`read_file`, `write_file`, `list_directory`	Local disk access
`web`	`fetch_url`, `http_get`, `browse`	External read — injection surface
`communication`	`send_email`, `post_to_slack`, `webhook`	External write — exfiltration path
`code_execution`	`bash`, `exec`, `python_repl`, `shell`	CRITICAL — arbitrary execution
`secrets`	`read_vault`, `get_secret`, `read_env`	Credential access
`admin`	`create_role`, `update_policy`, `grant`	IAM/privilege escalation
`crm`	`search_crm`, `get_customer`, `salesforce`	PII access
`analytics`	`run_report`, `query_metrics`, `dashboard`	Business data access
`infrastructure`	`deploy_lambda`, `scale_ecs`, `terraform`	Infrastructure control

Getting Help

sentinel --help
sentinel inspect --help
sentinel scan --help
sentinel secrets --help
sentinel discover --help
sentinel mcp scan --help
sentinel probe --help
sentinel ai-probe --help

Issues and contributions: github.com/jaydenaung/agentsentinel

FilesExpand file tree

DOCUMENTATION.md

Latest commit

History

DOCUMENTATION.md

File metadata and controls

AgentSentinel CLI — Complete Documentation

Table of Contents

Install

Recommended — pipx (isolated, no venv needed)

pip (standard)

Upgrade

Verify

Quick Start

Commands

sentinel inspect

Options

What it shows

Examples

Understanding the output

AI summary example

Trust score

sentinel scan

Options

Detection rules

Tool detection — what it recognises

Examples

Example output

sentinel secrets

Running it for the first time

Options

Choosing the right scope

Detection layers

Memory path registry

.gitignore check

Examples

Example output

Understanding the output

What to do when you find something

False positives

sentinel discover

Options

Examples

What it looks for

sentinel mcp scan

Options

Transport support

Detection rules

Examples

Example output

sentinel probe

Options

Attack categories

Auto-detection

Success detection

Examples

Reading the results

sentinel ai-probe

Options

How Claude probes

When to use ai-probe vs probe

Examples

Example output

Finding Suppression

--ignore-rule flag

.sentinelignore file

Suppression notice

What to suppress — and what not to

Incremental CI adoption

Real-World Workflows

Workflow 1: Unknown agent found in production

Workflow 2: Security review before deploying a new agent

Workflow 3: Audit an MCP server before connecting agents to it

Workflow 4: CISO asking "what AI agents do we have?"

Workflow 5: Ongoing security monitoring

Workflow 6: Singapore PDPA compliance check

CI/CD Integration

GitHub Actions

GitLab CI

Pre-commit hook