Every engagement I ran involved the same 30+ tools, run in roughly the same order — but never actually chained: subfinder to find subdomains, then dnsx, httpx, naabu, nuclei for the recon side, then a second wave of SQLMap, Dalfox, Jaeles, Nikto once targets were confirmed live, then manually copying output between each so the next tool had the right input file. If step 4 of 30 failed silently, I wouldn't notice until the report came back with a missing section three hours later.
The tools themselves are excellent. The problem was the wiring between them across the entire pipeline — not just enumeration, but the vulnerability scanning and exploitation steps after it too.
So I built Oculus — a single-file Python orchestrator that chains ~30 industry-standard CLI tools across five phases — discovery, infrastructure mapping, content discovery, vulnerability analysis, and targeted exploitation — with actual orchestration logic on top, not just a bash script gluing stdout to stdin.
🔗 Code: https://github.com/shlokkokk/Oculus
Try it in three commands
git clone https://github.com/shlokkokk/Oculus.git oculus && cd oculus
chmod +x install.sh && ./install.sh
python3 oculus.py -d example.com --full-recon --no-confirm
That runs subdomain enum → resolution → alive hosts → ports → nuclei, then spits out output-example.com/report.html. Or skip the subset and run everything:
python3 oculus.py -d example.com --full-spectrum --no-confirm
The four problems actually worth solving
1. Silent failures. Most recon scripts treat "the tool ran" and "the tool worked" as the same thing. Oculus gives every module an explicit status:
| Status | Meaning |
|---|---|
OK |
Finished with usable output |
Skipped |
Missing tool, missing input, or no API key — step didn't run |
Partial |
Ran but some sub-tools timed out or degraded |
Failed |
Critical failure — e.g. every subdomain tool errored out |
That distinction matters: a Partial on Nikto shouldn't block your report, but a Failed on subdomain enum means everything downstream is garbage — you need to know that immediately, not after reading a report with an empty findings section.
2. Fixed timeouts don't scale. A 600-second cap makes sense for a 50-host scan and is actively wrong for a 5,000-host one. Oculus scales timeouts to the size of the target list instead of using one constant everywhere, so large scopes don't get killed mid-run just because the number was tuned for a small test case.
3. Losing a scan to a crash. Session state gets written to output-<domain>/session.json after each module completes, so a killed process resumes from where it left off instead of restarting the whole 36-module chain.
4. Babysitting a terminal for hours. Full Spectrum runs all 36 modules across 5 concurrent phases, which can run long. Oculus pushes one consolidated push notification per module via ntfy:
ntfy:
enabled: true
url: "https://ntfy.sh/your-topic"
send_module_complete: true # one ping per module, not per finding
Each ping has target, phase, status, per-tool line counts, and merged totals (unique subdomains, alive hosts, vulns) — so you can walk away from the terminal without losing track.
The full pipeline — not just recon
Running everything (--full-spectrum) walks all 36 modules through 5 phases, each with its own concurrency model:
PHASE 1 · DISCOVERY
Subdomain Enum → DNS Bruteforce → DNS Resolution → Alive Hosts → TLS Scan
+ concurrent: ASN mapping, cloud asset probing, OSINT, Shodan, GitHub dorking
PHASE 2 · INFRASTRUCTURE
Fast port scan + tech fingerprinting + WAF detection + screenshots, concurrently
+ full Nmap port scan and Nikto run in the background
PHASE 3 · CONTENT DISCOVERY
URL collection → advanced crawl (hakrawler) → parameter mining + JS endpoint extraction
+ subdomain takeover checks, Cariddi crawl in the background
PHASE 4 · VULNERABILITY ANALYSIS
Nuclei → GF pattern filtering, directory + API fuzzing concurrently
+ Jaeles signature scanning in the background
PHASE 5 · TARGETED EXPLOITATION
SQLMap + Ghauri (SQLi), Dalfox (XSS), open redirect, CRLF injection,
SSTI (Tplmap), 403 bypass, CORS misconfig, HTTP smuggling — all concurrent
That fifth phase is the part people miss when they hear "recon tool" — Oculus isn't stopping at "here are your live subdomains." It runs SQLMap/Ghauri, Dalfox, Tplmap, and CRLFuzz against confirmed live targets automatically, with the same status tracking and resumability as every earlier phase.
If you don't want the full run, there are two lighter presets: --full-recon (just the core 8-step discovery chain, 15-45 min) and --deep (a fixed 14-step advanced chain assuming recon's already done). Full Spectrum is the one that goes end to end.
What's actually running under the hood
- Discovery: subfinder, amass, assetfinder → dnsx → httpx → naabu/nmap, katana/gau/waybackurls, hakrawler
- Infrastructure & content: wafw00f, whatweb, gowitness/EyeWitness, ParamSpider/Arjun, LinkFinder, Cariddi, subzy, tlsx
- Vulnerability analysis: nuclei, gf, ffuf, Kiterunner, Jaeles
- Exploitation: SQLMap + Ghauri, Dalfox, Tplmap, CRLFuzz, nomore403, custom CORS/redirect/smuggling probes
- OSINT & passive intel: theHarvester, Shodan + InternetDB, GitHub code search, ASN/cloud bucket probing
-
Orchestrator: pure Python 3.8+, no framework — just
requests,dnspython,tldextract - Reports: HTML, JSON, and Markdown generated from the same session data
- New in v4.2: a full web UI (FastAPI backend, React/Vite frontend) for running scans, watching live output, and browsing reports in-browser — including a screenshot review tab that groups captures by domain
What I'd actually want feedback on
The timeout-scaling formula and the four-state module status model are the two design decisions I iterated on the most, and I'm not fully convinced I've got them right yet. If you run recon pipelines regularly — what's your failure mode? Silent tool failures, timeout tuning, or something else entirely?
Only point this at systems you own or have written permission to test — it's built for authorized engagements and CTFs, not opportunistic scanning.
⭐ If you find it useful: https://github.com/shlokkokk/Oculus
Top comments (0)