HawkEye Documentation

Every feature, in plain English, with a copy-paste example and the trap that catches people out. If you're new to this: read the ⚠ Watch out boxes — that's where rookies slip.

What HawkEye is

HawkEye is a single-binary vulnerability intelligence platform: it scans a host or network, enriches every finding with live CVE data (NVD), maps it to MITRE ATT&CK, suggests Metasploit modules, and can chain the whole thing into an automated pentest with a professional report at the end. It has three broad modes:

Network / web scanning — point it at a target, get findings.
Source Assessment — point it at a code repo, audit the code and its dependencies.
Auto-Pentest — learn a network passively, then enumerate → vuln-map → plan exploits.

Install & first run

Download the Linux tarball from the Portal and unpack it — it's a single flat binary:
```
tar xzf hawkeye-latest-linux-x86_64.tar.gz
chmod +x hawkeye
./hawkeye
```
Log in with your NoHatHacker account (email OTP + authenticator). The license unlocks the tabs; the demo tier is read-only for some active features.
The top bar shows your running version. Use the ⬆ Update button when a newer build is available — it self-replaces and restarts.

Prerequisites

NVD API key recommended

CVE lookups hit NVD. Without a key you're throttled to 5 requests / 30s; with a free key it's 50 / 30s — a big difference on a real scan.

Get a key (emailed instantly): nvd.nist.gov/developers/request-an-api-key
Paste it into Scan → Advanced Scanning → NVD key (saved for next time), or export NVD_API_KEY=…. The badge shows your tier: ● 50/30s or ○ 5/30s.

When to run with sudo root

Task	Privilege
CVE lookup, Source Assessment, reports	normal user
Passive sniff, `nmap -O`/`-sS`, VLAN inject	sudo (raw sockets)

⚠ Watch out: tools installed via pip/pipx live in ~/.local/bin, which a bare sudo hawkeye can't see. Launch with sudo env "PATH=$PATH" hawkeye if a tool "isn't found" only under sudo.

OpenVAS / GVM (optional)

HawkEye detects OpenVAS via the gvm-cli binary — which ships in gvm-tools, not the gvm metapackage: sudo apt install gvm-tools, then sudo gvm-setup + sudo gvm-start. Override the path with HAWKEYE_GVM_CLI=/path/to/gvm-cli if autodetect misses it.

Network scan

What it is: the classic "point at a target, find vulns" scan. Nmap NSE plus a zero-dependency internal engine, run by parallel workers.

How

In the Scan tab, set Target — a single IP, a hostname, or a CIDR/range (192.168.1.0/24, 10.0.0.1-50). A range is ping-swept first, then each live host is scanned.
Pick a profile: Quick (top 1000 + vuln scripts), Full (all ports), Web (HTTP-focused), Stealth (slow SYN), or Custom (your own nmap args).
Choose the engine — Nmap, the internal scanner, or Both — and hit scan.

Target:  192.168.60.112
Profile: Quick
Engine:  Both

⚠ Watch out: a silently-dropping firewall is the slowest host to scan (every probe waits a full timeout), not the simplest. It can take many minutes — that's normal, not a hang. HawkEye favours completeness, so it lets each host finish rather than cutting it short.

Web / DAST web

What it is: active web-app testing layered on top of the port scan — SQLi/XSS/SSTI/traversal/header checks, plus optional Katana (JS crawl), Nikto, a headless browser engine (DOM XSS, prototype pollution) and OpenAPI/GraphQL spec import.

How

Enable the engines you want in Advanced Scanning (each shows "installed / not installed").
Point API Spec at a swagger.json/openapi.yaml, or leave blank to auto-probe common paths.

⚠ Watch out: Chromium is the package name for the browser engine, not chromium-browser (that no longer exists on current Debian/Ubuntu).

Authenticated scanning web

What it is: makes the web checks run as a logged-in user. Most real bugs live behind the login (admin panels, IDOR, authenticated SQLi); an anonymous scan only sees the public front door.

Form auth

Give HawkEye the login form and creds. It fetches the login page, carries hidden CSRF fields into the POST, then replays the session cookie on every request.

