# 🗺️ God's Eye v2 — Feature Map

> Living document. What's shipped · what's in progress · what's planned.
> If you're about to build on a feature, **check its status here first**.

**Status legend:**
- ✅ implemented and tested with `-race`
- 🟡 implemented, awaiting integration-level testing on live targets
- 🔵 skeleton in place (interfaces + scaffolding), body pending
- 📋 planned (design drafted, not yet written)
- ❌ intentionally deferred or declined

---

## At-a-glance

| Fase | Theme                              | Status |
|------|------------------------------------|--------|
| 0    | Foundation refactor                | ✅     |
| 1    | Discovery Supremacy                | 🟡 (core done, 40+ sources to add) |
| 2    | Vulnerability Engine               | 🟡 (4/10 native scanners done) |
| 3    | AI Agentic v2                      | 🔵 (interfaces + 2 tools; planner/workers pending) |
| 4    | TUI + Reporting                    | 🟡 (wizard done, LivePrinter done; report generator pending) |
| 5    | Continuous & Distributed           | 🟡 (diff + scheduler + webhook done; distributed pending) |
| 6    | Ecosystem & community              | 📋 (plan exists; templates + marketplace pending) |

---

## Fase 0 — Foundation refactor *(✅ complete)*

Prerequisite for everything else. Keeps v2 extensible and testable without changing v1's external behavior.

