deluluscan 0.3.1__py3-none-any.whl

deluluscan/__init__.py

@@ -0,0 +1,4 @@
+"""deluluscan — an AI-augmented, evidence-first security auditor for authorized testing of web,
+API, application, container, cloud and LLM/AI-system targets. Finds and verifies
+OWASP Top 10 issues across multiple identities, confirming to proof before asserting."""
+__version__ = "0.3.1"

deluluscan/active/__init__.py

@@ -0,0 +1,25 @@
+"""Active, AI-assisted testing — the Burp/Postman-style workbench.
+
+Unlike the passive scanners, these modules mutate requests (tokens, parameters,
+object ids, bodies) and replay them to confirm whether the server accepts the
+manipulation. Authorized-target only; confirms vulnerabilities by exercising
+them without weaponizing into third-party attacks or bulk data exfiltration.
+"""
+from .http_tools import (RequestSpec, Repeater, Intruder, Position,
+                         IntruderResult, Collection, parse_markers, set_at)
+from .jwt_lab import JwtLab, decode as jwt_decode, JwtTestResult
+from .authz_probe import AuthzProbe, AuthzResult
+from .recon import (ParamMiner, ContentDiscovery, VersionEnumerator,
+                    SupplyChainProbe)
+from .advanced import VerbTamper, RaceProbe, GraphQLAdvanced
+from .session_rules import MatchReplaceRule, Macro, Extraction, SessionEngine
+
+__all__ = [
+    "RequestSpec", "Repeater", "Intruder", "Position", "IntruderResult",
+    "Collection", "parse_markers", "set_at",
+    "JwtLab", "jwt_decode", "JwtTestResult",
+    "AuthzProbe", "AuthzResult",
+    "ParamMiner", "ContentDiscovery", "VersionEnumerator", "SupplyChainProbe",
+    "VerbTamper", "RaceProbe", "GraphQLAdvanced",
+    "MatchReplaceRule", "Macro", "Extraction", "SessionEngine",
+]

deluluscan/active/advanced.py

