### Automatic Setup Wizard

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Install requirements and launch the interactive setup wizard for initial configuration.

```bash
pip install -r requirements.txt
python deep_eye.py -u https://target.com
```

--------------------------------

### Manual Installation and Configuration

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Install requirements via pip and initialize the configuration file manually.

```bash
pip install -r requirements.txt
cp config/config.example.yaml config/config.yaml
# Edit config.yaml with your API keys
```

--------------------------------

### Configuration Example

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-f-rag-cve-design.md

Example configuration structure for enabling and tuning the RAG system.

```yaml
rag:
    enabled: false
    index_path: "data/cve_rag_index.pkl"
    auto_rebuild: true
    top_k: 5
    min_score: 0.15
```

--------------------------------

### Install Dependencies

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Install the required Python packages from the requirements file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/zakirkun/deep-eye/blob/main/CONTRIBUTING.md

Install required packages for development and testing.

```powershell
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

--------------------------------

### Configuration Example

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-d-captcha-login-replay-design.md

YAML configuration settings for CAPTCHA and login replay features.

```yaml
captcha:
  enabled: false
  skip_protected: true
  vendors: [recaptcha, hcaptcha, turnstile, generic]

login_replay:
  enabled: false
  macro_path: "config/login_macro.json"
  abort_on_fail: true
  recheck_interval_seconds: 600
```

--------------------------------

### Install Browser Automation

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Install Playwright and the Chromium browser for advanced security testing features.

```bash
pip install playwright && playwright install chromium
```

--------------------------------

### Example multi-format output file structure

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-a-export-formats-design.md

Shows the naming convention for generated report files when multiple formats are requested.

```text
reports/
  deep_eye_example.com_20260528_184400.junit.xml
  deep_eye_example.com_20260528_184400.csv
  deep_eye_example.com_20260528_184400.xlsx
```

--------------------------------

### Install Playwright Chromium

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Run this command to resolve browser test failures by forcing a fresh installation of the Chromium browser.

```bash
playwright install chromium --force
```

--------------------------------

### Login Macro JSON Format

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-d-captcha-login-replay-design.md

Example JSON structure for defining login sequences and authentication checks.

```json
{
  "version": 1,
  "name": "demo-login",
  "auth_check": {
    "url": "https://example.com/account",
    "must_contain": "Welcome",
    "must_not_contain": "Sign in"
  },
  "steps": [
    {"action": "get",  "url": "https://example.com/login"},
    {"action": "extract_csrf", "from": "input[name=_token]", "save_as": "csrf"},
    {"action": "post", "url": "https://example.com/login",
     "data": {"username": "user", "password": "pw", "_token": "${csrf}"},
     "expect_status": [200, 302]},
    {"action": "get",  "url": "https://example.com/account",
     "expect_contains": "Welcome"}
  ]
}
```

--------------------------------

### Install Deep Eye on Windows

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Execute the PowerShell script to install dependencies on Windows systems.

```powershell
.\scripts\install.ps1
```

--------------------------------

### Lazy dependency installation prompt

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-a-export-formats-design.md

The console message displayed when the openpyxl library is missing during an Excel export attempt.

```text
[!] xlsx export needs openpyxl. Install now? [y/N]:
```

--------------------------------

### Update Project Dependencies

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Execute this command to resolve import errors by ensuring all required packages are installed and up to date.

```bash
pip install -r requirements.txt --upgrade
```

--------------------------------

### Implement post-scan compliance enrichment

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-b-compliance-mapping-design.md

Example of how compliance data is injected into vulnerability objects during the scan process.

```python
vuln["compliance"] = {
    "PCI-DSS": [{"control_id": "6.2.4", ...}, ...],
    "SOC 2": [...],
    "ISO 27001": [...]
}
```

--------------------------------

### Install Deep Eye on Linux or Mac

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Grant execution permissions to the shell script and run it to install dependencies.

```bash
chmod +x scripts/install.sh && ./scripts/install.sh
```

--------------------------------

### Configure Intercepting Proxy

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Configures local binding for mitmproxy integration. Requires mitmproxy to be installed via pip.

```yaml
intercepting_proxy:
  enabled: true
  bind_host: "127.0.0.1"
  proxy_port: 8080
  mitmweb_port: 8081
```

```bash
pip install mitmproxy
```

--------------------------------

### Configure Application

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Initialize the configuration file and set up AI provider credentials.

```bash
cp config/config.example.yaml config/config.yaml
```

```yaml
ai_providers:
  openai:
    enabled: true
    api_key: "sk-your-key-here"
    model: "gpt-4o"
