klyrek-headers 0.1.0__tar.gz

klyrek_headers-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.qodo/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.log
+.idea/
+.vscode/
+!.vscode/extensions.json
+klyrek_output/

klyrek_headers-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: klyrek-headers
+Version: 0.1.0
+Summary: HTTP security header analysis for the Klyrek ecosystem
+Author: Klyrek Contributors
+License: MIT
+Keywords: appsec,http-headers,pentesting,reconnaissance,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: klyrek-core
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# klyrek-headers
+
+HTTP security header analysis. Takes a single `httpx.Response` (as returned by
+`klyrek-http`/`klyrek-crawler`) and produces `klyrek_core.models.Finding` objects for missing or
+misconfigured security controls: HSTS, CSP, clickjacking protection, cookie flags
+(`Secure`/`HttpOnly`/`SameSite`), CORS misconfiguration, and information-disclosure headers
+(`Server`, `X-Powered-By`).
+
+This is the first Klyrek module whose output is a `Finding` rather than just an `Endpoint` —
+everything upstream (`klyrek-crawler`) maps the application; this is where the tool starts
+telling you something is actually wrong.
+
+```python
+from klyrek_headers.analyzer import analyze
+
+response = client.get("https://target.com/")
+findings = analyze(response)
+
+for finding in findings:
+    print(finding.severity, finding.title)
+```
+
+Findings are informational hints for a human reviewer to confirm, not proof of exploitability —
+e.g. a missing `X-Frame-Options` header is flagged even though modern CSP `frame-ancestors` may
+cover it, and a wildcard CORS origin is flagged even when browsers would reject the exact
+combination sent, because both patterns indicate configuration worth a second look.

klyrek_headers-0.1.0/README.md

@@ -0,0 +1,26 @@
+# klyrek-headers
+
+HTTP security header analysis. Takes a single `httpx.Response` (as returned by
+`klyrek-http`/`klyrek-crawler`) and produces `klyrek_core.models.Finding` objects for missing or
+misconfigured security controls: HSTS, CSP, clickjacking protection, cookie flags
+(`Secure`/`HttpOnly`/`SameSite`), CORS misconfiguration, and information-disclosure headers
+(`Server`, `X-Powered-By`).
+
+This is the first Klyrek module whose output is a `Finding` rather than just an `Endpoint` —
+everything upstream (`klyrek-crawler`) maps the application; this is where the tool starts
+telling you something is actually wrong.
+
+```python
+from klyrek_headers.analyzer import analyze
+
+response = client.get("https://target.com/")
+findings = analyze(response)
+
+for finding in findings:
+    print(finding.severity, finding.title)
+```
+
+Findings are informational hints for a human reviewer to confirm, not proof of exploitability —
+e.g. a missing `X-Frame-Options` header is flagged even though modern CSP `frame-ancestors` may
+cover it, and a wildcard CORS origin is flagged even when browsers would reject the exact
+combination sent, because both patterns indicate configuration worth a second look.