@@ -0,0 +1,161 @@
+"""Advanced analyzers (v0.6): HTTP verb/method tampering, bounded race-condition
+testing, and deeper GraphQL abuse (batching, alias amplification, depth limits).
+
+All authorized-target only. The race prober is intentionally bounded (a small
+number of parallel requests to reveal a TOCTOU window) and is gated behind
+allow_state_changing because it may cause an action to execute more than once on
+your own test instance — it confirms the flaw by exercising it, nothing more.
+"""
+from __future__ import annotations
+
+import concurrent.futures
+import json
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+from ..verify import evidence as E
+
+
+# ===========================================================================
+# HTTP verb / method tampering — function-level authz bypass (API5 / A01)
+# ===========================================================================
+_ALT_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
+_OVERRIDE_HEADERS = ["X-HTTP-Method-Override", "X-HTTP-Method", "X-Method-Override"]
+
+
+@dataclass
+class VerbFinding:
+    technique: str      # "alt_method" | "method_override"
+    method: str
+    detail: str
+    status: int
+
+
+class VerbTamper:
+    """Given a canonical method that is DENIED, try alternate methods and
+    method-override headers; flag any that are granted (auth enforced on the
+    verb, not the resource)."""
+
+    def __init__(self, send: Callable):
+        # send(method, extra_headers) -> record
+        self.send = send
+
+    @staticmethod
+    def _granted(rec) -> bool:
+        # real content returned (not empty/denied/permission-message)
+        return E.classify_response(rec) == E.DISPOSITION_CONTENT
+
+    def test(self, canonical_method: str) -> list[VerbFinding]:
+        out: list[VerbFinding] = []
+        base = self.send(canonical_method, None)
+        if self._granted(base):
+            return out  # canonical already works; nothing to bypass
+        for m in _ALT_METHODS:
+            if m == canonical_method.upper():
+                continue
+            rec = self.send(m, None)
+            if self._granted(rec):
+                out.append(VerbFinding("alt_method", m,
+                    f"'{m}' reached the resource that '{canonical_method}' denied "
+                    f"— access control is enforced on the verb, not the object", rec.status))
+                break
+        for h in _OVERRIDE_HEADERS:
+            rec = self.send("POST", {h: canonical_method})
+            if self._granted(rec):
+                out.append(VerbFinding("method_override", canonical_method,
+                    f"method-override header '{h}: {canonical_method}' bypassed the "
+                    f"method restriction", rec.status))
+                break
+        return out
+
+
+# ===========================================================================
+# Race conditions — business-logic TOCTOU (API6). Bounded & gated.
+# ===========================================================================
+@dataclass
+class RaceFinding:
+    parallel: int
+    successes: int
+    detail: str
+
+
+class RaceProbe:
+    HARD_CAP = 20
+
+    def test(self, send_once: Callable, *, parallel: int = 8,
+             expected_successes: int = 1, success_pred: Optional[Callable] = None
+             ) -> Optional[RaceFinding]:
+        parallel = min(parallel, self.HARD_CAP)
+        pred = success_pred or (lambda r: r is not None and getattr(r, "status", 0) in (200, 201))
+        with concurrent.futures.ThreadPoolExecutor(max_workers=parallel) as ex:
+            recs = list(ex.map(lambda _: send_once(), range(parallel)))
+        successes = sum(1 for r in recs if pred(r))
+        if successes > expected_successes:
+            return RaceFinding(parallel, successes,
+                f"{successes}/{parallel} parallel requests succeeded where only "
+                f"{expected_successes} should — a race/TOCTOU window lets the action "
+                f"be performed multiple times (e.g. limit/coupon/balance overrun)")
+        return None
+
+
+# ===========================================================================
+# GraphQL deep abuse — batching, alias amplification, missing depth limit
+# ===========================================================================
+@dataclass
+class GraphQLAdvFinding:
+    kind: str          # "batching" | "alias_amplification" | "no_depth_limit"
+    detail: str
+    status: int
+
+
+def _nested_query(depth: int) -> str:
+    # a bounded self-referential introspection-ish nesting to test depth limits
+    inner = "name"
+    for _ in range(depth):
+        inner = f"fields{{type{{{inner}}}}}"
+    return json.dumps({"query": "query{__type(name:\"Query\"){" + inner + "}}"})
+
+
+def _batch_query(n: int) -> str:
+    return json.dumps([{"query": f"query a{i}{{__typename}}"} for i in range(n)])
+
+
+def _alias_query(n: int) -> str:
+    aliases = " ".join(f"a{i}:__typename" for i in range(n))
+    return json.dumps({"query": "query{" + aliases + "}"})
+
+
+class GraphQLAdvanced:
+    DEPTH_CAP = 8
+    BATCH_N = 10
+    ALIAS_N = 25
+
+    def test(self, send_body: Callable) -> list[GraphQLAdvFinding]:
+        # send_body(raw_json_string) -> record
+        out: list[GraphQLAdvFinding] = []
+
+        # batching: an array batch that all resolve => rate-limit bypass surface
+        rec = send_body(_batch_query(self.BATCH_N))
+        if rec is not None and rec.status == 200 and (rec.resp_body or "").count("__typename") \
+                + (rec.resp_body or "").count("Query") >= 2 and (rec.resp_body or "").strip().startswith("["):
+            out.append(GraphQLAdvFinding("batching",
+                f"the endpoint executed a batch of {self.BATCH_N} queries in one "
+                f"request — batching can bypass per-request rate limits (credential "
+                f"stuffing, enumeration)", rec.status))
+
+        # alias amplification: many aliases resolved in one query
+        rec = send_body(_alias_query(self.ALIAS_N))
+        if rec is not None and rec.status == 200 and (rec.resp_body or "").count("a0") >= 1 \
+                and (rec.resp_body or "").count(":") >= self.ALIAS_N // 2:
+            out.append(GraphQLAdvFinding("alias_amplification",
+                f"{self.ALIAS_N} aliased fields resolved in a single query — alias "
+                f"amplification enables resource abuse and rate-limit bypass", rec.status))
+
+        # depth limit: a deeply nested (bounded) query that is accepted
+        rec = send_body(_nested_query(self.DEPTH_CAP))
+        if rec is not None and rec.status == 200 and "error" not in (rec.resp_body or "").lower():
+            out.append(GraphQLAdvFinding("no_depth_limit",
+                f"a query nested to depth {self.DEPTH_CAP} was accepted without a "
+                f"complexity/depth error — nested-query DoS risk; enforce a depth "
+                f"and cost limit", rec.status))
+        return out