```

--------------------------------

### Clone the Repository

Source: https://github.com/zakirkun/deep-eye/blob/main/CONTRIBUTING.md

Initial steps to download the project source code.

```bash
git clone https://github.com/zakirkun/deep-eye.git
cd deep-eye
```

--------------------------------

### Define CLI entry point

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-i-async-migration-design.md

Standard entry point for executing the asynchronous application.

```python
def main():
    asyncio.run(_amain())
```

--------------------------------

### Run Scan with Configuration File

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Execute a scan using settings defined in a specific configuration file.

```bash
python deep_eye.py -c config/config.yaml
```

--------------------------------

### Run Tests

Source: https://github.com/zakirkun/deep-eye/blob/main/CONTRIBUTING.md

Commands to execute the test suite.

```bash
python -m pytest tests/
```

```powershell
pytest tests/ -v
```

--------------------------------

### Initialize Configuration

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Methods to generate the initial configuration file for Deep Eye.

```bash
python deep_eye.py -u https://target.com
# Wizard prompts: provider, API key, model, threads, depth, scan mode, report format
# Writes config/config.yaml automatically
```

```bash
cp config/config.example.yaml config/config.yaml
```

--------------------------------

### Enable Custom Templates

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Register custom template directories in the configuration file.

```yaml
templates:
  enabled: true
  template_directories:
    - "templates/custom"
```

--------------------------------

### Configure database settings

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Sets database type, storage path, and cleanup frequency.

```yaml
database:
  enabled: true
  type: "sqlite"
  path: "data/deep_eye.db"
  auto_cleanup_days: 30
```

--------------------------------

### Define Login Macro Format

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Structure for defining sequential login steps.

```yaml
steps:
  - url: "https://target.com/login"
    method: POST
    body:
      username: "testuser"
      password: "testpass"
    expect_status: 302
  - url: "https://target.com/dashboard"
    method: GET
    expect_status: 200
```

--------------------------------

### Define Nuclei-Style YAML Template Schema

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-g-template-engine-design.md

Example YAML template for detecting CORS wildcard misconfigurations using the HTTP protocol.

```yaml
id: cors-wildcard
info:
  name: CORS Wildcard Origin with Credentials
  author: deep-eye
  severity: high
  description: ...
  tags: [cors, misconfig]
  references: [...]
  classification:
    cwe-id: CWE-942
http:
  - method: GET
    path:
      - "{{BaseURL}}/api/user"
    headers:
      Origin: "https://evil.example.com"
    matchers-condition: and
    matchers:
      - type: word
        part: header
        words: ["Access-Control-Allow-Origin: https://evil.example.com"]
        case-insensitive: true
      - type: word
        part: header
        words: ["Access-Control-Allow-Credentials: true"]
        case-insensitive: true
    extractors:
      - type: regex
        part: header
        regex: ["Access-Control-Allow-Origin:\\s*([^\\r\\n]+)"]
        group: 1
```

--------------------------------

### Project Component Map

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-d-captcha-login-replay-design.md

Overview of project files and their integration points.

```text
modules/captcha_detection/__init__.py
modules/captcha_detection/detector.py
modules/login_replay/__init__.py
modules/login_replay/macro.py
modules/login_replay/player.py

core/scanner_engine.py
  + invoke LoginPlayer before crawl
  + invoke CaptchaDetector during URL fetch hook

config/config.example.yaml
  + captcha: {...}
  + login_replay: {...}
```

--------------------------------

### Configure Login Replay

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Settings for automated login macros.

```yaml
login_replay:
  enabled: false
  macro_path: "config/login_macro.yaml"
  abort_on_fail: true
  recheck_interval_seconds: 300
```

--------------------------------

### Component Overview

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-h-tls-cf-proxy-design.md

Summary of component responsibilities and integration points.

```text
utils/http_client.py
  + curl_cffi adapter when tls_evasion.enabled
  + proxy injection when intercepting_proxy.enabled

modules/challenge_solver/
  __init__.py
  detector.py
  solver.py

modules/intercepting_proxy/
  __init__.py
  proxy_runner.py

deep_eye.py
  + start/stop intercepting proxy
```

--------------------------------

### Configure Scanner Settings

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Set target URL, concurrency, crawl depth, and AI provider for the scanner.

```yaml
scanner:
  target_url: "https://target.com"
  default_threads: 5          # 1-50
  default_depth: 2            # crawl depth
  enable_recon: true
  full_scan: false
  ai_provider: "openai"
```

--------------------------------

### Configure compliance framework settings

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-b-compliance-mapping-design.md

YAML configuration for enabling compliance mapping and selecting active frameworks.

```yaml
compliance:
  enabled: true
  frameworks: [pci_dss, soc2, iso_27001]
