Production-grade security analysis using coordinated AI agents.
Detect vulnerabilities, threats, secrets, and compliance issues — then auto-fix them.
Getting Started · Features · Architecture · CI/CD · VS Code · Contributing
Most security scanners just find problems. Shield Agents finds AND fixes them using a team of specialized AI agents that work together like a real security team:
- VulnAgent — Finds SQL injection, XSS, command injection, and more
- ThreatAgent — Maps attack vectors to MITRE ATT&CK techniques
- ReconAgent — Detects information disclosure and exposed secrets
- ComplianceAgent — Checks against OWASP Top 10 2021
- ResponseAgent — Provides risk assessment and incident response plans
- AutoFixAgent — Generates copy-paste-ready code fixes
Works out of the box with the smart mock provider — no API key needed to start scanning.
# Install from source (mock provider included - no API key needed)
pip install -e .
# With OpenAI support
pip install -e ".[openai]"
# With all LLM providers (OpenAI + Anthropic + Ollama)
pip install -e ".[all]"
# With development tools
pip install -e ".[dev]"# Scan a project (uses smart mock provider by default)
shield-agents scan ./my-project
# Scan with auto-fix suggestions
shield-agents scan ./my-project --fix
# Full scan (ignore cache, scan everything)
shield-agents scan ./my-project --full
# Initialize configuration files
shield-agents init# Build and scan
docker-compose up shield-agents
# With Ollama for local LLM
docker-compose up ollama shield-agents| Feature | Details |
|---|---|
| SAST Scanner | 10 detection rules: SQL Injection, XSS, Command Injection, Path Traversal, Insecure Deserialization, Weak Crypto, Auth Issues, Hardcoded Credentials, SSL/TLS Issues, SSRF |
| Secrets Scanner | 24 pattern types: AWS, GitHub, Google, Slack, Stripe, DB connections, JWTs, Private Keys, and generic secrets with Shannon entropy filtering |
| 6 AI Agents | VulnAgent, ThreatAgent, ReconAgent, ComplianceAgent, ResponseAgent, AutoFixAgent |
| Auto-Fix Engine | Pattern-based instant fixes + LLM-powered deep remediation with copy-paste-ready code |
| Feature | Description |
|---|---|
| Smart Mock Provider | Pattern-matched findings based on actual code content — demo mode feels real, not static |
| Deduplication Engine | 3-phase dedup (exact → fuzzy → category merge) — when VulnAgent and SAST both find "SQL Injection", they merge into one finding with multiple sources |
| SARIF 2.1.0 Output | GitHub Security tab integration — upload results directly to GitHub code scanning |
.shieldignore File |
Like .gitignore for false positives — 9 rule types (file, category, severity, rule, path, line, title, cwe, id) |
| Caching / Incremental Scans | Cache previous results, only re-scan changed files — production-ready performance |
| LLM Fallback Parser | 5-strategy parser for when LLMs return invalid JSON (~30% failure rate) — never crash on bad responses |
| VS Code Extension | On-save scanning with inline diagnostics — security issues appear directly in your editor |
| Benchmark Suite | 13 OWASP WebGoat-style test cases — proves the scanner actually finds real bugs |
| CI/CD Mode | --ci flag for pipelines — JSON to stdout, SARIF output, exit code based on risk threshold |
| Format Options | Pipe results to other tools — structured JSON output for integration |
| Auto-Exclude | Tests, benchmarks, and examples automatically excluded from scan — eliminates ~70% false positives |
| Agent-Differentiated Mock | Each AI agent returns specialized findings in mock mode — VulnAgent finds vulns, ThreatAgent finds threats |
shield-agents scan <target> [options]
Options:
--config, -c Path to config YAML file
--full Full scan (ignore cache)
--fix Generate auto-fix suggestions
--no-report Skip report generation
--sarif-only Output only SARIF format
--output, -o Output directory for reports
--provider LLM provider: mock, openai, anthropic, ollama
--format, -f Output format: rich, json, sarif, plain (default: rich)
--ci CI/CD mode: silent except JSON on stdout
--fail-threshold Risk score threshold for CI failure (default: 75)
--no-cache Disable caching
--no-dedup Disable deduplication
--no-ignore Ignore .shieldignore rules
--verbose, -v Verbose output
--debug Debug output
Commands:
scan <target> Run security scan
init Create .shieldignore and config templates
cache --stats Show cache statistics
cache --clear Clear scan cache
version Show version info| Variable | Description | Default |
|---|---|---|
SHIELD_LLM_PROVIDER |
LLM provider (mock, openai, anthropic, ollama) | mock |
SHIELD_LLM_API_KEY |
API key for the LLM provider | None |
SHIELD_LLM_MODEL |
Model name | gpt-4 |
SHIELD_LLM_BASE_URL |
Custom API base URL (for Ollama) | None |
SHIELD_VERBOSE |
Enable verbose output | false |
SHIELD_DEBUG |
Enable debug output | false |
llm:
provider: mock # mock, openai, anthropic, ollama
model: gpt-4
temperature: 0.1
fallback_enabled: true # Robust JSON fallback parser
scanner:
sast_enabled: true
secrets_enabled: true
cache:
enabled: true
incremental: true # Only re-scan changed files
deduplication:
enabled: true
merge_sources: true # Merge duplicate findings from different sources
report:
output_dir: ./shield-reports
formats:
- html
- sarif
- jsonSuppress false positives with 9 rule types:
# Shield Agents Ignore File
category:information-disclosure # Ignore all info-disclosure findings
severity:LOW # Ignore LOW and INFO findings
rule:SAST-001 # Ignore a specific rule
file:test_app.py # Ignore all findings in a file
path:*test* # Ignore findings in test files
line:42:app.py # Ignore finding at specific line
title:Assertion* # Ignore findings with matching title (glob)
cwe:CWE-617 # Ignore findings with matching CWE
id:VulnAgent-3 # Ignore a specific finding by IDshield-agents/
├── shield_agents/
│ ├── agents/ # 6 AI agents
│ │ ├── base.py # Abstract base agent
│ │ ├── vuln.py # Vulnerability detection
│ │ ├── threat.py # Threat modeling & MITRE ATT&CK
│ │ ├── recon.py # Reconnaissance & info disclosure
│ │ ├── compliance.py # OWASP compliance checking
│ │ ├── response.py # Incident response & risk assessment
│ │ └── autofix.py # Auto-remediation
│ ├── scanners/ # Static analysis
│ │ ├── sast.py # 10 SAST detection rules
│ │ └── secrets.py # 24 secret type patterns
│ ├── report/ # Output generation
│ │ ├── generator.py # HTML + JSON reports
│ │ └── sarif.py # SARIF 2.1.0 for GitHub
│ ├── knowledge/ # Security knowledge bases
│ │ ├── owasp.py # OWASP Top 10 2021
│ │ ├── mitre.py # MITRE ATT&CK
│ │ └── cve.py # Known CVE database
│ ├── utils/ # Utilities
│ │ ├── crypto.py # Hashing for cache
│ │ └── helpers.py # File I/O, risk scoring
│ ├── config.py # Configuration management
│ ├── llm.py # LLM providers + 5-strategy fallback parser
│ ├── deduplication.py # 3-phase finding deduplication engine
│ ├── cache.py # Incremental scan caching
│ ├── shieldignore.py # .shieldignore file parser (9 rule types)
│ ├── orchestrator.py # Central coordinator (6-phase pipeline)
│ └── cli.py # Rich-powered CLI
├── vscode-extension/ # VS Code extension
├── benchmarks/ # OWASP-style benchmark suite (13 cases)
├── tests/ # 52 unit tests
├── examples/ # Vulnerable example app
├── .github/ # Issue/PR templates
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contribution guide
└── pyproject.toml # Modern Python packaging
┌─────────────┐ ┌──────────────────┐ ┌───────────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │
│ SAST Scan │──▶│ AI Agent Analysis│──▶│ Deduplication │
│ + Secrets │ │ (4 agents/file) │ │ (3 phases) │
└─────────────┘ └──────────────────┘ └───────────────┘
│
┌─────────────┐ ┌──────────────────┐ ┌───────────────┐
│ Phase 6 │ │ Phase 5 │ │ Phase 4 │
│ Reporting │◀──│ Auto-Fix Gen │◀──│ .shieldignore │
│ HTML/SARIF │ │ (Pattern + LLM) │ │ Filtering │
└─────────────┘ └──────────────────┘ └───────────────┘
name: Security Scan
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install Shield Agents
run: pip install -e .
- name: Run Security Scan
run: shield-agents scan ./src --ci --fail-threshold 75
- name: Upload SARIF
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: shield-reports/results.sarifsecurity-scan:
stage: test
image: python:3.11-slim
script:
- pip install -e .
- shield-agents scan ./src --ci --format json > scan-results.json
artifacts:
paths:
- shield-reports/
reports:
sast: shield-reports/results.sarif# JSON output for any CI system
shield-agents scan ./src --ci --format json
# Exit code: 0 = pass, 1 = risk score exceeds threshold
shield-agents scan ./src --ci --fail-threshold 60Real-time security scanning directly in your editor:
- Scan on Save — Automatically scans files when you save
- Inline Diagnostics — Security findings appear as editor warnings/errors
- Severity Highlighting — Color-coded CRITICAL/HIGH/MEDIUM/LOW indicators
- Quick Fix Suggestions — Remediation advice for each finding
- Workspace Scan — Scan your entire project with one command
Install the extension from the vscode-extension/ directory and configure via VS Code settings.
Shield Agents works seamlessly with AI coding assistants:
| Tool | How to Use |
|---|---|
| Cursor | Add shield-agents scan to .cursorrules for auto-scanning on changes |
| Claude Code | Run shield-agents scan in terminal, integrate findings into workflow |
| GitHub Copilot | VS Code extension provides inline security diagnostics alongside Copilot |
| Aider | Use --fix mode and pipe auto-fix suggestions for code modifications |
| Windsurf | CLI-based integration via terminal |
Verify detection accuracy with 13 OWASP WebGoat-style test cases:
python -m benchmarks.benchmark --verbose| Category | Test Cases |
|---|---|
| SQL Injection | String concat, format strings |
| XSS | DOM-based, template injection |
| Command Injection | os.system, subprocess |
| Path Traversal | User-controlled file paths |
| Insecure Deserialization | pickle, yaml, marshal |
| Weak Cryptography | MD5, SHA-1, random module |
| Hardcoded Secrets | Passwords, API keys, AWS credentials |
| SSL/TLS Issues | verify=False, unverified context |
| SSRF | User-controlled URLs |
| Auth Bypass | Assertion-based, session manipulation |
| Clean Code | Negative test (minimal findings) |
# Run all 52 unit tests
pytest tests/ -v
# Run specific test module
pytest tests/test_sast.py -v
pytest tests/test_secrets.py -v
pytest tests/test_llm.py -v
# Run benchmarks
python -m benchmarks.benchmark --verbose
# Lint
ruff check shield_agents/We love contributions! See CONTRIBUTING.md for detailed guidelines.
Quick start:
git clone https://github.com/shield-agents/shield-agents.git
cd shield-agents
pip install -e ".[dev]"
pytest tests/ -vMIT License — see LICENSE for details.
Shield Agents — Escáner de Ciberseguridad Multi-Agente con IA
Shield Agents es una plataforma de análisis de seguridad de grado producción que utiliza agentes de IA coordinados para detectar vulnerabilidades, amenazas, secretos y problemas de cumplimiento.
Características principales:
| Característica | Descripción |
|---|---|
| Escáner SAST | 10 reglas de detección: Inyección SQL, XSS, Inyección de Comandos, Path Traversal, Deserialización Insegura, Criptografía Débil, Problemas de Autenticación, Credenciales hardcodeadas, Problemas SSL/TLS, SSRF |
| Escáner de Secretos | 24 tipos de patrones: AWS, GitHub, Google, Slack, Stripe, conexiones DB, JWTs, Claves Privadas, con filtrado de entropía Shannon |
| 6 Agentes de IA | VulnAgent (vulnerabilidades), ThreatAgent (modelado de amenazas), ReconAgent (reconocimiento), ComplianceAgent (cumplimiento OWASP), ResponseAgent (respuesta a incidentes), AutoFixAgent (correcciones automáticas) |
| Motor de Deduplicación | 3 fases: coincidencia exacta → coincidencia difusa → fusión por categoría |
| Formato SARIF | Integración con la pestaña de Seguridad de GitHub |
Archivo .shieldignore |
Como .gitignore pero para falsos positivos — 9 tipos de reglas |
| Escaneo Incremental | Caché de resultados anteriores, solo re-escanea archivos modificados |
| Auto-Fix | Correcciones instantáneas basadas en patrones + correcciones profundas con LLM |
| Extensión VS Code | Escaneo al guardar con diagnósticos inline |
| Modo CI/CD | --ci para pipelines — JSON a stdout, SARIF, código de salida basado en riesgo |
Inicio rápido:
# Instalar (proveedor mock incluido — sin API key necesario)
pip install -e .
# Escanear un proyecto
shield-agents scan ./mi-proyecto
# Escanear con sugerencias de corrección automática
shield-agents scan ./mi-proyecto --fix
# Modo CI/CD
shield-agents scan ./src --ci --fail-threshold 75
# Inicializar configuración
shield-agents initCompatibilidad con asistentes de IA:
Shield Agents es compatible con Cursor, Claude Code, GitHub Copilot, Aider y Windsurf. Funciona como una herramienta CLI estándar que se integra en cualquier flujo de trabajo de desarrollo.
Contribuir:
Las contribuciones son bienvenidas. Lee CONTRIBUTING.md para las guías detalladas. Los reportes de bugs, solicitudes de funcionalidades y pull requests son apreciados.
Licencia: MIT
If you find Shield Agents useful, please star the repo — it helps others discover the project!
Built with care for the security community