klyrek-headers 0.1.0__py3-none-any.whl

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

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

@@ -0,0 +1,7 @@
+klyrek_headers/__init__.py,sha256=vPuvKhgpjznIjh4hV5FZmYoQYuakIIKeb2jbjtqShuA,218
+klyrek_headers/analyzer.py,sha256=Vnwa7PvS5heltYj9JDgA2GFC6mqdonmpIdGCKxJBVw0,803
+klyrek_headers/checks.py,sha256=HOZIK1kWK5nPeZSQILoZ876Zi2NGC928rFLqhmo0hZs,10158
+klyrek_headers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+klyrek_headers-0.1.0.dist-info/METADATA,sha256=4V9aNNEQqc15cwDuVxMF6p69oMmSQl2zj4XW_DhWgMI,1918
+klyrek_headers-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+klyrek_headers-0.1.0.dist-info/RECORD,,

klyrek_headers-0.1.0.dist-info/WHEEL

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