god-eye/README.md

<p align="center">
  <img src="https://raw.githubusercontent.com/Vyntral/god-eye/main/assets/logo.png" alt="God's Eye" width="220">
</p>

<h1 align="center">God's Eye</h1>

<h3 align="center">AI-powered attack-surface discovery & offensive security<br>in a single Go binary. Terminal-only. Zero cloud.</h3>

<p align="center">
  <img src="assets/wizard-demo.gif" alt="Interactive wizard walkthrough" width="90%">
</p>

<p align="center">
  <sub><em>Zero-flag launch → AI tier → model check → target → profile → live scan. Recorded live against <code>scanme.nmap.org</code>.</em></sub>
</p>

<p align="center">
  <a href="#"><img src="https://img.shields.io/badge/version-2.0--dev-blue.svg?style=for-the-badge" alt="Version"></a>
  <a href="https://golang.org/"><img src="https://img.shields.io/badge/language-Go%201.21-00ADD8.svg?style=for-the-badge&logo=go" alt="Go"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge" alt="License"></a>
  <a href="#ai-integration"><img src="https://img.shields.io/badge/AI-Ollama%20(local)-blueviolet.svg?style=for-the-badge&logo=ollama" alt="AI"></a>
  <a href="#nuclei-integration"><img src="https://img.shields.io/badge/Nuclei-13k%20templates-orange.svg?style=for-the-badge" alt="Nuclei"></a>
  <a href="AI_SETUP.md"><img src="https://img.shields.io/badge/privacy-100%25%20local-success.svg?style=for-the-badge" alt="Privacy"></a>
  <a href="#"><img src="https://img.shields.io/badge/tests-185%20race--safe-brightgreen.svg?style=for-the-badge" alt="Tests"></a>
  <a href="https://x.com/vyntral"><img src="https://img.shields.io/badge/follow-%40vyntral-000000.svg?style=for-the-badge&logo=x" alt="X / Twitter"></a>
</p>

<p align="center">
  <a href="#-30-second-quickstart">⚡ Quick start</a> •
  <a href="#-what-makes-god-eye-different">Why</a> •
  <a href="#-what-it-finds">Features</a> •
  <a href="#-the-wizard">Wizard</a> •
  <a href="#-ai-integration">AI</a> •
  <a href="BENCHMARK-SCANME.md">Live benchmark</a> •
  <a href="#-competitive-landscape">vs. competitors</a> •
  <a href="#-legal-notice">Legal</a>
</p>

---

## ⚡ 30-second quickstart

```bash
git clone https://github.com/Vyntral/god-eye && cd god-eye
go build -o god-eye ./cmd/god-eye
./god-eye
```

That's it. Running `./god-eye` with no flags launches an **interactive wizard** that:

1. Asks which AI tier you want (lean / balanced / heavy / none)
2. Checks Ollama, downloads missing models for you
3. Asks for your target, validates it, applies a scan profile
4. Streams colorized events live as the scan runs

Prefer one-liners? You're covered:

```bash
./god-eye -d target.com --pipeline --profile bugbounty --live
./god-eye -d target.com --pipeline --enable-ai --ai-profile heavy --nuclei --live
./god-eye -d target.com --pipeline --profile asm-continuous --monitor-interval 24h
```

---

## 🎯 What makes God's Eye different

Every OSS recon tool picks a lane: passive subdomain enum, or vuln scanning, or fingerprinting. You end up chaining four tools with Bash + `jq` and praying nothing breaks. **God's Eye v2 is the whole pipeline in a single binary, with an AI layer that no other OSS scanner has.**

### Six things no competitor does in one command

| | |
|---|---|
| 🧙 **Interactive wizard** | Zero-flag launch. Walks you through setup. |
| 🤖 **Local LLM CVE correlation** | Ollama cascade maps detected tech → real CVEs offline. |
| 🎚️ **AI tier presets** | `lean` / `balanced` / `heavy` — picks models for your RAM. |
| 📥 **Auto-manage 13k Nuclei templates** | `god-eye nuclei-update` downloads + refreshes the cache. |
| 🛰️ **Auto-pull Ollama models** | Missing models? Streams them from the registry. |
| 🔄 **ASM continuous monitoring** | Scheduler + diff engine + webhooks built-in. |

