AgentShield

Security scanner for AI agent extensions - offline-first, multi-framework, SARIF output.

AgentShield scans AI agent extensions for security vulnerabilities before they reach production. It runs locally as a single Rust binary, shares no source code with a service, and emits console, JSON, SARIF, and HTML reports.

AgentShield is currently aligned with the 0.8.0 release line.

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.

How it compares

Quick Start

GitHub Action

Add to .github/workflows/security.yml:

name: Agent Security
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: limaronaldo/agentshield@v1
        with:
          path: '.'
          fail-on: 'high'
          ignore-tests: true
          upload-sarif: true

Findings appear as PR annotations and in the repository's Security > Code scanning tab when SARIF upload is enabled.

CLI

# Install from crates.io
cargo install agent-shield

# Scan current directory
agentshield scan .

# Scan with a specific format and policy threshold
agentshield scan ./my-agent-extension --format sarif --fail-on medium --output results.sarif

# Skip test files
agentshield scan ./my-agent-extension --ignore-tests

# Generate a standalone HTML report
agentshield scan ./my-agent-extension --format html --output report.html

# List all rules
agentshield list-rules

# Create starter config
agentshield init

Pre-built binaries

Download from the latest release for Linux, macOS, and Windows targets.

From source

git clone https://github.com/limaronaldo/agentshield.git
cd agentshield
cargo build --release
./target/release/agentshield scan /path/to/agent-extension

Supported Frameworks

AgentShield runs all matching adapters in a repository instead of stopping at the first match.

CLI Commands

Useful scan options include --config, --format, --fail-on, --output, --ignore-tests, --baseline, --write-baseline, and --emit-egress-policy.

Detection Rules

AgentShield ships built-in rules for command execution, credential exfiltration, SSRF, arbitrary file access, runtime package installation, self-modification, prompt injection surfaces, excessive permissions, dependency hygiene, dynamic code execution, metadata service access, download-and-execute flows, overbroad filesystem capabilities, unsafe deserialization, archive traversal, and secret leakage.

Use the CLI for the authoritative rule list in your installed version:

agentshield list-rules
agentshield list-rules --format json

Output Formats

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, and runtime wrap support. If building from source, use cargo build --features full --release to include agentshield wrap.

Create .agentshield.toml in your project root or run agentshield init:

[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

Suppressions can be added through agentshield suppress <fingerprint> --reason "..." after obtaining finding fingerprints from JSON output.

Exit Codes

Language Support

Both tree-sitter parsers are feature-gated:

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.

Architecture

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.

Development

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.0.md and docs/RELEASE_CHECKLIST.md.