```

--------------------------------

### Configure Plugin Manager and Plugins

Source: https://github.com/zakirkun/deep-eye/blob/main/plugins/README.md

Enable the plugin manager and specific plugins within the config/config.yaml file.

```yaml
plugin_manager:
  enabled: true
  plugin_directory: "plugins"
  auto_load: true

# Plugin-specific configuration
plugins:
  mycustomscanner:  # Plugin ID (lowercase class name without 'plugin')
    enabled: true
    custom_setting: "value"
```

--------------------------------

### Login Replay Module Structure

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-d-captcha-login-replay-design.md

Directory structure for the login replay module.

```text
modules/login_replay/
  __init__.py
  macro.py
  player.py
```

--------------------------------

### Configure logging settings

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Sets log levels and file rotation policies.

```yaml
logging:
  level: "INFO"                # DEBUG, INFO, WARNING, ERROR
  log_to_file: true
  log_file: "logs/deep_eye.log"
  max_file_size: 10485760      # 10MB
  backup_count: 5
```

--------------------------------

### Configure notification channels

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Sets up email, Slack, and Discord alerts for critical events.

```yaml
notifications:
  enabled: false
  notify_on_critical: true
  email:
    enabled: false
    smtp_host: "smtp.gmail.com"
    smtp_port: 587
    username: ""
    password: ""
    from_address: ""
    recipients: []
  slack:
    enabled: false
    webhook_url: ""
  discord:
    enabled: false
    webhook_url: ""
```

--------------------------------

### Configure Challenge Solver

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Settings for bypassing anti-bot protections like Cloudflare or Akamai.

```yaml
challenge_solver:
  enabled: false
  vendors:
    - "cloudflare"
    - "akamai"
  playwright_headless: true
  cookie_ttl_seconds: 1800
  timeout_seconds: 30
```

--------------------------------

### Configure Templates

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Settings for external template directories and filtering.

```yaml
templates:
  enabled: false
  template_directories:
    - "templates/nuclei"
  tag_filters: []              # empty = all tags
  severity_filter: ""          # empty = all severities
```

--------------------------------

### Configuration Schema

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-h-tls-cf-proxy-design.md

YAML configuration schema for enabling and tuning the network features.

```yaml
tls_evasion:
  enabled: false
  impersonate: "chrome120"
  fallback_to_requests: true

challenge_solver:
  enabled: false
  vendors: [cloudflare, akamai]
  playwright_headless: true
  cookie_ttl_seconds: 1800
  timeout_seconds: 30

intercepting_proxy:
  enabled: false
  mitmweb_port: 8081
  proxy_port: 8080
  bind_host: "127.0.0.1"
```

--------------------------------

### Configure experimental features

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Toggles beta features like subdomain scanning and CVE matching.

```yaml
experimental:
  enable_subdomain_scanning: false
  aggressive_subdomain_enum: false
  max_subdomains_to_scan: 50
  enable_cve_matching: false
  cve_database_path: "data/cve_intelligence.db"
  auto_update_cve_db: false
  cve_lookback_days: 365
```

--------------------------------

### Define Project Component Integration

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-g-template-engine-design.md

Overview of how the template engine integrates with existing core components and configuration files.

```text
modules/template_engine/
  __init__.py
  parser.py
  matcher.py
  executor.py
  loader.py

templates/                  # ship starter pack
  exposures/git-config-exposure.yaml
  cves/cve-2021-44228-log4shell-headers.yaml
  misconfig/cors-wildcard.yaml

core/scanner_engine.py
  + invoke template engine after built-in scans

config/config.example.yaml
  + templates: {...}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/zakirkun/deep-eye/blob/main/CONTRIBUTING.md

Overview of the project file organization.

```text
deep-eye/
├── core/               # Core scanning engine
├── ai_providers/       # AI provider integrations
├── modules/           # Security testing modules
├── utils/             # Utility functions
├── config/            # Configuration files
├── templates/         # Report templates
├── tests/             # Unit tests
└── examples/          # Usage examples
```

--------------------------------

### Configure Scanner Settings

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

General scanner parameters including target URL, timeouts, and concurrency.

```yaml
scanner:
  target_url: "https://target.com"
  default_threads: 5            # 1-50
  default_depth: 2              # crawl depth 1-10
  max_urls: 100
  timeout: 10                   # HTTP timeout (seconds)
  scan_url_timeout: 30
  user_agent: "Deep-Eye/1.4"
  follow_redirects: true
  verify_ssl: true
  max_retries: 3
  enable_recon: false
  full_scan: false
  quick_scan: false
  ai_provider: "openai"        # which provider to use
  oast_callback_url: ""
  proxy: ""
  custom_headers: {}
  cookies: {}
```

--------------------------------