### A concrete example — what you get in one command

Running `./god-eye -d scanme.nmap.org --pipeline --profile bugbounty --ai-profile balanced --live` surfaces in **under 2½ minutes**:

- ✅ Full passive subdomain enumeration (26 sources, no API keys)
- ✅ HTTP probe + technology fingerprint (`Apache/2.4.7 (Ubuntu)`)
- ✅ TLS analysis + appliance fingerprint (25+ vendors)
- ✅ **AI-assisted CVE correlation** — `Apache 2.4.7 → CVE-2026-34197 (CRITICAL/9.8) +4 more`
- ✅ Security header audit (OWASP Secure Headers Project aligned)
- ✅ JS secret extraction (regex + filter against noise)
- ✅ Subdomain takeover check (110+ signatures)
- ✅ Cloud asset discovery (S3, GCS, Azure, Firebase)

No `subfinder | httpx | nuclei | tee | jq` pipeline. No glue scripts. One binary.

See the live, reproducible benchmark: **[BENCHMARK-SCANME.md](BENCHMARK-SCANME.md)**.

---

## 🧙 The wizard

```
═══════════════════════════════════════════════════════════
  God's Eye v2 — interactive setup
  Ctrl-C to abort at any time.
═══════════════════════════════════════════════════════════

? Select AI tier
  ▸ 1) Lean     — 16GB RAM · qwen3:1.7b + qwen2.5-coder:14b (default)
    2) Balanced — 32GB RAM · qwen3:4b + qwen3-coder:30b (MoE, 256K ctx)
    3) Heavy    — 64GB RAM · qwen3:8b + qwen3-coder:30b (max quality)
    4) No AI    — Pure recon without LLM analysis
  Choice [1]: 2

⚙ Checking Ollama at http://localhost:11434…
  ↓ Missing models: qwen3:4b, qwen3-coder:30b
? Download missing models now? [Y/n] y
↓ qwen3:4b            100%  2.5GB / 2.5GB  ✓ ready
↓ qwen3-coder:30b     100%  17GB / 17GB    ✓ ready

? Target domain
  > target.com

? Select scan profile
    1) Quick          — passive enum + HTTP probe, no brute
  ▸ 2) Bug bounty     — full recon, AI + all features (default)
    3) Pentest        — full recon + light stealth
    4) ASM continuous — recurring scans with diff + alerts
    5) Stealth max    — paranoid evasion

? Enable live event view? [Y/n] y
? Log every AI query to stderr? [y/N] y
? Save report to file (empty to skip)
  > report.json

─── Scan summary ───
  Target           target.com
  Scan profile     bugbounty
  AI tier          balanced
  AI auto-pull     yes
  AI verbose       yes
  Live view        yes (v=1)
  Output           report.json (format=json)

? Start scan? [Y/n]
```

Force the wizard even when `-d` is set:

```bash
./god-eye --wizard -d target.com
```

When stdin is not a TTY (CI, pipes), the wizard auto-skips — one binary, two modes.

<p align="center">
  <img src="assets/live-scan.gif" alt="Live event stream" width="90%">
</p>

<p align="center">
  <sub><em>Live colorized event stream — every finding appears as it's discovered.</em></sub>
</p>

---

## 🔍 What it finds

### 🛰️ Discovery — 11 module types, 26 passive sources

<details>
<summary><strong>Full source list</strong> — all key-less / free</summary>

crt.sh · Certspotter · AlienVault · HackerTarget · URLScan · RapidDNS · Anubis · ThreatMiner · DNSRepo · SubdomainCenter · Wayback · CommonCrawl · Sitedossier · Riddler · Robtex · DNSHistory · ArchiveToday · JLDC · SynapsInt · CensysFree · BufferOver · DNSDumpster · Omnisint · HudsonRock · WebArchiveCDX · Digitorus

</details>

Active techniques:

- **DNS brute-force** with opportunistic wildcard detection and per-host filtering
- **Recursive pattern learning** — learns naming conventions from found hosts
- **DNS permutation** (alterx-style, opt-in) — `api` → `api-v2`, `stg-api`, `api.dev`, etc.
- **AXFR zone-transfer** attempted against every authoritative name-server
- **Reverse DNS ±16 sweep** around every resolved IP (opt-in)
- **Virtual host discovery** (opt-in)
- **ASN/CIDR expansion** (opt-in)
- **Certificate Transparency live polling** (opt-in)
- **GitHub code dorks** (honors `GITHUB_TOKEN` env var for higher rate limits)
- **Supply-chain recon** — npm + PyPI packages referencing target brand

