# AgentShield
**Find risky behavior in MCP and AI agent extensions before they ship.**
[](https://github.com/aiconnai/agentshield/actions/workflows/ci.yml)
[](https://github.com/aiconnai/agentshield/releases/tag/v1.0.0)
[](https://aiconnai.github.io/agentshield/)
[](LICENSE-MIT)
[](https://crates.io/crates/agent-shield)
[](https://marketplace.visualstudio.com/items?itemName=aiconnai.agentshield)
[](https://docs.rs/agent-shield)
- [Website & Interactive Playground](https://aiconnai.github.io/agentshield/)
- [Contributing](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security Policy](SECURITY.md)
- [License](LICENSE)
AgentShield is an offline, high-performance Rust security engine for teams shipping tool-enabled AI agents across the modern AI stack. Native adapters cover MCP servers, OpenClaw skills, Hermes Agent configs, CrewAI, LangChain/LangGraph, GPT Actions, and Cursor Rules; the same checks help harden repositories built around OpenAI Agents SDK, Claude Code, Claude Desktop MCP setups, Browser Use, FastMCP, GitHub MCP Server, Playwright MCP, and other tool-heavy workflows.
It catches command injection, credential exfiltration, SSRF, unsafe file access, runtime package installs, prompt-injection surfaces, and dependency hygiene issues before an agent can call those tools.
AgentShield runs as a CLI, GitHub Action, VS Code extension, or Rust library. It operates 100% offline, keeping source code on your machine, and emits console, JSON, SARIF for GitHub Code Scanning, and standalone HTML reports. The current release line is `1.0.0` (General Availability).
## At a glance
| Scanner surface | Normalizes seven framework/client families into one IR: MCP, OpenClaw, Hermes Agent, CrewAI, LangChain/LangGraph, GPT Actions, and Cursor Rules. |
| Interprocedural Taint | Deep cross-function & cross-method call-graph analysis tracking untrusted inputs through utility wrappers to execution sinks in Python and TypeScript. |
| Detection | 20 built-in contextual rules plus a declarative YAML custom rule engine (`.agentshield/rules/*.yaml`). |
| Automated Remediation | Instant auto-fixing (`agentshield fix`) and VS Code lightbulb code actions (`Cmd + .`) for unsafe deserializers and unpinned dependencies. |
| Runtime Guard | Reverse proxy for MCP stdio and HTTP/SSE streams inspecting tool calls in real time and redacting leaked secrets. |
| Workflow fit | Works locally, in CI, in VS Code, and in GitHub Code Scanning without sending source code to a hosted service. |
For runtime guard scope and roadmap, see [docs/RUNTIME_GUARD.md](docs/RUNTIME_GUARD.md).
## Works With
AgentShield is useful anywhere an agent can call local tools, remote APIs,
browser automation, file operations, shell commands, or MCP servers.
| Claude Desktop and Claude Code | Scan MCP servers and tool repositories before adding them to Claude MCP configs or coding-agent workflows. |
| Cursor and Cursor Rules | Detect risky agent guidance, MCP server definitions, and tool code that can reach files, commands, or the network. |
| OpenAI Agents SDK | Scan tool implementations, OpenAPI/GPT Actions surfaces, and MCP-connected repos used by OpenAI agent apps. |
| LangGraph and LangChain | Analyze Python/TypeScript tool code and dependency surfaces before agents execute tools. |
| CrewAI | Check Python CrewAI tool projects for command execution, credential exfiltration, SSRF, and unsafe file access. |
| FastMCP, GitHub MCP Server, and Playwright MCP | Scan MCP server code, manifests, schemas, dependencies, and provenance before publishing or installing. |
| Browser Use and browser automation agents | Catch risky command, network, file, and dependency patterns in tool-enabled automation repos. |
Runnable examples live under [examples/](examples/README.md), with focused
guides for [Claude MCP security](docs/claude-mcp-security.md),
[MCP security scanning](docs/mcp-security-scanner.md), and
[OpenAI Agents security](docs/openai-agents-security.md).
---
## Why AgentShield?
AI agents are being connected to tools that can execute commands, read and write files, make HTTP requests, install packages, and call external services. A single malicious or poorly-written extension can:
- **Exfiltrate credentials** by reading environment variables or local secret files and sending them to an attacker-controlled endpoint.
- **Execute arbitrary commands** by passing user-controlled input into shell or process APIs.
- **Install backdoors at runtime** through package manager calls inside tool handlers.
- **Proxy SSRF requests** by fetching URLs derived from tool arguments.
- **Leak sensitive data to model context** through unguarded prompts, tool results, or rule files.
AgentShield catches these patterns with static analysis, framework adapters, policy evaluation, suppressions, baselines, egress policy generation, attestations, and SARIF output for GitHub Code Scanning.
### Use it with general security scanners
AgentShield complements general-purpose security tooling; it is not a replacement
for SAST, secret scanning, or broad dependency analysis. A practical security
stack is:
| CodeQL | General SAST for code vulnerabilities and quality issues | CodeQL is broad; AgentShield models agent/tool surfaces such as MCP tools, prompts, tool schemas, and egress. |
| Gitleaks | Hardcoded secrets across Git history and source files | Gitleaks is the right secret scanner; AgentShield focuses on secrets flowing through tools, logs, responses, and agent context. |
| Semgrep | Custom SAST rules, language-specific checks, SCA, and security policy | Semgrep is flexible and broad; AgentShield ships opinionated agent/MCP detectors and a normalized IR for supported agent frameworks. |
| AgentShield | MCP, agent tools, prompt surfaces, filesystem/network/process capabilities, egress policy, SARIF, and runtime guard experiments | This is the agent-specific layer that catches risks other scanners usually see only indirectly. |
Use `agentshield ci install --suite` when you want a starter GitHub Actions
workflow that runs CodeQL, Gitleaks, Semgrep CE, and AgentShield together.
### How it compares
| Rust single binary | Yes | No | No |
| Offline / local-first | Yes | Partial | No |
| Multi-framework adapters | Yes (7 frameworks) | MCP-focused | MCP-focused |
| Interprocedural Call-Graph Taint | Yes | No | No |
| Declarative Custom Rules (`.yaml`) | Yes | No | No |
| Automated Remediation (`fix`) | Yes | No | No |
| Runtime Guard MCP Proxy (stdio/SSE) | Yes | No | No |
| Static analysis | tree-sitter + AST + regex | Regex-oriented | Runtime/cloud-oriented |
| SARIF & HTML output | Yes | No | No |
| GitHub Action & VS Code Extension | Yes | No | No |
---
## Quick Start
### VS Code Extension
Install the [AgentShield VS Code Extension](vscode/) for inline security findings and lightbulb quick-fixes:
- **Inline Diagnostics**: Findings are highlighted as you type and on file save.
- **Lightbulb Quick-Fixes (`Cmd + .` / `Alt + Enter`)**: Instant 1-click remediation for unsafe deserializers (`yaml.load` $\to$ `safe_load`) and unpinned dependencies.
- **Interactive Suppressions**: Suppress false positives with a rationale saved directly to `.agentshield.toml`.
### GitHub Action
Add to `.github/workflows/security.yml`:
```yaml
name: Agent Security
on: [push, pull_request]
permissions:
actions: read
contents: read
security-events: write
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: aiconnai/agentshield@main
with:
path: '.'
fail-on: 'high'
ignore-tests: true
strict: true # set false only when no supported adapter layout is expected
upload-sarif: true
```
Findings appear as PR annotations and in the repository's **Security > Code scanning** tab when SARIF upload is enabled.
### CLI
```bash
# Install the v1.0.0 GA release with the full feature set
cargo install --git https://github.com/aiconnai/agentshield --tag v1.0.0 --features full --force
# First-run setup: config + explained first scan
agentshield quickstart
# Scan an agent extension or MCP repository
agentshield scan . --ignore-tests --fail-on high --explain
# Automatically remediate fixable findings (preview diff with --dry-run)
agentshield fix . --dry-run
agentshield fix .
# Scan with custom declarative rules
agentshield scan . --rules-dir .agentshield/rules
# Run runtime guard reverse-proxy for remote MCP SSE/HTTP endpoint
agentshield guard --listen 127.0.0.1:8080 --target http://127.0.0.1:3000
# Discover allowlisted local client configs without executing them
agentshield discover --no-default-paths --root .
# Add a GitHub Actions workflow
agentshield ci install
# Add a broader security suite: CodeQL + Gitleaks + Semgrep CE + AgentShield
agentshield ci install --suite
# Adopt in an existing repo without blocking on known findings
agentshield scan --write-baseline .agentshield-baseline.json
agentshield ci install --baseline .agentshield-baseline.json
# Generate a standalone HTML report
agentshield scan ./my-agent-extension --format html --output report.html
# List all built-in and custom rules
agentshield list-rules
```
If you only need static scanning in a published crates.io version, `cargo
install agent-shield` is also supported. Use the GitHub tag command above when
you need the latest release line before crates.io has been updated.
### Pre-built binaries
Download from the [latest release](https://github.com/aiconnai/agentshield/releases/latest) for Linux, macOS, and Windows targets.
For container consumers, the release image tag is:
```text
ghcr.io/aiconnai/agentshield:1.0.0
```
### Docker
The GHCR image is built with the `full` feature set, including runtime `wrap` support and experimental runtime guard commands. The image is published for `linux/amd64` and `linux/arm64`.
```bash
docker pull ghcr.io/aiconnai/agentshield:1.0.0
docker run --rm -v "$PWD:/scan" ghcr.io/aiconnai/agentshield:1.0.0 scan .
docker run --rm ghcr.io/aiconnai/agentshield:1.0.0 --version
```
If the GHCR package is private in your organization, authenticate first:
```bash
gh auth refresh -h github.com -s read:packages
### From source
```bash
git clone https://github.com/aiconnai/agentshield.git
cd agentshield
cargo build --release
./target/release/agentshield scan /path/to/agent-extension
```
## Token-Optimized Local Checks with RTK
AgentShield can produce noisy command output during local development, especially from `cargo test`, `cargo clippy`, and scanner runs that emit JSON or SARIF. If `rtk` is installed, use the optional wrapper to reduce output shown to humans and coding agents:
```bash
scripts/rtk-check.sh quick
scripts/rtk-check.sh test
scripts/rtk-check.sh clippy
scripts/rtk-check.sh scan-fixture
```
The wrapper is intentionally local-only. RTK filters local command output only. It must not alter AgentShield JSON, SARIF, HTML, or console output contracts consumed by users, clients, CI, or GitHub Code Scanning.
Use raw output for debugging, audit, and security decisions:
```bash
scripts/rtk-check.sh raw -- cargo test
scripts/rtk-check.sh raw -- cargo run -- scan tests/fixtures/mcp_servers/safe_calculator --format sarif --output target/agentshield/scan.sarif
```
Policy:
- Use filtered output for fast local feedback.
- Use raw output when investigating test failures, parser bugs, detector behavior, or security-sensitive findings.
- Always write complete `json` and `sarif` reports to files when clients or CI consume them.
---
## Supported Frameworks
AgentShield runs all matching adapters in a repository instead of stopping at the first match.
| MCP (Model Context Protocol) | Supported | MCP server manifests, Python/TypeScript/JavaScript source, tool schemas, dependencies, provenance |
| OpenClaw | Supported | `SKILL.md` skill files plus related source/dependency surfaces |
| Hermes Agent | Supported | Hermes config/profile files, `mcp_servers`, `.hermes.md`, skill trees, optional MCP manifests |
| CrewAI | Supported | Python projects detected from dependency metadata or imports |
| LangChain / LangGraph | Supported | LangChain/LangGraph dependency metadata, imports, and `langgraph.json` |
| GPT Actions | Supported | Action/OpenAPI-style surfaces for custom GPT integrations |
| Cursor Rules | Supported | Cursor rule files and related agent guidance surfaces |
---
## CLI Commands
| `agentshield discover` | Read allowlisted local client configuration paths without execution, network access, or automatic scanning; use `--no-default-paths`, repeated `--root`, `--format console\|json`, and `--explain` to control consent and output. |
| `agentshield scan [path]` | Scan an agent extension directory and emit console, JSON, SARIF, or HTML output. |
| `agentshield scan [path] --experimental-risk` | Add an informational, versioned risk index to console or JSON output without changing policy or exit status. |
| `agentshield scan [path] --explain` | Print a console-only gate, coverage, confidence, grouped findings, next-actions, and limits summary. |
| `agentshield quickstart [path]` | Create first-run config, suggest CI setup, run the first scan, and explain the result. |
| `agentshield ci install` | Generate a GitHub Actions workflow for AgentShield. |
| `agentshield ci install --suite` | Generate a broader GitHub Actions workflow with CodeQL, Gitleaks, Semgrep CE, and AgentShield. |
| `agentshield ci install --baseline <path>` | Generate a workflow that filters known findings through a baseline file. |
| `agentshield list-rules` | List available detection rules as a table or JSON. |
| `agentshield doctor [path]` | Print environment, config, compile-feature, and adapter diagnostics. |
| `agentshield init` | Generate a starter `.agentshield.toml` config file. |
| `agentshield fix [path]` | Automatically fix deterministic security issues (unsafe deserializers, unpinned dependencies); use `--dry-run` to preview unified diffs. |
| `agentshield suppress <fingerprint>` | Add a suppression entry with a required reason and optional expiry. |
| `agentshield list-suppressions` | Show suppressions configured in `.agentshield.toml`. |
| `agentshield certify [path]` | Generate a DSSE attestation envelope for scan results. |
| `agentshield wrap --policy <path> -- <command>` | Enforce an egress policy through a local HTTP proxy when built with the `runtime` feature. |
| `agentshield guard --stdin` | Evaluate one runtime event JSON document when built with the `runtime-guard` feature. |
| `agentshield guard --mcp-proxy [-- <server cmd...>]` | EXPERIMENTAL: evaluate line-delimited MCP JSON-RPC `tools/call` messages, block unsafe calls, and either emit forward markers or bridge stdio to a spawned downstream MCP server when built with the `runtime-guard` feature. |
Useful `scan` options include `--config`, `--format`, `--fail-on`, `--output`, `--ignore-tests`, `--explain`, `--experimental-risk`, `--baseline`, `--write-baseline`, and `--emit-egress-policy`.
Configured `[scan] include` and `[scan] exclude` filters scope source and
metadata-derived findings before detectors run.
For mature repositories with existing findings, write a baseline first and use
it in CI:
```bash
agentshield scan --write-baseline .agentshield-baseline.json
agentshield scan --baseline .agentshield-baseline.json --explain
agentshield ci install --baseline .agentshield-baseline.json
```
`--explain` is intentionally console-only. It will not append text to JSON,
SARIF, or HTML output. Explain output includes the scan root, metadata root
when different, and hotspot summaries for concentrated blocking findings.
`--experimental-risk` is a separate console/JSON-only mode and cannot be
combined with `--explain`. Its versioned index is informational: it does not
change findings, PASS/FAIL, policy thresholds, baselines, suppressions, or the
process exit status. SARIF, HTML, and DSSE remain unchanged.
---
## Detection Rules
AgentShield ships 20 built-in contextual rules covering command execution, credential exfiltration, composite toxic flows, SSRF, arbitrary file access, runtime package installation, prompt injection surfaces, excessive capabilities, dependency hygiene, dynamic code execution, metadata service access, unsafe deserialization, and secret leakage.
Use the CLI for the authoritative rule list in your installed version:
```bash
agentshield list-rules
agentshield list-rules --format json
```
### Custom Declarative Rules
You can define custom organization security policies in `.agentshield/rules/*.yaml` or pass `--rules-dir <path>`:
```yaml
id: "ORG-001"
name: "Banned Production Credentials"
description: "Detects legacy hardcoded connection strings"
severity: "high"
attack_category: "credential_access"
cwe_id: "CWE-798"
match:
regex: "postgres://prod_admin:[^@]+@"
file_glob: "*.{py,ts,js}"
message: "Hardcoded production database connection string detected"
remediation: "Inject database credentials via environment variables or secret store"
```
Banned dependency rules and prohibited tool name rules are also supported:
```yaml
id: "ORG-002"
name: "Banned Deprecated Library"
description: "Disallow telnetlib in agent tools"
severity: "medium"
attack_category: "supply_chain"
match:
banned_dependencies:
- name: "telnetlib"
reason: "Insecure unencrypted remote protocol"
tool_name_regex: "^telnet_"
```
---
## Output Formats
| Console | `--format console` | Local development default |
| JSON | `--format json` | Programmatic consumption and fingerprint extraction |
| SARIF | `--format sarif` | GitHub Code Scanning and compatible tools |
| HTML | `--format html` | Shareable standalone reports |
---
## Configuration
### Trust workflows
AgentShield includes trust workflow documentation for baselines, suppressions, certification attestations, and egress enforcement:
- `docs/BASELINES.md`: write and use `.agentshield-baseline.json` for known findings.
- `docs/SUPPRESSIONS.md`: suppress individual findings by fingerprint with required reasons and optional expiry.
- `docs/CERTIFICATION.md`: generate unsigned or Ed25519-signed DSSE attestations.
- `docs/EGRESS.md`: emit `agentshield.egress.toml` and enforce it with `agentshield wrap`.
Release binaries are built with the `full` feature set, including Python parsing, TypeScript parsing, runtime `wrap` support, and experimental runtime guard commands. If building from source, use `cargo build --features full --release` to include `agentshield wrap` and `agentshield guard`.
Create `.agentshield.toml` in your project root or run `agentshield init`:
```toml
[policy]
# Minimum severity to fail the scan: info, low, medium, high, critical
fail_on = "high"
# Rules to skip entirely
ignore_rules = ["SHIELD-008"]
# Downgrade specific rules
[policy.overrides]
"SHIELD-012" = "info"
[scan]
# Skip test files before parsing
ignore_tests = true
# Optional path filters are relative to the scan root.
# Empty include means all scan-supported files are eligible.
# Use ** for recursive directories; * and ? stay within one path segment.
include = ["src/**", "tools/**"]
exclude = ["legacy/**", "**/generated/**", "vendor/**"]
[runtime.proxy]
# Runtime MCP proxy guard blocking threshold: block, warn, or never.
fail_on = "block"
[[runtime.proxy.tool]]
name = "calculator.add"
fail_on = "never"
```
Suppressions can be added through `agentshield suppress <fingerprint> --reason "..."` after obtaining finding fingerprints from JSON output.
When both `include` and `exclude` match a file, `exclude` wins. Use
`agentshield scan . --explain` to confirm the active path filters and parsed
source-file count before relying on a focused scan in CI.
Path filter matching is case-sensitive, accepts `/` on all platforms, treats
leading `./` or `/` as relative to the scan root, and treats a trailing slash
such as `legacy/` as matching that directory's contents.
---
## Exit Codes
| 0 | Scan passed with no findings above threshold |
| 1 | Scan failed with findings above threshold |
| 2 | Scan error (e.g., invalid config); no supported adapter found is surfaced as scanner error and can be controlled by action `strict` mode |
| 3 | Runtime guard blocked or failed closed on invalid runtime input |
---
## Language Support
| Python | Regex parser with source/sink patterns | `python` compatibility flag (default) |
| TypeScript/TSX | tree-sitter AST with fallback patterns | `typescript` (default) |
| JavaScript/JSX | tree-sitter AST through TypeScript grammar support | `typescript` (default) |
| Shell | Regex parser | always on |
| JSON Schema / OpenAPI-style schemas | Schema parser | always on |
Go, Ruby, Java, and Rust source files are not execution-parsed or included in
the normalized execution surface in this release. They may be scanned by other
tools in a security stack, but AgentShield does not claim language-level source
or taint coverage for them yet.
TypeScript tree-sitter support is feature-gated; the Python compatibility flag keeps existing build commands stable:
```bash
cargo build --no-default-features
cargo build --features python
cargo build --features full
```
The `full` feature enables language parsers plus the runtime proxy used by `agentshield wrap` and the experimental runtime guard commands.
---
## Architecture
```text
CLI / GitHub Action / Library API
|
v
Scan Engine -> ScanReport
|
v
Adapters -> Parsers -> Cross-file analysis -> Unified IR (ScanTarget)
|
v
Rule Engine -> Policy / Suppressions / Baseline filtering
|
v
Console / JSON / SARIF / HTML / DSSE attestation
```
Adapters translate framework-specific files into a unified intermediate representation. Detectors consume only that IR, so new frameworks can be added without rewriting every rule. Policy, suppressions, and baselines are separate from detection so scans remain explainable and repeatable.
---
## Security Policy
Please report vulnerabilities privately. See [`SECURITY.md`](SECURITY.md) for supported versions, reporting guidance, and disclosure scope.
---
## Development
```bash
cargo test
cargo clippy -- -D warnings
cargo fmt --check
cargo run -- scan tests/fixtures/mcp_servers/vuln_cmd_inject
cargo run -- list-rules
```
For release-specific notes, see `docs/releases/0.8.7.md`,
`docs/releases/0.8.8.md`, and `docs/RELEASE_CHECKLIST.md`.