Field	Example (DVWA)
Target	`http://192.168.60.112`
login_url	`login.php`
username_field / password_field	`username` / `password`
username / password	`admin` / `password`
extra cookie	`security=low`

⚠ Watch out: the username_field/password_field are the HTML input names (e.g. email), not your username. And use the extra-cookies field for app state — DVWA needs security=low or every page returns the "impossible" hardened version and you'll find nothing.

Token auth

For APIs/SPAs, paste a Bearer token (or set a custom header like X-API-Key). For a JWT app, log in once and copy the token:

curl -s http://192.168.60.112:3000/rest/user/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@juice-sh.op","password":"admin123"}' \
  | jq -r .authentication.token
# → paste into the Bearer token field

OOB — Out-of-Band blind detection web

What it is: catches the bugs that never echo anything back — blind SQLi, SSRF, XXE, SSTI. HawkEye starts a local HTTP listener and injects callback URLs into its probes. If the target's server makes a request back to your listener, the injection is confirmed.

How

Tick OOB in Advanced Scanning.
Set OOB LHOST to your scanner's IP on a network the target can reach.
Set OOB LPORT (default 8877) and make sure it's open on your box.
Scan. A hit records the source IP, the path, and which probe fired.

⚠ Watch out — this is the #1 rookie mistake: LHOST must be an IP the target can call back to (your machine's LAN/routable IP). Never 127.0.0.1 — the target can't reach your loopback, so you'll get zero hits and wrongly assume "no blind bugs." Also open the port in your firewall.

OSV — dependency / supply-chain scan code

What it is: audits a source tree's dependencies, not a host. It parses Cargo.lock, package.json, package-lock.json, requirements.txt, go.sum and pom.xml, then queries api.osv.dev — one finding per vulnerable dependency.

How

Tick OSV in Advanced Scanning.
Set the OSV root to the repo/folder to audit (blank = current directory).

git clone https://github.com/mradamantware/HawkEyeDemo /tmp/HawkEyeDemo
# OSV root = /tmp/HawkEyeDemo
# → flags axios 0.21.0, lodash, requests, PyYAML, jwt-go, …

⚠ Watch out: OSV scans files on disk, so the manifests must be present locally (clone/copy the repo to the machine running HawkEye). It does not reach out to a remote host.

Source Assessment code

What it is: the 🧬 Source tab — register a Git/SVN/Mercurial repo and run three lanes: a ~40-rule static code-vulnerability scanner (SAST), the OSV supply-chain sensor above (SBOM + CVE + typosquat + malicious-package + install-script heuristics), and an optional AI code audit via Coding Sidekick. Everything merges into the same Findings / Chains / Report.

A deliberately-vulnerable demo repo is pre-seeded — press Sync & Scan to try it.

Skill / MCP audit code

What it is: a scanner for the AI-agent prompt layer that your code SAST can't see. Point it at a repo and it walks SKILL.md, CLAUDE.md, AGENTS.md, .cursorrules, mcp.json and the skills/·.claude/ trees, then grades prompt-injection, data-exfil, remote-code-fetch, credential-access and excessive-agency — plus structural traps regex misses: invisible/bidi Unicode and imperatives hidden in HTML comments. You get a 0–100 risk score with LOW/MEDIUM/HIGH/CRITICAL bands.

How

CLI: hawkeye skillaudit ./path/to/skill — or add --format json for machine output.
Gate a pipeline with --fail-over 51: HawkEye exits non-zero on a do-not-install score so a CI merge is blocked. A clean skill scores 0 and exits 0.
Findings are validation-first — a weak signal is born POTENTIAL FALSE POSITIVE (half-weight in the score) and rides the same status badge as every other finding.

⚠ Watch out: a high score means "don't install this skill", not "this repo's code is exploitable" — it's the instruction layer being judged. Review the flagged lines before trusting or rejecting a third-party skill.

CVE lookup & inline AI any

What it is: the CVE tab looks up any CVE (NVD + EPSS + KEV) and, since v3.9, has an inline 🧠 Ask AI panel. Select a CVE, pick a backend and model — local Ollama by default so nothing leaves your box — and get root cause, a realistic exploitation scenario, IOCs / detection opportunities, prioritised remediation and known PoC / in-the-wild status, ready to paste into a report.

