agentic-shield

AgentShield

Security scanner and runtime firewall for AI agents and MCP servers.

AgentShield protects your AI coding tools (Claude Code, Cursor, Windsurf, VS Code, Cline, Continue) from malicious MCP servers, tool poisoning, supply chain attacks, and configuration vulnerabilities.

The Problem

MCP servers are the plugins of AI coding tools. Developers install them from npm, give them access to their codebase, API keys, and databases — and nobody checks if they're safe.

• A plugin's tool description can contain hidden instructions that trick the AI into exfiltrating your data
• A typosquatted package like mcp-sevrer-semgrep silently installs malware
• Hardcoded API keys in config files get committed to git
• A trusted plugin gets silently updated with a malicious payload

AgentShield catches all of this.

Quick Start

pip install agentshield

Scan your MCP config:

# Auto-detect and scan .mcp.json in current directory
agentshield scan

# Scan a specific config file
agentshield scan mcp-config -f .mcp.json

# Scan all AI tool configs in a project
agentshield scan project --dir .

Output:

+-------------------------------- AgentShield --------------------------------+
| Scan Results                                                                |
| Target: .mcp.json                                                           |
| Servers: 4 scanned                                                          |
| Findings: 3 high, 1 medium                                                  |
+-----------------------------------------------------------------------------+

! CFG-NPX-server  Unverified npx install: server
  Uses 'npx -y' which auto-installs packages without verification.
  Fix: Pin the package version explicitly.

! CFG-SECRET-api-KEY  Hardcoded secret in config: API_KEY
  Has env var 'API_KEY' with a hardcoded value.
  Fix: Use environment variable references (${VAR}).

Features

Scanner (14 Security Checks)

Runtime Proxy (Firewall for AI Tool Calls)

AgentShield can sit between your AI client and MCP servers, intercepting every tool call:

# Generate a protected config
agentshield shield --config .mcp.json

# Wraps every server with the proxy:
#   "command": "agentshield"
#   "args": ["proxy", "--server", "name", "--config", ".mcp.json"]

Define guardrails in .agentshield.yml:

guardrails:
  default_action: allow
  rules:
    - name: block-destructive
      action: deny
      tools: ["delete_*", "rm_*", "drop_*"]
      message: "Destructive operations blocked"

    - name: audit-file-writes
      action: audit
      tools: ["write_*", "create_*", "edit_*"]

    - name: block-ssrf
      action: deny
      args_pattern: "169\\.254\\.169\\.254"
      message: "SSRF attempt blocked"

    - name: rate-limit
      action: rate_limit
      tools: ["*"]
      rate: "100/minute"

View the audit log:

agentshield audit

Policy Engine

# .agentshield.yml
version: 1
profile: standard  # strict | standard | minimal

checks:
  disabled:
    - transport-security

severity_overrides:
  "CFG-BINARY-*": low

ignore:
  - check_id: config-audit
    server: local-dev-server

custom_rules:
  - name: no-localhost
    pattern: "localhost"
    target: args
    severity: high
    message: "No localhost in production configs"

fail_on: medium

More Commands

# Auto-fix security issues
agentshield fix -f .mcp.json
agentshield fix -f .mcp.json --no-dry-run  # Apply fixes

# Compare scan results over time
agentshield scan mcp-config -f .mcp.json --format json -o baseline.json
# ... make changes ...
agentshield scan mcp-config -f .mcp.json --format json -o current.json
agentshield diff baseline.json current.json

# Watch for config changes in real-time
agentshield watch -f .mcp.json

# Machine-wide inventory of all MCP servers
agentshield inventory

# Convert configs between AI tools
agentshield convert -f .mcp.json --from claude --to cursor

# List compliance profiles
agentshield profiles

# Generate a secure config template
agentshield init --format claude

Output Formats

CI/CD Integration

GitHub Action

- uses: ewibrahim/agentshield@v1
  with:
    file: .mcp.json
    fail-on: high
    sarif-output: agentshield.sarif

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: agentshield.sarif

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/ewibrahim/agentshield
    rev: v1.0.0
    hooks:
      - id: agentshield

CI Pipeline

pip install agentshield
agentshield scan mcp-config -f .mcp.json --ci --fail-on high

Supported AI Tools

Plugin System

Create custom checks and distribute them as pip packages:

# my_plugin/checks.py
from agentshield.checks.base import BaseCheck, CheckContext
from agentshield.core.models import Finding

class MyCustomCheck(BaseCheck):
    id = "my-custom-check"
    name = "My Custom Check"
    requires_connection = True

    async def run(self, context: CheckContext) -> list[Finding]:
        # Your check logic here
        return []

# pyproject.toml
[project.entry-points."agentshield.checks"]
my_check = "my_plugin.checks:MyCustomCheck"

Testing

pip install -e ".[dev]"
pytest tests/ -v

Full test suite covering all 14 security checks, policy engine, guardrails, proxy, converter, and diff engine.

Architecture

agentshield/
  cli.py               # Typer CLI (13 commands)
  core/
    scanner.py          # Orchestrator
    models.py           # Pydantic data models
    mcp_client.py       # MCP connection (read-only, never calls tools)
    guardrails.py       # Runtime rule engine
    proxy.py            # MCP stdio proxy
    policy.py           # .agentshield.yml loading
    scoring.py          # Risk scoring (0-100)
    report.py           # Text/JSON/SARIF formatters
    ...
  checks/
    base.py             # BaseCheck ABC
    mcp/                # 14 security checks
  db/
    known_tools.json    # Known MCP tool definitions
    known_mcp_packages.json  # Known npm packages

Safety constraint: AgentShield never calls call_tool() on MCP servers. It only reads metadata via list_tools(), list_resources(), and list_prompts().

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

License

MIT