klyrek_headers-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "klyrek-headers"
+version = "0.1.0"
+description = "HTTP security header analysis for the Klyrek ecosystem"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Klyrek Contributors" }]
+keywords = ["security", "reconnaissance", "appsec", "pentesting", "http-headers"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+dependencies = [
+    "klyrek-core",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.10"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/klyrek_headers"]

klyrek_headers-0.1.0/src/klyrek_headers/__init__.py

@@ -0,0 +1,8 @@
+"""klyrek-headers: HTTP security header analysis."""
+
+from klyrek_headers.analyzer import analyze
+from klyrek_headers.checks import ALL_CHECKS
+
+__version__ = "0.1.0"
+
+__all__ = ["ALL_CHECKS", "__version__", "analyze"]

klyrek_headers-0.1.0/src/klyrek_headers/analyzer.py

@@ -0,0 +1,25 @@
+"""Run all header checks against a response and collect the resulting Findings."""
+
+from __future__ import annotations
+
+import httpx
+
+from klyrek_core.models import Endpoint, Finding
+from klyrek_headers.checks import ALL_CHECKS
+
+MODULE_NAME = "klyrek-headers"
+
+
+def analyze(response: httpx.Response, endpoint: Endpoint | None = None) -> list[Finding]:
+    """Run every registered header check against a response.
+
+    ``endpoint``, if given, is attached to each resulting Finding so it can be traced
+    back to where it was found in a larger ScanResult.
+    """
+    findings: list[Finding] = []
+    for check in ALL_CHECKS:
+        for finding in check(response):
+            finding.endpoint = endpoint
+            finding.module = MODULE_NAME
+            findings.append(finding)
+    return findings

klyrek_headers-0.1.0/src/klyrek_headers/checks.py

@@ -0,0 +1,258 @@
+"""Individual HTTP security header checks.
+
+Each check takes an ``httpx.Response`` and returns zero or more ``Finding`` objects.
+Checks are intentionally passive (header inspection only) — they flag configuration
+patterns worth a human's attention, not confirmed exploits.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from http.cookies import SimpleCookie
+
+import httpx
+
+from klyrek_core.models import Finding, Severity
+
+_VERSION_PATTERN = re.compile(r"\d+\.\d+")
+_MIN_HSTS_MAX_AGE = 15_552_000  # ~6 months, a common baseline recommendation
+
+HeaderCheck = Callable[[httpx.Response], list[Finding]]
+
+
+def check_hsts(response: httpx.Response) -> list[Finding]:
+    if response.url.scheme != "https":
+        return []
+    value = response.headers.get("strict-transport-security")
+    if value is None:
+        return [
+            Finding(
+                title="Missing Strict-Transport-Security header",
+                severity=Severity.MEDIUM,
+                description="HTTPS response has no HSTS header, so a user's first visit (or one "
+                "over a stripped connection) can be downgraded to plain HTTP.",
+                evidence=["no Strict-Transport-Security header present"],
+            )
+        ]
+    match = re.search(r"max-age=(\d+)", value, re.IGNORECASE)
+    max_age = int(match.group(1)) if match else 0
+    if max_age < _MIN_HSTS_MAX_AGE:
+        return [
+            Finding(
+                title="Weak Strict-Transport-Security max-age",
+                severity=Severity.LOW,
+                description=f"HSTS max-age is {max_age} seconds, below the "
+                f"{_MIN_HSTS_MAX_AGE}-second baseline.",
+                evidence=[f"Strict-Transport-Security: {value}"],
+            )
+        ]
+    return []
+
+
+def check_csp(response: httpx.Response) -> list[Finding]:
+    value = response.headers.get("content-security-policy")
+    if value is None:
+        return [
+            Finding(
+                title="Missing Content-Security-Policy header",
+                severity=Severity.MEDIUM,
+                description="No CSP header, so the browser applies no restriction on script, "
+                "style, or frame sources.",
+                evidence=["no Content-Security-Policy header present"],
+            )
+        ]
+    lowered = value.lower()
+    permissive_tokens = [t for t in ("unsafe-inline", "unsafe-eval", "*") if t in lowered]
+    if permissive_tokens:
+        return [
+            Finding(
+                title="Overly permissive Content-Security-Policy",
+                severity=Severity.LOW,
+                description="CSP contains directives that significantly weaken its protection.",
+                evidence=[f"Content-Security-Policy: {value}"],
+            )
+        ]
+    return []
+
+
+def check_x_content_type_options(response: httpx.Response) -> list[Finding]:
+    value = response.headers.get("x-content-type-options", "")
+    if value.strip().lower() != "nosniff":
+        return [
+            Finding(
+                title="Missing X-Content-Type-Options: nosniff",
+                severity=Severity.LOW,
+                description="Without this header, browsers may MIME-sniff responses, which can "
+                "turn a file upload or reflected response into script execution.",
+                evidence=[f"X-Content-Type-Options: {value}" if value else "header absent"],
+            )
+        ]
+    return []
+
+
+def check_frame_options(response: httpx.Response) -> list[Finding]:
+    if "x-frame-options" in response.headers:
+        return []
+    csp = response.headers.get("content-security-policy", "")
+    if "frame-ancestors" in csp.lower():
+        return []
+    return [
+        Finding(
+            title="Missing clickjacking protection",
+            severity=Severity.MEDIUM,
+            description="No X-Frame-Options header and no CSP frame-ancestors directive, so the "
+            "page can be embedded in a hostile iframe.",
+            evidence=["no X-Frame-Options header, no CSP frame-ancestors directive"],
+        )
+    ]
+
+
+def check_referrer_policy(response: httpx.Response) -> list[Finding]:
+    if "referrer-policy" not in response.headers:
+        return [
+            Finding(
+                title="Missing Referrer-Policy header",
+                severity=Severity.INFO,
+                description="Without this header, the full URL (potentially including sensitive "
+                "query parameters) may leak to third parties via the Referer header.",
+                evidence=["no Referrer-Policy header present"],
+            )
+        ]
+    return []
+
+
+def check_permissions_policy(response: httpx.Response) -> list[Finding]:
+    if "permissions-policy" not in response.headers:
+        return [
+            Finding(
+                title="Missing Permissions-Policy header",
+                severity=Severity.INFO,
+                description="No Permissions-Policy header, so the browser default is used for "
+                "powerful features (camera, geolocation, etc.) instead of an explicit opt-out.",
+                evidence=["no Permissions-Policy header present"],
+            )
+        ]
+    return []
+
+
+def check_information_disclosure(response: httpx.Response) -> list[Finding]:
+    findings: list[Finding] = []
+    server = response.headers.get("server")
+    if server and _VERSION_PATTERN.search(server):
+        findings.append(
+            Finding(
+                title="Server header discloses version information",
+                severity=Severity.INFO,
+                description="The Server header reveals specific software version(s), which helps "
+                "an attacker target known vulnerabilities for that version.",
+                evidence=[f"Server: {server}"],
+            )
+        )
+    powered_by = response.headers.get("x-powered-by")
+    if powered_by:
+        findings.append(
+            Finding(
+                title="X-Powered-By header discloses backend technology",
+                severity=Severity.INFO,
+                description="The X-Powered-By header reveals backend technology unnecessarily.",
+                evidence=[f"X-Powered-By: {powered_by}"],
+            )
+        )
+    return findings
+
+
+def check_cors(response: httpx.Response) -> list[Finding]:
+    origin = response.headers.get("access-control-allow-origin")
+    if origin is None:
+        return []
+    credentials = response.headers.get("access-control-allow-credentials", "").lower() == "true"
+    if origin == "*" and credentials:
+        return [
+            Finding(
+                title="CORS wildcard origin combined with allowed credentials",
+                severity=Severity.HIGH,
+                description="Access-Control-Allow-Origin: * together with "
+                "Access-Control-Allow-Credentials: true is a well-known misconfiguration "
+                "pattern; depending on how the server actually resolves the origin, this can "
+                "let any site make credentialed cross-origin requests.",
+                evidence=[
+                    f"Access-Control-Allow-Origin: {origin}",
+                    "Access-Control-Allow-Credentials: true",
+                ],
+            )
+        ]
+    if origin == "*":
+        return [
+            Finding(
+                title="CORS wildcard origin",
+                severity=Severity.LOW,
+                description="Access-Control-Allow-Origin: * allows any site to read responses "
+                "from this endpoint (without credentials).",
+                evidence=[f"Access-Control-Allow-Origin: {origin}"],
+            )
+        ]
+    return []
+
+
+def check_cookies(response: httpx.Response) -> list[Finding]:
+    findings: list[Finding] = []
+    is_https = response.url.scheme == "https"
+    for raw_cookie in response.headers.get_list("set-cookie"):
+        jar: SimpleCookie = SimpleCookie()
+        jar.load(raw_cookie)
+        for name, morsel in jar.items():
+            if is_https and not morsel["secure"]:
+                findings.append(
+                    Finding(
+                        title=f"Cookie '{name}' missing Secure flag",
+                        severity=Severity.MEDIUM,
+                        description="Cookie can be sent over an unencrypted HTTP connection.",
+                        evidence=[raw_cookie],
+                    )
+                )
+            if not morsel["httponly"]:
+                findings.append(
+                    Finding(
+                        title=f"Cookie '{name}' missing HttpOnly flag",
+                        severity=Severity.MEDIUM,
+                        description="Cookie is readable from JavaScript, so it is exposed to "
+                        "theft via any XSS on the page.",
+                        evidence=[raw_cookie],
+                    )
+                )
+            samesite = morsel["samesite"]
+            if not samesite:
+                findings.append(
+                    Finding(
+                        title=f"Cookie '{name}' missing SameSite attribute",
+                        severity=Severity.LOW,
+                        description="Without SameSite, the cookie is sent on cross-site requests "
+                        "per browser default, which varies and weakens CSRF defenses.",
+                        evidence=[raw_cookie],
+                    )
+                )
+            elif samesite.lower() == "none" and not morsel["secure"]:
+                findings.append(
+                    Finding(
+                        title=f"Cookie '{name}' has SameSite=None without Secure",
+                        severity=Severity.HIGH,
+                        description="SameSite=None requires the Secure attribute; without it, "
+                        "modern browsers reject the cookie or treat it inconsistently.",
+                        evidence=[raw_cookie],
+                    )
+                )
+    return findings
+
+
+ALL_CHECKS: list[HeaderCheck] = [
+    check_hsts,
+    check_csp,
+    check_x_content_type_options,
+    check_frame_options,
+    check_referrer_policy,
+    check_permissions_policy,
+    check_information_disclosure,
+    check_cors,
+    check_cookies,
+]

klyrek_headers-0.1.0/tests/test_analyzer.py

@@ -0,0 +1,45 @@
+import httpx
+
+from klyrek_core.models import Endpoint
+from klyrek_headers.analyzer import analyze
+
+_GOOD_HEADERS = {
+    "Strict-Transport-Security": "max-age=63072000; includeSubDomains",
+    "Content-Security-Policy": "default-src 'self'",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "no-referrer",
+    "Permissions-Policy": "geolocation=()",
+}
+
+
+def _response(url: str, headers: dict[str, str]) -> httpx.Response:
+    return httpx.Response(200, headers=headers, request=httpx.Request("GET", url))
+
+
+def test_well_configured_response_has_no_findings():
+    response = _response("https://target.com/", _GOOD_HEADERS)
+    assert analyze(response) == []
+
+
+def test_bare_response_produces_multiple_findings():
+    response = _response("https://target.com/", {})
+    findings = analyze(response)
+    titles = {f.title for f in findings}
+    assert len(findings) >= 6
+    assert any("Strict-Transport-Security" in t for t in titles)
+    assert any("Content-Security-Policy" in t for t in titles)
+
+
+def test_findings_are_tagged_with_module_and_endpoint():
+    endpoint = Endpoint(url="https://target.com/", method="GET")
+    response = _response("https://target.com/", {})
+    findings = analyze(response, endpoint=endpoint)
+    assert all(f.module == "klyrek-headers" for f in findings)
+    assert all(f.endpoint is endpoint for f in findings)
+
+
+def test_endpoint_defaults_to_none():
+    response = _response("https://target.com/", {})
+    findings = analyze(response)
+    assert all(f.endpoint is None for f in findings)

klyrek_headers-0.1.0/tests/test_checks.py

@@ -0,0 +1,204 @@
+import httpx
+
+from klyrek_headers.checks import (
+    check_cookies,
+    check_cors,
+    check_csp,
+    check_frame_options,
+    check_hsts,
+    check_information_disclosure,
+    check_permissions_policy,
+    check_referrer_policy,
+    check_x_content_type_options,
+)
+
+
+def _response(url: str, headers: dict[str, str] | list[tuple[str, str]]) -> httpx.Response:
+    return httpx.Response(200, headers=headers, request=httpx.Request("GET", url))
+
+
+def test_hsts_missing_on_https_is_flagged():
+    response = _response("https://target.com/", {})
+    findings = check_hsts(response)
+    assert len(findings) == 1
+    assert "Missing" in findings[0].title
+
+
+def test_hsts_not_required_on_plain_http():
+    response = _response("http://target.com/", {})
+    assert check_hsts(response) == []
+
+
+def test_hsts_weak_max_age_is_flagged():
+    response = _response("https://target.com/", {"Strict-Transport-Security": "max-age=60"})
+    findings = check_hsts(response)
+    assert len(findings) == 1
+    assert "Weak" in findings[0].title
+
+
+def test_hsts_strong_max_age_passes():
+    response = _response(
+        "https://target.com/",
+        {"Strict-Transport-Security": "max-age=63072000; includeSubDomains"},
+    )
+    assert check_hsts(response) == []
+
+
+def test_csp_missing_is_flagged():
+    response = _response("https://target.com/", {})
+    findings = check_csp(response)
+    assert len(findings) == 1
+
+
+def test_csp_permissive_directive_is_flagged():
+    response = _response(
+        "https://target.com/", {"Content-Security-Policy": "default-src 'unsafe-inline'"}
+    )
+    findings = check_csp(response)
+    assert len(findings) == 1
+    assert "permissive" in findings[0].title.lower()
+
+
+def test_csp_strict_policy_passes():
+    response = _response("https://target.com/", {"Content-Security-Policy": "default-src 'self'"})
+    assert check_csp(response) == []
+
+
+def test_x_content_type_options_missing():
+    response = _response("https://target.com/", {})
+    assert len(check_x_content_type_options(response)) == 1
+
+
+def test_x_content_type_options_present():
+    response = _response("https://target.com/", {"X-Content-Type-Options": "nosniff"})
+    assert check_x_content_type_options(response) == []
+
+
+def test_frame_options_missing_without_csp():
+    response = _response("https://target.com/", {})
+    assert len(check_frame_options(response)) == 1
+
+
+def test_frame_options_covered_by_csp_frame_ancestors():
+    response = _response(
+        "https://target.com/", {"Content-Security-Policy": "frame-ancestors 'self'"}
+    )
+    assert check_frame_options(response) == []
+
+
+def test_frame_options_header_present():
+    response = _response("https://target.com/", {"X-Frame-Options": "DENY"})
+    assert check_frame_options(response) == []
+
+
+def test_referrer_policy_missing():
+    response = _response("https://target.com/", {})
+    assert len(check_referrer_policy(response)) == 1
+
+
+def test_permissions_policy_missing():
+    response = _response("https://target.com/", {})
+    assert len(check_permissions_policy(response)) == 1
+
+
+def test_server_header_version_disclosure():
+    response = _response("https://target.com/", {"Server": "nginx/1.18.0"})
+    findings = check_information_disclosure(response)
+    assert len(findings) == 1
+    assert "Server" in findings[0].title
+
+
+def test_server_header_without_version_not_flagged():
+    response = _response("https://target.com/", {"Server": "nginx"})
+    assert check_information_disclosure(response) == []
+
+
+def test_x_powered_by_always_flagged():
+    response = _response("https://target.com/", {"X-Powered-By": "Express"})
+    findings = check_information_disclosure(response)
+    assert len(findings) == 1
+    assert "X-Powered-By" in findings[0].title
+
+
+def test_cors_wildcard_alone():
+    response = _response("https://target.com/", {"Access-Control-Allow-Origin": "*"})
+    findings = check_cors(response)
+    assert len(findings) == 1
+    assert findings[0].severity.value == "low"
+
+
+def test_cors_wildcard_with_credentials_is_high_severity():
+    response = _response(
+        "https://target.com/",
+        {
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Credentials": "true",
+        },
+    )
+    findings = check_cors(response)
+    assert len(findings) == 1
+    assert findings[0].severity.value == "high"
+
+
+def test_cors_specific_origin_not_flagged():
+    response = _response(
+        "https://target.com/", {"Access-Control-Allow-Origin": "https://partner.example.com"}
+    )
+    assert check_cors(response) == []
+
+
+def test_cors_header_absent_not_flagged():
+    response = _response("https://target.com/", {})
+    assert check_cors(response) == []
+
+
+def test_cookie_missing_secure_on_https():
+    response = _response(
+        "https://target.com/", [("Set-Cookie", "session=abc123; HttpOnly; SameSite=Strict")]
+    )
+    findings = check_cookies(response)
+    assert any("Secure" in f.title for f in findings)
+
+
+def test_cookie_missing_httponly():
+    response = _response(
+        "https://target.com/", [("Set-Cookie", "session=abc123; Secure; SameSite=Strict")]
+    )
+    findings = check_cookies(response)
+    assert any("HttpOnly" in f.title for f in findings)
+
+
+def test_cookie_missing_samesite():
+    response = _response(
+        "https://target.com/", [("Set-Cookie", "session=abc123; Secure; HttpOnly")]
+    )
+    findings = check_cookies(response)
+    assert any("SameSite" in f.title for f in findings)
+
+
+def test_cookie_samesite_none_without_secure_is_high():
+    response = _response(
+        "https://target.com/", [("Set-Cookie", "session=abc123; HttpOnly; SameSite=None")]
+    )
+    findings = check_cookies(response)
+    high_findings = [f for f in findings if f.severity.value == "high"]
+    assert any("SameSite=None" in f.title for f in high_findings)
+
+
+def test_cookie_with_all_flags_passes():
+    response = _response(
+        "https://target.com/", [("Set-Cookie", "session=abc123; Secure; HttpOnly; SameSite=Strict")]
+    )
+    assert check_cookies(response) == []
+
+
+def test_multiple_cookies_checked_independently():
+    response = _response(
+        "https://target.com/",
+        [
+            ("Set-Cookie", "session=abc; Secure; HttpOnly; SameSite=Strict"),
+            ("Set-Cookie", "tracker=xyz"),
+        ],
+    )
+    findings = check_cookies(response)
+    assert all("tracker" in f.title for f in findings)