HeaderHawk

A small, read-only HTTP security-header and cookie configuration auditor, designed as a portfolio-ready Python package.

HeaderHawk checks response configuration. It is not a penetration test, does not prove exploitability, and its score is not a security certification.

Install

python -m pip install -e '.[dev]'

Once published to PyPI, install using pip install headerhawk-auditor (subject to package name availability).

Usage

headerhawk scan https://example.com
headerhawk scan https://example.com --format json --output report.json
headerhawk scan https://example.com --format html --output report.html
python -m headerhawk scan https://example.com

Checks: HTTPS, HSTS, Content-Security-Policy, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, framing protection, Cache-Control presence, and Secure/HttpOnly/SameSite cookie attributes. Header checks are intentionally conservative: for example, a CSP being present does not mean it is effective. Cookies may legitimately need different flags based on application purpose. Cache-Control is informational.

Reports do not include cookie values or redirect destinations. When a response is a redirect, HeaderHawk records only that a Location header was present.

No redirects are followed; HTTP redirects must be audited by explicitly scanning the destination URL. No response body is downloaded beyond response headers. Private and loopback destinations are blocked unless --allow-private is provided. The DNS check is a best-effort guard, not a complete defense against DNS rebinding; do not run this tool as a privileged or public-facing URL-fetching service.

Only audit websites you own or have permission to assess.

Development

python -m pip install -e '.[dev]'
pytest -q
ruff check .
python -m build

Publishing

1. Choose a unique PyPI distribution name and update pyproject.toml.
2. Create a GitHub repository and configure PyPI Trusted Publishing for the repository's publish.yml workflow and pypi environment.
3. Tag a release such as v0.1.0, then run the publish workflow after verifying the build.
4. Never put API tokens or credentials in repository files.

Limitations

This MVP audits one response at a time. It does not crawl, brute-force, exploit, verify TLS certificate chains independently, or evaluate the semantics of every header directive. Findings are heuristic and can contain false positives or negatives.

License

Copyright © 2026 Noir Stack LLC. Licensed under the Proprietary Software License — Free Use, No Modification.