Deep Eye: an AI-orchestrated web scanner that ships YAML templates and a diff workflow

What Deep Eye actually runs when you point it at a URL

Deep Eye is a Python CLI whose entry point is a single file, `deep_eye.py`. The repository description frames it as orchestrating AI providers for payload generation against 45 plus vulnerability types, while the README claims 50 plus vulnerability checks and lists them by name: SQLi, XSS, SSRF, deep JWT, IDOR, deep GraphQL, CORS/CSP and supply-chain JavaScript analysis, among others. Both counts appear in the project's own materials and neither is reconciled in the docs, so treat the headline number as marketing and read `config/config.example.yaml` for the list you actually get. The MIT badge on the README sits next to a GitHub license field that reports NOASSERTION, while `setup.py` declares `License :: OSI Approved :: MIT License`. The version is 1.4.0 in both `setup.py` and the README badge, and the only tagged release is v1.4.

The workflow the README describes has four stages that you can turn on and off independently in the config file: an AI planner that suggests check order and budget, AI triage that filters false positives, an evidence summarizer that writes a per-finding summary, and a false-positive replay that re-runs rejected findings. That decomposition is the most defensible part of the design. Scanners that bolt a language model onto the end produce confident prose about findings they got wrong. Deep Eye instead separates generating a payload from judging whether a finding is real, and puts both behind YAML toggles.

Compliance mapping to PCI-DSS v4, SOC2 control criteria and ISO 27001:2022 rides along on the reporting side, along with export to HTML, PDF, JSON, SARIF, JUnit, CSV and XLSX. SARIF matters more than it looks, because that is the format code scanning tools ingest, so a Deep Eye run can sit next to Bandit or Semgrep output in the same view.

Installing on Linux and macOS with the bundled bootstrap script

The install path is a shell script that builds a project-local virtual environment named `.deep-venv`, which keeps the tool out of your system Python:

chmod +x scripts/install.sh && ./scripts/install.sh
source .deep-venv/bin/activate

A Windows PowerShell equivalent exists at `scripts/install.ps1` and uses the same environment name. There is also a manual route, which is the one to take on a machine where you want to see exactly what lands:

pip install -r requirements.txt
cp config/config.example.yaml config/config.yaml

The requirement file is worth a look before you run anything, because it is long and opinionated. It pulls in provider SDKs for OpenAI, Anthropic, Ollama, Mistral, both Google generative AI packages, LiteLLM and Groq, then crawlers (`selenium`, `httpx`, `playwright`), recon libraries (`dnspython`, `python-whois`, `shodan`), reporting (`reportlab`, `jinja2`), and a data science stack (`scikit-learn`, `numpy`, `pandas`). Both Google SDKs are present, `google-genai` and `google-generativeai`, and WeasyPrint is listed but commented out with a note that it needs GTK libraries on Windows, so ReportLab is the portable path. Playwright needs its own browser download on top of the pip install, which the README spells out as a separate optional step.

If you launch without a config file, an interactive wizard runs instead of failing. That is friendlier than a stack trace, though for anything scripted you want `config/config.yaml` in place before the first run.

Provider failover through a single generate abstraction

The claim to examine here is failover across providers, and the documentation is not consistent about how many there are. The repository description names ten: OpenAI, Claude, Grok, Gemini, OLLAMA, Groq, Mistral, OpenRouter, LiteLLM and LM Studio. The README feature list says eleven and adds OrcaRouter. The README's own provider list further down names thirteen keys, adding `requesty` and `nvidia_nim`. The release history supports the wider list: v1.4 shipped a Mistral provider, an OpenRouter provider, and an LM Studio provider via its OpenAI-compatible API, which is three of the later entries arriving in a single tagged release.

Configuration looks like this:

ai_providers:
  openai:
    enabled: true
    api_key: "sk-..."
    model: "gpt-4o"
  ollama:
    enabled: true
    base_url: "http://localhost:11434"
    model: "llama2"

Because Ollama and LM Studio both speak OpenAI-shaped APIs, a fully local run is a matter of pointing `base_url` at a local server and leaving the hosted keys out. That is the configuration most people running this against an internal network will want, since it removes the target's payloads from a third party's logs. The abstraction is described as a single `generate()` call, which is the right shape for it: a scanner that needs payload text should not care which vendor produced it.

The related feature is CVE intelligence, described as a RAG-indexed CVE database built from NVD, MITRE and Exploit-DB patterns, with builder scripts under `scripts/`. Payload generation is also context-aware, using WAF fingerprinting and detected tech stack, which is the difference between a scanner that sprays a fixed string list and one that tries a syntax a specific stack will parse differently.

Nuclei-style templates and the check catalogue

Checks are not hardcoded functions. They live as YAML templates under `templates/` with matchers and extractors, the same convention Nuclei uses, and the repository ships a `plugins/` directory for custom `PluginBase` plugins. The enabled set is configured rather than compiled:

