pentest-header-analyzer 0.1.1
A CLI tool for analyzing HTTP response headers for security misconfigurations.
License: MIT
Requires Python: >=3.8

# Pentest Header Analyzer

A lightweight Python CLI tool to analyze HTTP response headers for security misconfigurations. Supports single target or batch mode, TXT export, and cookie/TLS checks.

> Version: `0.1.1` (draft) — actively developed. Expect improvements and additions in future releases.

## Why `reqres.in` in examples?

`reqres.in` is a public demo API useful for testing and documentation. It returns predictable responses that are safe to use in examples. Using a demo endpoint avoids implying that you are targeting production services.

## Features

* Detects common security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Expect-CT, etc.)
* Prints a concise, colored summary table in the terminal
* Shows raw response headers (truncated for readability) when no `--txt` file is provided
* TXT export (security-focused) containing only security-relevant headers + cookie analysis, PoC, TLS info
* Batch scanning via `--batch`
* Simple scoring system to help triage quickly
* Proof-of-concept hints for missing protections (safe demo strings only)

## Installation

### From PyPI 

```bash
pip install pentest-header-analyzer
```
# From source (development / current)
Clone and install locally in a virtual environment (recommended while developing):

- git clone https://github.com/Root-huntress/pentest_header_analyzer.git
- cd pentest_header_analyzer
- python3 -m venv venv
- source venv/bin/activate
- pip install -r requirements.txt
- pip install -e .

# Notes:
pip install -e . installs the package in editable mode so changes you make to the source are reflected immediately in the pentest-header-analyzer CLI.

On Windows PowerShell replace source venv/bin/activate with .\venv\Scripts\Activate.ps1.

#Usage

**Single URL (default)**
Prints the summary table first, then raw headers (raw headers are shown only when --txt is not used).
> pentest-header-analyzer https://reqres.in/api/users/2

**Save compact TXT (security-focused)**
Save results to a compact file (suppresses raw headers in terminal):
> pentest-header-analyzer https://reqres.in/api/users/2 --txt reqres_report.txt

**Batch scanning (single TXT for all results)**
Scan many URLs from a file (one URL per line) and optionally save results into one file:
> pentest-header-analyzer --batch urls.txt --txt batch_results.txt

**Dev/run without reinstall**
Run from the repo directly without reinstalling:
> python -m pentest_header_analyzer.header_analyzer https://reqres.in/api/users/2

## Example Output (reqres.in — demo)

Run:

pentest-header-analyzer https://reqres.in/api/users/2

This is a demo example. Actual live output may differ.

### Expected terminal output (table first, then raw headers):

HTTP Security Header Report: https://reqres.in/api/users/2 
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Header                       ┃ Status     ┃ Severity    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ Content-Security-Policy      │ Missing ❌ │ Critical    │
│ Strict-Transport-Security    │ Missing ❌ │ Critical    │
│ X-Frame-Options              │ Present ✅ │ Critical    │
│ X-Content-Type-Options       │ Present ✅ │ Critical    │
│ Referrer-Policy              │ Present ✅ │ Recommended │
│ Permissions-Policy           │ Missing ❌ │ Optional    │
│ Expect-CT                    │ Missing ❌ │ Recommended │
│ Server                       │ Present ✅ │ Info        │
│ Cache-Control                │ Missing ❌ │ Recommended │
│ X-XSS-Protection             │ Present ✅ │ Optional    │
│ Cross-Origin-Resource-Policy │ Missing ❌ │ Recommended │
└──────────────────────────────┴────────────┴─────────────┘

Cookie Analysis (raw Set-Cookie headers + parsed cookies) 
No Set-Cookie header seen.

Site Security Score: 4/22 (18%) 
HTTP status code: 401

--- Raw Response Headers --- 
Date: Sat, 27 Sep 2025 01:13:17 GMT 
Content-Type: application/json; charset=utf-8 
Content-Length: 27 
Connection: keep-alive 
Access-Control-Allow-Credentials: true 
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, x-api-key  
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS 
Access-Control-Allow-Origin: http://localhost:5173 
Etag: W/"1b-FQ1mIOMgD7jlZN53VsiSdXzsYTY" 
Nel: {"report_to":"heroku-nel","response_headers":["Via"],"max_age":3600,"success_fraction":0.01,"failure_fraction":0.1}... (truncated) 
Ratelimit-Limit: 100 
Ratelimit-Policy: 100;w=60 
Ratelimit-Remaining: 99 
Ratelimit-Reset: 60 
Referrer-Policy: strict-origin-when-cross-origin 
Report-To: {"group":"heroku-nel","endpoints":[...]}... (truncated) 
Server: cloudflare 
Vary: Origin, accept-encoding 
Via: 1.1 heroku-router 
X-Content-Type-Options: nosniff 
X-Frame-Options: DENY 
X-Request-Id: 162437d5-80d5-eefd-6547-e8a883f32ff4 
X-Xss-Protection: 1; mode=block 
cf-cache-status: BYPASS 
CF-RAY: 98572339ecad63bb-LHR

## Notes & Roadmap

This is a draft release (`0.1.1`). The tool works well for quick reconnaissance and reporting, but new features and polishing are planned:

* `--no-raw` to explicitly suppress inline headers
* `--json` mode for structured exports (future)
* Per-target TXT files or NDJSON for heavy automation
* Additional checks (CORS wildcard detection, redirect-chain aggregation, CSP analysis)
* Unit tests and CI

## Ethics & Safe Testing

Only scan systems you have permission to test. `reqres.in` is a public demo API good for examples and safe testing. When you move to client or engagement targets, ensure you have written authorization.

## Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

## License

MIT — see the LICENSE file.
Copyright (c) 2025 Root-huntress