Metadata-Version: 2.4
Name: zyron-agentshield
Version: 1.0.0
Summary: Professional DAST & Pentest Framework
Home-page: https://github.com/zyron-security/agentshield
Author: Zyron Security
Author-email: security@zyron.io
Keywords: security pentesting dast vulnerability-scanning web-security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: click>=8.1.7
Requires-Dist: fpdf2>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: fonttools>=4.40.0
Requires-Dist: xmltodict>=0.13.0
Provides-Extra: ai
Requires-Dist: crewai>=0.28.0; extra == "ai"
Requires-Dist: anthropic>=0.25.0; extra == "ai"
Provides-Extra: browser
Requires-Dist: playwright>=1.44.0; extra == "browser"
Provides-Extra: full
Requires-Dist: crewai>=0.28.0; extra == "full"
Requires-Dist: anthropic>=0.25.0; extra == "full"
Requires-Dist: playwright>=1.44.0; extra == "full"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

```
 █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗██╗  ██╗██╗███████╗██╗     ██████╗
██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝██║  ██║██║██╔════╝██║     ██╔══██╗
███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗███████║██║█████╗  ██║     ██║  ██║
██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║██╔══██║██║██╔══╝  ██║     ██║  ██║
██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║██║  ██║██║███████╗███████╗██████╔╝
╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚═════╝
```

**Professional DAST & Pentest Framework — from passive posture scanning to active AI-powered attack simulation.**