deluluscan/active/authz_probe.py

@@ -0,0 +1,136 @@
+"""Active authorization & parameter-tampering probe.
+
+Where the passive scanners *observe*, this module *acts*: it takes a request that
+works for one identity and replays it with the credentials/parameters changed,
+then checks whether the server still grants access. That is how you confirm
+broken access control by exercising it (BOLA/IDOR, BFLA/privilege escalation,
+missing auth, mass assignment) — the same moves you'd make by hand in Burp
+Repeater, automated.
+
+Authorized-target only (the HttpClient safety gate still applies). It proves the
+issue by making the manipulated request succeed; it does not then use that
+access to harvest data at scale.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from .http_tools import Repeater, RequestSpec
+from ..semantic_diff import structural_similarity
+from ..verify import evidence as E
+
+# Fields an attacker commonly injects to grant themselves privileges the API
+# forgot to mask on write (mass assignment / BOPLA). These are *test* markers.
+_MASS_ASSIGN_FIELDS = {
+    "admin": True, "isAdmin": True, "is_admin": True, "roleId": "1",
+    "role": "admin", "roles": ["admin"], "active": True, "approved": True,
+    "emailVerified": True, "permissions": ["ADMIN"],
+}
+
+
+@dataclass
+class AuthzResult:
+    test: str
+    granted: bool
+    detail: str
+    status: Optional[int] = None
+    similarity: Optional[float] = None
+    changes: dict = field(default_factory=dict)
+
+
+def _looks_denied(rec) -> bool:
+    # content-aware: empty result sets and permission-messages served as 200 are
+    # denials, not "content served" (NIST 800-115 / OWASP WSTG 4.5).
+    return E.classify_response(rec) != E.DISPOSITION_CONTENT
+
+
+def _login_like(body: str) -> bool:
+    low = (body or "").lower()
+    return ("login" in low and "password" in low) or "j_security_check" in low
+
+
+class AuthzProbe:
+    def __init__(self, client):
+        self.repeater = Repeater(client)
+
+    # -- missing authentication --------------------------------------------
+    def test_missing_auth(self, spec: RequestSpec, good) -> AuthzResult:
+        # skip endpoints that are public by design (login/config/published)
+        if E.is_public_by_design(spec.path):
+            return AuthzResult("missing_auth", False,
+                               "endpoint is public by design; anonymous access "
+                               "is intended", None)
+        stripped = spec.with_header("Authorization", None)
+        stripped = stripped.with_header("Cookie", None)
+        rec = self.repeater.send(stripped, identity_label="anonymous")
+        # OWASP WSTG 4.5 oracle: the anonymous response must contain the SAME
+        # protected data the authorized user gets — not merely a 200.
+        res = E.served_protected_content(rec, good)
+        return AuthzResult("missing_auth", res.served,
+                           ("protected resource served to anonymous: " + res.reason)
+                           if res.served else ("not a bypass: " + res.reason),
+                           getattr(rec, "status", None), res.similarity)
+
+    # -- horizontal / vertical privilege via identity swap -----------------
+    def test_identity_swap(self, spec: RequestSpec, good, other_label: str,
+                            other_headers: dict) -> AuthzResult:
+        swapped = spec.with_header("Authorization", None).with_header("Cookie", None)
+        for k, v in (other_headers or {}).items():
+            swapped = swapped.with_header(k, v)
+        rec = self.repeater.send(swapped, identity_label=other_label)
+        res = E.served_protected_content(rec, good)
+        return AuthzResult("identity_swap", res.served,
+                           (f"'{other_label}' reached the same protected resource: {res.reason}"
+                            if res.served else f"'{other_label}' did not: {res.reason}"),
+                           getattr(rec, "status", None), res.similarity)
+
+    # -- BOLA via object-id swap -------------------------------------------
+    def test_bola_id(self, spec: RequestSpec, id_token: str, other_id: str,
+                     identity_label: str, headers: dict) -> AuthzResult:
+        """Replay the request as the SAME (lower-priv) identity but pointed at a
+        different principal's object id. If a bogus id 404s and a real other id
+        200s with an object, that's BOLA."""
+        base = spec
+        for k, v in (headers or {}).items():
+            base = base.with_header(k, v)
+        # control: a bogus id should NOT return an object
+        bogus = "00000000-0000-0000-0000-0000000000ff" if "-" in id_token else "999999999"
+        ctrl_spec = base.clone(); ctrl_spec.path = base.path.replace(id_token, bogus)
+        ctrl = self.repeater.send(ctrl_spec, identity_label=identity_label)
+        tgt_spec = base.clone(); tgt_spec.path = base.path.replace(id_token, other_id)
+        target = self.repeater.send(tgt_spec, identity_label=identity_label)
+        granted = (not _looks_denied(target)) and _looks_denied(ctrl)
+        return AuthzResult("bola_id_swap", granted,
+                           (f"object id {other_id} returned another principal's "
+                            f"object while a bogus id did not" if granted
+                            else "id swap did not yield object-scoped access"),
+                           getattr(target, "status", None),
+                           changes={"id": other_id})
+
+    # -- mass assignment ---------------------------------------------------
+    def test_mass_assignment(self, spec: RequestSpec, identity_label: str,
+                             headers: dict) -> list[AuthzResult]:
+        if spec.method.upper() not in ("POST", "PUT", "PATCH"):
+            return []
+        base = spec
+        for k, v in (headers or {}).items():
+            base = base.with_header(k, v)
+        baseline = self.repeater.send(base, identity_label=identity_label)
+        out: list[AuthzResult] = []
+        for field_name, value in _MASS_ASSIGN_FIELDS.items():
+            spec2 = base.with_json_field(field_name, value)
+            rec = self.repeater.send(spec2, identity_label=identity_label)
+            # signal: the elevated field is echoed back set, or status improved
+            echoed = f'"{field_name}"' in (rec.resp_body or "") and (
+                str(value).lower() in (rec.resp_body or "").lower())
+            if echoed and rec.status < 400:
+                out.append(AuthzResult(
+                    "mass_assignment", True,
+                    f"write accepted and reflected elevated field "
+                    f"{field_name}={value}", rec.status, changes={field_name: value}))
+        if not out:
+            out.append(AuthzResult("mass_assignment", False,
+                                   "no elevated field was accepted/reflected",
+                                   getattr(baseline, "status", None)))
+        return out