Configure backends and keys once in the AI Assist tab; the CVE panel reuses them. Cloud backends run an honest authorized-engagement prompt — no jailbreaks — while your local model is unrestricted and offline.

Auto-Pentest engine root

What it is: the 🛰 Auto-Pentest tab turns a network into an end-to-end assessment: passively learn the wire → interpret VLANs/rogue subnets → deep-scan each host → map CVEs/ATT&CK/MSF → match KB playbooks → produce a professional report with a planned attack path.

How

Interface / Our CIDR auto-fill from your NIC. The Scope allowlist is your authorization boundary — the CIDRs/VLANs you're allowed to touch.
Set the passive Learn capture seconds, leave Resume on (reuses already-scanned hosts so a restart isn't a full rescan), and run.
Passive mode learns/enumerates/vuln-maps/reports and never touches anything. Active mode additionally generates injection/exploit plans; live execution is gated behind the explicit Arm confirmation.

⚠ Watch out: the Scope allowlist is not a false-positive filter — it's the legal authorization boundary for intrusive actions. Active scanning, injection and exploitation against systems you don't own is a crime. Only ever run active mode within written authorization. Run the engine with sudo (it needs raw sockets for the passive sniff and OS detection).

Live Metasploit orchestration root v4.0

What it is: in Active mode HawkEye can drive Metasploit for real — a broker spawns and manages the msfconsole RPC daemon, generates and delivers the payload, fires the exploit and tracks the sessions and callbacks it opens. Every payload, callback and stage is written to an audit trail.

How

Run the auto-pentest in Active mode inside your Scope allowlist, then Arm — the arm confirmation is your written-authorization gate.
Fire a staged attack (or let a confirmed foothold chain). The broker brings up msf, delivers the payload and reports the session; the callback lands where the audit log records it.
Review the audit trail with the report — it lists every payload generated, every callback, and every stage, in-scope only.

⚠ Watch out: this is live offensive execution. It runs only when Active + Armed + in-scope + root, and only against systems you are authorised in writing to attack. HawkEye will never generate polymorphic or EDR-evasion payloads — it competes on truth and coverage, not stealth.

Attack-surface detections v4.0

What they are: three detections that widen a single pass, all surfaced automatically in your scan Findings:

Subdomain takeover — after HawkEye enumerates a target's subdomains it flags any dangling CNAME pointing at an unclaimed service (S3, Azure, GitHub Pages, Heroku…) that an attacker could claim. Detection-only.
Cryptojacking — a Stratum protocol probe plus mining-pool DNS and in-browser miner JS flags unauthorised mining on the network. It reads only what the audit already exposes — it never mines or joins a pool.
Default-credential audit — vendor-default logins on out-of-band management (BMC/iLO/iDRAC/IPMI, NAS, UPS/PDU, PLCs, switches) are reported confirmed. A default login here is pre-OS control of the box: power, virtual media, KVM, firmware.

⚠ Watch out: the default-credential audit tries known vendor defaults against management interfaces — only run it inside authorised scope.

Findings, ATT&CK & reports

Findings — every result, filterable by severity/host/CVE. Each carries CVSS, EPSS, CISA-KEV status, remediation and suggested MSF modules.
MITRE ATT&CK — coverage heatmap; the "All" view lists techniques by how many findings map to them.
Chains — pick findings to build an attack chain (access → privesc → lateral).
Report — export Markdown / HTML / PDF, ready to hand to a client.

Walkthrough 1 — Authenticated web scan of DVWA web

Goal: scan past a login and pull out the SQLi/XSS/LFI that an anonymous scan would never see. Assumes DVWA is reachable at http://192.168.60.112 and HawkEye is running + logged in.

Prep DVWA once. Browse to http://192.168.60.112/setup.php and click Create / Reset Database (skip if already done). Default creds are admin / password.
Scan tab → Target. Enter http://192.168.60.112. Profile = Web, Engine = Both.

Advanced Scanning. Tick Enhanced DAST. Tick Authenticated and fill:

login_url        = login.php
username_field   = username
password_field   = password
username         = admin
password         = password
extra cookie     = security=low

(Optional) paste your NVD key so findings get live CVE/CVSS enrichment.
Run. Watch the scan log — you should see Auth: fetching login form → login.php, then ✔ Login form detected, then the session cookie being reused. That confirms you're scanning as admin.
Findings tab. It fills with the authenticated bugs — SQL injection, reflected/stored XSS, command injection, LFI, file upload, CSRF. Filter by severity to triage.
Report tab. Export HTML or PDF — a client-ready report with findings, CVSS, remediation and ATT&CK mapping.

⚠ If Findings is nearly empty: you almost certainly missed the security=low extra cookie — DVWA served the hardened "impossible" pages. Add it and re-run. Second most common: username_field/password_field set to your creds instead of the HTML input names.

Walkthrough 2 — Auto-pentest a lab subnet root

Goal: point HawkEye at a subnet you're authorized to test and get a full assessment — hosts, services, CVEs, matched playbooks and a planned attack path — without touching anything (passive mode).

Launch with root (raw sockets for the sniff + OS detection):
```
sudo env "PATH=$PATH" hawkeye
```
🛰 Auto-Pentest tab. Interface and Our CIDR auto-fill from your NIC — check they're right. Set the Scope allowlist to the CIDR you're authorized to test (e.g. 192.168.60.0/24).
Set Learn capture to 30s, leave Resume on, Mode = Passive. Glance at the arsenal panel — tshark and nmap should show present (missing tools grey out stages).
Run. Stages tick through: preflight → learn (passive sniff) → deep-scan → vuln-map → report.
Read the report. Each host shows OS guess, fingerprinted services, mapped CVEs (with EPSS/KEV), ATT&CK techniques, matched KB playbooks, and a Planned Attack Path (PoC) — the exact commands an operator could run. Unreached/filtered assets are carried into "Recommended next steps".
Re-run any time. With Resume on, already-deep-scanned hosts are reused (the "N host(s) cached" indicator), so iterating isn't a full rescan.

⚠ Passive vs Active: passive mode never touches a target — it only listens + enumerates + plans. Active mode's inject/exploit steps are gated behind the explicit Arm confirmation and require written authorization for the scope. The Scope allowlist is that legal boundary, not a noise filter. Test only what you're allowed to.

Walkthrough 3 — Confirm a blind SSRF with OOB web

Goal: prove a blind injection (no visible response) by making the target call home to your listener.

Find your scanner's reachable IP (the one the target can route back to):

ip -o -4 addr show | awk '{print $2, $4}'
# e.g. ens33  192.168.60.50/24  → LHOST is 192.168.60.50

Scan tab → Target = the app under test, e.g. http://192.168.60.112:3000 (Juice Shop).

Advanced Scanning → OOB. Tick it and set:

OOB LHOST = 192.168.60.50      (NOT 127.0.0.1)
OOB LPORT = 8877               (open it in your firewall)

Run. HawkEye starts the listener and injects callback URLs into its probes.
When the app's server fetches http://192.168.60.50:8877/<token>, a confirmed OOB finding appears with the callback source IP, the path, and which probe fired (SSRF/SQLi/XXE/SSTI).

⚠ Zero hits ≠ no bug. If nothing comes back, first suspect LHOST/port reachability, not the app. Verify with nc -lvnp 8877 on your box and curl http://LHOST:8877/x from the target's network — if that doesn't land, HawkEye's callbacks won't either.

Rookie gotchas — the short list

OOB LHOST = 127.0.0.1 → zero callbacks. Use a target-reachable IP.
DVWA finds nothing → you forgot the security=low extra cookie.
Auth "username field" = the HTML input name, not your username.
Empty results / raw-socket errors → you need sudo for the network/auto-pentest scans.
"Tool not found" only under sudo → PATH issue; sudo env "PATH=$PATH" hawkeye.
OSV finds nothing → point it at a local repo path with real manifests, not a URL.
Firewall host "hangs" → it's just slow (silent drops). Let it finish; that's accuracy.
Throttled CVE lookups → add your free NVD API key.