### Configure proxy settings

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Sets HTTP and HTTPS proxy endpoints.

```yaml
proxy:
  enabled: false
  http: "http://127.0.0.1:8080"
  https: "http://127.0.0.1:8080"
```

--------------------------------

### Run Scans via CLI

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Execute security scans using different configuration modes.

```bash
python deep_eye.py -u https://target.com
```

```bash
python deep_eye.py
```

```bash
python deep_eye.py -u https://target.com -v
```

--------------------------------

### Challenge Solver Module Structure

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-h-tls-cf-proxy-design.md

Outlines the file structure for the challenge solver module.

```text
modules/challenge_solver/
  __init__.py
  detector.py
  solver.py
```

--------------------------------

### Configure Captcha and Login Replay

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Settings for handling captcha challenges and automating login sequences.

```yaml
captcha:
  enabled: true
  skip_protected: true
  vendors:
    - "recaptcha"
    - "hcaptcha"
    - "turnstile"

login_replay:
  enabled: true
  macro_path: "config/login_macro.yaml"
  abort_on_fail: true
  recheck_interval_seconds: 300
```

--------------------------------

### Configure Challenge Solver

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Settings for bypassing bot protection mechanisms like Cloudflare or Akamai.

```yaml
challenge_solver:
  enabled: true
  vendors:
    - "cloudflare"
    - "akamai"
  playwright_headless: true
  cookie_ttl_seconds: 1800
  timeout_seconds: 30
```

--------------------------------

### Enable Subdomain Scanning

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Configure the experimental subdomain scanning feature and set the scan limit.

```yaml
experimental:
  enable_subdomain_scanning: true
  max_subdomains_to_scan: 50
```

--------------------------------

### Configure Quick Scan

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Sets the scanner to perform a quick scan on the main URL only with a specified thread count.

```yaml
scanner:
  quick_scan: true
  default_threads: 5
```

--------------------------------

### Define a custom security module

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Implement the standard module interface by defining an __init__ method for configuration and a scan method that returns a list of vulnerability results.

```python
class ModuleName:
    def __init__(self, http_client, config):
        ...

    def scan(self, url) -> List[Dict]:
        # Returns list of vulnerability result dicts
        ...
```

--------------------------------

### Configure plugin manager

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Controls plugin loading and directory paths.

```yaml
plugin_manager:
  enabled: false
  plugin_directory: "plugins"
  auto_load: true
```

--------------------------------

### Create a Feature Branch

Source: https://github.com/zakirkun/deep-eye/blob/main/CONTRIBUTING.md

Command to create a new branch for development.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Index Build Process

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-f-rag-cve-design.md

The sequence of operations performed by the build script to generate the TF-IDF index.

```text
build_cve_rag_index.py
  -> open SQLite cve_intelligence.db
  -> SELECT cve_id, description, cvss_score, cwe_id, affected_products FROM cves
  -> documents = [f"{description} {cwe_id} {' '.join(products)}" per row]
  -> vectorizer = TfidfVectorizer(stop_words='english', ngram_range=(1,2), max_features=50000)
  -> matrix = vectorizer.fit_transform(documents)
  -> pickle dump to index_path
```

--------------------------------

### Configure Rate Limiting and Scanner Threads

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Adjust these settings in your configuration to manage request frequency and scanner performance to avoid WAF blocking.

```yaml
rate_limiting:
  requests_per_second: 2
  delay_on_error: 5

scanner:
  default_threads: 2
```

--------------------------------

### Configure Compliance Mapping

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Enable compliance reporting and specify the frameworks to map against.

```yaml
compliance:
  enabled: true
  frameworks:
    - pci_dss
    - soc2
    - iso_27001
```

--------------------------------

### Run Scan with Verbose Output

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Execute a scan with detailed logging enabled.

```bash
python deep_eye.py -u https://target.com -v
```

--------------------------------

### Configure Challenge Bypass

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Enables automated bypass for common WAF challenges using headless browser automation.

```yaml
challenge_solver:
  enabled: true
  vendors:
    - "cloudflare"
    - "akamai"
  playwright_headless: true
  cookie_ttl_seconds: 1800
```

--------------------------------

### Configure Compliance

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Enable specific regulatory frameworks for compliance scanning.

```yaml
compliance:
  enabled: false
  frameworks:
    - pci_dss        # PCI-DSS v4.0
    - soc2           # SOC 2 Type II
    - iso_27001      # ISO 27001:2022
```

--------------------------------

### Configure advanced browser and network settings

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Controls browser rendering, AI usage, and network exclusion patterns.