deluluscan/active/bypass.py

@@ -0,0 +1,84 @@
+"""Access-control bypass technique primitives.
+
+Grounded in the target CVE-2022-45782 (a semicolon/matrix parameter placed before a
+'/' bypasses the target's path-based access-control filters) and the broader
+403/401-bypass playbook expert hunters use (path normalization tricks, override
+headers, method changes). These are pure functions so they can be unit-tested and
+reused; the scanner applies them only where a baseline request was actually
+denied, and confirms a bypass with the content oracle.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BypassVariant:
+    label: str
+    method: str
+    path: str
+    headers: dict = field(default_factory=dict)
+
+
+def path_variants(path: str) -> list[BypassVariant]:
+    """Path-mangling tricks, incl. the target matrix-parameter (semicolon) bypass."""
+    p = path.split("?")[0]
+    q = ("?" + path.split("?", 1)[1]) if "?" in path else ""
+    segs = [s for s in p.split("/") if s != ""]
+    out: list[BypassVariant] = []
+
+    def v(label, newp):
+        out.append(BypassVariant(label, "GET", newp + q))
+
+    # CVE-2022-45782: matrix parameter (';') before a path separator evades the
+    # path-based "require login" filter while still resolving to the resource.
+    if segs:
+        v("matrix-semicolon-mid", "/" + "/".join(segs[:-1]) + "/;x=1/" + segs[-1])
+        v("matrix-semicolon-suffix", p + ";x=1")
+        v("matrix-jsessionid", p + ";jsessionid=1")
+        v("matrix-dot-semicolon", "/" + "/".join(segs[:-1]) + "/.;/" + segs[-1])
+        v("dotdot-semicolon", "/" + "/".join(segs) + "/..;/")
+    # generic 403/401 path-normalization bypasses
+    v("trailing-slash", p + "/")
+    v("trailing-slash-dot", p + "/.")
+    v("double-slash", "/" + "//".join(segs))
+    v("slash-dot-slash", "/./" + "/".join(segs))
+    v("encoded-slash", p.replace("/", "/%2e/", 1) if "/" in p else p)
+    v("trailing-encoded", p + "%20")
+    v("trailing-hash", p + "%23")
+    if segs:
+        v("uppercase-seg", "/" + "/".join(segs[:-1] + [segs[-1].upper()]))
+    return out
+
+
+def header_variants(path: str) -> list[BypassVariant]:
+    """Override / trust-signal headers that some stacks honor to bypass authz."""
+    ov = [
+        ("x-original-url", {"X-Original-URL": path}),
+        ("x-rewrite-url", {"X-Rewrite-URL": path}),
+        ("x-override-url", {"X-Override-URL": path}),
+        ("xff-localhost", {"X-Forwarded-For": "127.0.0.1"}),
+        ("x-custom-ip-auth", {"X-Custom-IP-Authorization": "127.0.0.1"}),
+        ("x-forwarded-host", {"X-Forwarded-Host": "127.0.0.1"}),
+        ("x-real-ip", {"X-Real-IP": "127.0.0.1"}),
+        ("referer-self", {"Referer": path}),
+        ("method-override", {"X-HTTP-Method-Override": "GET"}),
+    ]
+    return [BypassVariant(l, "GET", path, h) for l, h in ov]
+
+
+def method_variants(path: str) -> list[BypassVariant]:
+    return [BypassVariant(f"method-{m}", m, path, {}) for m in ("POST", "HEAD", "OPTIONS", "PUT")]
+
+
+def all_variants(path: str) -> list[BypassVariant]:
+    return path_variants(path) + header_variants(path) + method_variants(path)
+
+
+# ---- HTTP parameter pollution ---------------------------------------------
+def hpp_variants(param: str, value: str) -> list[str]:
+    """Duplicate/split a parameter to probe parser discrepancies / WAF bypass."""
+    return [f"{param}={value}&{param}={value}",       # duplicate
+            f"{param}[]={value}&{param}[]={value}",     # array
+            f"{param}={value}%00",                      # null truncation
+            f"{param}={value}%0a{param}={value}"]       # newline split

deluluscan/active/crawler.py

@@ -0,0 +1,133 @@
+"""SPA / JS-aware crawler.
+
+admin is an Angular SPA — most of its real API surface is only reachable by
+watching what the app calls at runtime or by mining the JS bundles. Top hunters
+(ZSeano's "make use of .js files" methodology) treat JS as the map of hidden
+endpoints, parameters, and leaked secrets.
+
+Two modes:
+  * render (Playwright): load the app, capture every XHR/fetch the SPA makes, and
+    read the rendered DOM — the ground truth of what the front end talks to.
+  * static (always available): fetch HTML, follow <script src>, and mine the
+    bundles for API paths, SSRF-prone endpoints, and leaked secrets.
+
+Same-origin, authorized target only; bounded. No secret is exfiltrated — leaked
+material is reported as a finding for the operator.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+from .jsrecon import extract_from_js, script_srcs
+
+# high-signal secret patterns (ZSeano/JS-recon); reported, never used
+_SECRET_PATTERNS = {
+    "aws_access_key": re.compile(r"AKIA[0-9A-Z]{16}"),
+    "google_api_key": re.compile(r"AIza[0-9A-Za-z_\-]{35}"),
+    "slack_token": re.compile(r"xox[baprs]-[0-9A-Za-z-]{10,}"),
+    "jwt": re.compile(r"eyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{5,}"),
+    "private_key": re.compile(r"-----BEGIN (?:RSA |EC )?PRIVATE KEY-----"),
+    "generic_secret": re.compile(r"(?i)(?:api[_-]?key|secret|passwd|password|token)"
+                                 r"['\"]?\s*[:=]\s*['\"]([A-Za-z0-9_\-]{12,})['\"]"),
+    "bearer": re.compile(r"(?i)bearer\s+[A-Za-z0-9_\-\.=]{20,}"),
+}
+_FALSE_SECRET = re.compile(r"(?i)example|placeholder|xxxx|your[_-]?(?:api|key|token)|dummy|test")
+
+
+@dataclass
+class CrawlResult:
+    paths: set[str] = field(default_factory=set)
+    ssrf_candidates: set[str] = field(default_factory=set)
+    secrets: list[tuple[str, str]] = field(default_factory=list)
+    scripts_scanned: int = 0
+    mode: str = "static"
+
+
+def mine_secrets(text: str) -> list[tuple[str, str]]:
+    out = []
+    for kind, rx in _SECRET_PATTERNS.items():
+        for m in rx.finditer(text or ""):
+            val = m.group(0)
+            if _FALSE_SECRET.search(val):
+                continue
+            out.append((kind, val[:60]))
+    # de-dup
+    seen, uniq = set(), []
+    for k, v in out:
+        if (k, v) not in seen:
+            seen.add((k, v)); uniq.append((k, v))
+    return uniq[:25]
+
+
+class SpaCrawler:
+    def __init__(self, fetch_text: Callable[[str], str], max_scripts: int = 25):
+        # fetch_text(path)-> body text (goes through the safety-gated client)
+        self.fetch_text = fetch_text
+        self.max_scripts = max_scripts
+
+    def static_crawl(self, roots=("/", "/admin/", "/html/")) -> CrawlResult:
+        out = CrawlResult(mode="static")
+        for root in roots:
+            html = self.fetch_text(root) or ""
+            p, s = extract_from_js(html)
+            out.paths |= p; out.ssrf_candidates |= s
+            out.secrets += mine_secrets(html)
+            for src in script_srcs(html)[: self.max_scripts]:
+                if not src.startswith(("/", "http")):
+                    continue
+                body = self.fetch_text(src) or ""
+                out.scripts_scanned += 1
+                pp, ss = extract_from_js(body)
+                out.paths |= pp; out.ssrf_candidates |= ss
+                out.secrets += mine_secrets(body)
+        # de-dup secrets across all sources
+        seen, uniq = set(), []
+        for k, v in out.secrets:
+            if (k, v) not in seen:
+                seen.add((k, v)); uniq.append((k, v))
+        out.secrets = uniq
+        return out
+
+
+def render_crawl(base_url: str, extra_headers: Optional[dict] = None,
+                 timeout_s: float = 15.0) -> CrawlResult:
+    """Playwright network-capture crawl: record every request the SPA issues.
+    No-ops (returns empty static result) if Playwright/browser isn't available."""
+    out = CrawlResult(mode="render")
+    try:
+        from playwright.sync_api import sync_playwright
+    except Exception:
+        return out
+    from urllib.parse import urlparse
+    host = urlparse(base_url).hostname
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            ctx = browser.new_context(ignore_https_errors=True,
+                                      extra_http_headers=extra_headers or {})
+            page = ctx.new_page()
+            seen_urls: set[str] = set()
+
+            def on_request(req):
+                try:
+                    u = urlparse(req.url)
+                    if u.hostname == host and ("/api/" in u.path or "/dwr" in u.path
+                                               or u.path.startswith("/html/")):
+                        seen_urls.add(u.path)
+                except Exception:
+                    pass
+            page.on("request", on_request)
+            for start in (base_url, base_url.rstrip("/") + "/admin/"):
+                try:
+                    page.goto(start, timeout=int(timeout_s * 1000), wait_until="networkidle")
+                    page.wait_for_timeout(800)
+                except Exception:
+                    continue
+                out.secrets += mine_secrets(page.content() or "")
+            out.paths |= seen_urls
+            browser.close()
+    except Exception:
+        return out
+    return out