[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge)](LICENSE)
[![Status](https://img.shields.io/badge/Status-Beta-f59e0b?style=for-the-badge)](https://github.com/zyron-security/agentshield)
[![Made by](https://img.shields.io/badge/Made%20by-Zyron%20Security-6366f1?style=for-the-badge)](https://zyron.security)
[![AI Powered](https://img.shields.io/badge/AI-Claude%20%2B%20CrewAI-e11d48?style=for-the-badge&logo=anthropic&logoColor=white)](https://anthropic.com)
[![DAST](https://img.shields.io/badge/Type-DAST%20%2F%20Pentest-0ea5e9?style=for-the-badge)](https://github.com/zyron-security/agentshield)

</div>

---

## 🛡️ What is AgentShield?

AgentShield is a **professional-grade Dynamic Application Security Testing (DAST) and Penetration Testing framework** built from the ground up by Zyron Security. Unlike traditional scanners that stop at header audits and signature matching, AgentShield actively attacks your applications — probing for SQL injection, cross-site scripting, command injection, path traversal, and advanced logic flaws using a payload library of 160+ real-world attack vectors. It does not just report *what might be wrong*; it confirms what *is actually exploitable*.

Built for **security professionals, penetration testers, and DevSecOps teams**, AgentShield bridges the gap between point-and-click web scanners and manual exploitation workflows. It integrates a full deep crawler (including Playwright-powered SPA traversal and Swagger/GraphQL endpoint discovery), a layered passive analyzer, an active fuzzing engine, and an AI intelligence layer powered by CrewAI and Anthropic Claude — making it the only open-source DAST tool capable of reasoning about business logic flaws, IDOR chains, and BOLA vulnerabilities at scale.

What sets AgentShield apart from the competition is its **AI-first design philosophy**. False positives are the single largest failure mode of automated security tooling — they erode trust, waste triage time, and obscure real findings. AgentShield's AI layer acts as a senior AppSec analyst: it cross-correlates findings, understands application context, filters noise, detects IDOR candidates by reasoning about object reference patterns, and generates executive-ready reports with full remediation guidance. The result is a tool that competes directly with Burp Suite Professional, Invicti, and Acunetix — at zero licensing cost.

---

## ⚡ Feature Matrix

| Feature | AgentShield | Burp Suite Pro | Acunetix | OWASP ZAP |
|---|:---:|:---:|:---:|:---:|
| Passive Header Scan | ✅ | ✅ | ✅ | ✅ |
| Cookie Security Flags | ✅ | ✅ | ✅ | ✅ |
| TLS/SSL Analysis | ✅ | ✅ | ✅ | ✅ |
| Active SQL Injection | ✅ | ✅ | ✅ | ✅ |
| XSS Detection | ✅ | ✅ | ✅ | ✅ |
| Command Injection | ✅ | ✅ | ✅ | ⚠️ |
| Path Traversal | ✅ | ✅ | ✅ | ✅ |
| **AI False Positive Reduction** | ✅ | ❌ | ❌ | ❌ |
| **Business Logic IDOR** | ✅ AI | ⚠️ Manual | ❌ | ❌ |
| **BOLA / Privilege Escalation** | ✅ AI | ⚠️ Manual | ❌ | ❌ |
| WAF Evasion Testing | ✅ | ✅ | ✅ | ⚠️ |
| Playwright SPA Crawler | ✅ | ✅ | ✅ | ⚠️ |
| Swagger / GraphQL Discovery | ✅ | ✅ | ✅ | ⚠️ |
| **CI/CD Pipeline Breaker** | ✅ | ❌ | ❌ | ✅ |
| **Jira Auto-Tickets** | ✅ | ❌ | ✅ | ❌ |
| **Historical Diff Tracking** | ✅ | ❌ | ✅ | ❌ |
| HTML + PDF Reports | ✅ | ✅ | ✅ | ✅ |
| **Executive AI Summary** | ✅ | ❌ | ❌ | ❌ |
| Open Source | ✅ | ❌ | ❌ | ✅ |
| **Cost** | **Free** | $449/yr | $$$$ | Free |

---

## 🏗️ Architecture

AgentShield is organized around five pillars that mirror the stages of a professional penetration test: discovery, passive analysis, active exploitation, AI reasoning, and reporting.

### The Five Pillars

**1. Passive Scanner** — Audits HTTP security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, X-XSS-Protection), cookie security attributes (Secure, HttpOnly, SameSite), CORS policy misconfigurations, TLS/SSL cipher and certificate issues, and information disclosure in response headers and error pages. No traffic is sent that could trigger application state changes.

**2. Active Attack Engine** — Executes a controlled fuzzing campaign using 160+ categorized payloads covering SQL injection (50+ vectors including time-based blind and out-of-band), XSS (50+ vectors including DOM-based and polyglots), OS command injection (30+ vectors), path traversal (20+ vectors), and WAF evasion variants (encoding, fragmentation, case mutation, Unicode normalization). Findings are confirmed via response analysis, time-delay detection, and out-of-band callback verification.

**3. Deep Crawler** — Discovers the full attack surface before scanning begins. Parses `sitemap.xml`, `robots.txt`, and HTML link graphs. Launches a headless Playwright browser to execute JavaScript-heavy SPAs and capture dynamically rendered routes. Probes well-known Swagger UI and OpenAPI paths. Introspects GraphQL schemas. Discovers and categorizes HTML forms, API endpoints, and file upload surfaces.

**4. AI Intelligence Layer** — A multi-agent pipeline built on CrewAI and Anthropic Claude. The AppSec Agent reviews raw findings and filters false positives using application context. The IDOR Detector identifies numeric and UUID-based object reference patterns across all discovered endpoints, generates test requests as alternate users, and confirms exploitability. The Privilege Escalation Agent probes role-sensitive parameters. The Reporting Agent synthesizes all confirmed findings into an executive summary with CVSS scores and prioritized remediation steps.

**5. DevSecOps Integration** — Designed to run inside CI/CD pipelines. Exits with a non-zero code when findings exceed a configurable severity threshold, breaking the pipeline on critical findings. Automatically creates Jira tickets for confirmed vulnerabilities with full reproduction steps. Persists scan results to disk and computes diffs between successive scans to surface new findings and track remediation progress.

### System Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                       AgentShield v1.0                          │
│                    Zyron Security Platform                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
   ┌──────────────────────────────────────────────────────────┐
   │                     CRAWL PHASE                          │
   │                                                          │
   │   Sitemap XML  •  robots.txt  •  HTML Link Graph         │
   │   Playwright SPA Spider  •  Swagger / OpenAPI Probe      │
   │   GraphQL Introspection  •  Form & Input Discovery       │
   └──────────────────────────────────────────────────────────┘
                              │
               ┌──────────────┴──────────────┐
               ▼                             ▼
┌──────────────────────┐       ┌──────────────────────────────┐
│    PASSIVE PHASE     │       │        ACTIVE PHASE          │
│                      │       │                              │
│  • 7 Security Headers│       │  • SQLi  (50+ payloads)      │
│  • Cookie Flags      │       │  • XSS   (50+ payloads)      │
│  • CORS Policy       │       │  • CMDi  (30+ payloads)      │
│  • TLS / SSL Audit   │       │  • Path Traversal (20+)      │
│  • Info Disclosure   │       │  • WAF Evasion Variants      │
│  • HTTP Methods      │       │  • Open Redirect             │
│  • Error Disclosure  │       │  • SSRF Probes               │
└──────────────────────┘       └──────────────────────────────┘
               │                             │
               └──────────────┬──────────────┘
                              ▼
               ┌──────────────────────────────┐
               │      AI ANALYSIS LAYER       │
               │                              │
               │  AppSec Agent  (Claude)      │
               │  ├─ False Positive Filter    │
               │  ├─ CVSS Scoring             │
               │  └─ Remediation Guidance     │
               │                              │
               │  IDOR / BOLA Detector        │
               │  ├─ Object Ref Enumeration   │
               │  ├─ Cross-User Validation    │
               │  └─ Privilege Escalation     │
               │                              │
               │  Reporting Agent             │
               │  └─ Executive Summary        │
               └──────────────────────────────┘
                              │
                              ▼
   ┌──────────────────────────────────────────────────────────┐
   │                 OUTPUT & INTEGRATIONS                    │
   │                                                          │
   │   HTML Report (dark)     PDF Report     JSON (raw)       │
   │   Jira Auto-Tickets      GitHub Actions (exit codes)     │
   │   Historical Diff        Slack Webhook  (optional)       │
   └──────────────────────────────────────────────────────────┘
```

---

## 📦 Installation

### Prerequisites

- Python 3.11 or higher
- pip / virtualenv
- (Optional) Playwright Chromium — required for SPA crawling
- (Optional) Anthropic API key — required for AI features

### Basic Install (Passive Scanning Only)

```bash
# Clone the repository
git clone https://github.com/zyron-security/agentshield.git
cd agentshield

# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install in editable mode — passive scanner + active fuzzer
pip install -e .
```

### Full Install (AI + Browser + All Features)

```bash
# Install all optional dependencies
pip install -e ".[full]"

# Install Playwright's Chromium browser
playwright install chromium

# Copy and configure the environment file
cp .env.example .env
```

Edit `.env` and supply your credentials:

```env
# Required for AI features
ANTHROPIC_API_KEY=sk-ant-...

# Optional: Jira integration
JIRA_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=security@yourcompany.com
JIRA_API_TOKEN=...
JIRA_PROJECT_KEY=SEC

# Optional: Slack webhook for notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
```

### Docker (Recommended for CI/CD)

```bash
docker pull zyron/agentshield:latest

docker run --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd)/reports:/app/reports \
  zyron/agentshield:latest \
  scan https://target.com --format both
```

---

## 🚀 Quick Start

```bash
# Passive scan only — safe for any authorized target (no active attacks)
agentshield scan https://target.com --passive-only

# Full scan — passive analysis + active fuzzing
agentshield scan https://target.com

# Full scan with AI analysis + dual-format report (HTML + PDF)
agentshield scan https://target.com --format both

# Scan with authentication (JWT bearer token)
agentshield scan https://target.com --auth-token "Bearer eyJhbGci..."

# Scan with cookie-based authentication
agentshield scan https://target.com \
  --auth-cookie "session=abc123; csrftoken=xyz456"

# Scan with Jira integration (auto-creates tickets for findings)
agentshield scan https://target.com \
  --jira-url https://company.atlassian.net \
  --jira-token YOUR_JIRA_API_TOKEN \
  --jira-project SEC

# Compare current scan results with the previous scan
agentshield diff https://target.com

# View scan history for a target
agentshield history https://target.com

# Generate a report from a previous raw JSON result
agentshield report results/scan_20260411_143022.json --format html
```

---

## 📖 CLI Reference

### `agentshield scan`

| Option | Type | Default | Description |
|---|---|---|---|
| `TARGET` | `str` | required | Target URL to scan (must include scheme) |
| `--passive-only` | flag | `False` | Run passive analysis only, skip active fuzzing |
| `--format` | `html\|pdf\|json\|both` | `html` | Output report format |
| `--output-dir` | `path` | `./reports` | Directory for report output |
| `--auth-token` | `str` | — | Authorization header value (e.g. `Bearer <jwt>`) |
| `--auth-cookie` | `str` | — | Cookie header string for authenticated scans |
| `--depth` | `int` | `3` | Maximum crawler depth |
| `--threads` | `int` | `10` | Concurrent request threads |
| `--timeout` | `int` | `10` | HTTP request timeout in seconds |
| `--user-agent` | `str` | AgentShield/1.0 | Custom User-Agent string |
| `--rate-limit` | `int` | `50` | Maximum requests per second |
| `--no-ai` | flag | `False` | Disable AI analysis (faster, no API cost) |
| `--no-crawler` | flag | `False` | Skip crawling, scan provided URL only |
| `--playwright` | flag | `False` | Enable Playwright SPA crawling |
| `--jira-url` | `str` | — | Jira instance base URL |
| `--jira-token` | `str` | — | Jira API token |
| `--jira-project` | `str` | — | Jira project key for ticket creation |
| `--fail-on` | `low\|medium\|high\|critical` | `critical` | Exit code 1 if findings meet or exceed severity |
| `--exclude` | `str` | — | Comma-separated URL patterns to exclude |
| `--headers` | `str` | — | Extra request headers as `Key:Value,Key:Value` |
| `--proxy` | `str` | — | HTTP proxy URL (e.g. `http://127.0.0.1:8080`) |
| `--verbose` | flag | `False` | Print detailed scan progress |

### `agentshield diff`

```bash
agentshield diff TARGET [--since SCAN_ID] [--format html|json]
```

Compares the latest scan against a previous scan for the same target. Outputs new findings, resolved findings, and severity changes.

### `agentshield history`

```bash
agentshield history TARGET [--limit 10]
```

Lists all previous scan results for a target with timestamps, finding counts, and risk scores.

### `agentshield report`

```bash
agentshield report SCAN_JSON [--format html|pdf|both] [--output-dir PATH]
```

Regenerates a report from a raw JSON scan result file.

---

## 🔍 Scan Modules

### 1. Passive Scanner

The passive scanner audits the security posture of HTTP responses without modifying application state. It assigns a risk score from 0 to 100 and flags deviations from OWASP and industry best practices.

**Headers Analyzed:**

| Header | Expected Value | Risk if Missing |
|---|---|---|
| `Content-Security-Policy` | Restrictive policy | HIGH |
| `Strict-Transport-Security` | `max-age≥31536000; includeSubDomains` | HIGH |
| `X-Frame-Options` | `DENY` or `SAMEORIGIN` | MEDIUM |
| `X-Content-Type-Options` | `nosniff` | MEDIUM |
| `Referrer-Policy` | `strict-origin-when-cross-origin` | LOW |
| `Permissions-Policy` | Restrictive permissions | LOW |
| `X-XSS-Protection` | Deprecated — flagged if present with `1; mode=block` | INFO |

**Cookie Flags Checked:**

- `Secure` — cookie must not be transmitted over HTTP
- `HttpOnly` — cookie must not be accessible via JavaScript
- `SameSite` — value must be `Strict` or `Lax`

**Example Passive Output:**

```
[PASSIVE] Content-Security-Policy   MISSING          +10 pts  HIGH
[PASSIVE] Strict-Transport-Security PRESENT          +0  pts  OK
[PASSIVE] CORS Policy               OPEN (*)         +30 pts  CRITICAL
[PASSIVE] session cookie            Missing HttpOnly  +15 pts  HIGH
[PASSIVE] Server header             "Apache/2.4.51"  +5  pts  INFO

Passive Score: 60/100 — ALTO
```

---

### 2. Active Fuzzer

The active fuzzing engine injects payloads into all discovered input vectors: GET/POST parameters, JSON body fields, HTTP headers, path segments, and file upload endpoints.

**Payload Categories:**

| Category | Vectors | Detection Method |
|---|---|---|
| SQL Injection (Error-based) | 20+ | Error string matching |
| SQL Injection (Boolean-blind) | 15+ | Response length differential |
| SQL Injection (Time-based) | 10+ | Response time delta ≥ 5s |
| SQL Injection (Out-of-band) | 5+ | DNS callback (if configured) |
| Reflected XSS | 25+ | Payload echo in response |
| DOM XSS | 15+ | Playwright DOM inspection |
| Stored XSS | 10+ | Subsequent GET response check |
| OS Command Injection | 30+ | Time delta + output matching |
| Path Traversal | 20+ | File content signatures |
| Open Redirect | 15+ | Location header analysis |
| SSRF | 10+ | Internal IP / callback matching |
| WAF Evasion | 20+ | Bypass variants per category |

**WAF Evasion Techniques:**

- URL encoding, double encoding, Unicode normalization
- Case mutation (`sElEcT`, `SeLeCt`)
- Comment injection (`SEL/**/ECT`)
- Null byte insertion (`%00`)
- HTTP parameter pollution
- Chunked transfer encoding abuse
- Header injection variants

---

### 3. AI IDOR Detection

The IDOR Detector is AgentShield's most distinctive feature. It reasons about object reference patterns across all discovered endpoints and autonomously tests for unauthorized access.

**How It Works:**

1. The crawler collects all API endpoints containing numeric IDs or UUIDs.
2. The AI agent identifies likely resource-owner relationships (e.g., `/api/invoices/1024` likely belongs to the authenticated user).
3. It generates test requests for adjacent IDs (`1023`, `1025`) and UUIDs from a pre-seeded list.
4. If the application returns a 200 with a non-empty body (and not the same body as the original), the finding is flagged as a confirmed IDOR.
5. For APIs with a second test account configured (`--auth-token-b`), it cross-validates by confirming that user B's token retrieves user A's resource.

**Example IDOR Finding:**

```
[AI-IDOR] Endpoint: GET /api/faturas/{id}
          Tested:   /api/faturas/1024  → 200 OK (your invoice)
          Probed:   /api/faturas/1025  → 200 OK (another user's invoice)
          Verdict:  CONFIRMED IDOR — object reference not validated server-side
          CVSS:     7.5 HIGH
          Fix:      Validate that the authenticated user owns the requested resource
                    before returning data. Use opaque, non-sequential identifiers.
```

---

### 4. Business Logic Testing

The Privilege Escalation Agent examines request/response cycles for role-sensitive parameters and attempts to elevate privileges by modifying them.

**Techniques:**

- JSON body mutation: `{"role": "user"}` → `{"role": "admin"}`
- Parameter tampering: `?is_admin=false` → `?is_admin=true`
- JWT claim modification (with and without signature bypass)
- Mass assignment probing on PUT/PATCH endpoints
- Forced browsing to admin-prefixed routes

**Example Finding:**

```
[AI-PRIV] Endpoint: PUT /api/users/profile
          Original body: {"name": "Alice", "role": "user"}
          Modified body: {"name": "Alice", "role": "admin"}
          Response:      200 OK — role field accepted without validation
          Verdict:       CONFIRMED Privilege Escalation via Mass Assignment
          CVSS:          9.1 CRITICAL
```

---

### 5. CI/CD Pipeline Breaker

AgentShield is designed to fail fast inside CI/CD pipelines when security regressions are introduced. Configure the minimum severity threshold that blocks deployment using `--fail-on`.

**Exit Codes:**

| Code | Meaning |
|---|---|
| `0` | Scan complete, no findings at or above threshold |
| `1` | Scan complete, findings found at or above `--fail-on` severity |
| `2` | Scan failed due to target unreachable or configuration error |

---

## 📊 Report Examples

### HTML Report (Dark Theme)

The HTML report is a self-contained single-file document with a dark security dashboard aesthetic. It includes:

- Executive summary card with overall risk score and grade
- Severity breakdown donut chart
- Finding cards grouped by severity with full request/response reproduction
- CVSS scores, CWE references, and OWASP Top 10 mapping
- AI-generated remediation guidance per finding
- Technical details section with raw evidence

### PDF Report

The PDF report mirrors the HTML layout and is formatted for printing and client delivery. It includes a cover page with target information, scan metadata, and a signature block. Generated via WeasyPrint.

### JSON Output

The raw JSON output contains every request/response pair, payload used, detection method, AI analysis output, and CVSS calculation. It is the input format for `agentshield diff` and `agentshield report`.

---

## 🔗 DevSecOps Integration

### GitHub Actions

Add AgentShield to your deployment pipeline to block releases that introduce security regressions:

```yaml
# .github/workflows/security-scan.yml
name: Security Scan

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'   # Nightly full scan

jobs:
  agentshield:
    name: AgentShield DAST
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install AgentShield
        run: |
          pip install agentshield[full]
          playwright install chromium --with-deps

      - name: Run DAST Scan
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          agentshield scan ${{ vars.TARGET_URL }} \
            --format both \
            --output-dir reports/ \
            --fail-on high \
            --auth-token "${{ secrets.SCAN_AUTH_TOKEN }}" \
            --playwright \
            --verbose

      - name: Upload Security Report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-report-${{ github.run_number }}
          path: reports/
          retention-days: 90

      - name: Comment PR with Summary
        if: github.event_name == 'pull_request' && always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const summary = JSON.parse(
              fs.readFileSync('reports/summary.json', 'utf8')
            );
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🛡️ AgentShield Security Scan\n\n` +
                    `**Risk Score:** ${summary.score}/100 — ${summary.grade}\n` +
                    `**Critical:** ${summary.critical} | **High:** ${summary.high} ` +
                    `| **Medium:** ${summary.medium} | **Low:** ${summary.low}\n\n` +
                    `[Full Report](${summary.report_url})`
            });
```

### Jira Integration

When `--jira-url`, `--jira-token`, and `--jira-project` are provided, AgentShield automatically creates Jira issues for all confirmed findings of Medium severity and above.

Each ticket includes:

- **Summary:** `[AgentShield] {Severity} — {Finding Type} on {Endpoint}`
- **Description:** Full technical details, request/response evidence, CVSS score, CWE reference, OWASP category
- **Labels:** `security`, `agentshield`, `{severity}`, `{finding-type}`
- **Priority:** Mapped from CVSS score (Critical → Highest, High → High, etc.)
- **Components:** `Security` (auto-created if absent)

Duplicate suppression is built in — AgentShield checks for open tickets with the same endpoint and finding type before creating a new one.

### Historical Diff Tracking

AgentShield persists scan results in `~/.agentshield/history/` (or `--output-dir`) indexed by target hostname and timestamp. The `diff` command computes the delta between the latest two scans:

```bash
agentshield diff https://target.com
```

**Diff Output Example:**

```
AgentShield Diff — target.com
Compared: 2026-04-11 14:30 vs 2026-04-10 09:15

NEW FINDINGS (2):
  + CRITICAL  SQLi confirmed on POST /api/search (param: q)
  + HIGH      Missing CSP header on /admin

RESOLVED FINDINGS (1):
  - MEDIUM    Insecure cookie (session) — HttpOnly now set

UNCHANGED FINDINGS (4):
  ● HIGH      CORS open policy on /api/*
  ● MEDIUM    Server version disclosure
  ● MEDIUM    Missing Referrer-Policy on 3 endpoints
  ● LOW       Deprecated X-XSS-Protection header

Net change: +1 severity point (score: 58 → 59)
```

---

## 🎯 Scoring System

AgentShield produces a 0–100 risk score for each target. The score is additive — each finding contributes its weight, capped at 100.

### Severity Grades

| Score Range | Grade | Color | Meaning |
|---|---|---|---|
| 0 – 19 | **BAIXO** | 🟢 Green | Low risk, good security posture |
| 20 – 39 | **MÉDIO** | 🟡 Yellow | Moderate risk, some improvements needed |
| 40 – 69 | **ALTO** | 🟠 Orange | High risk, significant vulnerabilities present |
| 70 – 100 | **CRÍTICO** | 🔴 Red | Critical risk, immediate remediation required |

### Score Weight Table

| Finding Type | Weight |
|---|---|
| Missing security header | +10 pts each |
| Insecure cookie flag (each missing flag) | +15 pts each |
| Information disclosure in header | +5 pts each |
| HTTP methods misconfiguration | +10 pts |
| CORS policy open (`*`) | +30 pts |
| TLS/SSL weak cipher or misconfiguration | +20 pts |
| Expired or self-signed certificate | +25 pts |
| Active SQLi confirmed | +40 pts |
| Active XSS confirmed (reflected) | +35 pts |
| Active XSS confirmed (stored) | +45 pts |
| OS command injection confirmed | +50 pts |
| Path traversal confirmed | +35 pts |
| Open redirect confirmed | +20 pts |
| SSRF confirmed | +45 pts |
| IDOR confirmed | +45 pts |
| Privilege escalation confirmed | +50 pts |
| Mass assignment confirmed | +40 pts |

> Scores are capped at 100. A single confirmed IDOR or privilege escalation finding is sufficient to push any target into CRÍTICO territory.

---

## 🔒 Modules & Payloads Reference

### SQL Injection Payloads (sample)

```
' OR '1'='1
' OR 1=1--
'; DROP TABLE users;--
' UNION SELECT NULL,NULL--
' AND SLEEP(5)--
'; WAITFOR DELAY '0:0:5'--
' AND 1=CONVERT(int,(SELECT TOP 1 table_name FROM information_schema.tables))--
```

### XSS Payloads (sample)

```
<script>alert(1)</script>
"><img src=x onerror=alert(1)>
javascript:alert(document.cookie)
<svg/onload=alert(1)>
';alert(String.fromCharCode(88,83,83))//
<details/open/ontoggle=alert(1)>
```

### WAF Evasion (sample)

```
sElEcT 1,2,3
SE/**/LECT 1,2,3
%53%45%4c%45%43%54 1,2,3
' /*!50000OR*/ '1'='1
```

---

## ⚠️ Legal Notice

```
╔══════════════════════════════════════════════════════════════════════╗
║          LEGAL NOTICE — MANDATORY READ BEFORE USE                   ║
╠══════════════════════════════════════════════════════════════════════╣
║                                                                      ║
║  AgentShield includes active attack capabilities including SQL       ║
║  injection fuzzing, XSS injection, command injection probing,        ║
║  path traversal testing, IDOR enumeration, and privilege escalation  ║
║  simulation.                                                         ║
║                                                                      ║
║  USE ONLY on systems you own or have EXPLICIT WRITTEN AUTHORIZATION  ║
║  to test. Verbal authorization is insufficient.                      ║
║                                                                      ║
║  Unauthorized use against systems you do not own may violate:        ║
║                                                                      ║
║  🇧🇷  Brazil:        Lei Nº 12.737/2012 (Lei Carolina Dieckmann)     ║
║  🇺🇸  USA:           Computer Fraud and Abuse Act (CFAA) 18 U.S.C.  ║
║                      § 1030                                          ║
║  🇪🇺  European Union: Directive 2013/40/EU on attacks against        ║
║                      information systems                             ║
║  🌍  International:  Budapest Convention on Cybercrime               ║
║                      (ETS No. 185)                                   ║
║                                                                      ║
║  Zyron Security assumes NO LIABILITY for unauthorized or illegal     ║
║  use of this tool. Users are solely responsible for ensuring they    ║
║  have proper authorization before initiating any scan.               ║
║                                                                      ║
║  This tool is intended for:                                          ║
║  • Security professionals testing systems they are authorized to test║
║  • Organizations scanning their own infrastructure                   ║
║  • Penetration testers with signed scope-of-work agreements          ║
║  • Security researchers operating within responsible disclosure      ║
║                                                                      ║
╚══════════════════════════════════════════════════════════════════════╝
```

---

## 🤝 Contributing

Contributions are welcome and encouraged. AgentShield is a community project — the more payload variants, detection techniques, and integration modules the community contributes, the more powerful it becomes.

### How to Contribute

1. **Fork** the repository and create a feature branch from `develop`.
2. **Search for existing issues** before opening a new one — your bug may already be tracked.
3. **Follow the existing code style** — functions under 50 lines, files under 800 lines, no hardcoded values.
4. **Write tests** — all new modules require unit tests. Minimum 80% coverage for new code.
5. **Open a pull request** against `develop` with a clear description of what the change does and why.

### Priority Contribution Areas

- New payload vectors (SQLi, XSS, SSTI, XXE, deserialization)
- Framework-specific detection signatures (Spring Boot, Django, Laravel, Rails)
- Authentication scheme support (OAuth2, SAML, mTLS)
- Additional CI/CD integrations (GitLab CI, Azure DevOps, CircleCI, Jenkins)
- Output format modules (SARIF, CycloneDX, DefectDojo)
- False positive reduction improvements

### Code of Conduct

All contributors are expected to act professionally and respectfully. Security tooling carries an ethical responsibility — do not contribute payloads or techniques designed to cause irreversible damage, data destruction, or denial of service to production systems.

### Reporting Security Issues

If you discover a security vulnerability in AgentShield itself, please do **not** open a public issue. Email `security@zyron.security` with full details. We follow a 90-day coordinated disclosure policy.

---

## 📝 License

```
MIT License

Copyright (c) 2026 Zyron Security

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

---

## 🏢 About Zyron Security

Zyron Security is a Brazilian cybersecurity firm specializing in application security, penetration testing, and AI-powered security tooling — building open-source frameworks and commercial solutions that give security teams enterprise-grade capabilities without enterprise-grade price tags.

---

<div align="center">

**Built with precision by [Zyron Security](https://zyron.security)**

[![GitHub Stars](https://img.shields.io/github/stars/zyron-security/agentshield?style=social)](https://github.com/zyron-security/agentshield)
[![GitHub Issues](https://img.shields.io/github/issues/zyron-security/agentshield?color=red)](https://github.com/zyron-security/agentshield/issues)
[![GitHub PRs](https://img.shields.io/github/issues-pr/zyron-security/agentshield?color=6366f1)](https://github.com/zyron-security/agentshield/pulls)

*Security is not a product. It is a process.*

</div>