```yaml
advanced:
  enable_javascript_rendering: false
  screenshot_enabled: false
  enable_browser_use_ai: false
  browser_timeout: 30
  ua_rotation: false
  jitter_min: 0
  jitter_max: 0
  proxy_pool: []
  exclude_extensions: [".jpg", ".png", ".gif", ".css", ".js", ".ico"]
  exclude_patterns: []
  max_response_size: 10485760  # 10MB
  custom_dns_servers: []
```

--------------------------------

### Execute Deep Eye Scan

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/SCAN_FLOW.md

Initiate a scan by providing a target URL to the main entry point script.

```bash
python deep_eye.py -u https://target.com
```

--------------------------------

### Deep Eye CLI Commands

Source: https://github.com/zakirkun/deep-eye/blob/main/CLAUDE.md

Commands for project initialization, target scanning, database updates, and test execution.

```bash
# Setup
pip install -r requirements.txt
cp config/config.example.yaml config/config.yaml

# Browser automation (optional)
pip install playwright && playwright install chromium

# Run
python deep_eye.py -u https://example.com
python deep_eye.py -c config/config.yaml
python deep_eye.py -u https://example.com -v        # verbose
python deep_eye.py -u https://example.com --no-banner

# CVE database update
python scripts/update_cve_database.py

# Build RAG index for CVE intelligence
python scripts/build_cve_rag_index.py

# Tests
pytest
pytest tests/test_litellm_provider.py -v            # single test file
pytest tests/test_export_formats.py -v              # export formats
pytest tests/test_compliance_mapping.py -v          # compliance
pytest tests/test_scan_diff.py -v                   # scan diffing
pytest tests/test_rag_index.py -v                   # RAG/CVE index
pytest tests/test_ai_triage.py -v                   # AI triage
pytest tests/test_captcha_detection.py -v           # CAPTCHA detection
pytest tests/test_template_engine.py -v           # Nuclei-style templates
pytest tests/test_challenge_solver.py -v            # CF/Akamai solver
pytest tests/test_intercepting_proxy.py -v          # intercepting proxy
python tests/e2e_litellm.py                         # e2e test (requires API key)
```

--------------------------------

### Configure Template Engine

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Settings for defining template directories and filters for Nuclei-compatible checks.

```yaml
templates:
  enabled: true
  template_directories:
    - "templates/nuclei"
    - "templates/custom"
  tag_filters:
    - "cve"
    - "rce"
  severity_filter: "critical,high"
```

--------------------------------

### ScannerEngine Integration Logic

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-d-captcha-login-replay-design.md

Logic for invoking the LoginPlayer within the scanner engine before crawling.

```python
if config['login_replay']['enabled']:
    macro = load_macro(config['login_replay']['macro_path'])
    player = LoginPlayer(self.http_client, config)
    if not player.play(macro):
        if config['login_replay']['abort_on_fail']:
            return
```

--------------------------------

### Implement a Custom Scanner Plugin

Source: https://github.com/zakirkun/deep-eye/blob/main/plugins/README.md

Create a new class inheriting from PluginBase and implement the scan method to define custom vulnerability detection logic.

```python
from typing import Dict, List
from core.plugin_manager import PluginBase


class MyCustomScanner(PluginBase):
    """My custom vulnerability scanner."""
    
    # Plugin metadata
    name = "My Custom Scanner"
    version = "1.0.0"
    author = "Your Name"
    description = "Scans for custom vulnerabilities"
    
    def scan(self, url: str, context: Dict) -> List[Dict]:
        """
        Scan URL for vulnerabilities.
        
        Args:
            url: Target URL
            context: Scan context (response, headers, etc.)
            
        Returns:
            List of vulnerabilities found
        """
        vulnerabilities = []
        
        # Your scanning logic here
        response = context.get('response')
        if response:
            # Example: Check for custom header
            if 'X-Custom-Header' not in response.headers:
                vulnerabilities.append({
                    'type': 'Missing Custom Header',
                    'severity': 'low',
                    'url': url,
                    'evidence': 'X-Custom-Header not found',
                    'description': 'Custom security header is missing',
                    'remediation': 'Add X-Custom-Header to responses',
                    'plugin': self.name
                })
        
        return vulnerabilities
```

--------------------------------

### Intercepting Proxy Module Structure

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-h-tls-cf-proxy-design.md

Outlines the file structure for the intercepting proxy module.

```text
modules/intercepting_proxy/
  __init__.py
  proxy_runner.py
```

--------------------------------

### Payload Generation Flow Diagram

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/SCAN_FLOW.md

Visual representation of the context-aware payload generation process.

```text
URL + Response Context
        |
        v
Context Analysis (tech stack, WAF, DB fingerprint)
        |
        v
AI Provider generate(prompt) --> Generated Payloads
        |                              |
        v                              v
CVE-based payloads            Obfuscated variants
```

