headerhawk-auditor 0.1.0__tar.gz

headerhawk_auditor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e '.[dev]'
+      - run: pytest -q
+      - run: ruff check .
+      - run: python -m build

headerhawk_auditor-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install release tools
+        run: python -m pip install --upgrade build twine
+      - name: Confirm the tag matches the package version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          if os.environ["RELEASE_TAG"] != f"v{version}":
+              raise SystemExit("Release tag does not match the package version.")
+          PY
+      - name: Build distributions
+        run: python -m build
+      - name: Validate distributions
+        run: twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

headerhawk_auditor-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/

headerhawk_auditor-0.1.0/LICENSE

@@ -0,0 +1,38 @@
+Proprietary Software License — Free Use, No Modification
+
+Copyright (c) 2026 Noir Stack LLC. All rights reserved.
+
+## 1. Grant of License
+
+The copyright holder grants users a non-exclusive, worldwide, royalty-free license to download, install, and use this software for personal, educational, research, and commercial purposes, subject to the conditions below.
+
+## 2. Restrictions
+
+Users may not, without prior written permission from the copyright holder:
+
+- Modify, adapt, translate, or create derivative works based on the software.
+- Redistribute, publish, sell, sublicense, or repackage the software.
+- Remove or alter copyright, attribution, or license notices.
+- Claim ownership or authorship of the software.
+
+## 3. Ownership
+
+All rights, title, and interest in the software, including its source code and associated intellectual property, remain with the copyright holder.
+
+No ownership rights are transferred under this license.
+
+## 4. No Warranty
+
+The software is provided "AS IS", without warranty of any kind, express or implied, to the extent permitted by applicable law.
+
+## 5. Limitation of Liability
+
+To the extent permitted by applicable law, the copyright holder shall not be liable for damages arising from the use or inability to use the software.
+
+## 6. Termination
+
+Permission to use the software terminates upon a material violation of this license, subject to applicable law.
+
+## 7. Additional Permissions
+
+Any permissions not expressly granted must be obtained in writing from the copyright holder.

headerhawk_auditor-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+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).

headerhawk_auditor-0.1.0/README.md

@@ -0,0 +1,55 @@
+# 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).

headerhawk_auditor-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "headerhawk-auditor"
+version = "0.1.0"
+description = "A lightweight, read-only HTTP security header and cookie auditor"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary Software License — Free Use, No Modification" }
+authors = [{name = "Noir Stack LLC"}]
+keywords = ["security", "headers", "audit", "cli", "http"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Security"]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2", "ruff>=0.6"]
+
+[project.scripts]
+headerhawk = "headerhawk.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/headerhawk"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

headerhawk_auditor-0.1.0/src/headerhawk/__init__.py

@@ -0,0 +1,2 @@
+"""HeaderHawk: read-only HTTP security configuration checks."""
+__version__ = "0.1.0"

headerhawk_auditor-0.1.0/src/headerhawk/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

headerhawk_auditor-0.1.0/src/headerhawk/audit.py

