headerhawk-auditor 0.1.0__py3-none-any.whl

headerhawk/__init__.py

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

headerhawk/__main__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+headerhawk/__init__.py,sha256=elk9rcK-Ld4KFpBofaPFBEPFOsAXQzlxrfEBf2rlRUI,86
+headerhawk/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+headerhawk/audit.py,sha256=kPx2rNnQkVimPFkyKr--K2F4YAmDv6TGVbGHSTT-lXY,3652
+headerhawk/cli.py,sha256=vpAOARUimaf1MBGHocGGTK25tWMA4AftqBPp5lVlktg,5193
+headerhawk_auditor-0.1.0.dist-info/METADATA,sha256=oBBo-1sDGP3MAmywOC2KdWWW7ufJmxG87eEHNZRv_NA,3233
+headerhawk_auditor-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+headerhawk_auditor-0.1.0.dist-info/entry_points.txt,sha256=hacrXIQ5aQlsZnypTym-uqh_TKyGtleFk_Dz9lMa4wg,51
+headerhawk_auditor-0.1.0.dist-info/licenses/LICENSE,sha256=WMqIJXD3rBuirXChYblF7ipgFsKgYZR2DdUpEV-agjk,1527
+headerhawk_auditor-0.1.0.dist-info/RECORD,,

headerhawk_auditor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

headerhawk_auditor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+headerhawk = headerhawk.cli:main

headerhawk_auditor-0.1.0.dist-info/licenses/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.