--------------------------------

### Configure ML detection parameters

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Sets thresholds and features for machine learning-based anomaly detection.

```yaml
ml_detection:
  enabled: false
  baseline_samples: 50
  anomaly_threshold: 0.7
  features:
    - response_time
    - status_code
    - content_length
    - error_keywords
  save_model: true
  model_path: "data/ml_model.pkl"
```

--------------------------------

### Define Custom Nuclei-Style Templates

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Create YAML-based templates to define custom security checks.

```yaml
# templates/custom/my-check.yaml
id: my-custom-check
info:
  name: Custom Header Check
  severity: medium
  description: Checks for missing security header
  tags:
    - headers

http:
  - method: GET
    path:
      - "{{BaseURL}}/"
    matchers:
      - type: word
        words:
          - "X-Custom-Header"
        negative: true
        part: header
```

--------------------------------

### Define Bug Bounty Writer Prompt

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-c-ai-triage-design.md

System prompt used to generate HackerOne-format Markdown reports.

```text
Generate a HackerOne-format Markdown bug report.

Vulnerability:
  Type: {type}
  Severity: {severity}
  CVSS: {cvss_score}
  URL: {url}
  Parameter: {parameter}
  Payload: {payload}
  Evidence: {evidence}
  Description: {description}
  Remediation: {remediation}

Required sections:
  ## Summary
  ## Steps to Reproduce
  ## Impact
  ## Proof of Concept (payload in code block)
  ## Suggested Fix
  ## Severity Justification

Clear, concise. No marketing fluff.
```

--------------------------------

### Configure AI Providers

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Define settings for various AI services used by the scanner.

```yaml
ai_providers:
  openai:
    enabled: true
    api_key: "sk-..."
    model: "gpt-4o"
    temperature: 0.7
    max_tokens: 2000
    timeout: 30

  claude:
    enabled: true
    api_key: "sk-ant-..."
    model: "claude-3-5-sonnet-20241022"
    temperature: 0.7
    max_tokens: 2000
    timeout: 30

  ollama:
    enabled: false
    base_url: "http://localhost:11434"
    model: "llama2"
    timeout: 60

  openrouter:
    enabled: false
    api_key: "sk-or-..."
    model: "openai/gpt-4o"
    temperature: 0.7
    max_tokens: 2000
    timeout: 30

  requesty:
    enabled: false
    api_key: "sk-..."          # Get a key at https://app.requesty.ai/api-keys
    model: "openai/gpt-4o-mini"
    temperature: 0.7
    max_tokens: 2000
    timeout: 30
```

--------------------------------

### Challenge Solving Flow Diagram

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/SCAN_FLOW.md

Logic flow for detecting and solving WAF challenges like Cloudflare or Akamai.

```text
HTTP Request --> Response
        |
        v
ChallengeDetector.detect(html, headers)
        |
        +-- No challenge --> proceed normally
        |
        +-- Challenge detected
                |
                v
        ChallengeSolver.solve(url)
                |
                +-- Cache hit (within TTL) --> inject cached cookies
                |
                +-- Cache miss --> launch headless Chromium
                        --> wait for JS challenge
                        --> extract clearance cookies
                        --> inject into HTTPClient
                        --> cache with TTL
```

--------------------------------

### Execute Maintenance Scripts

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Commands to update the CVE database and build the RAG vector index for search functionality.

```bash
# Update CVE intelligence database from NVD
python scripts/update_cve_database.py

# Build RAG vector index for CVE search
python scripts/build_cve_rag_index.py
```

--------------------------------

### Configure CVE Intelligence

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Settings for CVE matching and RAG-based vulnerability indexing.

```yaml
experimental:
  enable_cve_matching: true
  cve_database_path: "data/cve_intelligence.db"

rag:
  enabled: true
  index_path: "data/rag_index"
  auto_rebuild: false
  top_k: 5
  min_score: 0.7
```

--------------------------------

### Configure Bug Bounty

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Settings for generating bug bounty reports.

```yaml
bug_bounty:
  enabled: false
  format: "markdown"
  min_severity: "medium"
  output_directory: "reports/bounty"
  one_file_per_vuln: true
```

--------------------------------

### Define Custom Template Format

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Structure for creating custom YAML-based security checks.

```yaml
id: custom-check-id
info:
  name: Check Name
  severity: high
  description: What this checks
  tags:
    - custom
  reference:
    - https://example.com

http:
  - method: GET
    path:
      - "{{BaseURL}}/endpoint"
    matchers:
      - type: word
        words:
          - "sensitive_string"
        part: body
      - type: status
        status:
          - 200
    matchers-condition: and
    extractors:
      - type: regex
        regex:
          - "token=([a-f0-9]+)"
        group: 1
```

