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.

_{Built the binary yet? go build -o god-eye ./cmd/god-eye — then pick a recipe.}

---

---

Index

1. Zero-flag launch (interactive wizard)
2. Quick passive reconnaissance
3. Full bug-bounty recon with AI
4. Authorized penetration test
5. Continuous attack-surface monitoring
6. Maximum stealth mode
7. Using a YAML config file
8. Custom wordlist + resolvers
9. Subdomain enumeration pipeline (unix-pipeline style)
10. AI profile decision guide
11. Parity check: v1 vs v2
12. Scripted (CI) invocation
13. Troubleshooting

---

1. Zero-flag launch (interactive wizard)

The easiest way to scan something. No flags, no docs-reading required.

./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:

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

---

2. Quick passive reconnaissance

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

./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:

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

./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?

./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:

./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:

./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:

./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:

{
  "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:

./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:

./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:

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

./god-eye -d target.com --pipeline

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

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

---

8. Custom wordlist + resolvers

Use a bigger wordlist and specific DNS servers:

./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 (~500k–5M lines)
  • 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:

./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:

./god-eye -d target.com --pipeline --silent --no-probe -o subdomains.txt -f txt

For pure JSON consumption by other tools:

./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:

./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:

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.

# .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:

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

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

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