Slfgod commited on
Commit
201413a
·
1 Parent(s): 9e6273a

refactor: remove excessive emojis for a more professional README appearance

Browse files
Files changed (1) hide show
  1. README.md +50 -50
README.md CHANGED
@@ -1,6 +1,6 @@
1
  <div align="center">
2
 
3
- # 🛡️ Shield Agents
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](#-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** — The "Master White Hat Hacker" that 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,7 +80,7 @@ docker-compose up ollama shield-agents
80
 
81
  ---
82
 
83
- ## 🛡️ Features
84
 
85
  ### Core Scanning Engine
86
 
@@ -93,24 +93,24 @@ docker-compose up ollama shield-agents
93
 
94
  ### Production Features (v2.0)
95
 
96
- | # | Feature | Description |
97
- |---|---------|-------------|
98
- | 1 | **Smart Mock Provider** | Pattern-matched findings based on actual code content — demo mode feels real, not static |
99
- | 2 | **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
- | 3 | **SARIF 2.1.0 Output** | GitHub Security tab integration — upload results directly to GitHub code scanning |
101
- | 4 | **`.shieldignore` File** | Like `.gitignore` for false positives — 9 rule types (file, category, severity, rule, path, line, title, cwe, id) |
102
- | 5 | **Caching / Incremental Scans** | Cache previous results, only re-scan changed files — production-ready performance |
103
- | 6 | **LLM Fallback Parser** | 5-strategy parser for when LLMs return invalid JSON (~30% failure rate) — never crash on bad responses |
104
- | 7 | **VS Code Extension** | On-save scanning with inline diagnostics — security issues appear directly in your editor |
105
- | 8 | **Benchmark Suite** | 13 OWASP WebGoat-style test cases — proves the scanner actually finds real bugs |
106
- | 9 | **CI/CD Mode** | `--ci` flag for pipelines — JSON to stdout, SARIF output, exit code based on risk threshold |
107
- | 10 | **`--format json`** | Pipe results to other tools — structured JSON output for integration |
108
- | 11 | **Auto-Exclude** | Tests, benchmarks, and examples automatically excluded from scan — eliminates ~70% false positives |
109
- | 12 | **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,7 +142,7 @@ Commands:
142
 
143
  ---
144
 
145
- ## ⚙️ Configuration
146
 
147
  ### Environment Variables
148
 
@@ -203,7 +203,7 @@ id:VulnAgent-3 # Ignore a specific finding by ID
203
 
204
  ---
205
 
206
- ## 🏗️ Architecture
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 (Master White Hat Hacker)
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
- ## 🔄 CI/CD Integration
268
 
269
  ### GitHub Actions
270
 
@@ -319,7 +319,7 @@ shield-agents scan ./src --ci --fail-threshold 60
319
 
320
  ---
321
 
322
- ## 💻 VS Code Extension
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
- ## 🤖 AI Assistant Compatibility
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
- ## 📊 Benchmark Suite
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
- ## 🧪 Running Tests
375
 
376
  ```bash
377
  # Run all 52 unit tests
@@ -391,7 +391,7 @@ ruff check shield_agents/
391
 
392
  ---
393
 
394
- ## 🤝 Contributing
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
- ## 📄 License
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
- ### 🌐 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 en tu código fuente. No solo encuentra los problemas — los **arregla automáticamente**.
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, 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 (corrección automática — el "Hacker Ético Maestro") |
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,8 +466,8 @@ Las contribuciones son bienvenidas. Lee [CONTRIBUTING.md](CONTRIBUTING.md) para
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>
 
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>