| Feature                                    | Status | Location                                  |
|--------------------------------------------|:------:|-------------------------------------------|
| Typed event bus with per-subscriber goroutines | ✅ | `internal/eventbus/`                      |
| 20 canonical event types                   | ✅     | `internal/eventbus/events.go`             |
| Non-blocking publish with drop counter     | ✅     | `internal/eventbus/bus.go`                |
| Panic-safe handlers                        | ✅     | `internal/eventbus/bus.go:run()`          |
| Module interface + auto-registry           | ✅     | `internal/module/`                        |
| Phase-based selection + Consumes/Produces  | ✅     | `internal/module/registry.go`             |
| In-memory store with per-host locks        | ✅     | `internal/store/memory.go`                |
| Deep-copy Get (caller can't corrupt state) | ✅     | `internal/store/memory.go:cloneHost`      |
| Pipeline coordinator with phase barriers   | ✅     | `internal/pipeline/pipeline.go`           |
| Error aggregation via `errors.Join`        | ✅     | `internal/pipeline/pipeline.go:Run`       |
| YAML config loader + 5 scan profiles       | ✅     | `internal/config/profile.go` + `yaml.go`  |
| AI profiles (lean/balanced/heavy)          | ✅     | `internal/config/ai_profile.go`           |
| ConfigView exposed to modules              | ✅     | `internal/config/view.go`                 |
| 185 unit tests passing with `-race`        | ✅     | `*_test.go` across 15 packages            |
| BoltDB store backend                       | 📋    | deferred to Fase 5                        |

---

## Fase 1 — Discovery Supremacy *(🟡 core done)*

Goal: match or beat BBOT and Amass in subdomain coverage.

### Passive sources

| Source                          | Status | Module                                     |
|---------------------------------|:------:|--------------------------------------------|
| 20 v1 sources (crt.sh, CertSpotter, AlienVault, HackerTarget, URLScan, RapidDNS, Anubis, ThreatMiner, DNSRepo, SubdomainCenter, Wayback, CommonCrawl, Sitedossier, Riddler, Robtex, DNSHistory, ArchiveToday, JLDC, SynapsInt, CensysFree) | ✅ | `internal/modules/passive` (wrapper) |
| Shodan, Censys, BinaryEdge, SecurityTrails, FOFA, ZoomEye, Quake, Netlas (key-gated) | 📋 | planned |
| VirusTotal, Chaos, BufferOver, Shrewdeye | 📋 | planned |
| **Supply chain**: npm + PyPI dorks | ✅ | `internal/modules/supplychain` |
| GitHub code-search dorks         | ✅     | `internal/modules/github`                  |
| Certificate Transparency live   | ✅ (opt-in) | `internal/modules/ctstream`         |

### Active discovery

| Technique                        | Status | Module                                     |
|----------------------------------|:------:|--------------------------------------------|
| DNS wordlist brute-force         | ✅     | `internal/modules/bruteforce`              |
| Wildcard DNS detection + filter  | ✅     | v1 `internal/dns/wildcard.go` + bruteforce |
| Recursive pattern learning       | ✅     | `internal/modules/recursive`               |
| DNS permutation (alterx-style)   | ✅ (opt-in) | `internal/modules/permutation`         |
| AXFR zone-transfer attempt       | ✅     | `internal/modules/axfr`                    |
| Reverse DNS ±16 sweep per seed IP | ✅ (opt-in) | `internal/modules/reversedns`          |
| Virtual host discovery           | ✅ (opt-in) | `internal/modules/vhost`               |
| ASN/CIDR expansion               | ✅ (opt-in) | `internal/modules/asn`                 |

---

## Fase 2 — Vulnerability Engine *(🟡 4/10 native done)*

Goal: move beyond v1's "chain Nuclei and pray" model — build native, accurate, high-signal detections.

| Scanner                          | Status | Module                                        |
|----------------------------------|:------:|-----------------------------------------------|
| v1 security checks (open redirect, CORS, HTTP methods, git/svn, backups, admin, API) | ✅ | `internal/modules/security` |
| Subdomain takeover (110+ fingerprints) | ✅ | `internal/modules/takeover`                   |
| Cloud asset discovery (S3 / GCS / Azure / CDNs) | ✅ | `internal/modules/cloud` + v1 `internal/cloud` |
| JS secret extraction             | ✅     | `internal/modules/javascript`                 |
| Security headers audit (OWASP-aligned) | ✅ | `internal/modules/headers`                    |
| GraphQL introspection + mutation flag | ✅ | `internal/modules/graphql`                    |
| JWT analyzer + weak-secret crack | ✅     | `internal/modules/jwt`                        |
| HTTP request smuggling (CL.TE / TE.CL timing probe) | ✅ (opt-in) | `internal/modules/smuggling` |
| Nuclei template compatibility layer | 📋 | planned                                        |
| SPA crawler w/ headless browser (chromedp) | 📋 | planned                                    |
| OAuth / SAML flow misconfig      | 📋    | planned                                       |
| Race condition scanner           | 📋    | planned                                       |
| Prototype pollution              | 📋    | planned                                       |
| SSRF + built-in OOB canary server | 📋   | planned                                       |
| Live secret validation against source APIs | 📋 | planned                                 |

---

## Fase 3 — AI Agentic v2 *(🔵 scaffolding done)*

Goal: move from "LLM reviews findings" to "LLM plans + executes multi-step investigations using tools".

| Component                                  | Status | Location                         |
|--------------------------------------------|:------:|----------------------------------|
| v1 Ollama cascade wrapper (triage+deep)    | ✅     | `internal/ai/ollama.go` + `modules/ai` |
| Multi-agent orchestrator (8 specialist agents: XSS, SQLi, Auth, API, Crypto, Secrets, Headers, General) | ✅ (from v1) | `internal/ai/agents/` |
| CVE matching via KEV (offline) + NVD (online) | ✅ | `internal/ai/kev.go` + `cve.go`     |
| Function calling to live CVE lookup        | ✅     | `internal/ai/tools.go`           |
| Model ensurer (auto-pull via `/api/pull`)  | ✅     | `internal/ai/ensure.go`          |
| AI profiles (lean / balanced / heavy)      | ✅     | `internal/config/ai_profile.go`  |
| Verbose per-query logging                  | ✅     | `internal/ai/ollama.go:logVerbose` |
| Agent / Planner / Worker interfaces        | ✅     | `internal/agent/agent.go`        |
| Built-in tools: `http_request`, `dns_resolve` | ✅ | `internal/agent/tools.go`        |
| Native Planner (reasoning loop)            | 🔵    | planned                           |
| Native Worker specializations              | 🔵    | planned                           |
| Vulnerability-chain composer agent         | 📋    | planned                           |
| Fine-tuning dataset pipeline               | 📋    | planned                           |
| RAG over CISA KEV + HackerOne public reports | 📋 | planned                           |

---

## Fase 4 — Terminal UX + Reporting *(🟡 partial)*

**Terminal-only by explicit design.** No web dashboard.

| Feature                                    | Status | Location                         |
|--------------------------------------------|:------:|----------------------------------|
| Interactive setup wizard                   | ✅     | `internal/wizard/`               |
| Auto-launch on zero-flag TTY invocation    | ✅     | `cmd/god-eye/main.go`            |
| `--wizard` force flag                      | ✅     | `cmd/god-eye/main.go`            |
| Model pull consent + streaming progress    | ✅     | `internal/wizard/wizard.go:handleAIModels` |
| Live colorized event stream (`--live`)     | ✅     | `internal/tui/live.go`           |
| 3-level verbosity (findings / normal / noisy) | ✅ | `internal/tui/live.go`           |
| Bubbletea-based interactive TUI (k9s-like) | 📋    | planned                           |
| Professional report generator (PDF/HTML/Markdown with CVSS + MITRE mapping) | 📋 | planned |
| Burp / Caido extension for findings export | 📋    | planned                           |

---

## Fase 5 — Continuous & Distributed *(🟡 single-node done)*

Goal: turn God's Eye into an Attack Surface Management (ASM) daemon.

| Feature                                    | Status | Location                         |
|--------------------------------------------|:------:|----------------------------------|
| Diff engine (9 change kinds)               | ✅     | `internal/diff/`                 |
| Scheduler with interval ticker             | ✅     | `internal/scheduler/scheduler.go`|
| `StdoutAlerter` (human-readable)           | ✅     | `internal/scheduler/alerter.go`  |
| `WebhookAlerter` (generic JSON POST)       | ✅     | `internal/scheduler/alerter.go`  |
| `--monitor-interval` + `--monitor-webhook` | ✅     | `cmd/god-eye/main.go:runMonitor` |
| BoltDB / SQLite persistent store           | 📋    | planned (requires Store backend) |
| Cron-syntax scheduling                     | 📋    | planned                           |
| Distributed worker pool (NATS/Redis)       | 📋    | planned                           |
| Slack / Discord / Teams / Linear adapters  | 📋    | planned                           |

---

## Fase 6 — Ecosystem *(📋 planned)*

| Feature                                    | Status |
|--------------------------------------------|:------:|
| Community template repository              | 📋    |
| Module marketplace (`god-eye module install`) | 📋 |
| Docs site (VitePress)                      | 📋    |
| Integrations: HackerOne / Bugcrowd / Intigriti APIs | 📋 |
| Published benchmark suite vs BBOT / Subfinder / Amass | 📋 |

---

## Operational / cross-cutting features

### Config

| Feature                                    | Status | Notes |
|--------------------------------------------|:------:|-------|
| CLI flags (backwards-compatible with v0.1) | ✅     | `cmd/god-eye/main.go` |
| YAML config auto-discovery                 | ✅     | `./god-eye.yaml`, `.god-eye.yaml`, `~/.god-eye/config.yaml` |
| `--config <path>` override                 | ✅     |       |
| Named scan profiles (`--profile`)          | ✅     | 5 profiles: bugbounty, pentest, asm-continuous, stealth-max, quick |
| Named AI profiles (`--ai-profile`)         | ✅     | lean / balanced / heavy |
| Per-module enable/disable via YAML         | ✅     | `modules:` YAML key |

### Stealth

| Feature                                    | Status | Notes |
|--------------------------------------------|:------:|-------|
| 4-level stealth mode                       | ✅ (v1 heritage) | light / moderate / aggressive / paranoid |
| 25+ User-Agent rotation pool               | ✅     | `internal/stealth/` |
| Randomized delays, per-host throttling     | ✅     | `internal/stealth/`, `internal/ratelimit/` |
| Adaptive backoff on error-rate spikes      | ✅     | `internal/ratelimit/ratelimit.go` |
| Retry with exponential backoff             | ✅     | `internal/retry/retry.go` |
| **Proxy / SOCKS5 / Tor routing**           | ✅     | `internal/proxyconf/` · issue [#1](https://github.com/Vyntral/god-eye/issues/1) |

### Observability

| Feature                                    | Status |
|--------------------------------------------|:------:|
| Event bus stats (published / delivered / dropped) | ✅ |
| Per-phase timing events                    | ✅     |
| Module error events (non-fatal)            | ✅     |
| AI verbose logging (`--ai-verbose`)        | ✅     |
| Structured JSON output                     | ✅     |

### Security of the tool itself

| Feature                                    | Status |
|--------------------------------------------|:------:|
| Input validation (domain, wordlist path, output path, resolvers, concurrency, timeout) | ✅ |
| Rejects write to system paths (/etc, /var, /proc, etc.) | ✅ |
| Null-byte and path-traversal rejection     | ✅     |
| Panic containment in event handlers        | ✅     |
| Per-subscriber goroutine isolation         | ✅     |

---

## What's intentionally NOT on the roadmap

- **Web UI** — explicit scope choice. Terminal only.
- **Exploitation / payload delivery** — detection, chaining and PoC generation only; no shell, no persistence.
- **Collaborative multi-user state** — single-operator tool.
- **Proprietary feed integrations (Shodan / Censys paid tiers) by default** — must be user-configured with their own API keys.
- **Agent-based compromise of targets** — scope is bounded to authorized offensive reconnaissance and disclosure-track testing.

---

## Test coverage snapshot

| Package             | Tests | `-race` | Notes                                   |
|---------------------|------:|:-------:|-----------------------------------------|
| validator           |  ~30  | ✅     | exhaustive input validation             |
| sources             |   ~5  | ✅     | extract subdomains, client pooling      |
| dns                 |  ~10  | ✅     | wildcard helpers, pure functions only   |
| config              |  ~25  | ✅     | profiles, YAML, View                    |
| eventbus            |  ~15  | ✅     | pub/sub, drop invariant, concurrent     |
| module              |  ~13  | ✅     | registry, filtering, dep graph          |
| store               |  ~15  | ✅     | concurrent Upsert, deep-copy Get        |
| pipeline            |   ~9  | ✅     | phase barriers, panic recovery          |
| diff                |   ~9  | ✅     | 9 change kinds                          |
| scheduler           |   ~3  | ✅     | interval + diff integration             |
| wizard              |  ~15  | ✅     | prompts, validation, EOF cancel         |
| ai (ensurer)        |  ~10  | ✅     | mock httptest Ollama                    |
| scanner (v1 legacy) |  ~10  | ✅     | helper functions                        |

**185 tests total** across 15 packages, all green with the `-race` flag on Go 1.21.

### Since v0.1

- **+15 packages** (foundation + modules + operational)
- **~26 modules** auto-registered in the pipeline
- **~200 lines of documentation per topic area** (README, AI, EXAMPLES, SECURITY, BENCHMARK, FEATURE)
- **3 GIF demos** captured live against `scanme.nmap.org`
- **Issue [#1](https://github.com/Vyntral/god-eye/issues/1)** (SOCKS5 / Tor support) fixed