🛡️ AgentShield

AI Agent Risk Scanner — Detect security risks before they reach your agents
AI Agent 风险扫描器 — 基于 OWASP/MITRE 标准检测安全风险

🇨🇳 中文文档 · 📚 Methodology · 📖 Rule Docs · 🔌 Integration

Scan skills, MCP servers, and plugins for data exfiltration, backdoors, prompt injection, tool poisoning, and supply chain risks. Every finding is mapped to OWASP Top 10 for LLM, MITRE ATLAS, and CWE — so you're reviewing established standards, not our opinions.

Offline-first. AST-powered. Open source. Your data never leaves your machine.

npx @elliotllliu/agent-shield scan ./my-skill/

💡 Example Output

🛡️  AgentShield Risk Report
────────────────────────────────────────────────────
📁 Target:  ./my-plugin
📄 Files:   8 files, 262 lines
⏱  Time:    245ms
────────────────────────────────────────────────────

📊 Risk Summary

  🔴 LLM09: Supply Chain Vulnerabilities (3 high, 2 medium)
     https://genai.owasp.org/llmrisk/llm09-supply-chain-vulnerabilities/
  🟡 LLM06: Sensitive Information Disclosure (1 medium)
     https://genai.owasp.org/llmrisk/llm06-sensitive-information-disclosure/
  🟢 LLM01: Prompt Injection (2 low)
     https://genai.owasp.org/llmrisk/llm01-prompt-injection/

📋 Detailed Findings

  [LLM09: Supply Chain Vulnerabilities]
  Skill/plugin behavioral hijacking — patterns that modify agent config,
  inject prompts, or override other skills.
  Standards: OWASP LLM09 · CWE-829 · ATLAS AML.T0049
  Research: Greshake et al. (2023) "Not what you've signed up for"

    ├─ plugin.ts:15 — Plugin injects content via before_prompt_build
    ├─ install.sh:8 — Config tampering: Modifies agent configuration
    └─ SKILL.md:5  — Behavioral override: forced usage directive

  [LLM06: Sensitive Information Disclosure]
  Patterns where sensitive data is read and sent via network requests.
  Standards: OWASP LLM06 · CWE-200 · ATLAS AML.T0048.004

    └─ media.js:14 — Reads sensitive data and sends HTTP request

✅ No security risks detected.     ← Clean projects show this

We are an X-ray machine, not a doctor. We show what patterns exist and cite established standards — you decide what they mean for your use case.

🏆 What Makes AgentShield Different

1. 📚 Standards-Based Detection

Every finding is mapped to authoritative security frameworks:

We don't invent risk categories. We map code patterns to standards that industry experts have already established.

2. 🔒 Runtime MCP Interception

Other tools only scan source code. AgentShield also sits between your MCP client and server, intercepting every JSON-RPC message in real-time:

# Insert AgentShield between client and server
agent-shield proxy node my-mcp-server.js

# Enforce mode: automatically block high-risk tool calls
agent-shield proxy --enforce python mcp_server.py

What it catches at runtime:

• 🎭 Tool description injection — hidden instructions in tool descriptions
• 💉 Result injection — malicious content in tool return values
• 🔑 Credential leakage — sensitive data in tool call parameters
• 📡 Beacon behavior — abnormal periodic callbacks (C2 pattern)
• 🪤 Rug-pull attacks — tools changing behavior after initial trust

3. ⛓️ Cross-File Attack Chain Detection

Most scanners check one file at a time. AgentShield traces data flow across your entire codebase:

🔴 Cross-file data flow (OWASP LLM09 · CWE-506):
   config_reader.py reads ~/.ssh/id_rsa → exfiltrator.py POSTs to external server

🔴 Kill Chain detected (ATLAS AML.T0049):
   Reconnaissance → Access → Collection → Exfiltration → Persistence

4. 🧠 AST Taint Tracking (Not Regex)

Uses Python's ast module for precise analysis — dramatically reducing false positives:

user = input("cmd: ")
eval(user)          # → 🔴 Tainted input flows to eval (CWE-94)
eval("{'a': 1}")    # → ✅ NOT flagged (safe string literal)
exec(config_var)    # → 🟡 Dynamic, not proven tainted

5. 🕵️ Skill Hijack Detection

Detects multi-layer supply chain attacks targeting AI agent ecosystems:

[LLM09: Supply Chain Vulnerabilities]
Standards: OWASP LLM09 · CWE-829 · ATLAS AML.T0049

  🔴 Plugin prompt injection: before_prompt_build + prependContext
  🔴 Config tampering: Modifies agent configuration via CLI
  🔴 Silent OTA: Downloads update then re-executes itself
  🟡 Non-standard install source: non-registry domain
  🟡 Behavioral override: forced usage directive in SKILL.md

Real-world case study: detected a 3-layer supply chain attack where a published skill silently installed a CLI tool from a private CDN, which then injected prompts, modified agent config, and auto-updated without user consent.

⚡ Quick Start

# Scan a skill / MCP server / plugin (29 rules, offline, <1s)
npx @elliotllliu/agent-shield scan ./my-skill/

# Multi-engine scan — run multiple scanners, cross-validate results
npx @elliotllliu/agent-shield scan ./my-skill/ --engines all

# Scan with optional reference score
npx @elliotllliu/agent-shield scan ./my-skill/ --score

# Scan Dify plugins (.difypkg auto-extraction)
npx @elliotllliu/agent-shield scan ./plugin.difypkg