vulnerability_scanner:
  enabled_checks:
    - sql_injection
    - xss
    - ssrf
    - cors_csp
    - jwt_deep
    - idor
    - graphql_deep
  payload_generation:
    use_ai: true
    context_aware: true

Two things follow from the template format. First, adding a check no longer means writing Python, which is the difference between a tool people extend and a tool people only run. Second, templates are reviewable text, so you can read what a check actually sends before pointing it at anything. The README's comment that the full list lives in `config.example.yaml` is an honest one, since the abbreviated block above is exactly what the docs show you.

The rest of the tree tells you what the pipeline is made of: `core/` holds the engine, scanner, reports and plugin loading, `modules/` holds attack and pipeline modules, `utils/` holds HTTP, exports, compliance, scope and fingerprinting, and `data/` holds a SQLite store plus an `auth_sessions` table and the RAG index. That session store is what makes multi-role testing possible, since login macro replay lets you hold several authenticated sessions and test IDOR against each one rather than just the first. There is a pytest suite under `tests/`, and `proxy/` is described as a skill discovery loader with agent skills under `.agents/skills/` covering pentest, bounty, red and blue team, and CTF work.

Baseline diffing and retest workflows for repeat scans

Most web scanners treat every run as a fresh report, which turns a known finding into noise on the next scan. Deep Eye treats a scan as a baseline you can compare against:

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

The related flag does the same job inside a live scan, keeping only findings that are new relative to a baseline:

python deep_eye.py -u https://target.com --retest-new baseline.json

Together with finding dedupe, which the README describes as fingerprint collapse, this is what makes the tool usable on a schedule. A pentest engagement is mostly re-confirmation, and a scanner that can say what changed since March is worth more than one that lists forty findings every April. The diff can output HTML, JSON or CSV, and the scan itself can emit JUnit, so a regression suite can assert on the count.

Scope control is the other half of making a scan repeatable. Beyond URL patterns, `--scope-nl` takes a natural language string:

python deep_eye.py -u https://target.com --scope-nl "only /api/* no /logout host target.com"

Read that flag as a convenience rather than a control. A language model deciding scope is a reasonable first pass and a poor last line of defence, so pair it with an explicit allowlist in the config. The CAPTCHA handling deserves a note too: reCAPTCHA, hCaptcha, Cloudflare Turnstile and Arkose are detected, with solver support and a skip path, via Playwright and optionally Browser Use. Browser automation and mitmproxy integration are both there too, and `curl_cffi` is listed as optional for TLS evasion, which tells you the tool expects to meet bot protection head on.

Where the README stops and the docs directory takes over

The README is a feature list with working commands, and it hands off early. The documentation table at its end points at `docs/QUICKSTART.md` for install and first scan and `docs/CONFIGURATION.md` for the full YAML reference, and that second file is the one to read before running anything real. The scanner defaults are short enough to absorb:

scanner:
  target_url: "https://target.com"
  default_threads: 5
  default_depth: 2
  enable_recon: true
  ai_provider: "openai"

Five threads and depth two are conservative defaults for a tool that will send generated payloads at a host, and `enable_recon` on by default means a bare `-u` invocation crawls before it attacks. Worth knowing before your first run.

Beyond that, `CHANGELOG.md`, `SECURITY.md`, `CONTRIBUTING.md`, `AGENTS.md` and `CLAUDE.md` all sit at the repo root, and the v1.4 release notes show why `SECURITY.md` matters: three separate security fixes in that release, replacing a hardcoded attacker callback domain with a configurable one, sanitizing vulnerability evidence in webhook notifications, and fixing a path traversal in collaborative scanner session loading. Findings contain proof-of-concept payloads and webhook notifications carry them off the machine, so treat those two paths as sensitive.

The last thing to settle is activity. The repository is not archived, with 12 open issues, 2,310 stars, 421 forks and a last push on 2026-09-04. The v1.4 tag carries a release name of "Release Beta Version" and the classifiers in `setup.py` agree, calling it Development Status 4, Beta. That is a self-description worth carrying into an evaluation: treat the compliance mapping and the AI triage as claims to check against your own findings, not as settled behaviour.

Editorial conclusion

Deep Eye is interesting less as a scanner and more as a shape of tool. Payload generation is delegated to whichever provider answers, checks are YAML templates rather than hardcoded functions, and a scan produces a JSON baseline you can diff against next time, which is the part most web scanners get wrong. The costs are real: the provider matrix is unevenly filled, the check count is quoted two different ways, and almost every operational question lives in docs/CONFIGURATION.md rather than the README. Start with the single-URL invocation, read the configuration file end to end before trusting it with anything you care about, and treat the compliance mapping and AI triage as features to verify against your own findings rather than conclusions to import.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. zakirkun/deep-eye on GitHub