HeadSeeker

A cyberpunk-styled, interactive TUI for scanning HTTP security headers straight from your terminal.

What it does

HeadSeeker performs a single HTTP GET against a target URL, inspects the response headers, and grades the site's security posture from A+ to F based on the presence and correctness of the most impactful security headers.

It then drops you into an interactive dashboard where you can navigate the missing headers with your arrow keys and read, for each one:

a plain-English description of the vulnerability,
the risk level (High / Medium / Low),
copy-paste remediation snippets for Nginx and Apache.

The whole report can be exported to JSON with a single keypress.

Headers checked

Header	Weight	Risk
`Content-Security-Policy`	25	High
`Strict-Transport-Security`	20	High
`Permissions-Policy`	15	Medium
`X-Frame-Options`	10	Medium
`X-Content-Type-Options`	10	Medium
`Referrer-Policy`	10	Low

The final score is a weighted percentage mapped to a letter grade:

Score	Grade
95-100	A+
90-94	A
80-89	B
70-79	C
60-69	D
40-59	E
0-39	F

Screens

Banner screen - neon-green ASCII art + URL prompt.
Loading state - animated spinner while the HTTP request is in flight.
Dashboard - grade panel, headers table, contextual recommendation panel.
Export - JSON dump of the full scan.

Controls

Key	Action
`Up` / `Down` (or `k` / `j`)	Navigate the header list
`S`	Export the report to `headseeker-report.json`
`Q` or `Ctrl+C`	Quit

Installation

git clone https://github.com/<your-user>/HeadSeaker.git
cd HeadSeaker
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

Usage

One-click launcher (Windows)

Just double-click start.bat (or run it from a terminal). It will:

detect whether a local .venv exists;
if not, ask Y/N whether to create one — Y builds the venv and installs requirements.txt into it;
if you answer N, it verifies the dependencies on the system Python and offers to install them globally if any are missing;
once everything is ready, it launches headseeker.py.

start.bat

Manual run

python headseeker.py

You'll be prompted for a target URL (e.g. https://example.com). The https:// prefix is added automatically if omitted. After the scan completes you land in the interactive dashboard.

Non-interactive scan (scripting)

HeadSeeker is also importable as a library:

from headseeker import scan_url, export_report

report = scan_url("https://example.com")
print(report.grade, report.score)
export_report(report, "report.json")

Exported JSON format

headseeker-report.json contains the full scan:

{
  "url": "https://example.com",
  "scanned_at": "2026-09-04T12:00:00+00:00",
  "status_code": 200,
  "score": 35,
  "grade": "E",
  "headers": [
    {
      "name": "Content-Security-Policy",
      "present": false,
      "value": null,
      "weight": 25,
      "risk": "High",
      "summary": "...",
      "missing": "...",
      "nginx": "add_header Content-Security-Policy ...",
      "apache": "Header always set Content-Security-Policy ..."
    }
  ]
}

Design

Palette: neon green #39FF14, cyan #00E5FF, red #FF3B3B, orange #FF8C00 - a clean cyberpunk / hacker aesthetic.
Rendering: rich Live panels with a full-screen layout.
Input: readchar for raw, cross-platform single-keypress navigation.

Project layout

HeadSeaker/
├── headseeker.py       # single-file TUI application
├── start.bat           # Windows one-click launcher (venv + deps + run)
├── requirements.txt
└── README.md

Disclaimer

HeadSeeker only performs a single, passive GET request against a target you control or are authorised to test. It does not perform any active exploitation, fuzzing, or intrusive scanning. Always obtain permission before scanning third-party hosts.

License

MIT - see LICENSE for details.