docs(v2): full documentation rewrite + CHANGELOG + live benchmark

Eight documents polished for v2.0 release: - README.md: hero + 30-sec quickstart + feature matrix + competitive landscape + wizard/live/AI GIF demos - AI_SETUP.md: 3 AI profiles + cascade + auto-pull + end-of-scan brief + model comparison + troubleshooting + privacy model - EXAMPLES.md: 14 practical recipes from zero-flag wizard to routing via Tor / Burp / mitmproxy - BENCHMARK.md: cross-tool comparison matrix + methodology + caveats - BENCHMARK-SCANME.md (new): reproducible live benchmark on Nmap's authorized test host, documents three bugs fixed mid-test - FEATURE_ANALYSIS.md: per-feature status across all 6 phases - SECURITY.md: ethical guidelines + disclosure + compliance - CHANGELOG.md (new): complete v2.0.0-rc1 release notes
2026-07-08 21:27:50 +02:00 · 2026-04-18 16:49:04 +02:00
parent 8356eb573d
commit 05e837fa4c
8 changed files with 2439 additions and 2457 deletions
@@ -1,434 +1,442 @@
-# God's Eye - AI Integration Examples
+# 📖 God's Eye v2 — Usage Cookbook

-## 🎯 Real-World Usage Examples
+> 14 practical recipes, from "zero-flag launch" to "route-everything-through-Tor".
+> Every example is copy-paste ready. All targets must be **ones you own or have explicit written permission to test**.