### 🧬 Enrichment

- HTTP/HTTPS probing — status, title, content length, server, response time
- Technology fingerprinting (WordPress, React, Next.js, Angular, Laravel, Django, …)
- **TLS appliance fingerprinting for 25+ vendors** — Fortinet FortiGate, Palo Alto PAN-OS, Cisco ASA, F5 BIG-IP, SonicWall, Check Point, pfSense, OPNsense, Juniper SRX, OpenVPN, Pulse Secure, GlobalProtect, Citrix NetScaler, …
- Internal-hostname extraction from certificate SANs
- TCP connect port scan on common ports

### 🛡️ Vulnerability detection

<table>
<tr><td><b>Header audit</b></td><td>HSTS · CSP · X-Frame-Options · X-Content-Type-Options · Referrer-Policy · Permissions-Policy. OWASP-aligned with remediation text.</td></tr>
<tr><td><b>Surface misconfigs</b></td><td>Open redirect · CORS wildcards · dangerous HTTP methods · Git/SVN exposure · backup-file discovery · admin/API-endpoint enumeration</td></tr>
<tr><td><b>Takeover</b></td><td>110+ fingerprints: GitHub Pages, S3, CloudFront, Heroku, Netlify, Vercel, Azure Web Apps, Shopify, …</td></tr>
<tr><td><b>GraphQL</b></td><td>Introspection enabled detection + mutation-enabled flag (v2 native)</td></tr>
<tr><td><b>JWT</b></td><td><code>alg=none</code>, excessive expiry, kid-injection, weak-HMAC crack (v2 native)</td></tr>
<tr><td><b>HTTP smuggling</b></td><td>CL.TE / TE.CL timing probe, non-destructive (v2 native, opt-in)</td></tr>
<tr><td><b>Cloud assets</b></td><td>S3 / GCS / Azure Blob / Firebase enumeration</td></tr>
<tr><td><b>Secret extraction</b></td><td>Regex + entropy + validation. FP denylist for third-party APIs and UI strings.</td></tr>
<tr><td><b>Nuclei compat</b></td><td>~13k community templates, HTTP subset, auto-scope-filtered (no off-host false positives)</td></tr>
</table>

### 🧠 AI layer

