Metadata-Version: 2.5
Name: headerhawk-auditor
Version: 0.1.0
Summary: A lightweight, read-only HTTP security header and cookie auditor
Author: Noir Stack LLC
License: Proprietary Software License — Free Use, No Modification
License-File: LICENSE
Keywords: audit,cli,headers,http,security
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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

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

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

## Usage

```bash
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

```bash
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](LICENSE).
