HeaderPulse-CLI (headerpulse)

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.

[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:

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

# Or using standard pip
pip install headerpulse

Option B: Local Virtual Environment from Source

# 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:

# 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

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

# 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):

{
  "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:

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

---

📊 Telemetry Output Schema

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

{
  "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

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