Metadata-Version: 2.4
Name: header-analyzer
Version: 1.0.0
Summary: A CLI tool for analyzing HTTP security headers
Author: negoro26
License: MIT
Project-URL: Homepage, https://github.com/negoro26/Header-analyzer
Project-URL: Repository, https://github.com/negoro26/Header-analyzer.git
Project-URL: Issues, https://github.com/negoro26/Header-analyzer/issues
Keywords: security,http,headers,infosec,cli,hsts
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# Header-analyzer

A Python CLI tool for analyzing HTTP security headers. Scans target URLs, evaluates security posture, and provides a letter grade with detailed breakdown.

## Features

- **Security Header Analysis** – Checks for HSTS, CSP, X-Frame-Options, X-Content-Type-Options, and more
- **Security Grading** – Letter grade (A+ to F) based on header configuration
- **HSTS Preload Detection** – Sites on browser preload lists get automatic A+ rating
- **Sensitive Header Detection** – Flags headers that may leak server/stack details
- **Flexible Requests** – Custom headers, User-Agent override, timeout, and SSL bypass options

## Installation

### Via pip (recommended)

```bash
pip install git+https://github.com/negoro26/Header-analyzer.git
```

This installs the `header-analyzer` command globally (or in your active virtual environment).

### Development install (editable)

```bash
git clone https://github.com/negoro26/Header-analyzer.git
cd Header-analyzer

# Windows
py -3 -m venv .venv && .\.venv\Scripts\Activate.ps1

# macOS/Linux
python3 -m venv .venv && source .venv/bin/activate

pip install -e .
```

## Usage

```bash
header-analyzer <url> [options]
```

### Options

| Flag | Description |
|------|-------------|
| `-k, --insecure` | Skip SSL certificate verification |
| `--timeout <int>` | Request timeout in seconds (default: 10) |
| `--user-agent <string>` | Override User-Agent header |
| `-H, --header "Key: Value"` | Add custom request header (repeatable) |
| `--no-default-headers` | Start with empty header set |
| `--json` | Output headers as prettified JSON |

### Examples

```bash
# Basic scan
header-analyzer example.com

# Skip SSL verification with shorter timeout
header-analyzer https://example.com -k --timeout 5

# Custom headers
header-analyzer https://example.com --user-agent "MyScanner/1.0" \
  -H "Accept-Language: en-US"
```

## Grading System

Sites are graded based on security header presence and configuration:

| Grade | Score | Description |
|-------|-------|-------------|
| A+ | — | Browser Trusted (HSTS preloaded) |
| A+ | 90%+ | Excellent |
| A | 75%+ | Very Good |
| B | 60%+ | Good |
| C | 45%+ | Acceptable |
| D | 30%+ | Poor |
| F | <30% | Critical |

### Scoring Breakdown

- **HTTPS Baseline**: +25 pts
- **Strict-Transport-Security**: +25 pts
- **Content-Security-Policy**: +20 pts
- **X-Content-Type-Options**: +10 pts
- **X-Frame-Options**: +10 pts
- **Referrer-Policy**: +5 pts
- **Permissions-Policy**: +5 pts
- **Sensitive headers exposed**: -2 pts each (max -10)

Sites in the [HSTS Preload List](https://hstspreload.org/) receive automatic A+ since browsers enforce HTTPS at the protocol level.

## Sample Output

```
[+] Target: https://twitter.com
[+] Status Code: 200

============================================================
[+] SECURITY GRADE
============================================================

  Grade: A+ (Browser Trusted)

  ★ This site is in the HSTS Preload List (twitter.com)
  ★ HSTS is built into all major browsers (Chrome, Firefox, Safari, Edge)
  ★ Browsers will ALWAYS use HTTPS for this site, even on first visit
  ★ Header analysis is not needed - browser-level trust is the gold standard
```

## Requirements

- Python 3.8+
- `requests>=2.28.0` (listed in `requirements.txt` and `pyproject.toml`)

## License

MIT
