god-eye/EXAMPLES.md

# 📖 God's Eye v2 — Usage Cookbook

> 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**.

<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
./god-eye
```

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
./god-eye --wizard -d target.com
```

---

## 2. Quick passive reconnaissance

Get a fast subdomain list without DNS brute-force or HTTP probing:

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

- 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

For pure subdomain output, pipe to a file:

```bash
./god-eye -d target.com --pipeline --profile quick --no-probe --silent > hosts.txt
```

---

## 3. Full bug-bounty recon with AI

The default workflow: full discovery + security checks + AI triage.

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

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.

Want the output saved too?

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

---

## 4. Authorized penetration test

Like bug-bounty but with light stealth to evade basic rate limits:

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

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
./god-eye -d client.example --pipeline --profile pentest \
  --stealth moderate \
  -c 100
```

---

## 5. Continuous attack-surface monitoring

Run once, then every 24h, diffing against the last snapshot:

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

What happens:

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

Sample webhook payload:

```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"
    }
  ]
}
```

For local testing without a webhook, the `StdoutAlerter` always runs:

```bash
./god-eye -d target.com --pipeline --profile asm-continuous --monitor-interval 10m
```

---

## 6. Maximum stealth mode

For highly-sensitive targets where any detection is unacceptable:

```bash
./god-eye -d target.com --pipeline --profile stealth-max --live --live-verbosity 0
```

`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
./god-eye -d target.com --pipeline
```

CLI flags always win over YAML, so you can still override anything:

```bash
./god-eye -d target.com --pipeline --stealth paranoid    # overrides stealth: light
```

---

## 8. Custom wordlist + resolvers

Use a bigger wordlist and specific DNS servers:

```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
```

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.

---

## 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
```