--------------------------------

### Configure WebSocket security settings

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Defines security validation parameters for WebSocket connections.

```yaml
websocket:
  enabled: false
  test_origin_validation: true
  test_authentication: true
  test_injection_attacks: true
  test_dos_attacks: false
  test_rate_limiting: true
  test_tls_verification: true
  connection_timeout: 10
  max_message_size: 65536
```

--------------------------------

### Configure Full Deep Scan

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Enables deep scanning with increased depth and AI-driven payload generation.

```yaml
scanner:
  full_scan: true
  default_depth: 5
  default_threads: 10
  enable_recon: true

vulnerability_scanner:
  payload_generation:
    use_ai: true
    context_aware: true
    cve_database: true
```

--------------------------------

### Configure RAG

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Settings for Retrieval-Augmented Generation indexing.

```yaml
rag:
  enabled: false
  index_path: "data/rag_index"
  auto_rebuild: false
  top_k: 5
  min_score: 0.7
```

--------------------------------

### Configure ML Detection

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Settings for anomaly detection using IsolationForest.

```yaml
ml_detection:
  enabled: true
  baseline_samples: 50
  anomaly_threshold: 0.7
  features:
    - response_time
    - status_code
    - content_length
    - error_keywords
  save_model: true
  model_path: "data/ml_model.pkl"
```

--------------------------------

### Configure Captcha

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Settings for handling various captcha providers.

```yaml
captcha:
  enabled: false
  skip_protected: true
  vendors:
    - "recaptcha"
    - "hcaptcha"
    - "turnstile"
    - "arkose"
```

--------------------------------

### Configure Reporting

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Settings for output formats and directory locations for scan reports.

```yaml
reporting:
  enabled: true
  output_directory: "reports"
  output_filename: ""           # auto-generated if empty
  default_format: "html"        # html, pdf, json, sarif
  formats:                      # additional exports
    - junit
    - csv
    - xlsx
  xlsx_interactive_install: true
```

--------------------------------

### CLI Usage for Scan Diff

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-e-scan-diff-design.md

Commands to execute the diffing process between two scan files with optional output configuration.

```bash
python deep_eye.py --diff baseline.json current.json
python deep_eye.py --diff baseline.json current.json --diff-output report.html --diff-format html
```

--------------------------------

### Configure scan scope

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Defines allowed hosts, excluded paths, and permitted ports.

```yaml
scope:
  enabled: false
  allowed_hosts: []            # empty = target host only
  excluded_paths:
    - "/logout"
    - "/admin"
  allowed_ports: [80, 443, 8080, 8443]
```

--------------------------------

### Configure reconnaissance modules

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Defines active modules, subdomain sources, and port scanning behavior.

```yaml
reconnaissance:
  enabled_modules:
    - dns_enumeration
    - whois_lookup
    - technology_detection
    - ssl_analysis
    - osint_gathering
  subdomain_sources:
    - certificate_transparency
    - dns_bruteforce
  port_scan:
    common_ports: [80, 443, 8080, 8443, 3000, 5000, 8000, 9090]
    scan_timeout: 5
```

--------------------------------

### Implement scan loop with semaphore

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-i-async-migration-design.md

Asynchronous scan loop utilizing asyncio.Semaphore to manage concurrency limits.

```python
async def scan_all_urls(self, urls):
    sem = asyncio.Semaphore(self.threads)
    async def bounded(url):
        async with sem:
            return await self.scan_url(url)
    results = await asyncio.gather(*(bounded(u) for u in urls), return_exceptions=True)
```

--------------------------------

### Configure payload obfuscation techniques

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Lists available obfuscation methods and toggles WAF bypass mode.

```yaml
payload_obfuscation:
  enabled: false
  techniques:
    - base64
    - url_encode
    - double_url_encode
    - unicode
    - hex
    - random_case
    - comment_insertion
    - string_concatenation
    - null_byte
    - char_substitution
    - multiple_encoding
  waf_bypass_mode: false
```

--------------------------------

### Configure Vulnerability Checks

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Enable specific vulnerability checks and configure AI-driven payload generation.

```yaml
vulnerability_scanner:
  enabled_checks:
    - sql_injection
    - xss
    - command_injection
    - ssrf
    - ssti
    - lfi
    - rfi
    - jwt_vulnerabilities
    # ... 45+ available checks
  payload_generation:
    use_ai: true
    context_aware: true
    cve_database: true
```

--------------------------------

### Configure environment variable substitution in YAML

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Use the ${ENV_VAR} or ${ENV_VAR:-default} syntax to inject environment variables into your configuration files.

