Metadata-Version: 2.4
Name: headerpulse
Version: 0.1.0
Summary: An Asynchronous HTTP Security Header, Cookie & CORS Auditor
Author: Dhruv Rathod
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 :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp==3.11.11
Requires-Dist: colorama==0.4.6
Requires-Dist: python-dotenv==1.0.1
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# HeaderPulse-CLI (headerpulse)

[![PyPI Version](https://img.shields.io/pypi/v/headerpulse.svg)](https://pypi.org/project/headerpulse/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Layer 7 Concurrency](https://img.shields.io/badge/concurrency-asyncio%20%7C%20aiohttp-brightgreen.svg)](https://docs.python.org/3/library/asyncio.html)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey.svg)](https://github.com/dhruvrathod68/HeaderPulse-CLI)

**HeaderPulse-CLI** is a high-speed, non-blocking HTTP security posture auditor engineered in Python. It evaluates web applications and APIs against OWASP security header benchmarks, audits sensitive session cookie flags, tests for active CORS origin reflection vulnerabilities, and calculates an automated security posture score without thread-pool overhead.

---

## 🎯 Primary Use Cases

* **DevSecOps & CI/CD Release Gates:** Execute sub-second security baseline checks in deployment pipelines to fail builds that introduce missing headers or unhardened cookies.
* **External Perimeter Auditing:** Rapidly audit public domains and API gateways for missing browser-side protection boundaries during external penetration tests.
* **CORS Misconfiguration Hunting:** Actively probe backend endpoints with untrusted origins to uncover credentialed cross-origin data exposure vulnerabilities.
* **Compliance & Hardening Verification:** Verify transport security and session isolation against PCI-DSS 4.0, SOC 2, and ISO 27001 mandates.

---

## 🏛️ Architectural Overview

Traditional dynamic web vulnerability scanners crawl entire applications and execute heavy parameter fuzzing, requiring minutes or hours to complete. **HeaderPulse-CLI** operates as a targeted, passive-active baseline prober that resolves transport security, session attributes, and cross-domain controls in under 500 milliseconds.

```text
[CLI Entrypoint: headerpulse <target>]
               │
               ▼
   [Baseline Config Resolver]  <── (Embedded Defaults or Custom JSON)
               │
               ▼
  [Async Event Loop Initiated]
               │
 ┌─────────────┴─────────────┐
 ▼                           ▼
[Security Headers Audit]    [Active CORS Probing Engine]
 * HSTS, CSP, XFO, etc.      * Origin Reflection Probes
 * Case-Insensitive Parsing  * ACAO / ACAC Analysis
 └─────────────┬─────────────┘
               │
               ▼
   [Session Cookie Inspector]
    * HttpOnly, Secure, SameSite
               │
               ▼
  [Security Grading Engine]
    * 100-Point Algorithmic Scoring (A+ to F)
               │
        ┌──────┴──────┐
        ▼             ▼
[Colorama ANSI UI] [Structured JSON Telemetry]

```

### Key Technical Advantages

* **Single-Threaded Asynchronous I/O:** Uses Python's `asyncio` event loop and `aiohttp.ClientSession` connection pooling to evaluate targets with sub-millisecond overhead.
* **Embedded Configuration Resilience:** Ships with built-in OWASP baseline headers directly in memory, ensuring CLI commands execute reliably even when external configuration files are separated.
* **Active CORS Probing:** Actively injects untrusted origin request headers to identify dangerous backend reflection paired with `Access-Control-Allow-Credentials: true`.
* **Algorithmic Security Grading:** Converts granular vulnerability findings into standardized numerical scores (0–100) and letter grades (`A+` through `F`).

---

## 🚀 Installation & Setup

### Option A: Global System Installation via PyPI (Recommended)

Install `headerpulse` directly into an isolated global environment:

```bash
# Using pipx (Recommended for standalone CLI tools)
pipx install headerpulse

# Or using standard pip
pip install headerpulse

```

### Option B: Local Virtual Environment from Source

```bash
# 1. Clone the repository
git clone https://github.com/dhruvrathod68/HeaderPulse-CLI.git
cd HeaderPulse-CLI

# 2. Create and activate a virtual environment
# On Linux / macOS / Kali:
python3 -m venv venv
source venv/bin/activate

# On Windows PowerShell:
python -m venv venv
.\venv\Scripts\Activate.ps1

# 3. Install in editable mode
pip install -e .

```

---

## 🔄 Updating HeaderPulse-CLI

To update your globally installed version to the latest release:

```bash
# If installed via pipx
pipx upgrade headerpulse

# If installed via pip
pip install --upgrade headerpulse

# If cloned from Git source
git pull origin main
pip install -e .

```

---

## 💻 Usage & Command Reference

```text
usage: headerpulse [-h] [-t TARGET_FLAG] [-o OUTPUT_FILE] [-c CONFIG_FILE]
                   [--timeout TIMEOUT] [--cors-origin CORS_ORIGIN]
                   [--no-cors]
                   [target]

positional arguments:
  target                Target URL or hostname to audit (e.g., https://example.com).

options:
  -h, --help            Show this help message and exit.
  -t, --target          Target URL or hostname (flag format).
  -o, --output          File path to export structured JSON telemetry report.
  -c, --config          Custom file path to headers baseline JSON configuration.
  --timeout             HTTP request connection/read timeout in seconds (default: 5.0).
  --cors-origin         Origin header to test dynamic CORS reflection (default: https://evil-attacker.com).
  --no-cors             Skip active CORS probing.

```

### Example Commands

```bash
# 1. Basic Security Header & Cookie Audit
headerpulse https://example.com

# 2. Bare Hostname Audit with Custom CORS Origin and JSON Export
headerpulse api.example.com --cors-origin https://attacker.com -o audit_report.json

# 3. Audit Without CORS Probing with Fast Timeout
headerpulse https://example.com --no-cors --timeout 2.5

```

---

## 🛠️ Customizing & Extending Header Benchmarks

You can supply a custom JSON configuration file without modifying any Python code. By default, `HeaderPulse-CLI` audits against standard OWASP baseline headers.

### Adding Custom Header Benchmarks

Create a JSON file (e.g., `custom_headers.json`):

```json
{
  "security_headers": [
    {
      "name": "Strict-Transport-Security",
      "severity": "HIGH",
      "required": true,
      "recommended": "max-age=31536000; includeSubDomains",
      "description": "Enforces TLS encryption and blocks SSL-stripping MITM attacks."
    },
    {
      "name": "X-Custom-Defense-Header",
      "severity": "MEDIUM",
      "required": false,
      "recommended": "enforced",
      "description": "Custom enterprise edge gateway protection directive."
    }
  ]
}

```

Run your audit with the custom baseline:

```bash
headerpulse https://example.com -c custom_headers.json

```

---

## 📊 Telemetry Output Schema

When `-o` or `--output` is supplied, `HeaderPulse-CLI` exports a structured JSON report:

```json
{
  "target": "https://example.com",
  "effective_url": "https://example.com/",
  "status_code": 200,
  "timestamp_utc": "2026-09-03T14:55:10.123456+00:00",
  "duration_ms": 112.45,
  "grade": "B",
  "numerical_score": 80,
  "summary": {
    "total_headers": 7,
    "passed": 5,
    "warnings": 2,
    "failed": 0,
    "cookies_flagged": 1,
    "cors_vulnerable": false
  },
  "headers": [
    {
      "name": "Strict-Transport-Security",
      "severity": "HIGH",
      "status": "PASS",
      "value": "max-age=31536000; includeSubDomains",
      "recommendation": "Hardened HSTS configured."
    },
    {
      "name": "Content-Security-Policy",
      "severity": "HIGH",
      "status": "WARN",
      "value": "script-src 'self' 'unsafe-inline'",
      "recommendation": "CSP permissive: contains 'unsafe-inline'."
    }
  ],
  "cookies": [
    {
      "name": "session_id",
      "http_only": true,
      "secure": true,
      "same_site": "Lax",
      "status": "PASS",
      "risk": "Hardened flags set"
    }
  ],
  "cors": {
    "tested": true,
    "probe_origin": "https://evil-attacker.com",
    "acao": null,
    "acac": null,
    "status": "PASS",
    "risk_level": "NONE",
    "description": "No Access-Control-Allow-Origin header returned for probe origin."
  }
}

```

### Telemetry Field Definitions

| Field | Type | Description |
| --- | --- | --- |
| `target` | `string` | Initial target URL or hostname audited. |
| `effective_url` | `string` | Final destination URL after resolving redirects. |
| `status_code` | `integer` | HTTP response code returned by the endpoint. |
| `timestamp_utc` | `string (ISO-8601)` | Audit execution start timestamp in UTC. |
| `duration_ms` | `float` | Cumulative network round-trip latency in milliseconds. |
| `grade` | `string` | Overall security posture grade (`A+`, `A`, `B`, `C`, `D`, `F`). |
| `numerical_score` | `integer` | Calculated posture score out of 100. |
| `summary` | `object` | Aggregate counts (`passed`, `warnings`, `failed`, `cookies_flagged`, `cors_vulnerable`). |
| `headers` | `array of objects` | Itemized audit findings per security header. |
| `cookies` | `array of objects` | Session cookie attribute findings (`HttpOnly`, `Secure`, `SameSite`). |
| `cors` | `object` | Active CORS origin reflection probing results and risk classifications. |

---

## 📂 Project Directory Structure

```text
HeaderPulse-CLI/
├── config/
│   └── headers.json        # OWASP Security Header Benchmarks
├── venv/                   # Python Virtual Environment (git-ignored)
├── .gitignore              # Repository Exclusion Rules
├── LICENSE                 # MIT License (2026 Dhruv Rathod)
├── MANIFEST.in             # Source Distribution Packaging Manifest
├── main.py                 # Core Asynchronous Engine & CLI Entrypoint
├── requirements.txt        # Pinned Dependencies Manifest
├── setup.py                # Setuptools Packaging Manifest & Console Scripts
└── README.md               # Enterprise Documentation Module

```

---

## 🗺️ Roadmap & Upcoming Features

* **TLS/SSL Cipher Suite Auditing:** Extract TLS handshake version, negotiated cipher suites, and certificate lifespan.
* **Cache Header Vulnerability Checks:** Deep inspection of `Cache-Control` and `Pragma` directives on authenticated routes.
* **SARIF & HTML Export:** Native export into Static Analysis Results Interchange Format (SARIF) for GitHub Security tab integration.
* **Bulk URL Scanning:** Support scanning target lists from text files or stdin with configurable concurrency workers.

---

## 🤝 Contributing & Issue Reporting

Contributions, issues, and security header rule updates are welcome.

### Submitting Pull Requests

1. Fork the repository.
2. Create a feature branch (`git checkout -b feature/AddSecurityRule`).
3. Commit changes with clear descriptions (`git commit -m 'feat: add Cross-Origin-Opener-Policy check'`).
4. Push to the branch (`git push origin feature/AddSecurityRule`).
5. Open a Pull Request.

---

## ⚖️ License & Attribution

Distributed under the MIT License. See `LICENSE` for full details.

**Author:** Dhruv Rathod

**Year:** 2026
