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

  1. 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
  2. Log in with your NoHatHacker account (email OTP + authenticator). The license unlocks the tabs; the demo tier is read-only for some active features.
  3. 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

TaskPrivilege
CVE lookup, Source Assessment, reportsnormal user
Passive sniff, nmap -O/-sS, VLAN injectsudo (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

  1. 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.
  2. Pick a profile: Quick (top 1000 + vuln scripts), Full (all ports), Web (HTTP-focused), Stealth (slow SYN), or Custom (your own nmap args).
  3. 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.

FieldExample (DVWA)
Targethttp://192.168.60.112
login_urllogin.php
username_field / password_fieldusername / password
username / passwordadmin / password
extra cookiesecurity=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

  1. Tick OOB in Advanced Scanning.
  2. Set OOB LHOST to your scanner's IP on a network the target can reach.
  3. Set OOB LPORT (default 8877) and make sure it's open on your box.
  4. 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

  1. Tick OSV in Advanced Scanning.
  2. 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.

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

  1. Interface / Our CIDR auto-fill from your NIC. The Scope allowlist is your authorization boundary — the CIDRs/VLANs you're allowed to touch.
  2. Set the passive Learn capture seconds, leave Resume on (reuses already-scanned hosts so a restart isn't a full rescan), and run.
  3. 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).

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.

  1. 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.
  2. Scan tab → Target. Enter http://192.168.60.112. Profile = Web, Engine = Both.
  3. 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
  4. (Optional) paste your NVD key so findings get live CVE/CVSS enrichment.
  5. 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.
  6. Findings tab. It fills with the authenticated bugs — SQL injection, reflected/stored XSS, command injection, LFI, file upload, CSRF. Filter by severity to triage.
  7. 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).

  1. Launch with root (raw sockets for the sniff + OS detection): 
    sudo env "PATH=$PATH" hawkeye
  2. 🛰 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).
  3. 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).
  4. Run. Stages tick through: preflight → learn (passive sniff) → deep-scan → vuln-map → report.
  5. 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".
  6. 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.

  1. 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
  2. Scan tab → Target = the app under test, e.g. http://192.168.60.112:3000 (Juice Shop).
  3. 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)
  4. Run. HawkEye starts the listener and injects callback URLs into its probes.
  5. 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.