# Runtime interception (MCP proxy)
npx @elliotllliu/agent-shield proxy node my-mcp-server.js

# AI-powered deep analysis (uses YOUR API key)
npx @elliotllliu/agent-shield scan ./skill/ --ai --provider openai --model gpt-4o

# Discover installed agents on your machine
npx @elliotllliu/agent-shield discover

# JSON output for programmatic use
npx @elliotllliu/agent-shield scan ./skill/ --json

# SARIF output for GitHub Code Scanning
npx @elliotllliu/agent-shield scan ./skill/ --sarif -o results.sarif

# HTML report
npx @elliotllliu/agent-shield scan ./skill/ --html

🔗 Multi-Engine Aggregation

Run multiple security scanners simultaneously and get a unified report with cross-engine validation — findings confirmed by multiple engines have higher confidence.

# Run all available engines
agent-shield scan ./my-skill/ --engines all

# Choose specific engines
agent-shield scan ./my-skill/ --engines agentshield,aguara

# List available engines
agent-shield scan ./my-skill/ --engines list

Integrated Engines

Cross-Engine Validation

The most valuable part of multi-engine scanning — when multiple independent scanners agree on a finding, it's much more likely to be a real issue:

🔗 Cross-Engine Validation

  HIGH [3/3 engines] plugin.ts:15
    Dynamic code execution via eval()
    Detected by: AgentShield · Aguara · Skill Vetter

  MEDIUM [2/3 engines] src/bot.ts:492
    Tool output interception
    Detected by: Aguara · Skill Vetter

We aggregate, not compete. Each engine has unique strengths — together they provide more complete coverage and higher confidence.

🔍 29 Security Rules (Mapped to Standards)

Risk Category: Code Execution (OWASP LLM09 · CWE-94)

Risk Category: Data Safety (OWASP LLM06 · CWE-200)

Risk Category: Tool Integrity (OWASP LLM07)

Risk Category: Prompt Injection (OWASP LLM01 · ATLAS AML.T0051)

Risk Category: Supply Chain (OWASP LLM09 · ATLAS AML.T0049)

Risk Category: Permissions & Quality

📊 Key Features

We focus on detection and evidence. We show you what patterns exist, cite the relevant standards, and let you decide what action to take.

📋 Real-World Validation: 493 Dify Plugins

We scanned the entire langgenius/dify-plugins repository:

6 plugins flagged with eval()/exec() executing dynamic code (CWE-94).

Full report →

🔌 Integrate AgentShield Into Your Platform

Running a skill marketplace, MCP directory, or plugin registry?

Your platform lists hundreds of skills and plugins. Users install them into AI agents with access to files, credentials, and shell commands. AgentShield gives you:

• Risk reports on every submission — based on industry standards, not arbitrary scores
• CI/CD gates — fail PRs that introduce high-risk patterns
• SARIF integration — feed results into GitHub Code Scanning

How to Integrate

npx @elliotllliu/agent-shield scan ./skill --json

{
  "totalFindings": 3,
  "summary": { "high": 1, "medium": 1, "low": 1 },
  "findings": [
    {
      "severity": "high",
      "rule": "skill-hijack",
      "file": "plugin.ts",
      "line": 15,
      "message": "Plugin injects content via before_prompt_build",
      "references": {
        "owasp": "LLM09: Supply Chain Vulnerabilities",
        "cwe": "CWE-829"
      }
    }
  ]
}

📖 Full Integration Guide →

📦 Ecosystem

🤖 GitHub App

Auto-scan every PR for security risks. Learn more →

💻 VS Code Extension

Real-time security diagnostics in your editor. Learn more →

🔒 Runtime MCP Proxy

Monitor MCP server behavior in real-time.

agent-shield proxy --enforce node my-mcp-server.js

⚙️ CI Integration

GitHub Action

name: Security Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: elliotllliu/agent-shield@main
        with:
          path: './skills/'

GitHub Action with SARIF Upload

name: Security Scan (SARIF)
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: elliotllliu/agent-shield@main
        with:
          path: './skills/'
          sarif: 'true'
      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: agent-shield-results.sarif

npx one-liner

- name: Security scan
  run: npx -y @elliotllliu/agent-shield scan .

⚙️ Configuration

Create .agent-shield.yml (or run agent-shield init):

rules:
  disable:
    - supply-chain
    - phone-home
ignore:
  - "tests/**"
  - "*.test.ts"

🗂️ Supported Platforms

📚 Methodology & References

AgentShield's detection rules are grounded in established security research:

• OWASP Top 10 for LLM Applications (2025) — genai.owasp.org
• MITRE ATLAS — atlas.mitre.org
• CWE (Common Weakness Enumeration) — cwe.mitre.org
• NIST AI 100-2 — Adversarial Machine Learning taxonomy
• Greshake et al. (2023) — "Not what you've signed up for" — arXiv:2302.12173
• Liu et al. (2024) — "Automatic and Universal Prompt Injection" — arXiv:2403.04957
• Invariant Labs (2024) — "Tool Poisoning Attacks on MCP Servers" — invariantlabs.ai

For a detailed mapping of each rule to its standards, see docs/rules.md.

🤝 Contributing

We especially welcome:

• New detection rules (with CWE/OWASP mapping)
• False positive / false negative reports
• Third-party benchmark test results

See CONTRIBUTING.md

🌐 Community & Partners

Links

📦 npm · 📖 Rule Docs · 🤖 GitHub App · 💻 VS Code · 🔌 Integration Guide · 🇨🇳 中文 README

License

MIT