Slfgod/shield-agents

Shield Agents

AI-Powered Multi-Agent Cybersecurity Scanner

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

---

Why Shield Agents?

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.

---

Getting Started

Installation

# 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]"

Your First Scan

# 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

Docker

# Build and scan
docker-compose up shield-agents

# With Ollama for local LLM
docker-compose up ollama shield-agents

---

Features

Core Scanning Engine

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

Production Features (v2.0)

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

---

CLI Reference

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

---

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)

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:

# 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

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

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)

# 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:

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

# 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 for detailed guidelines.

Quick start:

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 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:

# 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 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