Slfgod

refactor: remove excessive emojis for a more professional README appearance

201413a 5 months ago

17.6 kB

<div align="center">

# Shield Agents

### AI-Powered Multi-Agent Cybersecurity Scanner

[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-ff6b6b?style=for-the-badge)](https://github.com/astral-sh/ruff)
[![Tests: 52](https://img.shields.io/badge/tests-52%20passing-brightgreen?style=for-the-badge)]()
[![Benchmarks: 13/13](https://img.shields.io/badge/benchmarks-13%2F13-brightgreen?style=for-the-badge)]()

**Production-grade security analysis using coordinated AI agents.**  
Detect vulnerabilities, threats, secrets, and compliance issues — then auto-fix them.

[Getting Started](#getting-started) · [Features](#features) · [Architecture](#architecture) · [CI/CD](#cicd-integration) · [VS Code](#vs-code-extension) · [Contributing](CONTRIBUTING.md)

</div>

---

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

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

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

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

```bash
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`)

```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.

---

<div align="center">

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

</div>

	<div align="center">

	# Shield Agents

	### AI-Powered Multi-Agent Cybersecurity Scanner

	[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
	[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
	[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-ff6b6b?style=for-the-badge)](https://github.com/astral-sh/ruff)
	[![Tests: 52](https://img.shields.io/badge/tests-52%20passing-brightgreen?style=for-the-badge)]()
	[![Benchmarks: 13/13](https://img.shields.io/badge/benchmarks-13%2F13-brightgreen?style=for-the-badge)]()

	Production-grade security analysis using coordinated AI agents.
	Detect vulnerabilities, threats, secrets, and compliance issues — then auto-fix them.

	[Getting Started](#getting-started) · [Features](#features) · [Architecture](#architecture) · [CI/CD](#cicd-integration) · [VS Code](#vs-code-extension) · [Contributing](CONTRIBUTING.md)

	</div>

	---

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

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

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

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

	```bash
	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`)

	```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.

	---

	<div align="center">

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

	</div>