Run security scan
init Create .shieldignore and config templates
cache --stats Show cache statistics
cache --clear Clear scan cache
version Show version info
```
---
## Configuration
### Environment Variables
| 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` |
### Config File (`config.yaml`)
```yaml
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
- json
```
### `.shieldignore` File
Suppress false positives with 9 rule types:
```gitignore
# 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 ID
```
---
## Architecture
```
shield-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
```
### 6-Phase Scan Pipeline
```
┌─────────────┐ ┌──────────────────┐ ┌───────────────┐
│ 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 │
└─────────────┘ └──────────────────┘ └───────────────┘
```
---
## CI/CD Integration
### GitHub Actions
```yaml
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.sarif
```
### GitLab CI
```yaml
security-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
```
### Generic Pipeline (JSON to stdout)
```bash
# 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 60
```
---
## VS Code Extension
Real-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.
---
## AI Assistant Compatibility
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 |
---
## Benchmark Suite
Verify detection accuracy with 13 OWASP WebGoat-style test cases:
```bash
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) |
---
## Running Tests
```bash
# 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/
```
---
## Contributing
We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
Quick start:
```bash
git clone https://github.com/shield-agents/shield-agents.git
cd shield-agents
pip install -e ".[dev]"
pytest tests/ -v
```
---
## License
MIT License — see [LICENSE](LICENSE) for details.
---
### En Español
**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:**
```bash
# 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 init
```
**Compatibilidad 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](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