```yaml
ai_providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
    model: "${OPENAI_MODEL:-gpt-4o}"
```

--------------------------------

### Update CVE Database and Index

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/MODULES.md

Commands to update the local CVE database and rebuild the RAG index.

```bash
python scripts/update_cve_database.py
python scripts/build_cve_rag_index.py
```

--------------------------------

### Define Template Engine Configuration

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-g-template-engine-design.md

YAML configuration structure for enabling and filtering templates.

```yaml
templates:
  enabled: false
  template_directories: ["templates"]
  tag_filters: []
  severity_filter: []
```

--------------------------------

### Configure Compliance Reporting

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Enables compliance framework checks and specifies output formats for reports.

```yaml
compliance:
  enabled: true
  frameworks:
    - pci_dss
    - soc2
    - iso_27001

reporting:
  formats:
    - html
    - xlsx
    - junit
```

--------------------------------

### LoginPlayer Class Interface

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-d-captcha-login-replay-design.md

Python interface for the LoginPlayer component responsible for executing macros.

```python
class LoginPlayer:
    def __init__(self, http_client, config: Dict)
    def play(self, macro: Dict) -> bool
    def is_authenticated(self) -> bool
```

--------------------------------

### Configure OSINT gathering modules

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Enables various open-source intelligence gathering techniques and search limits.

```yaml
osint:
  enabled: false
  google_dorking: true
  email_harvesting: true
  metadata_extraction: true
  social_media_check: true
  breach_database_check: true
  certificate_transparency: true
  github_search: true
  pastebin_search: true
  max_search_results: 50
  timeout: 15
```

--------------------------------

### Configure Vulnerability Scanner

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Define enabled security checks and payload generation strategies.

```yaml
vulnerability_scanner:
  enabled_checks:
    - sql_injection
    - xss
    - command_injection
    - ssrf
    - xxe
    - path_traversal
    - csrf
    - open_redirect
    - cors_misconfiguration
    - security_misconfiguration
    - lfi
    - rfi
    - ssti
    - crlf_injection
    - host_header_injection
    - ldap_injection
    - xml_injection
    - insecure_deserialization
    - authentication_bypass
    - information_disclosure
    - sensitive_data_exposure
    - jwt_vulnerabilities
    - broken_authentication

  payload_generation:
    use_ai: true
    context_aware: true
    cve_database: false
    custom_wordlists: []
    use_payload_obfuscation: false

  testing:
    thorough_mode: false
    time_based_detection_delay: 5
    blind_injection_attempts: 3
```

--------------------------------

### Define compliance module directory structure

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-b-compliance-mapping-design.md

The directory layout for the new compliance utility module.

```text
utils/compliance/
  __init__.py
  mapper.py
  frameworks/
    pci_dss_v4.json
    soc2_cc.json
    iso_27001_2022.json
```

--------------------------------

### Format and Lint Code

Source: https://github.com/zakirkun/deep-eye/blob/main/CONTRIBUTING.md

Commands to maintain code quality using black and flake8.

```powershell
# Format code
black .

# Check linting
flake8 .
```

--------------------------------

### Export Scan Results in Multiple Formats

Source: https://github.com/zakirkun/deep-eye/blob/main/README.md

Specify output formats for the scan results using a comma-separated list.

```bash
python deep_eye.py -u https://target.com --formats junit,csv,xlsx
```

--------------------------------

### Compare Scan Results

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/QUICKSTART.md

Uses the CLI to compare two JSON scan result files and generate a diff report.

```bash
# Run baseline scan (results saved as JSON)
python deep_eye.py -u https://target.com

# Later, run another scan
python deep_eye.py -u https://target.com

# Compare
python deep_eye.py --diff reports/scan_baseline.json reports/scan_current.json \
  --diff-format html --diff-output reports/diff.html
```

--------------------------------

### Configure rate limiting

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/CONFIGURATION.md

Sets request throttling and error handling delays.

```yaml
rate_limiting:
  enabled: true
  requests_per_second: 5
  burst_size: 10
  delay_on_error: 3
```

--------------------------------

### Vulnerability Enrichment Integration

Source: https://github.com/zakirkun/deep-eye/blob/main/docs/superpowers/specs/2026-05-28-group-f-rag-cve-design.md

Logic for enriching vulnerability findings with CVE references using the RAG index.

```python
for vuln in self.vulnerabilities:
    query = f"{vuln['type']} {vuln.get('parameter','')} {vuln.get('evidence','')[:200]}"
    hits = rag.search(query, top_k=3)
    if hits and not vuln.get('cve_references'):
        vuln['cve_references'] = [h['cve_id'] for h in hits if h['score'] >= min_score]
        vuln['rag_matched'] = True
```