deep eye

The Problem Security teams that rely on a single LLM often hit rate‑limits, provider outages, or model‑specific blind spots. When a penetration‑test requires dozens of payload variations across many vulnerability classes, manually switching APIs or re‑prompting is time‑consuming and error‑prone.

What This Does Deep Eye is a Python‑3.8+ CLI that drives a multi‑provider LLM layer (OpenAI, Claude, Gemini, Grok, Ollama, Groq, Mistral, OpenRouter, OrcaRouter, LiteLLM, LM Studio) to generate, rank, and validate exploitation payloads. The scan engine enumerates ≈ 50 vulnerability checks—SQLi, XSS, SSRF, IDOR, GraphQL, JWT misuse, etc.—and assembles a compliance‑mapped report (PCI‑DSS, SOC 2, ISO 27001).

Key source locations:

How It Is Wired

1. Start – python deep_eye.py -u https://target.com runs the script in the repository root.
2. Config load – deep_eye.py reads config/config.example.yaml (or config.yaml if present) to pull API keys, timeout budgets, and optional Playwright settings.
3. Target init – The orchestrator creates a TargetContext object, optionally seeding from an OpenAPI spec (core/openapi_ingestor.py).
4. Module loop – For each file in modules/ that registers a VulnCheck class, the orchestrator calls check(). Inside check(): Prompt is assembled (tech‑stack, WAF fingerprint, CVE hints). provider_manager.generate(prompt) selects the first healthy provider; on failure it falls back to the next. The LLM response is parsed by a regex/YAML matcher defined in the corresponding templates/ file. Evidence (HTTP request/response) is stored in a Finding object.
5. Deduplication & compliance – After all modules run, utils/dedupe.py collapses duplicate fingerprints; utils/compliance_mapper.py adds PCI/SOC/ISO tags.
6. Report output – utils/report_builder.py writes the selected formats (--formats junit,csv,xlsx etc.) and optionally triggers notifications (Slack/Discord) via utils/notifier.py.

The widest blast radius lies in provider_manager.py because every vulnerability check depends on it; a provider‑API change or network outage will halt the entire scan. The module registry in core/__init__.py is the only hub that introduces cycles (providers may call back into utils for rate‑limit handling), so modifications there should be carefully isolated.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/deep-eye
cd deep-eye

# Create a virtual‑env and install deps
python -m venv .deep-venv
source .deep-venv/bin/activate
pip install -r requirements.txt

# Copy the example config and insert your API keys
cp config/config.example.yaml config/config.yaml
# Edit config/config.yaml → add OpenAI, Claude, etc. keys

# Optional: install Playwright for CAPTCHA handling
pip install playwright && playwright install chromium

# Run a basic scan
python deep_eye.py -u https://demo.target.com

# Run with a custom config and multiple output formats
python deep_eye.py -c config/config.yaml -u https://demo.target.com \
    --formats html,json,sarif

If you need a differential scan, supply the baseline JSON as shown in the README:

python deep_eye.py --diff baseline.json current.json \
    --diff-format html --diff-output diff_report.html

Real‑World Use A red‑team operator can integrate Deep Eye into a CI pipeline that triggers on new pull‑requests to a staging environment. The pipeline runs deep_eye.py with a service‑account API key, stores the JSON report as an artifact, and fails the build if any finding maps to “Critical” severity under PCI‑DSS. The same artifact can be fed to a ticketing system via the Slack webhook configured in config.yaml.

Code Health & Issues

• Medium – No CI/CD pipeline – repository lacks .github/workflows/ or other automation config.
• Low – No lockfile – dependencies are listed only in requirements.txt; reproducible builds are not guaranteed.
• Medium – Sparse test coverage – 93 test files exist, but no test runner configuration (e.g., pytest.ini) is present, making local execution non‑trivial.
• Low – Documentation gaps – While README.md and many .md files describe usage, there is no generated API reference for the provider manager or module interfaces.

The Bottom Line Deep Eye delivers a functional, extensible multi‑LLM penetration‑testing framework with a clear modular layout and solid reporting features. It is ready for internal use or prototype integration, but production adoption should first add a CI pipeline, a dependency lockfile (e.g., requirements.lock), and a formal test harness to ensure stability when updating providers or adding new vulnerability modules.