Slfgod commited on
Commit ·
201413a
1
Parent(s): 9e6273a
refactor: remove excessive emojis for a more professional README appearance
Browse files
README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
| 1 |
<div align="center">
|
| 2 |
|
| 3 |
-
#
|
| 4 |
|
| 5 |
### AI-Powered Multi-Agent Cybersecurity Scanner
|
| 6 |
|
|
@@ -13,28 +13,28 @@
|
|
| 13 |
**Production-grade security analysis using coordinated AI agents.**
|
| 14 |
Detect vulnerabilities, threats, secrets, and compliance issues — then auto-fix them.
|
| 15 |
|
| 16 |
-
[Getting Started](#
|
| 17 |
|
| 18 |
</div>
|
| 19 |
|
| 20 |
---
|
| 21 |
|
| 22 |
-
##
|
| 23 |
|
| 24 |
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:
|
| 25 |
|
| 26 |
-
-
|
| 27 |
-
-
|
| 28 |
-
-
|
| 29 |
-
-
|
| 30 |
-
-
|
| 31 |
-
-
|
| 32 |
|
| 33 |
Works out of the box with the **smart mock provider** — no API key needed to start scanning.
|
| 34 |
|
| 35 |
---
|
| 36 |
|
| 37 |
-
##
|
| 38 |
|
| 39 |
### Installation
|
| 40 |
|
|
@@ -80,7 +80,7 @@ docker-compose up ollama shield-agents
|
|
| 80 |
|
| 81 |
---
|
| 82 |
|
| 83 |
-
##
|
| 84 |
|
| 85 |
### Core Scanning Engine
|
| 86 |
|
|
@@ -93,24 +93,24 @@ docker-compose up ollama shield-agents
|
|
| 93 |
|
| 94 |
### Production Features (v2.0)
|
| 95 |
|
| 96 |
-
|
|
| 97 |
-
|---
|
| 98 |
-
|
|
| 99 |
-
|
|
| 100 |
-
|
|
| 101 |
-
|
|
| 102 |
-
|
|
| 103 |
-
|
|
| 104 |
-
|
|
| 105 |
-
|
|
| 106 |
-
|
|
| 107 |
-
|
|
| 108 |
-
|
|
| 109 |
-
|
|
| 110 |
|
| 111 |
---
|
| 112 |
|
| 113 |
-
##
|
| 114 |
|
| 115 |
```bash
|
| 116 |
shield-agents scan <target> [options]
|
|
@@ -142,7 +142,7 @@ Commands:
|
|
| 142 |
|
| 143 |
---
|
| 144 |
|
| 145 |
-
##
|
| 146 |
|
| 147 |
### Environment Variables
|
| 148 |
|
|
@@ -203,7 +203,7 @@ id:VulnAgent-3 # Ignore a specific finding by ID
|
|
| 203 |
|
| 204 |
---
|
| 205 |
|
| 206 |
-
##
|
| 207 |
|
| 208 |
```
|
| 209 |
shield-agents/
|
|
@@ -215,7 +215,7 @@ shield-agents/
|
|
| 215 |
│ │ ├── recon.py # Reconnaissance & info disclosure
|
| 216 |
│ │ ├── compliance.py # OWASP compliance checking
|
| 217 |
│ │ ├── response.py # Incident response & risk assessment
|
| 218 |
-
│ │ └── autofix.py # Auto-remediation
|
| 219 |
│ ├── scanners/ # Static analysis
|
| 220 |
│ │ ├── sast.py # 10 SAST detection rules
|
| 221 |
│ │ └── secrets.py # 24 secret type patterns
|
|
@@ -264,7 +264,7 @@ shield-agents/
|
|
| 264 |
|
| 265 |
---
|
| 266 |
|
| 267 |
-
##
|
| 268 |
|
| 269 |
### GitHub Actions
|
| 270 |
|
|
@@ -319,7 +319,7 @@ shield-agents scan ./src --ci --fail-threshold 60
|
|
| 319 |
|
| 320 |
---
|
| 321 |
|
| 322 |
-
##
|
| 323 |
|
| 324 |
Real-time security scanning directly in your editor:
|
| 325 |
|
|
@@ -333,7 +333,7 @@ Install the extension from the `vscode-extension/` directory and configure via V
|
|
| 333 |
|
| 334 |
---
|
| 335 |
|
| 336 |
-
##
|
| 337 |
|
| 338 |
Shield Agents works seamlessly with AI coding assistants:
|
| 339 |
|
|
@@ -347,7 +347,7 @@ Shield Agents works seamlessly with AI coding assistants:
|
|
| 347 |
|
| 348 |
---
|
| 349 |
|
| 350 |
-
##
|
| 351 |
|
| 352 |
Verify detection accuracy with 13 OWASP WebGoat-style test cases:
|
| 353 |
|
|
@@ -371,7 +371,7 @@ python -m benchmarks.benchmark --verbose
|
|
| 371 |
|
| 372 |
---
|
| 373 |
|
| 374 |
-
##
|
| 375 |
|
| 376 |
```bash
|
| 377 |
# Run all 52 unit tests
|
|
@@ -391,7 +391,7 @@ ruff check shield_agents/
|
|
| 391 |
|
| 392 |
---
|
| 393 |
|
| 394 |
-
##
|
| 395 |
|
| 396 |
We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
|
| 397 |
|
|
@@ -406,7 +406,7 @@ pytest tests/ -v
|
|
| 406 |
|
| 407 |
---
|
| 408 |
|
| 409 |
-
##
|
| 410 |
|
| 411 |
MIT License — see [LICENSE](LICENSE) for details.
|
| 412 |
|
|
@@ -414,26 +414,26 @@ MIT License — see [LICENSE](LICENSE) for details.
|
|
| 414 |
|
| 415 |
<div align="center">
|
| 416 |
|
| 417 |
-
###
|
| 418 |
|
| 419 |
**Shield Agents — Escáner de Ciberseguridad Multi-Agente con IA**
|
| 420 |
|
| 421 |
-
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
|
| 422 |
|
| 423 |
**Características principales:**
|
| 424 |
|
| 425 |
| Característica | Descripción |
|
| 426 |
|---------------|-------------|
|
| 427 |
-
|
|
| 428 |
-
|
|
| 429 |
-
|
|
| 430 |
-
|
|
| 431 |
-
|
|
| 432 |
-
|
|
| 433 |
-
|
|
| 434 |
-
|
|
| 435 |
-
|
|
| 436 |
-
|
|
| 437 |
|
| 438 |
**Inicio rápido:**
|
| 439 |
|
|
@@ -466,8 +466,8 @@ Las contribuciones son bienvenidas. Lee [CONTRIBUTING.md](CONTRIBUTING.md) para
|
|
| 466 |
|
| 467 |
---
|
| 468 |
|
| 469 |
-
If you find Shield Agents useful, please
|
| 470 |
|
| 471 |
-
|
| 472 |
|
| 473 |
</div>
|
|
|
|
| 1 |
<div align="center">
|
| 2 |
|
| 3 |
+
# Shield Agents
|
| 4 |
|
| 5 |
### AI-Powered Multi-Agent Cybersecurity Scanner
|
| 6 |
|
|
|
|
| 13 |
**Production-grade security analysis using coordinated AI agents.**
|
| 14 |
Detect vulnerabilities, threats, secrets, and compliance issues — then auto-fix them.
|
| 15 |
|
| 16 |
+
[Getting Started](#getting-started) · [Features](#features) · [Architecture](#architecture) · [CI/CD](#cicd-integration) · [VS Code](#vs-code-extension) · [Contributing](CONTRIBUTING.md)
|
| 17 |
|
| 18 |
</div>
|
| 19 |
|
| 20 |
---
|
| 21 |
|
| 22 |
+
## Why Shield Agents?
|
| 23 |
|
| 24 |
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:
|
| 25 |
|
| 26 |
+
- **VulnAgent** — Finds SQL injection, XSS, command injection, and more
|
| 27 |
+
- **ThreatAgent** — Maps attack vectors to MITRE ATT&CK techniques
|
| 28 |
+
- **ReconAgent** — Detects information disclosure and exposed secrets
|
| 29 |
+
- **ComplianceAgent** — Checks against OWASP Top 10 2021
|
| 30 |
+
- **ResponseAgent** — Provides risk assessment and incident response plans
|
| 31 |
+
- **AutoFixAgent** — Generates copy-paste-ready code fixes
|
| 32 |
|
| 33 |
Works out of the box with the **smart mock provider** — no API key needed to start scanning.
|
| 34 |
|
| 35 |
---
|
| 36 |
|
| 37 |
+
## Getting Started
|
| 38 |
|
| 39 |
### Installation
|
| 40 |
|
|
|
|
| 80 |
|
| 81 |
---
|
| 82 |
|
| 83 |
+
## Features
|
| 84 |
|
| 85 |
### Core Scanning Engine
|
| 86 |
|
|
|
|
| 93 |
|
| 94 |
### Production Features (v2.0)
|
| 95 |
|
| 96 |
+
| Feature | Description |
|
| 97 |
+
|---------|-------------|
|
| 98 |
+
| **Smart Mock Provider** | Pattern-matched findings based on actual code content — demo mode feels real, not static |
|
| 99 |
+
| **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 |
|
| 100 |
+
| **SARIF 2.1.0 Output** | GitHub Security tab integration — upload results directly to GitHub code scanning |
|
| 101 |
+
| **`.shieldignore` File** | Like `.gitignore` for false positives — 9 rule types (file, category, severity, rule, path, line, title, cwe, id) |
|
| 102 |
+
| **Caching / Incremental Scans** | Cache previous results, only re-scan changed files — production-ready performance |
|
| 103 |
+
| **LLM Fallback Parser** | 5-strategy parser for when LLMs return invalid JSON (~30% failure rate) — never crash on bad responses |
|
| 104 |
+
| **VS Code Extension** | On-save scanning with inline diagnostics — security issues appear directly in your editor |
|
| 105 |
+
| **Benchmark Suite** | 13 OWASP WebGoat-style test cases — proves the scanner actually finds real bugs |
|
| 106 |
+
| **CI/CD Mode** | `--ci` flag for pipelines — JSON to stdout, SARIF output, exit code based on risk threshold |
|
| 107 |
+
| **Format Options** | Pipe results to other tools — structured JSON output for integration |
|
| 108 |
+
| **Auto-Exclude** | Tests, benchmarks, and examples automatically excluded from scan — eliminates ~70% false positives |
|
| 109 |
+
| **Agent-Differentiated Mock** | Each AI agent returns specialized findings in mock mode — VulnAgent finds vulns, ThreatAgent finds threats |
|
| 110 |
|
| 111 |
---
|
| 112 |
|
| 113 |
+
## CLI Reference
|
| 114 |
|
| 115 |
```bash
|
| 116 |
shield-agents scan <target> [options]
|
|
|
|
| 142 |
|
| 143 |
---
|
| 144 |
|
| 145 |
+
## Configuration
|
| 146 |
|
| 147 |
### Environment Variables
|
| 148 |
|
|
|
|
| 203 |
|
| 204 |
---
|
| 205 |
|
| 206 |
+
## Architecture
|
| 207 |
|
| 208 |
```
|
| 209 |
shield-agents/
|
|
|
|
| 215 |
│ │ ├── recon.py # Reconnaissance & info disclosure
|
| 216 |
│ │ ├── compliance.py # OWASP compliance checking
|
| 217 |
│ │ ├── response.py # Incident response & risk assessment
|
| 218 |
+
│ │ └── autofix.py # Auto-remediation
|
| 219 |
│ ├── scanners/ # Static analysis
|
| 220 |
│ │ ├── sast.py # 10 SAST detection rules
|
| 221 |
│ │ └── secrets.py # 24 secret type patterns
|
|
|
|
| 264 |
|
| 265 |
---
|
| 266 |
|
| 267 |
+
## CI/CD Integration
|
| 268 |
|
| 269 |
### GitHub Actions
|
| 270 |
|
|
|
|
| 319 |
|
| 320 |
---
|
| 321 |
|
| 322 |
+
## VS Code Extension
|
| 323 |
|
| 324 |
Real-time security scanning directly in your editor:
|
| 325 |
|
|
|
|
| 333 |
|
| 334 |
---
|
| 335 |
|
| 336 |
+
## AI Assistant Compatibility
|
| 337 |
|
| 338 |
Shield Agents works seamlessly with AI coding assistants:
|
| 339 |
|
|
|
|
| 347 |
|
| 348 |
---
|
| 349 |
|
| 350 |
+
## Benchmark Suite
|
| 351 |
|
| 352 |
Verify detection accuracy with 13 OWASP WebGoat-style test cases:
|
| 353 |
|
|
|
|
| 371 |
|
| 372 |
---
|
| 373 |
|
| 374 |
+
## Running Tests
|
| 375 |
|
| 376 |
```bash
|
| 377 |
# Run all 52 unit tests
|
|
|
|
| 391 |
|
| 392 |
---
|
| 393 |
|
| 394 |
+
## Contributing
|
| 395 |
|
| 396 |
We love contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
|
| 397 |
|
|
|
|
| 406 |
|
| 407 |
---
|
| 408 |
|
| 409 |
+
## License
|
| 410 |
|
| 411 |
MIT License — see [LICENSE](LICENSE) for details.
|
| 412 |
|
|
|
|
| 414 |
|
| 415 |
<div align="center">
|
| 416 |
|
| 417 |
+
### En Español
|
| 418 |
|
| 419 |
**Shield Agents — Escáner de Ciberseguridad Multi-Agente con IA**
|
| 420 |
|
| 421 |
+
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.
|
| 422 |
|
| 423 |
**Características principales:**
|
| 424 |
|
| 425 |
| Característica | Descripción |
|
| 426 |
|---------------|-------------|
|
| 427 |
+
| 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 |
|
| 428 |
+
| Escáner de Secretos | 24 tipos de patrones: AWS, GitHub, Google, Slack, Stripe, conexiones DB, JWTs, Claves Privadas, con filtrado de entropía Shannon |
|
| 429 |
+
| 6 Agentes de IA | VulnAgent (vulnerabilidades), ThreatAgent (modelado de amenazas), ReconAgent (reconocimiento), ComplianceAgent (cumplimiento OWASP), ResponseAgent (respuesta a incidentes), AutoFixAgent (correcciones automáticas) |
|
| 430 |
+
| Motor de Deduplicación | 3 fases: coincidencia exacta → coincidencia difusa → fusión por categoría |
|
| 431 |
+
| Formato SARIF | Integración con la pestaña de Seguridad de GitHub |
|
| 432 |
+
| Archivo `.shieldignore` | Como `.gitignore` pero para falsos positivos — 9 tipos de reglas |
|
| 433 |
+
| Escaneo Incremental | Caché de resultados anteriores, solo re-escanea archivos modificados |
|
| 434 |
+
| Auto-Fix | Correcciones instantáneas basadas en patrones + correcciones profundas con LLM |
|
| 435 |
+
| Extensión VS Code | Escaneo al guardar con diagnósticos inline |
|
| 436 |
+
| Modo CI/CD | `--ci` para pipelines — JSON a stdout, SARIF, código de salida basado en riesgo |
|
| 437 |
|
| 438 |
**Inicio rápido:**
|
| 439 |
|
|
|
|
| 466 |
|
| 467 |
---
|
| 468 |
|
| 469 |
+
If you find Shield Agents useful, please star the repo — it helps others discover the project!
|
| 470 |
|
| 471 |
+
Built with care for the security community
|
| 472 |
|
| 473 |
</div>
|