- **Local LLM** via [Ollama](https://ollama.com) — fully private, no API keys, no cloud.
- **Six event-driven handlers** — CVE correlation · JavaScript secret validation · HTTP response anomaly analysis · Secret filtering · Multi-agent vulnerability enrichment · End-of-scan anomaly detection + executive report
- **End-of-scan AI brief** — a framed terminal summary with severity totals, top exploitable chains, AI agent contributions, executive prose, and recommended next actions
- Content-hash cache so the same tech detected on 10 hosts fires **one** Ollama call, not ten
- Three tuned profiles:

| Tier          | Triage model | Deep model                | RAM | Context |
|---------------|--------------|---------------------------|-----|---------|
| **lean**      | qwen3:1.7b   | qwen2.5-coder:14b         | 16GB| 32K     |
| **balanced**  | qwen3:4b     | **qwen3-coder:30b (MoE)** | 32GB| **256K**|
| **heavy**     | qwen3:8b     | qwen3-coder:30b (MoE)     | 64GB| 256K    |

- **Cascade architecture** — fast triage filters ~70% of noise; deep model runs only on relevant findings. Cuts AI overhead to ~20-30% of total scan time.
- **8 specialized agents** (multi-agent mode): XSS, SQLi, Auth, API, Crypto, Secrets, Headers, General.
- **Automatic CVE correlation** — offline CISA KEV (~1500 actively-exploited CVEs) + online NVD function-calling fallback.
- **Auto-pull of missing models** — no manual `ollama pull`.
- `--ai-verbose` streams every query to stderr for observability.

### 🔄 Continuous monitoring (ASM)

```bash
./god-eye -d target.com --pipeline --profile asm-continuous \
  --monitor-interval 24h --monitor-webhook https://hooks.slack.com/...
```

- Interval-based re-scans with **diff engine** (9 change kinds: `new_host`, `removed_host`, `new_ip`, `removed_ip`, `status_change`, `tech_change`, `new_vuln`, `cleared_vuln`, `cert_change`, `new_takeover`)
- Webhook (generic JSON POST) + stdout alerter. Slack/Discord/Linear adapters planned.

### 🥷 Stealth — 4 levels

| Mode         | Threads | Delay       | Rate  | Use case                       |
|--------------|---------|-------------|-------|--------------------------------|
| `light`      | 100     | 10-50ms     | 100/s | Avoid basic rate limits        |
| `moderate`   | 30      | 50-200ms    | 30/s  | Evade WAF detection            |
| `aggressive` | 10      | 200ms-1s    | 10/s  | Sensitive targets              |
| `paranoid`   | 3       | 1-5s        | 2/s   | Maximum evasion                |

All modes use: UA rotation (25+), request randomization, DNS query distribution, per-host throttling, 50-70% timing jitter (aggressive+), adaptive backoff on error-rate spikes.

---

## 🧠 AI integration

God's Eye v2 is the only open-source recon tool that ships **LLM-assisted CVE correlation out of the box**, running entirely on your machine.

### One-shot setup

```bash
# 1. Install Ollama (one-time)
curl https://ollama.ai/install.sh | sh
ollama serve &

# 2. Let the wizard pull your tier's models automatically
./god-eye
```

Or manually:

```bash
# Lean (default, 16GB RAM) — tried and tested
ollama pull qwen3:1.7b && ollama pull qwen2.5-coder:14b

# Balanced (32GB RAM, MoE 30B — the sweet spot)
ollama pull qwen3:4b && ollama pull qwen3-coder:30b

# Heavy (64GB+ RAM, top quality)
ollama pull qwen3:8b && ollama pull qwen3-coder:30b
```

### Why MoE matters

`qwen3-coder:30b` is a **Mixture-of-Experts** model: 30B total parameters, only **3.3B active per token**. You get dense-30B quality at the inference speed of a dense-3B model, with a **256K context window** — enough to ingest entire JS bundles + long HTTP bodies in a single prompt.

Complete AI guide: **[AI_SETUP.md](AI_SETUP.md)**

---

## 🎯 Nuclei integration

13,023 community templates auto-downloaded and executed through a compat layer:

```bash
# One-time: download + extract templates (~40MB, ~15 seconds)
./god-eye nuclei-update

# Or let the scan auto-download on first use
./god-eye -d target.com --pipeline --nuclei --live
```

**Supported subset** (≈ 65-70% of community templates):

- `http:` / `requests:` protocols
- Matchers: `word` · `regex` · `status` · `size` (with `part`: header/body/response, `condition`: and/or, negative matching)
- Templating: `{{BaseURL}}` · `{{Hostname}}` · `{{RootURL}}`

**Out of scope** (templates auto-skipped):

- DNS / SSL / network / headless / code / workflow protocols
- Payloads, fuzzing, DSL matchers
- Off-host templates (OSINT-style user lookups on third-party services)

---

## 🧩 The wizard walks you through everything. Power users get every knob.

```text
Core flags:
  -d, --domain string        Target domain
  -c, --concurrency int      Workers (default 1000)
  -t, --timeout int          Per-request timeout (default 5s)
  -o, --output string        Output file
  -f, --format string        txt | json | csv
  -s, --silent               Suppress console output
  -v, --verbose              Verbose logs

Pipeline (v2):
      --pipeline             Use v2 event-driven pipeline
      --wizard               Force interactive setup (even with -d set)
      --profile string       bugbounty | pentest | asm-continuous | stealth-max | quick
      --config string        Path to YAML config (auto-discovers ~/.god-eye/config.yaml)
      --live                 Colorized live event stream
      --live-verbosity int   0 (findings) | 1 (normal) | 2 (noisy)

AI:
      --enable-ai            Turn on AI cascade
      --ai-profile string    lean | balanced | heavy
      --ai-url string        Ollama URL (default http://localhost:11434)
      --ai-fast-model str    Triage model tag
      --ai-deep-model str    Deep-analysis model tag
      --ai-cascade           Use triage→deep cascade (default true)
      --ai-deep              Skip triage, always run deep
      --multi-agent          Enable 8-agent orchestration
      --ai-verbose           Log every Ollama query to stderr
      --ai-auto-pull         Auto-download missing models (default true)

Nuclei:
      --nuclei               Run Nuclei-format templates
      --nuclei-templates str Template directory override
      --nuclei-auto-download Auto-fetch templates from GitHub (default true)

Stealth:
      --stealth string       light | moderate | aggressive | paranoid
      --proxy string         Outbound proxy URL. Supports http://, https://, socks5://, socks5h:// (Tor). Basic auth via http://user:pass@host.

Monitoring:
      --monitor-interval X   Re-scan every X (e.g. 24h, 6h)
      --monitor-webhook URL  POST diff reports to URL

Subcommands:
  update-db                  Refresh CISA KEV CVE cache
  db-info                    Show KEV cache status
  nuclei-update              Refresh nuclei-templates ZIP cache
```

Full list: `./god-eye --help` • Full cookbook: **[EXAMPLES.md](EXAMPLES.md)**

---

## 📊 Competitive landscape

On `scanme.nmap.org` (Nmap's authorized test host) — see full methodology in **[BENCHMARK-SCANME.md](BENCHMARK-SCANME.md)**.

| Capability | God's Eye v2 | Subfinder | Amass | Assetfinder | Findomain | BBOT | Nuclei |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| **Discovery** | | | | | | | |
| Passive sources | 26 | 30+ | 20+ | 8 | 15 | 40+ | — |
| DNS brute-force | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | — |
| Permutation (alterx) | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | — |
| AXFR / ASN | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | — |
| **Enrichment** | | | | | | | |
| HTTP probe + tech | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ◐ |
| TLS appliance fingerprint | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Vulnerability** | | | | | | | |
| Headers / CORS / redirect | ✅ | ❌ | ❌ | ❌ | ❌ | ◐ | ✅ |
| Takeover (110+) | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| GraphQL introspection | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| JWT analyzer + crack | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| HTTP smuggling probe | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ◐ |
| Cloud assets (S3/GCS) | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Nuclei templates | ✅ subset | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ full |
| **AI** | | | | | | | |
| Local LLM analysis | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Multi-agent orchestration | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Auto-pull models | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| AI CVE correlation | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Ops** | | | | | | | |
| Interactive wizard | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Continuous monitoring + diff | ✅ | ❌ | ❌ | ❌ | ❌ | ◐ | ❌ |
| Webhook alerts | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Event-driven plugin arch | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Stealth profiles (4 levels) | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |

### Honest positioning

**Where God's Eye v2 wins:**

- **AI-assisted CVE correlation** — no other OSS scanner does `Apache 2.4.7 → CVE-2026-34197 (CRITICAL/9.8) +4 more` automatically.
- **Single-binary full-pipeline workflow** — replaces `subfinder | httpx | nuclei | katana` + Bash glue.
- **Interactive wizard + auto-managed dependencies** (Ollama models, Nuclei templates).
- **ASM continuous mode** — scheduler + diff + webhooks out of the box.

**Where competitors still beat us:**

- **Pure passive speed** — `assetfinder` and `subfinder` are 3-5 s on single-host targets. We're slower because we also probe + analyze.
- **Nuclei template breadth** — full `nuclei` CLI runs DNS/SSL/network/headless templates too; our compat layer is HTTP-only (~70% coverage).
- **Amass ASN graph depth** — unmatched for multi-asset infrastructure reconstruction.
- **BBOT module count** — 100+ Python modules vs our 29.

Full methodology and scenario runs: **[BENCHMARK.md](BENCHMARK.md)**.

---

## 🔁 Continuous monitoring example

```bash
./god-eye -d target.com --pipeline --profile asm-continuous \
  --monitor-interval 24h \
  --monitor-webhook https://hooks.slack.com/services/T.../B.../XXX
```

Every 24h the scan reruns. When the diff contains meaningful changes, the webhook fires:

```json
{
  "target": "target.com",
  "changes": [
    {
      "kind": "new_host",
      "host": "staging-v2.target.com",
      "detected_at": "2026-04-19T08:02:14Z"
    },
    {
      "kind": "new_vuln",
      "host": "admin.target.com",
      "after": "Git Repository Exposed",
      "severity": "critical",
      "detected_at": "2026-04-19T08:04:01Z"
    }
  ]
}
```

Supported `kind` values: `new_host` · `removed_host` · `new_ip` · `removed_ip` · `status_change` · `tech_change` · `new_vuln` · `cleared_vuln` · `cert_change` · `new_takeover`.

---

## 📐 Output formats

### Colorized terminal (`--live`)

```text
▶ phase discovery
↳ passive:crt.sh  api.target.com
↳ passive:crt.sh  admin.target.com
↳ brute           staging.target.com
↳ axfr:ns1.target.com  internal-gw.target.com
▣ phase discovery  42.3s
▶ phase resolution
⏚ api.target.com  [1.2.3.4]
● https://api.target.com [200] API Documentation
● https://admin.target.com [401]
[HIGH]  CORS Misconfiguration  https://api.target.com  cors-misconfig
[CRIT]  Git Repository Exposed  https://staging.target.com/.git/config  git-exposed
 TAKEOVER  dev.target.com  service=GitHub Pages
[HIGH]  CVE Apache@2.4.7 → CVE-2026-34197 (CRITICAL/9.8) +4 more
·  scan elapsed 2m47s, 847 events seen
```

### JSON (`-f json -o report.json`)

```json
{
  "subdomain": "api.target.com",
  "ips": ["1.2.3.4"],
  "status_code": 200,
  "technologies": ["nginx/1.18.0", "Node.js"],
  "cloud_provider": "AWS",
  "tls_fingerprint": {
    "vendor": "Fortinet",
    "product": "FortiGate",
    "appliance_type": "firewall",
    "internal_hosts": ["fw-internal.corp.local"]
  },
  "security_headers": ["HSTS"],
  "missing_headers": ["Content-Security-Policy", "X-Frame-Options"],
  "cors_misconfig": "wildcard with credentials",
  "ai_findings": ["Reflected XSS via user parameter"],
  "cve_findings": ["CVE-2021-23017"]
}
```

### CSV

Flat columns suitable for spreadsheet / pivot table analysis.

---

## 💡 Typical use cases

### Bug-bounty recon

```bash
./god-eye -d in-scope.com --pipeline --profile bugbounty --live \
  -o bounty-findings.json -f json
```

### Authorized penetration test (with light stealth)

```bash
./god-eye -d client.com --pipeline --profile pentest \
  --stealth light --live -o pentest-report.json -f json
```

### Fast triage on a fresh target

```bash
./god-eye -d target.com --pipeline --profile quick
```

### ASM continuous monitoring (daily diff + Slack)

```bash
./god-eye -d company.com --pipeline --profile asm-continuous \
  --monitor-interval 12h \
  --monitor-webhook https://hooks.slack.com/...
```

Full cookbook of 13 recipes: **[EXAMPLES.md](EXAMPLES.md)**.

---

## 📋 Requirements & install

- **Go 1.21+** for building
- **Ollama** (optional, for AI features) — [installation guide](https://ollama.com)
- **RAM:** 16GB (lean tier), 32GB (balanced), 64GB+ (heavy)

```bash
git clone https://github.com/Vyntral/god-eye.git
cd god-eye
go build -o god-eye ./cmd/god-eye
./god-eye --help
```

Dependencies (pure Go, no cgo):

```
github.com/fatih/color
github.com/miekg/dns
github.com/spf13/cobra
github.com/mattn/go-isatty
gopkg.in/yaml.v3
```

Single static binary on every platform.

---

## 🏗️ Architecture

v2 is structured in three layers — see **[CLAUDE.md](CLAUDE.md)** for the full reference.

**Foundation** (`internal/`)

- `eventbus` — typed pub/sub, race-safe, per-subscriber goroutines, drop counter
- `module` — interface + auto-registering registry, phase-based selection
- `store` — thread-safe host store, per-host locks, deep-copy reads
- `pipeline` — coordinator with phase barriers, panic recovery, error aggregation
- `config` — 5 scan profiles + 3 AI tiers, YAML loader, CLI overrides

**Modules** (`internal/modules/*`)

29 auto-registered modules across 6 phases: discovery, resolution, enrichment, analysis, reporting. Adding one is ~60 lines of Go; new modules plug in without touching `main.go`.

**Operational** (`internal/`)

- `wizard` — interactive setup (9 prompts, input validation, TTY detection)
- `tui` — colorized live event printer, 3 verbosity levels
- `nucleitpl` — Nuclei template parser + executor + auto-downloader
- `diff` + `scheduler` — ASM continuous mode

### Testing

```bash
go test ./... -race -timeout 120s
```

**200+ tests across 14 packages**, all race-detector clean.

---

## 🗺️ Roadmap

v2.0 is in active development. Current state:

| Fase | Theme                                    | Status            |
|------|------------------------------------------|-------------------|
| 0    | Foundation refactor                      | ✅ complete       |
| 1    | Discovery Supremacy                      | 🟡 core done      |
| 2    | Vulnerability Engine                     | 🟡 5/10 native    |
| 3    | AI Agentic v2                            | 🔵 scaffolding    |
| 4    | TUI + Reporting (terminal-only)          | 🟡 wizard + live  |
| 5    | Continuous & Distributed                 | 🟡 single-node    |
| 6    | Ecosystem & community                    | 📋 planned        |

Full breakdown: **[FEATURE_ANALYSIS.md](FEATURE_ANALYSIS.md)**.

---

## 🧪 Contributing

1. Fork
2. Create a branch: `git checkout -b feat/your-feature`
3. Ship with tests (`-race` mandatory)
4. Open a PR

**New modules** should:

- Live under `internal/modules/<name>/`
- Implement `module.Module`
- Register in `internal/modules/all/all.go`
- Emit events via the bus; no direct cross-module calls
- Drain the store at `Run()` start + subscribe for late events

See **[CLAUDE.md](CLAUDE.md)** for the full conventions.

---

## ⚖️ Legal notice

**For authorized security testing only.** By using God's Eye you agree to:

- ✅ Only scan domains you own or have **written permission** to test
- ✅ Comply with local laws (CFAA, Computer Misuse Act, GDPR, NIS2, …)
- ✅ Respect bug-bounty program scopes
- ❌ Never use for unauthorized access, exploitation, or malicious activity

**The author accepts NO liability for misuse.** Full terms: **[SECURITY.md](SECURITY.md)** · **[LICENSE](LICENSE)**.

> *Unauthorized computer access is illegal. Always get written permission first.*

---

## 📚 Documentation map

| Document                                         | What it covers                                                 |
|--------------------------------------------------|----------------------------------------------------------------|
| [README.md](README.md)                           | You're here. Everything, high level.                           |
| [CHANGELOG.md](CHANGELOG.md)                     | What changed in v2 vs v0.1. Read before upgrading.             |
| [EXAMPLES.md](EXAMPLES.md)                       | 14 practical recipes — bug-bounty, pentest, ASM, stealth, CI, Tor. |
| [AI_SETUP.md](AI_SETUP.md)                       | Complete AI layer guide — profiles, Ollama, cascade, verbose.  |
| [BENCHMARK.md](BENCHMARK.md)                     | Cross-tool benchmarks, methodology, honest caveats.            |
| [BENCHMARK-SCANME.md](BENCHMARK-SCANME.md)       | **Live reproducible benchmark** on `scanme.nmap.org`.          |
| [FEATURE_ANALYSIS.md](FEATURE_ANALYSIS.md)       | Per-feature status across all 6 development phases.            |
| [SECURITY.md](SECURITY.md)                       | Ethical guidelines, disclosure process, data protection.       |
| [CLAUDE.md](CLAUDE.md)                           | Architecture reference for contributors and AI agents.         |

---

## 👤 Author

Made by **Vyntral** — [GitHub](https://github.com/Vyntral) · [X / Twitter](https://x.com/vyntral).

Contributions welcome. Bug reports, feature requests, and PRs go on [GitHub Issues](https://github.com/Vyntral/god-eye/issues).

<p align="center">
  <sub>Every number in this README is reproducible. No marketing fluff, no synthetic benchmarks, no vendor lock-in. Just a single Go binary, your local machine, and the targets you're authorized to test.</sub>
</p>