Welcome. This portal contains technical documentation for all No Hat Hacker tools. Access is controlled by your license entitlement — sections unlock automatically when you purchase or register for a product.
All Sidekick tools share a common design pattern:
| Property | Value |
|---|---|
| Platform | Debian / Kali Linux · x86-64 |
| Distribution | Single static binary — no installer, no dependencies |
| Interfaces | GUI (egui desktop app) + headless CLI |
| Auth | Email OTP → TOTP (Google Authenticator) → 30-min session |
| License | Online validation · machine-fingerprint locked |
| License server | license.nohathacker.com |
All No Hat Hacker tools use a unified 3-factor authentication flow. No passwords — ever.
On your very first login, after the email code step you will be shown a QR code to scan with Google Authenticator. Scan it once and confirm with the first 6-digit code. From that point on, step 3 is just entering the rotating code from the app.
Session data is stored locally at ~/.config/eps/session.json. It contains your session token and the database decryption key. The file is set to 0600 permissions automatically.
Manage your license, download binaries, and view invoices at nohathacker.com/portal. Same 3FA login applies.
The most complete email security assessment framework in existence. This documentation covers installation, the 3FA login flow, each GUI module, and the full CLI reference.
Built-in SMTP capture server. Bind to any host/port and receive test emails for callback and bounce analysis. No Postfix required.
Send individual test emails using built-in phishing scenarios or fully custom parameters. Supports DKIM signing, relay configuration, and evasion headers.
Multi-target email delivery with per-target delay, relay rotation, and live log output. Loads target lists from the text area (one address per line).
CIDR-range SMTP scanner. Discovers open relays across IP ranges. Feeds discovered relays into the relay database for use in Send/Campaign.
Live credential vault. Stores SMTP credentials found via spray or manual entry. Status tracked per credential (Live / Dead / Untested). Feeds directly into campaign relay rotation.
Recursively resolves the full SPF authorisation tree for any domain. Every include:, redirect=, and nested mechanism exposed. Identifies which ESPs are authorised to send on behalf of the target.
Domain permutation generator with live DNS validation. Surfaces all registered lookalike domains. Results are checked for MX records and classified by risk.
Tor-routed credential search across dark web paste sites and leak indexes. HIBP stealer log enrichment. Discovered credentials are automatically tested live against the target mail server.
Email header forensic analyser. Paste raw email headers to extract routing path, authentication results (SPF/DKIM/DMARC), delivery timestamps, and MUA/MTA fingerprints.
SMTP AUTH password spray. Single or multi-target. Bundled Ignis wordlists (10K, 100K, 1M). STARTTLS, configurable delay, stop-on-hit. Hits are saved to the credential vault automatically.
Professional HTML/PDF assessment report. Covers DMARC posture, credential hits, relay exposure, dark web leaks, and delivery results. Open in browser or save to file.
| Command | Description |
|---|---|
| eps login | 3FA authentication (email OTP → TOTP) — required before any other command |
| eps status | Show current session: email, license type, minutes remaining |
| eps logout | Clear session immediately |
| eps list | List all built-in phishing scenarios |
| eps test <id> <target> | Run a scenario against a target address |
| eps custom | Send a fully custom email (all fields via flags) |
| eps spray | SMTP password spray |
| eps server | Start SMTP capture server |
| eps logs | Show recent test log entries |
| eps report | Generate HTML assessment report |
Network infrastructure pentesting with built-in intelligence. This documentation covers installation, the login flow, each GUI tab, the attack template library, gateway discovery, and the CLI reference.
Set the target host/CIDR, port range, and output directory before running any attacks. These values are substituted into all templates via {host}, {port}, {outdir}, and {iface} placeholders.
50+ one-click attack templates organised by category. Select a template, review the command, and click Run. Output streams live. Findings are automatically extracted and added to the Results tab.
Template categories: Reconnaissance, Service Enumeration, Vulnerability Assessment, Exploitation, VLAN Discovery, Gateway Recon, Post-Exploitation, Lateral Movement, Exfiltration.
All findings in a sortable, filterable table. Each finding has: severity (Critical/High/Medium/Low/Info), MITRE ATT&CK technique ID, title, target, timestamp, raw evidence block. Click any finding to expand the full evidence. Use the filter controls to drill into a specific severity or technique.
Live network topology map. Hosts auto-populate from scan output — even after clearing the output log. Positions are auto-arranged by subnet, then saved between sessions.
Controls:
- Scroll wheel — zoom in/out toward cursor (0.15× to 4×)
- Middle-drag or right-drag — pan the canvas
- Left-drag on a node — reposition it (saved to disk)
- Reset Layout — re-run auto-layout for all nodes
- Clear All Hosts — wipe topology (does not affect findings)
Gateway diamonds: Blue diamond = confirmed default gateway from ip route. Red diamond = rogue/unexpected routing device. Amber diamond = alt gateway found during discovery.
Incrementally probes private /24 ranges looking for networks reachable through detected gateways. Configure up to three seed networks (e.g. 10.0.0.0/24, 172.16.0.0/24, 192.168.0.0/24). The probe expands each seed across all 256 third-octets and ping-sweeps each /24 with configurable thread count (1–8, default 4).
Click Discover Gateways to run the full rogue gateway detection chain:
- Routing table — reads
ip route show, identifies default GW and suspicious non-defaultviaentries - Multi-path traceroute — traces to 8.8.8.8, 1.1.1.1, 9.9.9.9. Multiple hop-1 IPs = asymmetric routing alert
- Active /24 sweep — nmap ping-sweep of the local subnet derived from the default GW (catches rogue devices not in ARP cache)
- ARP cache merge — combines with
arp -n/ip neigh show - Fingerprint — nmap
-sV -p 22,80,443,8080,8443,8291,8728,179+ curl banner grab per candidate. 30+ vendor signatures matched
Vendor coverage: pfSense, OPNsense, FortiGate, Palo Alto, F5 BIG-IP, Check Point, SonicWall, Juniper, MikroTik, Cisco, ClearOS, VyOS, Ubiquiti (UniFi / EdgeOS / AirOS), OpenWrt, DD-WRT, OpenMediaVault, Linksys, Zyxel, Netgear, SMC Networks, Huawei, D-Link, TP-Link, Alcatel-Lucent.
OSINT IP discovery using Shodan, Censys, FOFA, and ZoomEye. Requires API keys configured in the Vault tab. Results auto-populate the topology map.
Secure local storage for API keys (Shodan, Censys, FOFA, ZoomEye) and captured credentials. Keys are stored encrypted at ~/.config/ips/vault.json.
Generate a professional HTML report containing: engagement metadata, executive summary, severity scorecard, notes, the topology SVG as it is arranged on screen, per-finding index table, and full evidence blocks. Click Generate HTML Report — the file opens automatically in your browser.
Raw socket operations require root. Run sudo ips-gui or add the binary to sudoers for the specific capabilities you need.
IPS parses IPs from scan output files in ~/.config/ips/scans/ and from live output. If you cleared the output log, hosts already discovered are preserved in the persistent topology set. If no hosts appear, verify the template used {outdir} and that the scan completed successfully.
This was fixed in v1.0.0. The stop logic now kills individual child PIDs only — never the process group. Update to v1.0.0 if you experienced this.
An AI coding agent that fronts any model — Claude, GPT-4o, Gemini, or a local Ollama instance — with a rich terminal UI, 300+ built-in tools, team orchestration, and a built-in permission layer you can fully control. One binary, zero containers, no Node runtime.
almanac.toml.Built-in Project Management. CS enforces structured PM practices on every project — automatically. Missing
SCOPE.md, WBS.md, TASKS.md, CHANGE_REQUESTS.md, or SCOPE_CREEP.md files are created at startup. The LOCKED pipeline ensures scope changes never silently overwrite committed work. Human workers and AI workers share the same plain-text files committed to git.
CSK reads config from two locations — global defaults first, then project-local overrides:
Minimal config to set your default provider:
All providers are configured under [providers.<id>] blocks:
cs exec runs a single task with full tool use, all confirmations auto-approved, and the result streamed to stdout. It is designed to be called from scripts, pipelines, or other applications (such as HawkEye) that need AI reasoning without any human interaction.
Use {key} placeholders in the prompt and supply values with --var key=value. This lets callers build a prompt template once and inject runtime values (paths, credentials, scan targets) without string-concatenation hacks.
cs exec always runs with SirYesSir (auto-yes). The agent can read, write, and execute anything in the working directory. Run it in a container or with a restricted user account when the prompt or target is untrusted.Launch with cs --tui. Three-pane layout: conversation (scrollable), input box, status bar.
- Enter — send message (or queue it while agent is thinking)
- ↑ / ↓ — cycle through sent-prompt history · navigate ask_user option list
- Esc — clear input (or return to draft when browsing history)
- PgUp / PgDn — scroll conversation
- Ctrl+C — copy input field to clipboard
- Ctrl+X — cut input field to clipboard
- Ctrl+V — paste from clipboard into input
- Ctrl+Y — yank last agent response to clipboard
- Ctrl+Z — cancel the running task (aborts the agent turn; does not quit)
- Ctrl+D — quit
- y / n — answer a tool confirmation modal
- Enter / 1–9 — confirm selected option in ask_user modal
- Shift+drag — native terminal text selection (bypasses TUI mouse capture)
- Click [×] — cancel a specific running task from the task bar
The bottom line shows: provider chip · model chip · mode label · thinking indicator (●). When SirYesSir is active a bright green SIR YES SIR badge appears on the right so you always know the permission mode at a glance.
By default CSK shows a confirmation modal any time a tool wants to write a file, run a bash command, or take any side-effecting action. SirYesSir bypasses this gate entirely — all confirmations are auto-approved instantly.
Define named workers in opencode.toml, each with a pinned model, provider, skill set, and cost tier. The TUI queue is skill-aware: messages that match a free worker's skills are dispatched immediately in parallel, without blocking the main conversation thread.
When you type while the main agent is thinking, the queue checks your message against every free worker's skills list (case-insensitive substring match). If a match is found, the message is dispatched immediately to that worker — in parallel with the ongoing main turn. The queue pane shows all active lanes:
Worker output appears in the conversation labeled [worker-id]: in cyan, separate from the main agent: thread. When a worker finishes, the next queued message matching that worker's skills is automatically dispatched — no manual routing required.
If no worker matches (or all matching workers are busy), the message stays in the queue and is submitted to the main provider when it finishes its current turn. Lower cost_tier workers are preferred when multiple workers match the same message.
Six AI workers. One shared context file. A pipeline that takes an idea from a sentence to deployed code without you touching a keyboard between steps. Each worker is permanently wired to the phase it does best — the skill-aware queue handles all routing automatically.
.md
Skills : idea, plan, tasks, spec, breakdown, feature, roadmap, brainstorm
qwen-scout → Scaffolding (runs before Claude)
Provider : Ollama (qwen2.5-coder:32b — local)
Does : reads task MD files, creates file stubs, folder structure, boilerplate
Skills : scaffold, stub, init, skeleton, prepare, structure, boilerplate
claude-engineer → Architecture & implementation
Provider : Anthropic (claude-opus-4-8)
Does : reads task MD + scaffolded stubs, writes production code and tests
Skills : code, implement, architecture, design, write, build, function, class
llama-translator → Docs localisation
Provider : Ollama (llama3.2 — local)
Does : translates all reference files from English into configured target languages
Skills : translate, localise, language, i18n, spanish, french, german, portuguese
gemini-visual → Images & visual context
Provider : Google Gemini (gemini-2.0-flash)
Does : generates diagrams, banner images, annotated screenshots for docs
Skills : image, diagram, visual, screenshot, banner, icon, figure, illustration
gemma-deployer → Build, rsync & deploy
Provider : Ollama (gemma3:12b — local)
Does : runs build commands, rsyncs artefacts to remote servers, restarts services
Skills : deploy, rsync, build, release, publish, ship, restart, uploadTEAM.md is the single source of truth every worker reads at the start of a session. It lives in the repository root and is committed to git so all workers — and all humans — see the same information. Every worker reads it via their system prompt or a /context TEAM.md command before starting work.
Type one instruction. The skill queue fans it out to the right worker automatically. Here is the full idea-to-ship sequence:
The queue pane shows all active lanes in real time:
Each provider needs its credentials available before cs starts. The cleanest approach is a per-project .env file sourced in your shell profile, or a [env] block in opencode.toml (not committed to git).
Start every session by injecting TEAM.md into the context. CSK supports a /context command that reads a file and prepends it to the active conversation:
Alternatively, reference TEAM.md explicitly in your message: "Using the server details in TEAM.md, deploy to production." — the agent fetches and reads it via the read_file tool before acting.
Three of the six workers run on local Ollama — zero API cost and no rate limits. Only the planner, engineer, and visual worker call external APIs. On a mid-range machine with a GPU, the entire idea-to-deploy loop for a medium feature typically completes in under two minutes, with all workers running in parallel wherever the dependency graph allows.
Run cs mesh serve on each machine in your WireGuard mesh. Every node exposes its local AI resources — Ollama models, Anthropic keys, OpenAI keys — through a lightweight OpenAI-compatible HTTP proxy on port 11435. Other CS nodes discover peers via a shared almanac.toml and use any model in the network as if it were local.
Copy the backend blocks from mesh-backends.toml into your opencode.toml, or just paste the ones you want. The model field uses the prefix ollama: to tell the mesh proxy which local backend to use on the remote node.
Configure what happens when the active provider returns a 429:
Shell commands fired on lifecycle events. pre_tool_use with non-zero exit blocks the tool. All others are advisory.
Available events: pre_tool_use, post_tool_use, stop, user_prompt_submit. Each hook receives a JSON payload on stdin with the relevant context (event, tool name, input, output).
Attach any MCP-compatible server — its tools register under mcp.<name>.<tool> and the agent uses them like native tools.
CSK reads the key from the environment variable named in api_key_env. Make sure the variable is exported in the shell before running: export ANTHROPIC_API_KEY=sk-ant-.... You can also put it in [env] in the config file (not recommended for shared configs).
Some smaller or locally-hosted models do not support structured tool calls reliably. Add --smart to switch to aider-style edit-block parsing: cs --smart --tui. The agent outputs diffs in plain text and CSK applies them.
Set on_rate_limit = "wait" or add an OpenAI backup under [[chat_backends]] with on_rate_limit = "shift". For a Max subscription, the --compact-tools flag cuts ~25k tokens per turn and significantly reduces the chance of hitting rate limits during long sessions.
Add COLUMNS = "220" and LINES = "50" to the [env] block in your config. This pins the terminal dimensions so the readline input layer does not try to adapt to the physical window size.
CS ships a lightweight project management framework built around five plain-text Markdown files. Every worker — human or AI — reads and writes the same files. Git keeps everyone in sync. The LOCKED pattern prevents drift: once an item moves forward in the pipeline, it is frozen and future changes go through the proper channel.
| File | Purpose | Written by |
|---|---|---|
SCOPE.md | What we are building — the authoritative scope | Human or AI at project start |
CHANGE_REQUESTS.md | Changes to scope that is already locked | Anyone who needs a change |
SCOPE_CREEP.md | Good ideas that are out of scope right now | Anyone who spots one |
WBS.md | Work Breakdown Structure — scope broken into modules | PM or AI after scope is set |
TASKS.md | Atomic tasks workers claim, execute, and close | PM or AI from WBS modules |
When an item is processed into the next layer of the pipeline, it receives a LOCKED marker and must never be modified again. To change it, open a new entry in the appropriate upstream register.
This rule is absolute: locked = frozen. The pipeline that follows it is already built from that snapshot.
| Command | Effect |
|---|---|
cs pm init "Name" | Create all five template files |
cs pm status | Print open/claimed/done counts for all files |
cs pm task add "Title" WBS-001 "Description" | Add a new TASK-NNN to TASKS.md |
cs pm task grab TASK-001 worker-id | Claim a task (OPEN → CLAIMED) |
cs pm task done TASK-001 worker-id "Summary" | Complete + LOCK a task |
cs pm task release TASK-001 "reason" | Release a claimed task back to OPEN |
cs pm wbs add "Title" SCOPE-001 "Description" | Add WBS-NNN module from a scope item |
cs pm cr add "Title" HIGH "Description" | Log a change request |
cs pm sc add "Title" "noted during X" "Description" | Log a scope creep item |
cs pm lock SCOPE-001 SCOPE.md WBS-001 | Mark any item LOCKED (moved to target) |
CS includes built-in rsync-based file sync between mesh nodes. Push PM files and the almanac to a peer, or pull from one — no manual rsync commands needed.
Not every worker needs a git account. One node holds the credentials and acts as the vault. All others sync through it using cs mesh push-files / pull-files.
TEAM.md in the repo root so every worker knows who holds the keys and how to reach them. Print the git bridge help any time with cs pm git-bridge.| Rule | Why |
|---|---|
| Never edit SCOPE.md after the first LOCKED item | Downstream WBS and tasks are already built from that snapshot |
| One heading per scope item / task | The cs pm parser relies on ## [ID] structure |
| Commit PM files after every state change | Git log = audit trail of who did what and when |
AI workers should call cs pm status before grabbing a task | Prevents two workers from claiming the same task |
| Release rather than abandon | RELEASED tasks reappear in the OPEN pool; abandoned tasks block the module |
| Scope creep is not a dirty word | SCOPE_CREEP.md captures ideas without polluting active scope |
Tor + WireGuard Machine Mesh
Infrastructure guide · Linux · Leave machines at the office, orchestrate from anywhere
This guide builds a private mesh network that lets you reach every machine you own — regardless of NAT, corporate firewalls, or dynamic IPs. WireGuard carries the fast day-to-day traffic. Tor hidden services act as an always-on fallback for SSH when the office firewall blocks UDP or the WireGuard connection drops. Together they give you a resilient, authenticated, zero-trust tunnel to any machine in your fleet.
Hub-and-spoke, not full mesh. The VPS is the single WireGuard endpoint every spoke dials. Office machines never need an open inbound port — they initiate outbound UDP to the VPS on port 51820. From home you reach any office machine by routing through the VPS subnet (10.99.0.0/24). Tor is a parallel channel you fall back to when WireGuard is unavailable.
Run these commands once on your public VPS. This machine becomes the hub every spoke dials in to.
Create /etc/wireguard/wg0.conf on the VPS. Add a [Peer] block for every machine in the mesh.
Repeat on every machine you want in the mesh. Change Address to the unique IP for that machine (home = 10.99.0.2, office-1 = 10.99.0.10, office-2 = 10.99.0.11, etc.).
[Peer] on the VPS, then run wg addpeer or restart wg-quick@wg0 on the VPS. No other spoke needs to change — they all route through the hub.Install Tor on each office machine and expose its SSH port as a hidden service. This gives every machine a stable .onion address that works even behind the strictest corporate firewall — no port forwarding, no dynamic DNS needed.
The hidden service key lives at /var/lib/tor/ssh_hs/hs_ed25519_secret_key. Back it up — if you lose it, the onion address changes.
Set up SSH aliases so you can type ssh office1 for the fast WireGuard path and ssh office1-tor when WireGuard is down. Tor requires a local Tor instance running at 127.0.0.1:9050.
WireGuard reconnects automatically after a reboot — systemctl enable wg-quick@wg0 handles that. Office machines behind NAT need PersistentKeepalive = 25 (already in the config above) so the NAT mapping stays alive even when idle.
Document the mesh in your project's TEAM.md so every CSK worker knows which machine does what. The deployer worker can then SSH into any mesh machine by name.
[Peer] from the VPS and run wg syncconf wg0 <(wg-quick strip wg0).HawkEye
HawkEye is a professional-grade, all-in-one vulnerability assessment platform built as a native desktop application. It covers every stage of a modern pentest or red-team engagement — from raw network discovery to exploit chaining, PDF report generation, and one-click push to your ticketing system.
What Makes HawkEye Different
Most scanners are single-purpose: Nmap enumerates, Nuclei templates scan, ZAP fuzzes. HawkEye chains all of those engines together in a single workflow and adds capabilities found nowhere else at this price point:
| Capability | HawkEye | Nessus | Burp Pro | OpenVAS |
|---|---|---|---|---|
| Network-to-web full pipeline | ✅ Native | ✅ | ❌ Web only | ⚠ Partial |
| Browser-engine DAST (CDP) | ✅ Phase 6 | ❌ | ✅ | ❌ |
| Kill chain / ATT&CK mapping | ✅ Phase 7 | ❌ | ❌ | ❌ |
| Parallel worker pool | ✅ 1–10 | ✅ | ❌ | ⚠ |
| Scan history & delta diff | ✅ | ✅ | ❌ | ❌ |
| PDF + Jira/Linear/Slack push | ✅ | ⚠ Add-on | ⚠ Add-on | ❌ |
| Offline, no cloud SaaS required | ✅ | ❌ | ❌ | ✅ |
| Open-ended licensing | ✅ | ❌ Per IP | ❌ Annual | ✅ Free |
The Seven Phases
Every scan runs a configurable pipeline of up to seven phases. Each phase feeds findings into the next.
| # | Phase | Engine(s) | Key outputs |
|---|---|---|---|
| 1 | Network Discovery & NSE | Nmap + NSE scripts | Live hosts, open ports, banners, Nmap NSE findings |
| 2 | Internal CVE Scanner | Built-in + NVD API | Service-matched CVEs with CVSS, EPSS, KEV flag |
| 3 | Nuclei Templates | Nuclei binary (9,000+ templates) | Critical/High/Med/Low/Info findings per host |
| 4 | Web Attack Surface | Katana spider + API spec + CMS + OSV + OOB | Crawled URLs, tech fingerprints, CMS CVEs, OOB callbacks |
| 5 | Deep DAST | Internal HTTP fuzzer | SQLi (error/blind/time), XSS (stored/reflected), CSRF, JWT, LDAP/XPath injection |
| 6 | Browser-Engine DAST | Chromium DevTools Protocol | DOM XSS, CSTI, prototype pollution, CORS misconfig, CSP analysis |
| 7 | Kill Chain Engine & Reports | Internal pattern matcher | ATT&CK-mapped kill chains, remediation roadmap, PDF export, integration push |
Core Design Principles
- Native desktop, zero cloud dependency — all processing is local. Credentials never leave your machine.
- Parallel work-stealing engine — up to 10 concurrent scan workers with automatic load balancing.
- Scan history & delta diffing — compare any two scans to track remediation progress or detect regressions.
- Pluggable integrations — push findings directly to Jira, Linear, Slack, or any webhook endpoint.
- Report-grade output — one-click HTML and PDF reports suitable for client delivery.
Installation & Setup
System Requirements
| Requirement | Minimum | Recommended |
|---|---|---|
| OS | Linux x86_64, macOS 12+, Windows 10+ | Linux (best tool compatibility) |
| RAM | 512 MB | 4 GB+ (browser DAST uses more) |
| Disk | 50 MB binary | 2 GB (Nuclei templates cached) |
| Rust toolchain | 1.78+ (build from source) | Latest stable |
| OpenGL | OpenGL 2.0 or Vulkan | GPU-accelerated desktop |
Build from Source
HawkEye uses the Rust toolchain. Install Rust via rustup, then:
git clone https://github.com/mradamantware/HawkEye cd HawkEye cargo build --release # Binary at: ./target/release/hawk_eye
On Linux you may need system libraries for the GUI backend:
# Ubuntu / Debian
sudo apt install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev \
libspeechd-dev libxkbcommon-dev libssl-dev
# Fedora / RHEL
sudo dnf install libxcb-devel libxkbcommon-devel openssl-devel
Optional External Tools
HawkEye can run without any of these, but each unlocks additional scan phases. Install only what you need.
| Tool | Phase | Install |
|---|---|---|
| Nmap 7.9+ | 1 — Network Discovery | sudo apt install nmap |
| Nuclei 3.x | 3 — Nuclei Templates | go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest |
| Katana | 4 — Web Spider | go install github.com/projectdiscovery/katana/cmd/katana@latest |
| Nikto | 4 — Web Checks | sudo apt install nikto |
| Chromium | 6 — Browser DAST + PDF | sudo apt install chromium-browser |
| OpenVAS / GVM | 4 — Imported findings | Follow GVM community docs |
| Metasploit | 5 Scenarios — PoC run | sudo apt install metasploit-framework |
First Launch
Run the binary directly — no install step required:
./target/release/hawk_eye
HawkEye creates its data directory at ~/.hawkeye/ on first launch. Scan history is stored at ~/.hawkeye/history/ as individual JSON files.
NVD API Key (Optional but Recommended)
Phase 2 queries the National Vulnerability Database. Without a key, requests are rate-limited to ~5/min. With a free NVD API key the limit is 50/min.
- Register at nvd.nist.gov/developers/request-an-api-key
- Paste the key into the API Keys panel in the Scan tab → Advanced → NVD API Key field
Running a Scan
The Scan Tab
When HawkEye launches it opens on the Scan tab. Everything needed to start a scan lives here, organized into collapsible panels.
Step 1 — Set Your Target
Enter a target in the Target field. Accepted formats:
| Format | Example | Notes |
|---|---|---|
| Single IP | 192.168.1.10 | Scans one host |
| CIDR range | 10.0.0.0/24 | Enumerates all 254 hosts |
| Hostname / URL | example.com | Resolves DNS, then scans |
| Range notation | 10.0.1.1-50 | 50 host sweep |
Step 2 — Choose a Scan Profile
Profiles set the Nmap flags and enable/disable internal scanner modules. Select from the Profile dropdown:
| Profile | Nmap flags | Best for |
|---|---|---|
| Quick | -T4 --top-ports 100 | Fast recon, large /16 ranges |
| Full | -T3 -p- -sV | Complete audit, all 65 535 ports |
| Web | -T4 -p 80,443,8080,8443,8000 -sV | Web-focused, skips non-HTTP |
| Stealth | -T1 -sS --randomize-hosts | IDS evasion, red team ops |
| Custom | Your own flags | Anything else |
Step 3 — Select the Scan Engine
The Engine toggle controls how Phase 1 finds services:
- Nmap NSE — delegates entirely to Nmap with NSE scripts. Most compatible, produces detailed banners.
- Internal — HawkEye's built-in TCP prober + banner grabber. No Nmap required.
- Both — runs both in sequence and deduplicates findings. Most thorough.
Step 4 — Configure Parallel Workers
The Workers slider (1–10) sets how many hosts are scanned in parallel. Workers use a work-stealing queue — fast hosts free up workers immediately for the next host, avoiding the idle time of static batching.
| Workers | Typical use case | Stealth impact |
|---|---|---|
| 1 | Single host or careful audits | None |
| 2–4 | Small /24 ranges | Low |
| 5–8 | Internal network sweeps | Medium — IDS may alert |
| 9–10 | Speed-critical CI/CD pipelines | High — not stealthy |
Step 5 — Start the Scan
Click ▶ Start Scan. The scan log panel below shows real-time output from all workers. A progress bar tracks hosts completed / total hosts. Findings appear in the Findings tab as they are discovered, without waiting for the scan to finish.
Click ⏹ Stop at any time — workers finish their current host then exit cleanly. All findings up to that point are preserved.
Advanced Panels
Expand the Advanced Scanning accordion for additional capabilities:
- Subdomain Enumeration — passive + active subdomain discovery for a domain target.
- Authentication — provide credentials (HTTP Basic, form login, token, cookie) so authenticated pages are scanned.
- OpenVAS — import a GVM XML report to merge third-party findings into the same scan session.
- OOB Listener — starts a local out-of-band callback server. Detected when Phase 4 injects OOB payloads.
- API Spec — upload an OpenAPI / Swagger JSON spec to guide Phase 4 web enumeration.
- API Keys — NVD API key for higher Phase 2 rate limits.
Phase Guide (1–7)
Phases run sequentially per host. Each phase receives the port/service data produced by the previous phase and adds new findings. You can enable or disable phases per profile.
Phase 1 — Network Discovery & Nmap NSE
The entry point for every scan. HawkEye first determines which hosts are alive (ICMP ping + TCP ACK on port 443), then scans open ports and optionally runs Nmap NSE scripts.
What it does
- TCP SYN/connect scan across the configured port range
- Service version detection (-sV)
- OS fingerprinting (when run as root)
- NSE script categories: vuln,safe,default
- Banner grabbing on all open ports
Findings produced
Phase 1 findings include: open port disclosures, service version exposures, Nmap NSE vulnerability matches (e.g. EternalBlue, Heartbleed, ShellShock via dedicated scripts), and weak SSH algorithms.
Phase 2 — Internal CVE Scanner + NVD Enrichment
Using the service name and version strings collected in Phase 1, HawkEye queries the NVD API for known CVEs and matches them against its internal rule set.
What it does
- Version-to-CVE matching via CPE strings
- CVSS v3 score fetched per CVE
- EPSS probability score fetched (daily exploit likelihood)
- CISA KEV (Known Exploited Vulnerabilities) flag checked
- Internal rules for common misconfigurations (anonymous FTP, weak SNMP community, default credentials)
EPSS & KEV Badges
Findings with a KEV flag are marked with a red KEV badge in the Findings tab — these are actively exploited in the wild and should be prioritised. EPSS scores above 10% appear as an orange badge showing the probability.
Phase 3 — Nuclei Templates
HawkEye invokes the Nuclei binary against every HTTP/HTTPS endpoint discovered in Phase 1. The community template library contains 9,000+ checks covering CVEs, misconfigurations, default credentials, exposed panels, and more.
Template categories run
By default HawkEye runs: cves, exposed-panels, misconfiguration, default-logins, technologies. Informational-only templates are filtered unless the profile includes them.
Rate limiting
Nuclei is invoked with -rate-limit 100 by default. Stealth profile reduces this to -rate-limit 10. You can override via the custom Nmap flags field (flags are forwarded to Nuclei as well).
Phase 4 — Web Attack Surface
Phase 4 maps the web attack surface of every HTTP endpoint. It combines five sub-engines:
| Sub-engine | What it finds |
|---|---|
| Katana spider | All reachable URLs, forms, JS entrypoints, parameters |
| Nikto | Server misconfigurations, version disclosures, dangerous HTTP methods |
| CMS scanner | WordPress / Joomla / Drupal plugin & theme CVEs via WPScan-style matching |
| OSV.dev | Open-source dependency CVEs via manifest files (package.json, requirements.txt) |
| OOB callbacks | SSRF, blind XXE, blind command injection via the local OOB listener |
API Specification scanning
If an OpenAPI or Swagger JSON spec is provided, Katana seeds its crawl from every endpoint defined in the spec. This ensures 100% endpoint coverage even for SPAs with no anchor links.
Phase 5 — Deep DAST
Phase 5 applies an internal HTTP fuzzer to every parameter and input discovered in Phase 4. It tests for injection classes that require crafted payloads and response analysis.
| Attack class | Detection method |
|---|---|
| SQL Injection — error-based | Database error signatures in response body |
| SQL Injection — blind | Boolean diffing (true vs. false condition response delta) |
| SQL Injection — time-based | Response delay ≥ 5 s on SLEEP/WAITFOR payload |
| XSS — reflected | Injected payload echoed unescaped in response |
| XSS — stored | Payload stored, then retrieved on a second request |
| CSRF | State-changing POST with no CSRF token detected |
| JWT vulnerabilities | None algorithm, weak secret, missing signature verification |
| LDAP injection | LDAP error strings in response |
| XPath injection | XPath error strings in response |
| Header injection | CRLF + Host header reflection |
Phase 6 — Browser-Engine DAST
Phase 6 launches a headless Chromium instance controlled via the Chrome DevTools Protocol (CDP) to find vulnerabilities that only manifest in a fully rendered browser context — JavaScript-heavy SPAs, DOM manipulation, and browser-specific security controls.
| Check | What is tested |
|---|---|
| DOM XSS | JavaScript sinks: innerHTML, document.write, eval, location.href with taint tracking |
| Client-Side Template Injection | Angular, Vue, Handlebars template expression execution |
| Prototype Pollution | Object prototype modification via URL parameters |
| CORS misconfiguration | Wildcard or reflected Origin in Access-Control-Allow-Origin |
| CSP analysis | Missing, weak, or bypassable Content-Security-Policy headers |
| Subresource Integrity | Third-party scripts loaded without SRI hashes |
| Mixed content | HTTP resources loaded over HTTPS pages |
Phase 7 — Kill Chain Engine & Report Engine
Phase 7 runs automatically after all hosts complete. It does not send new network traffic — it analyses the full findings corpus collected in Phases 1–6.
Kill Chain Pattern Engine
The engine applies 15 MITRE ATT&CK-mapped patterns to the finding set. Each pattern defines:
- require_all — all of these finding types must be present
- require_any — at least one of these must be present
- bonus — these increase confidence if present
When a pattern matches, HawkEye builds a kill-chain narrative: a step-by-step description of how a real attacker would chain those specific findings into a full compromise path. Each chain includes MITRE technique IDs, suggested next steps, and a combined remediation strategy.
Remediation Roadmap
All findings are scored using the priority formula:
priority = (CVSS × 0.4) + KEV_bonus(2.0) + EPSS_bonus(1.5 if >10%) + severity_bonus
clamped to [0, 10]
The roadmap sorts findings by priority and groups them by owner (Security team, DevOps, Development, Network team) with effort estimates (Quick Win / 1 sprint / Quarter).
Kill Chains Tab
After a scan, open the Kill Chains tab to view matched chains. Each chain card is expandable and shows:
- Chain name and severity
- Narrative description of the attack path
- Step-by-step attack flow with MITRE technique IDs
- Finding IDs that triggered the pattern
- Suggested next steps for an attacker (useful for validating the finding)
- Combined remediation recommendation
Scroll down in the Kill Chains tab to see the Remediation Roadmap — a prioritised table of all findings sorted by risk.
History Tab
Every completed scan is automatically saved to ~/.hawkeye/history/. The History tab lists all past scans. Select any two to generate a delta diff:
- New findings — appeared in current scan, not in baseline
- Regressions — previously fixed, now back
- Persisted findings — still present in both scans
- Fixed findings — in baseline but gone from current scan
Findings & Reports
Findings Tab
The Findings tab is your central workspace for reviewing, filtering, and acting on discovered vulnerabilities.
Finding Cards
Each finding shows:
| Field | Description |
|---|---|
| Severity badge | Critical / High / Medium / Low / Info — colour-coded |
| Title | Short vulnerability name |
| Host : Port | Affected target |
| Service | Protocol or service name (http, ssh, ftp, …) |
| CVE ID | Linked CVE if applicable |
| CVSS score | Numeric severity score (0–10) |
| EPSS badge | Probability of exploitation in next 30 days |
| KEV badge | Red — actively exploited per CISA KEV catalogue |
| OWASP category | OWASP Top 10 / API Top 10 mapping |
| Status | Open / Acknowledged / Fixed (you set this manually) |
Filters
Use the filter bar at the top of the Findings tab to narrow the list:
- Severity filter — multi-select checkboxes (Critical, High, Medium, Low, Info)
- Status filter — Open, Acknowledged, Fixed, All
- Search box — full-text match against title, description, CVE, and host
Detail Panel
Click any finding to expand the detail panel. It shows:
- Description — what the vulnerability is and why it matters
- Evidence — raw proof: HTTP response excerpt, banner, payload that triggered the finding
- Remediation — concrete fix guidance
- References — CVE links, OWASP pages, vendor advisories
Report Tab
The Report tab generates client-ready output from the current scan session.
HTML Report
Click Generate HTML Report to produce a self-contained HTML file at ~/.hawkeye/reports/<scan-id>.html. The report includes:
- Executive summary with finding counts by severity
- Target scope and scan metadata (date, profile, engine)
- Complete finding table with all fields
- Kill chain narratives (if Phase 7 matched patterns)
- Remediation roadmap sorted by priority
- Classification footer (Confidential / Internal / Public)
PDF Export
With Chromium installed, click Export PDF to convert the HTML report to PDF using headless Chromium. The PDF is saved alongside the HTML file with a .pdf extension.
# HawkEye runs this internally:
chromium --headless --disable-gpu --no-sandbox \
--print-to-pdf=report.pdf \
--print-to-pdf-no-header \
file:///path/to/report.html
Report Classification
Select a classification level from the dropdown before generating: Confidential (default), Internal, or Public. The classification banner appears on every page of the PDF and in the HTML header/footer.
CVE Lookup Tab
Use the CVE Lookup tab to search the NVD directly without running a scan. Enter a CVE ID (e.g. CVE-2021-44228) to fetch:
- Full description and CVSS v3 vector
- Affected CPE configurations
- EPSS score
- CISA KEV status
- Published and last-modified dates
MITRE ATT&CK Tab
The MITRE tab renders a heatmap overlay of the ATT&CK Enterprise matrix. Techniques covered by findings from the current scan are highlighted. Hover a cell to see which findings map to that technique.
Scenarios Tab
The Scenarios tab lists pre-built attack scenarios for the most common vulnerability classes. Each scenario provides:
- Prerequisite findings required
- Manual exploitation steps
- Metasploit module reference (if applicable)
- Proof-of-concept code snippet
- Estimated CVSS impact if exploited
Scenarios are matched to the current scan — only scenarios relevant to what was found are shown.
Integrations
HawkEye can push findings directly to your team's issue tracker, messaging platform, or any custom webhook endpoint. All integration configuration is stored locally and never leaves your machine.
Find the integration settings in Report tab → Push Integrations. Configure one or more targets, then click Push Findings to send all current findings.
Jira
Creates one Jira issue per finding using the Jira REST API v3.
| Field | Description |
|---|---|
| Base URL | Your Jira instance root, e.g. https://yourcompany.atlassian.net |
| Jira account email address | |
| API Token | Personal Access Token from id.atlassian.com/manage/api-tokens |
| Project Key | The project key, e.g. SEC |
| Issue Type | e.g. Bug, Vulnerability, Security Risk |
Issue description is formatted as Atlassian Document Format (ADF) with sections for Description, Evidence, Remediation, CVE, CVSS, OWASP, and Host. Severity maps to Jira priority: Critical → Highest, High → High, Medium → Medium, Low → Low.
# HawkEye calls: POST https://yourcompany.atlassian.net/rest/api/3/issue Authorization: Basic base64(email:token) Content-Type: application/json
Linear
Creates one Linear issue per finding using the Linear GraphQL API.
| Field | Description |
|---|---|
| API Key | Linear personal API key from linear.app/settings/api |
| Team ID | The UUID of the target team (from Linear URL or API) |
HawkEye uses the issueCreate mutation. Title, description (Markdown), and priority are set per finding. Labels are not set automatically — add them via Linear's API if needed.
# HawkEye calls: POST https://api.linear.app/graphql Authorization: Bearer <api_key>
Slack
Posts a colour-coded message attachment per finding to a Slack channel via an Incoming Webhook.
| Field | Description |
|---|---|
| Webhook URL | Your Slack Incoming Webhook URL, e.g. https://hooks.slack.com/services/… |
Create a webhook at api.slack.com/apps → Incoming Webhooks. Each finding is a separate attachment. Attachment colour maps to severity: Critical/High → red, Medium → amber, Low/Info → good (green).
Generic Webhook
POSTs each finding as a JSON object to any HTTP endpoint. Suitable for SIEM ingestion (Splunk HEC, Elastic, Wazuh), custom dashboards, or in-house tooling.
| Field | Description |
|---|---|
| URL | Full endpoint URL |
| Method | POST or PUT |
| Auth Header | Optional, e.g. Authorization: Bearer <token> |
Each request body is a JSON object with the following fields:
{
"id": 42,
"title": "Apache Log4Shell (CVE-2021-44228)",
"severity": "Critical",
"host": "10.0.1.15",
"port": 8080,
"service": "http",
"cve": "CVE-2021-44228",
"cvss": 10.0,
"owasp": "A06:2021 – Vulnerable Components",
"description": "...",
"evidence": "...",
"remediation": "..."
}
Push Behaviour
All enabled integrations are pushed simultaneously when you click Push Findings. HawkEye shows a per-integration status log — green for success, red for failure with the HTTP status code and error message.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Jira 401 Unauthorized | Wrong email or API token | Regenerate token at id.atlassian.com |
| Jira 400 Bad Request | Issue type name doesn't exist in project | Check project's available issue types |
| Linear 200 but no issue created | Wrong Team ID (UUID format required) | Copy Team ID from Linear → Settings → API |
| Slack message not delivered | Webhook URL revoked or app removed | Recreate webhook in Slack app settings |
| Webhook connection refused | Endpoint not reachable from this host | Test with curl -X POST <url> manually |