-### Example 1: Bug Bounty Recon
+<p align="center">
+  <sub>Built the binary yet? <code>go build -o god-eye ./cmd/god-eye</code> — then pick a recipe.</sub>
+</p>
+
+---
+
+---
+
+## Index
+
+1. [Zero-flag launch (interactive wizard)](#1-zero-flag-launch-interactive-wizard)
+2. [Quick passive reconnaissance](#2-quick-passive-reconnaissance)
+3. [Full bug-bounty recon with AI](#3-full-bug-bounty-recon-with-ai)
+4. [Authorized penetration test](#4-authorized-penetration-test)
+5. [Continuous attack-surface monitoring](#5-continuous-attack-surface-monitoring)
+6. [Maximum stealth mode](#6-maximum-stealth-mode)
+7. [Using a YAML config file](#7-using-a-yaml-config-file)
+8. [Custom wordlist + resolvers](#8-custom-wordlist--resolvers)
+9. [Subdomain enumeration pipeline (unix-pipeline style)](#9-subdomain-enumeration-pipeline-unix-pipeline-style)
+10. [AI profile decision guide](#10-ai-profile-decision-guide)
+11. [Parity check: v1 vs v2](#11-parity-check-v1-vs-v2)
+12. [Scripted (CI) invocation](#12-scripted-ci-invocation)
+13. [Troubleshooting](#13-troubleshooting)
+
+---
+
+## 1. Zero-flag launch (interactive wizard)
+
+The easiest way to scan something. No flags, no docs-reading required.

 ```bash
-# Initial reconnaissance with AI analysis
-./god-eye -d target.com --enable-ai -o recon.json -f json
-
-# Filter high-severity AI findings
-cat recon.json | jq '.[] | select(.ai_severity == "critical" or .ai_severity == "high")'
-
-# Extract subdomains with CVEs
-cat recon.json | jq '.[] | select(.cve_findings | length > 0)'
-
-# Get AI-detected admin panels
-cat recon.json | jq '.[] | select(.admin_panels | length > 0)'
+./god-eye
 ```

-### Example 2: Pentesting Workflow
+The wizard walks you through:
+
+1. **AI tier** — lean / balanced / heavy / no-AI
+2. **Ollama check** — if AI, verifies the server is running and offers to pull missing models with live progress
+3. **Target domain** — validated against RFC 1035
+4. **Scan profile** — quick / bugbounty / pentest / asm-continuous / stealth-max
+5. **Live event view** — colorized per-event stream in the terminal
+6. **AI verbose mode** — log every LLM query to stderr
+7. **Output file** (optional) — txt / json / csv
+8. **Confirmation** — last chance to edit before the scan starts
+
+Force the wizard even with a target already set:

 ```bash
-# Fast scan for initial scope
-./god-eye -d client.com --enable-ai --no-brute --active
-
-# Deep analysis on interesting findings
-./god-eye -d client.com --enable-ai --ai-deep -c 500
-
-# Generate report for client
-./god-eye -d client.com --enable-ai -o client_report.txt
-```
-
-### Example 3: Security Audit
-
-```bash
-# Comprehensive audit with all checks
-./god-eye -d company.com --enable-ai
-
-# Focus on specific issues
-./god-eye -d company.com --enable-ai --active | grep -E "AI:CRITICAL|CVE"
-
-# Export for further analysis
-./god-eye -d company.com --enable-ai -o audit.csv -f csv
-```
-
-### Example 4: Quick Triage
-
-```bash
-# Super fast scan (no brute-force, cascade enabled)
-time ./god-eye -d target.com --enable-ai --no-brute
-
-# Should complete in ~30-60 seconds for small targets
-```
-
-### Example 5: Development Environment Check
-
-```bash
-# Find exposed dev/staging environments
-./god-eye -d company.com --enable-ai | grep -E "dev|staging|test"
-
-# AI will identify debug mode, error messages, etc.
+./god-eye --wizard -d target.com
 ```

 ---

-## 📊 Expected Output Examples
+## 2. Quick passive reconnaissance

-### Without AI
+Get a fast subdomain list without DNS brute-force or HTTP probing:

-```
-═══════════════════════════════════════════════════
-● api.example.com [200] ⚡156ms
-    IP: 93.184.216.34
-    Tech: nginx, React
-    FOUND: Admin: /admin [200]
-    JS SECRET: api_key: "sk_test_123..."
-═══════════════════════════════════════════════════
+```bash
+./god-eye -d target.com --pipeline --profile quick
 ```

-### With AI Enabled
+- Runs 26 passive sources concurrently
+- No DNS brute-force (saves time + noise)
+- Still probes HTTP on resolved hosts (remove with `--no-probe` if you want silence)
+- No AI analysis

-```
-═══════════════════════════════════════════════════
-● api.example.com [200] ⚡156ms
-    IP: 93.184.216.34
-    Tech: nginx, React
-    FOUND: Admin: /admin [200]
-    JS SECRET: api_key: "sk_test_123..."
-    AI:CRITICAL: Hardcoded Stripe test API key exposed in main.js
-                 Authentication bypass possible via admin parameter
-                 React version 16.8.0 has known XSS vulnerability
-                 Missing rate limiting on /api/v1/users endpoint
-                 (1 more findings...)
-                 model: deepseek-r1:1.5b→qwen2.5-coder:7b
-    CVE: React: CVE-2020-15168 - XSS vulnerability in development mode
-═══════════════════════════════════════════════════
-```
+For pure subdomain output, pipe to a file:

-### AI Report Section
-
-```
-🧠 AI-POWERED ANALYSIS (cascade: deepseek-r1:1.5b + qwen2.5-coder:7b)
-   Analyzing findings with local LLM
-
-   AI:C  api.example.com → 4 findings
-   AI:H  admin.example.com → 2 findings
-   AI:H  dev.example.com → 3 findings
-   AI:M  staging.example.com → 5 findings
-
-   ✓ AI analysis complete: 14 findings across 4 subdomains
-
-📋 AI SECURITY REPORT
-
-## Executive Summary
-Analysis identified 14 security findings across 4 subdomains, with 1 critical
-and 2 high-severity issues requiring immediate attention. Key concerns include
-hardcoded credentials and exposed development environments.
-
-## Critical Findings
-
-[CRITICAL] api.example.com:
-  - Hardcoded Stripe API key in main.js (test key exposed)
-  - Authentication bypass via admin parameter
-  - React XSS vulnerability (CVE-2020-15168)
-  CVEs:
-    - React: CVE-2020-15168
-
-[HIGH] admin.example.com:
-  - Basic auth with default credentials detected
-  - Directory listing enabled on /uploads/
-
-[HIGH] dev.example.com:
-  - Django debug mode enabled with stack traces
-  - Source code exposure via .git directory
-  - Database connection string in error messages
-
-## Recommendations
-1. IMMEDIATE: Remove hardcoded API keys and rotate credentials
-2. IMMEDIATE: Disable debug mode in production environments
-3. IMMEDIATE: Remove exposed .git directory
-4. HIGH: Update React to latest stable version
-5. HIGH: Implement proper authentication on admin panel
-6. MEDIUM: Disable directory listing on sensitive paths
-7. MEDIUM: Configure proper error handling to prevent information disclosure
+```bash
+./god-eye -d target.com --pipeline --profile quick --no-probe --silent > hosts.txt
 ```

 ---

-## 🤖 Multi-Agent Examples
+## 3. Full bug-bounty recon with AI

-### Example 6: Multi-Agent Deep Analysis
+The default workflow: full discovery + security checks + AI triage.

 ```bash
-# Enable 8 specialized AI agents for comprehensive analysis
-./god-eye -d target.com --enable-ai --multi-agent --no-brute
-
-# Combine with active filter
-./god-eye -d target.com --enable-ai --multi-agent --active
+./god-eye -d target.com --pipeline --profile bugbounty --live
 ```

-### Multi-Agent Output
+The `bugbounty` profile flips on: recursive discovery, cloud scan, API scan, secrets scan, tech scan, ASN expansion, vhost scan, AI cascade, and multi-agent orchestration. The `--live` flag streams colorized events to the terminal as findings come in.

-```
-🤖 MULTI-AGENT ANALYSIS
-──────────────────────────────────────────────────
-  Routing findings to specialized AI agents...
-  ✓ Multi-agent analysis complete: 4 critical, 34 high, 0 medium
-  Agent usage:
-    headers: 10 analyses (avg confidence: 50%)
-    crypto: 17 analyses (avg confidence: 50%)
-    xss: 3 analyses (avg confidence: 50%)
-    api: 2 analyses (avg confidence: 50%)
-    secrets: 3 analyses (avg confidence: 50%)
-    !! Weak CSP directives: headers agent
-    !! CORS allows all origins: headers agent
-    ! Missing HSTS: headers agent
-    ! Cookie without Secure flag: headers agent
-```
-
-### Agent-Specific Analysis
-
-Each agent provides domain-specific findings:
-
-| Agent | Sample Finding |
-|-------|----------------|
-| Headers | Missing CSP, HSTS, X-Frame-Options, cookie flags |
-| Secrets | Hardcoded API keys, tokens, passwords in JS |
-| XSS | DOM sinks, innerHTML, unsafe event handlers |
-| API | CORS misconfiguration, rate limiting issues |
-| Auth | IDOR, session fixation, JWT problems |
-| Crypto | Weak TLS, expired certs, self-signed issues |
-
---
-
-## 🎭 Scenario-Based Examples
-
-### Scenario 1: Found a Suspicious Subdomain
+Want the output saved too?

 ```bash
-# Initial scan found dev.target.com
-# Let AI analyze it in detail
-
-./god-eye -d target.com --enable-ai --ai-deep
-
-# AI might find:
-# - Debug mode enabled
-# - Test credentials in source
-# - Exposed API documentation
-# - Missing security headers
-```
-
-### Scenario 2: JavaScript Heavy Application
-
-```bash
-# SPA with lots of JavaScript
-./god-eye -d webapp.com --enable-ai
-
-# AI excels at:
-# ✓ Analyzing minified/obfuscated code
-# ✓ Finding hidden API endpoints
-# ✓ Detecting auth bypass logic
-# ✓ Identifying client-side security issues
-```
-
-### Scenario 3: API-First Platform
-
-```bash
-# Multiple API subdomains
-./god-eye -d api-platform.com --enable-ai --ai-deep
-
-# AI will identify:
-# ✓ API version mismatches
-# ✓ Unprotected endpoints
-# ✓ CORS issues
-# ✓ Rate limiting problems
-```
-
-### Scenario 4: Legacy Application
-
-```bash
-# Old PHP/WordPress site
-./god-eye -d old-site.com --enable-ai
-
-# AI checks for:
-# ✓ Known CVEs in detected versions
-# ✓ Common WordPress vulns
-# ✓ Outdated library versions
-# ✓ Exposed backup files
+./god-eye -d target.com --pipeline --profile bugbounty --live \
+  -o findings.json -f json
 ```

 ---

-## 💡 Pro Tips
+## 4. Authorized penetration test

-### Tip 1: Combine with Other Tools
+Like bug-bounty but with light stealth to evade basic rate limits:

 ```bash
-# God's Eye → Nuclei pipeline
-./god-eye -d target.com --enable-ai --active -s | nuclei -t cves/
-
-# God's Eye → httpx pipeline
-./god-eye -d target.com --enable-ai -s | httpx -tech-detect
-
-# God's Eye → Custom script
-./god-eye -d target.com --enable-ai -o scan.json -f json
-python analyze.py scan.json
+./god-eye -d client.example --pipeline --profile pentest --live \
+  -o pentest-report.json -f json
 ```

-### Tip 2: Incremental Scans
+Differences from bugbounty profile:
+- **Concurrency** reduced to 300 (was 1000)
+- **Stealth** set to `light` (10–50ms request delays, UA rotation)
+- Same AI + modules enabled
+
+For even more caution:

 ```bash
-# Day 1: Initial recon
-./god-eye -d target.com --enable-ai -o day1.json -f json
-
-# Day 2: Update scan
-./god-eye -d target.com --enable-ai -o day2.json -f json
-
-# Compare findings
-diff <(jq '.[] | .subdomain' day1.json) <(jq '.[] | .subdomain' day2.json)
-```
-
-### Tip 3: Filter by AI Severity
-
-```bash
-# Only show critical findings
-./god-eye -d target.com --enable-ai -o scan.json -f json
-cat scan.json | jq '.[] | select(.ai_severity == "critical")'
-
-# Count findings by severity
-cat scan.json | jq -r '.[] | .ai_severity' | sort | uniq -c
-```
-
-### Tip 4: Custom Wordlist with AI
-
-```bash
-# AI can help identify naming patterns
-# First run to learn patterns
-./god-eye -d target.com --enable-ai --no-brute
-
-# AI identifies pattern: api-v1, api-v2, api-v3
-# Create custom wordlist:
-echo -e "api-v4\napi-v5\napi-staging\napi-prod" > custom.txt
-
-# Second run with custom wordlist
-./god-eye -d target.com --enable-ai -w custom.txt
-```
-
-### Tip 5: Monitoring Setup
-
-```bash
-#!/bin/bash
-# monitor-target.sh - Daily AI-powered monitoring
-
-TARGET="target.com"
-DATE=$(date +%Y%m%d)
-OUTPUT="scans/${TARGET}_${DATE}.json"
-
-./god-eye -d $TARGET --enable-ai --active -o $OUTPUT -f json
-
-# Alert on new critical findings
-CRITICAL=$(cat $OUTPUT | jq '.[] | select(.ai_severity == "critical")' | wc -l)
-if [ $CRITICAL -gt 0 ]; then
-    echo "ALERT: $CRITICAL critical findings for $TARGET"
-    cat $OUTPUT | jq '.[] | select(.ai_severity == "critical")'
-fi
+./god-eye -d client.example --pipeline --profile pentest \
+  --stealth moderate \
+  -c 100
 ```

 ---

-## 🧪 Testing AI Features
+## 5. Continuous attack-surface monitoring

-### Test 1: Verify AI is Working
+Run once, then every 24h, diffing against the last snapshot:

 ```bash
-# Should show AI analysis section
-./god-eye -d example.com --enable-ai --no-brute -v
-
-# Look for:
-# ✓ "🧠 AI-POWERED ANALYSIS"
-# ✓ Model names in output
-# ✓ AI findings if vulnerabilities detected
+./god-eye -d target.com --pipeline --profile asm-continuous \
+  --monitor-interval 24h \
+  --monitor-webhook https://hooks.slack.com/services/T.../B.../XXX
 ```

-### Test 2: Compare AI vs No-AI
+What happens:

-```bash
-# Without AI
-time ./god-eye -d target.com --no-brute -o noai.json -f json
+1. First scan executes immediately, snapshot saved
+2. Every 24h: re-scan, compute diff
+3. If diff contains meaningful changes (`new_host`, `new_vuln`, `new_takeover`, `removed_host`), fire webhook with JSON payload
+4. Continues until Ctrl-C

-# With AI
-time ./god-eye -d target.com --no-brute --enable-ai -o ai.json -f json
+Sample webhook payload:

-# Compare
-echo "Findings without AI: $(cat noai.json | jq length)"
-echo "Findings with AI: $(cat ai.json | jq length)"
-echo "New AI findings: $(cat ai.json | jq '[.[] | select(.ai_findings != null)] | length')"
+```json
+{
+  "target": "target.com",
+  "old_scan_at": "2026-04-15T08:00:00Z",
+  "new_scan_at": "2026-04-16T08:00:00Z",
+  "changes": [
+    {
+      "kind": "new_host",
+      "host": "staging-v2.target.com",
+      "detected_at": "2026-04-16T08:02:14Z"
+    },
+    {
+      "kind": "new_vuln",
+      "host": "admin.target.com",
+      "after": "Git Repository Exposed",
+      "severity": "critical",
+      "detected_at": "2026-04-16T08:04:01Z"
+    }
+  ]
+}
 ```

-### Test 3: Benchmark Different Modes
+For local testing without a webhook, the `StdoutAlerter` always runs:

 ```bash
-# Cascade (default)
-time ./god-eye -d target.com --enable-ai --no-brute
-
-# No cascade
-time ./god-eye -d target.com --enable-ai --ai-cascade=false --no-brute
-
-# Deep mode
-time ./god-eye -d target.com --enable-ai --ai-deep --no-brute
+./god-eye -d target.com --pipeline --profile asm-continuous --monitor-interval 10m
 ```

 ---

-## 📈 Performance Optimization
+## 6. Maximum stealth mode

-### For Large Targets (>100 subdomains)
+For highly-sensitive targets where any detection is unacceptable:

 ```bash
-# Reduce concurrency to avoid overwhelming Ollama
-./god-eye -d large-target.com --enable-ai -c 500
-
-# Use fast model only (skip deep analysis)
-./god-eye -d large-target.com --enable-ai --ai-cascade=false \
-  --ai-deep-model deepseek-r1:1.5b
-
-# Disable AI for initial enumeration, enable for interesting findings
-./god-eye -d large-target.com --no-brute -s > subdomains.txt
-cat subdomains.txt | head -20 | while read sub; do
-    ./god-eye -d $sub --enable-ai --no-brute
-done
+./god-eye -d target.com --pipeline --profile stealth-max --live --live-verbosity 0
 ```

-### For GPU Acceleration
+`stealth-max` profile:
+- Concurrency 3 (vs 1000 default)
+- Paranoid delays (1–5s between requests)
+- 70% timing jitter
+- Single connection per host
+- No DNS brute-force
+- No port scan
+- AI disabled (too slow to be worth it in this mode)
+
+`--live-verbosity 0` suppresses everything except actual vulnerability findings.
+
+---
+
+## 7. Using a YAML config file
+
+Put long-lived settings in a config file, scan with one flag:
+
+```yaml
+# god-eye.yaml (auto-discovered in CWD or ~/.god-eye/config.yaml)
+profile: bugbounty
+concurrency: 500
+timeout: 10
+stealth: light
+
+resolvers:
+  - 1.1.1.1
+  - 8.8.8.8
+  - 9.9.9.9
+
+wordlist: /usr/local/share/wordlists/subdomains-top1million-110000.txt
+
+modules:
+  discovery.permutation: true     # opt-in module
+  discovery.reverse-dns: true
+  discovery.vhost: false          # disable vhost even though bugbounty normally enables it
+  vuln.http-smuggling: true       # opt-in timing probe
+
+ai:
+  enabled: true
+  url: http://localhost:11434
+  fast_model: qwen3:4b            # upgrade from default lean
+  deep_model: qwen3-coder:30b
+  cascade: true
+  deep: true
+  multi_agent: true
+
+output:
+  path: reports/scan.json
+  format: json
+```
+
+Scan:

 ```bash
-# Ollama automatically uses GPU if available
-# Check GPU usage:
-nvidia-smi  # Linux/Windows with NVIDIA
-ollama ps   # Should show GPU model
+./god-eye -d target.com --pipeline
+```

-# With GPU, you can use larger models:
-./god-eye -d target.com --enable-ai \
-  --ai-deep-model deepseek-coder-v2:16b
+CLI flags always win over YAML, so you can still override anything:
+
+```bash
+./god-eye -d target.com --pipeline --stealth paranoid    # overrides stealth: light
 ```

 ---

-## 🎓 Learning from AI Output
+## 8. Custom wordlist + resolvers

-### Example: Understanding AI Findings
+Use a bigger wordlist and specific DNS servers:

-**Input:** JavaScript code with potential issue
-```javascript
-const API_KEY = "sk_live_51H...";
-fetch(`/api/user/${userId}`);
+```bash
+./god-eye -d target.com --pipeline \
+  -w /usr/share/wordlists/SecLists/Discovery/DNS/subdomains-top1million-5000.txt \
+  -r 1.1.1.1,1.0.0.1,8.8.8.8,8.8.4.4 \
+  -c 2000
 ```

-**AI Output:**
-```
-AI:CRITICAL: Hardcoded production API key detected
-             Unsanitized user input in URL parameter
-             Missing authentication on API endpoint
-```
-
-**What to Do:**
-1. Verify the API key is active
-2. Test the userId parameter for injection
-3. Check if /api/user requires authentication
-4. Report to bug bounty program or client
+Notes:
+- Wordlists have massive impact on runtime. Common picks:
+  - [assetnote/commonspeak2-wordlists](https://github.com/assetnote/commonspeak2-wordlists) (~500k–5M lines)
+  - [n0kovo/n0kovo_subdomains](https://github.com/n0kovo/n0kovo_subdomains) (~10M)
+- High concurrency (2k+) needs a beefy machine + resolvers that allow it. If you see timeouts, drop to 500.

 ---

-**Happy Hunting with AI! 🎯🧠**
+## 9. Subdomain enumeration pipeline (unix-pipeline style)
+
+God's Eye can still be used as a subdomain tool in the classic `tool | tool | tool` style:
+
+```bash
+./god-eye -d target.com --pipeline --silent --no-probe --no-ports \
+  | httpx -silent -status-code -title \
+  | nuclei -t ~/nuclei-templates/
+```
+
+Or export to a file for post-processing:
+
+```bash
+./god-eye -d target.com --pipeline --silent --no-probe -o subdomains.txt -f txt
+```
+
+For pure JSON consumption by other tools:
+
+```bash
+./god-eye -d target.com --pipeline --json > findings.ndjson
+jq '.subdomains | keys[]' findings.ndjson
+```
+
+---
+
+## 10. AI profile decision guide
+
+Use this to pick the right `--ai-profile`:
+
+| Your machine                     | Recommended profile | Pull size | Notes                                |
+|----------------------------------|---------------------|-----------|--------------------------------------|
+| 8GB RAM laptop                    | `lean` (default)   | ~10GB     | Runs but AI will be slow             |
+| 16GB RAM / integrated GPU         | `lean`             | ~10GB     | Sweet spot for most laptops          |
+| 32GB RAM / Apple Silicon M-series | `balanced`         | ~20GB     | Best ratio of speed vs quality       |
+| 32GB + discrete 24GB GPU          | `balanced` or `heavy` | ~23GB  | `heavy` for top-quality triage       |
+| 64GB+ / server-class              | `heavy`            | ~23GB     | Best quality, same deep model as balanced |
+| No AI wanted                      | *(skip `--enable-ai`)* | 0     | Pure recon; still uses v1's CVE matching |
+
+Example — balanced cascade with verbose logging:
+
+```bash
+./god-eye -d target.com --pipeline --enable-ai --ai-profile balanced --ai-verbose --live
+```
+
+Output on stderr during AI calls:
+
+```
+[ai] → qwen3:4b  prompt=2341B timeout=60s
+[ai] ← qwen3:4b  response=512B  1.8s
+[ai] → qwen3-coder:30b  prompt=8291B timeout=120s
+[ai] ← qwen3-coder:30b  response=1832B  9.3s
+```
+
+---
+
+## 11. Parity check: v1 vs v2
+
+Worried the new pipeline misses something v1 found? Use the built-in parity tool:
+
+```bash
+go build -o god-eye ./cmd/god-eye
+go run ./tools/parity -d your-own-domain.com --bin ./god-eye
+```
+
+Runs the binary twice (with and without `--pipeline`), diffs the subdomain sets + HTTP status codes, and reports meaningful divergence. Use before promoting v2 to your default workflow.
+
+---
+
+## 12. Scripted (CI) invocation
+
+For CI jobs the wizard should stay out of the way. When stdin isn't a TTY, the wizard auto-skips.
+
+```yaml
+# .github/workflows/asm.yml (example)
+jobs:
+  asm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with: { go-version: '1.21' }
+      - run: go build -o god-eye ./cmd/god-eye
+      - name: Scan
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # used by discovery.github-dorks
+        run: |
+          ./god-eye \
+            -d ${{ vars.SCAN_TARGET }} \
+            --pipeline \
+            --profile quick \
+            --silent \
+            -o report.json -f json
+      - uses: actions/upload-artifact@v4
+        with: { name: scan-report, path: report.json }
+```
+
+Detect CI without TTY, use `--pipeline --silent --json` and redirect to a file. The wizard won't trigger.
+
+---
+
+## 13. Troubleshooting
+
+**"No modules selected — check config and module registrations"**
+Some profile disabled everything or you set `modules:` in YAML with all `false` values. Run with `-v` to see which modules are selected.
+
+**Pipeline hangs in "PhaseDiscovery"**
+A passive source is waiting on a slow network call. Every source has its own timeout (15s–120s depending on the provider) so it will resolve, but passive-heavy scans can take 90s before moving on. Use `--no-brute --profile quick` to skip if you're in a hurry.
+
+**"AI modules will no-op for this run"**
+Ollama isn't reachable. Start it: `ollama serve &`. Then retry. If you chose `--ai-auto-pull=false`, missing models also skip — re-enable auto-pull or pull manually: `ollama pull qwen3:1.7b`.
+
+**Brute-force finds zero subdomains**
+Wildcard DNS detected. Check the output near the top of the scan — "Wildcard DNS: DETECTED" means every random guess resolves and brute-force can't distinguish real hosts from wildcards. Use `-w` with a curated wordlist or rely on passive + AXFR + permutation.
+
+**Go data race in tests?**
+Please file an issue. Every v2 package is tested with `-race`; any race is a real bug.
+
+**Live view messes up my terminal**
+`--live` uses ANSI escapes. In non-TTY environments, disable it: `--live=false` or omit the flag.
+
+---
+
+## 14. Route everything through a proxy (Burp / mitmproxy / Tor)
+
+Every outbound HTTP request — passive sources, HTTP probes, Nuclei templates, secret fetches, Ollama (if remote) — can go through a proxy:
+
+```bash
+# Burp / mitmproxy / ZAP (upstream HTTP CONNECT)
+./god-eye -d target.com --pipeline --proxy http://127.0.0.1:8080 --live
+
+# Basic auth
+./god-eye -d target.com --pipeline --proxy http://user:pass@proxy.corp:3128
+
+# Tor (SOCKS5 with remote DNS — matches Tor's default)
+./god-eye -d target.com --pipeline --proxy socks5h://127.0.0.1:9050
+
+# SOCKS5 with local DNS (if you trust your resolver)
+./god-eye -d target.com --pipeline --proxy socks5://127.0.0.1:9050
+```
+
+**What gets proxied:**
+- ✅ Passive sources (crt.sh, CertSpotter, AlienVault, etc.)
+- ✅ HTTP probing (status, titles, headers)
+- ✅ Security checks (CORS, redirect, git/svn, backups)
+- ✅ TLS analysis
+- ✅ Nuclei template execution
+- ✅ JS file harvesting
+
+**What does NOT get proxied:**
+- ❌ DNS brute-force (uses UDP, driven by `internal/dns/resolver.go` through the `miekg/dns` library — set your resolvers explicitly with `-r <ip>` if you need a specific path)
+- ❌ Ollama calls when hitting `localhost` (as expected)
+
+If you need **full isolation** (including DNS brute-force) for threat-model reasons, wrap the whole binary:
+
+```bash
+torsocks ./god-eye -d target.com --pipeline --profile bugbounty
+```
+
+The tool won't fight torsocks; in fact the per-host concurrency and retry logic are already tuned conservatively (≤ 100 parallel dials by default, exponential backoff on failure) so torsocks doesn't choke.
+
+---
+
+## One-liner cheat-sheet
+
+```bash
+./god-eye                                                                # wizard
+./god-eye -d TARGET                                                      # v1 monolith scan
+./god-eye -d TARGET --pipeline --profile bugbounty --live                # v2 full recon
+./god-eye -d TARGET --pipeline --enable-ai --ai-profile heavy --live     # max power
+./god-eye -d TARGET --pipeline --profile asm-continuous --monitor-interval 24h \
+  --monitor-webhook https://hook                                         # ASM
+./god-eye -d TARGET --pipeline --profile stealth-max                     # evasion
+./god-eye -d TARGET --pipeline --proxy socks5h://127.0.0.1:9050          # route via Tor
+./god-eye -d TARGET --pipeline --proxy http://127.0.0.1:8080             # through Burp
+./god-eye update-db                                                      # refresh CISA KEV
+./god-eye nuclei-update                                                  # refresh Nuclei templates
+./god-eye db-info                                                        # KEV status
+go run ./tools/parity -d TARGET --bin ./god-eye                          # v1-vs-v2 diff
+```