@@ -0,0 +1,56 @@
+"""Pure response analysis; no networking in this module."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Finding:
+    id: str
+    severity: str
+    title: str
+    recommendation: str
+    passed: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def audit_response(url: str, headers: dict[str, str], cookies: list[str] | None = None) -> dict[str, Any]:
+    h = {k.lower(): v for k, v in headers.items()}
+    findings: list[Finding] = []
+
+    def check(id: str, severity: str, title: str, ok: bool, recommendation: str) -> None:
+        findings.append(Finding(id, severity, title, recommendation, ok))
+
+    https = url.lower().startswith("https://")
+    check("https", "high", "HTTPS in use", https, "Serve the site over HTTPS.")
+    check("hsts", "medium", "HTTP Strict Transport Security", not https or bool(h.get("strict-transport-security")), "Set Strict-Transport-Security on HTTPS responses after validating rollout readiness.")
+    check("csp", "medium", "Content Security Policy", bool(h.get("content-security-policy")), "Deploy a restrictive Content-Security-Policy appropriate for the application.")
+    check("nosniff", "medium", "MIME sniffing protection", h.get("x-content-type-options", "").lower().strip() == "nosniff", "Set X-Content-Type-Options: nosniff.")
+    check("referrer", "low", "Referrer policy", bool(h.get("referrer-policy")), "Set a privacy-conscious Referrer-Policy such as strict-origin-when-cross-origin.")
+    check("permissions", "low", "Permissions policy", bool(h.get("permissions-policy")), "Define Permissions-Policy to limit unused browser features.")
+    check("frame", "medium", "Framing protection", bool(h.get("x-frame-options")) or "frame-ancestors" in h.get("content-security-policy", "").lower(), "Use CSP frame-ancestors (or X-Frame-Options for older browsers).")
+    check("cache", "info", "Cache-control header", bool(h.get("cache-control")), "Review Cache-Control based on whether the response contains sensitive data.")
+
+    for i, raw in enumerate(cookies or [], start=1):
+        # Cookie values are never included in findings or reports.
+        # Attribute matching is case-insensitive and works with nonstandard cookie values.
+        attributes = raw.split(";", 1)[1].lower() if ";" in raw else ""
+        parts = [part.strip() for part in attributes.split(";")]
+        has_secure = any(part == "secure" for part in parts)
+        has_httponly = any(part == "httponly" for part in parts)
+        has_samesite = any(part.startswith("samesite=") for part in parts)
+        prefix = f"cookie-{i}"
+        check(f"{prefix}-secure", "medium", f"Cookie {i}: Secure flag", has_secure, "Set Secure for cookies sent over HTTPS.")
+        check(f"{prefix}-httponly", "medium", f"Cookie {i}: HttpOnly flag", has_httponly, "Set HttpOnly for cookies not needed by JavaScript.")
+        check(f"{prefix}-samesite", "low", f"Cookie {i}: SameSite attribute", has_samesite, "Set SameSite=Lax or Strict where appropriate.")
+
+    # Score is a configuration heuristic, not a security guarantee.
+    weighted = {"high": 15, "medium": 10, "low": 5, "info": 0}
+    scored = [f for f in findings if weighted[f.severity] > 0 and not (f.id == "hsts" and not https)]
+    possible = sum(weighted[f.severity] for f in scored)
+    earned = sum(weighted[f.severity] for f in scored if f.passed)
+    score = round(100 * earned / possible) if possible else 100
+    return {"url": url, "score": score, "passed": sum(f.passed for f in findings), "total": len(findings), "findings": [f.to_dict() for f in findings]}

headerhawk_auditor-0.1.0/src/headerhawk/cli.py

@@ -0,0 +1,105 @@
+"""Command line entrypoint for HeaderHawk."""
+from __future__ import annotations
+
+import argparse
+import html
+import ipaddress
+import json
+import socket
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import httpx
+
+from . import __version__
+from .audit import audit_response
+
+
+def validate_url(url: str, allow_private: bool = False) -> None:
+    parts = urlsplit(url)
+    if parts.scheme not in {"http", "https"} or not parts.hostname or parts.username or parts.password:
+        raise ValueError("Supply an http(s) URL without embedded credentials.")
+    if not allow_private:
+        try:
+            addresses = socket.getaddrinfo(parts.hostname, parts.port or (443 if parts.scheme == "https" else 80), type=socket.SOCK_STREAM)
+        except socket.gaierror as exc:
+            raise ValueError(f"DNS resolution failed: {exc}") from exc
+        if not addresses or any(not ipaddress.ip_address(entry[4][0]).is_global for entry in addresses):
+            raise ValueError("Private, loopback, link-local, and non-global destinations are blocked by default. Use --allow-private for trusted local targets.")
+
+
+def fetch(url: str, timeout: float, allow_private: bool) -> dict:
+    validate_url(url, allow_private)
+    # No redirects: prevents silently following to an unexpected destination.
+    # No proxy environment variables: avoids unexpected routing.
+    with httpx.Client(
+        timeout=timeout,
+        follow_redirects=False,
+        trust_env=False,
+        headers={"User-Agent": f"HeaderHawk/{__version__}"},
+    ) as client, client.stream("GET", url) as response:
+        headers = dict(response.headers)
+        cookies = response.headers.get_list("set-cookie")
+        result = audit_response(str(response.url), headers, cookies)
+        result["status_code"] = response.status_code
+        result["redirect_location_present"] = "location" in response.headers
+        return result
+
+
+def render_html(result: dict) -> str:
+    rows = "\n".join(
+        f"<tr><td>{html.escape(item['title'])}</td><td>{html.escape(item['severity'])}</td><td>{'PASS' if item['passed'] else 'REVIEW'}</td><td>{html.escape(item['recommendation'])}</td></tr>"
+        for item in result["findings"]
+    )
+    return ("<!doctype html><html lang='en'><head><meta charset='utf-8'><title>HeaderHawk report</title>"
+            "<style>body{font:16px system-ui;max-width:1100px;margin:3rem auto;padding:0 1rem;color:#17212d}table{border-collapse:collapse;width:100%}td,th{border:1px solid #ccc;padding:.6rem;text-align:left}tr:nth-child(even){background:#f4f6f8}</style></head><body>"
+            f"<h1>HeaderHawk report</h1><p>URL: {html.escape(result['url'])}</p><p>Configuration score: {result['score']}/100</p>"
+            f"<p>HTTP status: {result.get('status_code', 'N/A')}</p><table><thead><tr><th>Check</th><th>Severity</th><th>Result</th><th>Recommendation</th></tr></thead><tbody>{rows}</tbody></table>"
+            "<p>Heuristic checks only; a passing score does not establish application security.</p></body></html>")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="headerhawk", description="Read-only HTTP security header and cookie auditor")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    scan = sub.add_parser("scan", help="Audit one HTTP(S) URL")
+    scan.add_argument("url")
+    scan.add_argument("--format", choices=["text", "json", "html"], default="text")
+    scan.add_argument("--output", type=Path, help="Write report to a file")
+    scan.add_argument("--timeout", type=float, default=10.0)
+    scan.add_argument("--allow-private", action="store_true", help="Permit localhost and private network targets")
+    args = parser.parse_args(argv)
+    if args.timeout <= 0 or args.timeout > 60:
+        parser.error("--timeout must be greater than 0 and at most 60")
+    try:
+        result = fetch(args.url, args.timeout, args.allow_private)
+    except (ValueError, httpx.HTTPError, OSError) as exc:
+        print(f"headerhawk: {exc}", file=sys.stderr)
+        return 2
+    if args.format == "json":
+        content = json.dumps(result, indent=2)
+    elif args.format == "html":
+        content = render_html(result)
+    else:
+        lines = [f"HeaderHawk | {result['url']}", f"HTTP {result['status_code']} | Configuration score: {result['score']}/100"]
+        for item in result["findings"]:
+            lines.append(f"[{'PASS' if item['passed'] else 'REVIEW'}] {item['title']} ({item['severity']})")
+            if not item["passed"]:
+                lines.append(f"  {item['recommendation']}")
+        lines.append("Note: configuration heuristic only; not a vulnerability assessment.")
+        content = "\n".join(lines)
+    if args.output:
+        try:
+            args.output.write_text(content + "\n", encoding="utf-8")
+        except OSError as exc:
+            print(f"headerhawk: cannot write report: {exc}", file=sys.stderr)
+            return 2
+        print(f"Report saved to {args.output}")
+    else:
+        print(content)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

headerhawk_auditor-0.1.0/tests/test_audit.py

@@ -0,0 +1,56 @@
+import httpx
+import pytest
+
+from headerhawk import cli
+from headerhawk.audit import audit_response
+from headerhawk.cli import render_html, validate_url
+
+
+def test_missing_headers_reduce_score():
+    result = audit_response("https://example.com", {})
+    assert result["score"] < 50
+    assert any(f["id"] == "hsts" and not f["passed"] for f in result["findings"])
+
+
+def test_good_headers():
+    headers = {"Strict-Transport-Security": "max-age=31536000", "Content-Security-Policy": "default-src 'self'; frame-ancestors 'none'", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer", "Permissions-Policy": "camera=()"}
+    result = audit_response("https://example.com", headers, ["session=redacted; Secure; HttpOnly; SameSite=Lax"])
+    assert result["score"] == 100
+    assert "redacted" not in str(result)
+
+
+def test_html_escapes_url():
+    result = audit_response("https://example.com/?x=<script>", {})
+    assert "<script>" not in render_html(result)
+
+
+def test_url_rejects_credentials():
+    with pytest.raises(ValueError):
+        validate_url("https://user:pass@example.com")
+
+
+def test_url_rejects_local_by_default():
+    with pytest.raises(ValueError):
+        validate_url("http://127.0.0.1")
+
+
+def test_allow_private():
+    validate_url("http://127.0.0.1", allow_private=True)
+
+
+def test_redirect_location_is_not_reported_verbatim(monkeypatch):
+    secret_location = "https://example.com/next?token=secret"
+    transport = httpx.MockTransport(
+        lambda request: httpx.Response(302, headers={"location": secret_location}, request=request)
+    )
+    real_client = httpx.Client
+
+    def mock_client(*args, **kwargs):
+        kwargs["transport"] = transport
+        return real_client(*args, **kwargs)
+
+    monkeypatch.setattr(cli, "validate_url", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(cli.httpx, "Client", mock_client)
+    result = cli.fetch("https://example.com", timeout=1, allow_private=False)
+    assert result["redirect_location_present"] is True
+    assert secret_location not in str(result)