attackmap 0.6.4__py3-none-any.whl

attackmap/route_auth_fusion.py

@@ -0,0 +1,474 @@
+"""Fuse routes + middleware/guard chains + auth_hints into precise findings (#140).
+
+`scan.auth_hints` are raw signals — a large monorepo emits hundreds. They're
+useful evidence, but reviewers want conclusions. This pass resolves, *per
+route*, whether an authentication/authorization control guards it, and emits a
+single precise finding for the state-changing routes that have none — each
+carrying the resolved middleware/guard chain as evidence.
+
+Why not reuse `AttackSurface.auth_signals`? That attribution is file-windowed
+(±40 lines), so in a compact file every route inherits a neighbor's auth code.
+This module resolves the control on the route's *own* registration chain:
+
+- **Express / Koa / Fastify (JS/TS)** — an auth middleware in the route's
+  argument list (`app.post('/x', requireAuth, handler)`) or a global
+  `app.use(requireAuth)` / `router.use(...)`.
+- **FastAPI / Flask (Python)** — an auth decorator (`@login_required`,
+  `@jwt_required`, …), a `dependencies=[Depends(...)]` on the route decorator,
+  `Depends(<auth>)` / `Security(...)` in the handler signature, or a
+  router-level dependency.
+- **Spring (Java)** — `@PreAuthorize` / `@PostAuthorize` / `@Secured` /
+  `@RolesAllowed` on the method or controller, or a global security config that
+  requires authentication for every request.
+
+Scope: public, state-changing (`POST/PUT/PATCH/DELETE`) `public_api` routes,
+plus privileged routes — `admin`, and `internal` routes whose own path says
+`/internal` or `/debug` (#242). The admin/internal category findings are
+file-windowed advisories; this pass gives those routes the same precise
+per-route answer. Webhook, upload and auth routes keep their dedicated
+findings. `auth_hints` emission is untouched; this only consumes them.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .handler_auth import handler_body, mask, session_gate
+from .safe_fs import read_repo_text, walk_repo
+from .srcpaths import JS_TS_SUFFIXES, split_lines
+from .models import AttackSurface, AttackTechnique, Finding, FindingLocation, Route, ScanResult
+
+_MUTATING = {"POST", "PUT", "PATCH", "DELETE"}
+# An `internal` surface counts only when the route's own path says so; one
+# classified internal from worker/event-handler metadata is not HTTP-reachable.
+_INTERNAL_PATH = re.compile(r"/(?:internal|debug)(?:/|$)", re.IGNORECASE)
+_JS_SUFFIXES = JS_TS_SUFFIXES
+_PY_SUFFIXES = {".py"}
+_JAVA_SUFFIXES = {".java", ".kt"}
+
+# Identifiers whose presence in a route's chain means it is guarded. Broad
+# enough to catch common conventions, specific enough not to match ordinary
+# handler code.
+_JS_AUTH_TOKEN = re.compile(
+    r"\b(?:require(?:Auth|Login|User|Token|Admin)|requiresAuth|isAuthenticated|"
+    r"ensureAuth\w*|ensureLoggedIn|ensureAuthenticated|authenticat\w*|authGuard|"
+    r"authMiddleware|authenticateJWT|checkAuth|checkJwt|verify(?:Token|Jwt|Auth)|"
+    r"jwtMiddleware|passport|protect(?:ed)?Route|withAuth|guard)\b",
+    re.IGNORECASE,
+)
+_PY_AUTH_DECORATOR = re.compile(
+    r"@(?:\w+\.)*(?:login_required|jwt_required|token_required|auth_required|"
+    r"requires_auth|require_auth|authenticated|permission_required|"
+    r"require_(?:oauth|api_key|token)|protected)\b",
+    re.IGNORECASE,
+)
+_PY_DEPENDS_AUTH = re.compile(
+    r"(?:Security|Depends)\(\s*(?:[\w.]*)?(?:oauth2_scheme|get_current_user|"
+    r"current_user|current_active_user|verify_token|require_\w+|auth\w*|"
+    r"authenticate\w*|HTTPBearer|HTTPBasic|JWTBearer|get_user|require_user)",
+    re.IGNORECASE,
+)
+_PY_SECURITY_CALL = re.compile(r"\bSecurity\s*\(")  # fastapi.Security is always auth
+_JAVA_AUTH_ANNOTATION = re.compile(
+    r"@(?:PreAuthorize|PostAuthorize|Secured|RolesAllowed|RoleAllowed|"
+    r"Authenticated|HasRole|HasAuthority)\b"
+)
+# A quoted string literal. A backslash is consumed only by the escape branch,
+# so an unterminated quote followed by many backslashes can't backtrack
+# exponentially (CodeQL py/redos).
+_STRING_LITERAL_RE = re.compile(r"""(['"`])(?:\\.|(?!\1)[^\\])*\1""")
+_JAVA_GLOBAL_AUTH = re.compile(
+    r"\.(?:anyRequest|anyExchange)\s*\(\s*\)\s*\.(?:authenticated|hasRole|hasAuthority|hasAnyRole)"
+    r"|\.authorize(?:HttpRequests|Requests|Exchange)\b",
+)
+
+
+def unauthenticated_routes(
+    scan: ScanResult, surfaces: list[AttackSurface]
+) -> list[tuple[Route, str]]:
+    """The in-scope state-changing routes with no resolved authentication
+    control, each with its control-chain evidence."""
+    root = Path(scan.root)
+    surface_by_key: dict[tuple[str, str, str], AttackSurface] = {}
+    for s in surfaces:
+        surface_by_key.setdefault((s.method, s.route, s.file), s)
+
+    content_cache: dict[str, str | None] = {}
+    # Only pay the Spring-config scan when there are Java routes to attribute —
+    # otherwise this is a no-op that would needlessly walk the whole tree.
+    has_java_routes = any(
+        Path(r.file).suffix.lower() in _JAVA_SUFFIXES for r in scan.routes
+    )
+    java_global_auth = (
+        repo_has_java_global_auth(scan, root, content_cache) if has_java_routes else False
+    )
+
+    line_starts: dict[str, tuple[list[int], str]] = {}
+    hop_box: list = []
+
+    flagged: list[tuple[Route, str]] = []
+    for route in scan.routes:
+        if route.method.upper() not in _MUTATING:
+            continue
+        surface = surface_by_key.get((route.method, route.path, route.file))
+        if surface is None or not _in_scope(surface, route):
+            continue
+        # Trust a plugin-declared state (#256); resolve ourselves only when the
+        # plugin couldn't tell.
+        if route.auth == "required":
+            continue
+        if route.auth == "anonymous":
+            flagged.append((route, _declared_anonymous_evidence(route)))
+            continue
+        content = _read(root, route.file, content_cache)
+        if content is None:
+            continue
+        control = resolve_control(route, content, java_global_auth)
+        if control is not None:
+            continue  # guarded — not a finding
+        if Path(route.file).suffix.lower() in _JS_SUFFIXES and _handler_session_gate(
+            route, content, root, content_cache, line_starts, hop_box
+        ):
+            continue  # the handler rejects a request without a session (#348)
+        flagged.append((route, _chain_evidence(route, content)))
+    return flagged
+
+
+_REGISTRATION_CALL = re.compile(r"\.\s*(?P<verb>get|post|put|patch|delete|all|route|on)\s*\(", re.IGNORECASE)
+_NEWLINE = re.compile(r"\n")
+_READ_ONLY_MIDDLEWARE = re.compile(
+    r"(?:[A-Za-z_$][\w$]{0,40}\.)?"
+    r"(?:(?:[a-z]{1,3}V|v)alidat(?:or|e|ion)(?:Body|Query|Params|Request|Input|Schema|Json|Middleware)?"
+    r"|json|urlencoded|text|raw|cors|helmet|rateLimit(?:er)?|[A-Za-z_$]{0,20}[Ll]imiter)"
+    r"\s*\([^;]{0,400}\)"
+)
+_CHAIN_CONTINUES = re.compile(r"[ \t\r\n]{0,200}\.")
+_PATH_LITERAL = re.compile(r"(?<!\s)\s*+['\"`/]")
+_SOLE_REF = re.compile(r"([A-Za-z_$][\w$]{0,80}(?:\.[A-Za-z_$][\w$]{0,80})?)")
+
+
+def _top_level_args(text: str) -> list[tuple[int, str]]:
+    """``text`` split on commas outside brackets, as ``(offset, argument)``;
+    a trailing comma adds no empty argument."""
+    args: list[tuple[int, str]] = []
+    depth = 0
+    start = 0
+    for i, ch in enumerate(text):
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            args.append((start, text[start:i]))
+            start = i + 1
+    if text[start:].strip():
+        args.append((start, text[start:]))
+    return args
+
+
+def _handler_session_gate(
+    route: Route,
+    content: str,
+    root: Path,
+    cache: dict[str, str | None],
+    line_starts: dict[str, tuple[list[int], str]],
+    hop_box: list,
+) -> str | None:
+    """A session check that rejects (see :mod:`handler_auth`) in the route's
+    own handler: the inline handler, clamped to its closing brace, or the one
+    function the registration passes by reference (one hop)."""
+    if route.line is None:
+        return None
+    # Route.line counts `\n` only; `splitlines()` would also split on
+    # U+2028, `\f` or a lone `\r` and shift the handler to another route.
+    # The file is masked once and shared by all its routes.
+    if route.file not in line_starts:
+        line_starts[route.file] = ([0] + [m.end() for m in _NEWLINE.finditer(content)], mask(content))
+    starts, file_code = line_starts[route.file]
+    if not 1 <= route.line <= len(starts):
+        return None
+    offset = starts[route.line - 1]
+    text = content[offset : offset + 20_000]
+    code = file_code[offset : offset + 20_000]
+    first_line = code[: code.find("\n") + 1 if "\n" in code else len(code)]
+    calls = list(_REGISTRATION_CALL.finditer(first_line))
+    if not calls:
+        if _CHAIN_CONTINUES.match(code, len(first_line)):
+            return None  # `router\n  .route('/x')\n  .post(mw, h)`: a chain we don't follow
+        # Not a call registration (a decorator, a function header): the
+        # handler body is the first function body that follows.
+        return session_gate(text, code)
+    # Several registrations on one line (`.get(a).post(b)`, `app.get(…); app.post(…)`):
+    # only the one for this route's method, and only if it is unambiguous.
+    same_method = [c for c in calls if c.group("verb").lower() == route.method.lower()]
+    if len(same_method) == 1:
+        call = same_method[0]
+    elif len(calls) == 1 and not same_method and calls[0].group("verb").lower() in ("all", "route", "on"):
+        call = calls[0]
+    else:
+        return None
+    open_paren = call.end() - 1
+    depth = 0
+    reg_close = None
+    for i in range(open_paren, len(code)):
+        if code[i] == "(":
+            depth += 1
+        elif code[i] == ")":
+            depth -= 1
+            if depth == 0:
+                reg_close = i
+                break
+    if reg_close is None:
+        return None
+    args = _top_level_args(code[open_paren + 1 : reg_close])
+    # Middleware: every argument between the path (when the first argument is
+    # one; `.route('/x').post(mw, h)` has none) and the handler. A gate in the
+    # handler runs after it (multer, a writer) has already acted. Validators,
+    # body parsers, cors and rate limiters only read the request.
+    has_path = bool(args) and _PATH_LITERAL.match(args[0][1]) is not None
+    middleware = args[1 if has_path else 0 : -1]
+    if not all(_READ_ONLY_MIDDLEWARE.fullmatch(text[open_paren + 1 + o : open_paren + 1 + o + len(a)].strip()) for o, a in middleware):
+        return None
+    # An inline handler: clamp to the registration, so a one-line route costs
+    # its own length. The body must open in the last argument, not in a
+    # callback passed to middleware (`validate({ custom: (req) => { … } })`).
+    last_start = open_paren + 1 + args[-1][0] if args else reg_close
+    inline_text, inline_code = text[: reg_close + 1], code[: reg_close + 1]
+    body = handler_body(inline_text[last_start:], inline_code[last_start:])
+    if body is not None:
+        return session_gate(inline_text[last_start:], inline_code[last_start:])
+    ref = _SOLE_REF.fullmatch(args[-1][1].strip()) if args else None
+    if ref is None:
+        return None
+    if not hop_box:
+        from .authz import _HopResolver  # local import: authz imports this module
+
+        # The resolver, and (file, function) → gate shared by every route using it.
+        hop_box.extend([_HopResolver(root, cache), {}])
+    hop, gates = hop_box
+    owner, _, func = ref.group(1).rpartition(".")
+    imports = hop._import_map(route.file, content)
+    if owner and owner not in imports:
+        return None  # `ctl.create` with `ctl` not imported: don't guess a local `create`
+    target = imports.get(owner or func, route.file)
+    key = (target, func)
+    if key not in gates:
+        definition = hop._definition(target, func)
+        gates[key] = session_gate(definition) if definition else None
+    return gates[key]
+
+
+def _in_scope(surface: AttackSurface, route: Route) -> bool:
+    if surface.category == "public_api":
+        return surface.exposure == "public"
+    if surface.category == "admin":
+        return True
+    return surface.category == "internal" and bool(_INTERNAL_PATH.search(route.path))
+
+
+def synthesize_unauthenticated_routes(
+    scan: ScanResult,
+    surfaces: list[AttackSurface],
+    flagged: list[tuple[Route, str]] | None = None,
+) -> list[Finding]:
+    """Return at most one finding aggregating unauthenticated state-changing
+    routes, with the resolved control chain per route as evidence. Pass
+    ``flagged`` (from :func:`unauthenticated_routes`) to reuse a resolution."""
+    if flagged is None:
+        flagged = unauthenticated_routes(scan, surfaces)
+    if not flagged:
+        return []
+
+    evidence = [chain for _, chain in flagged[:10]]
+    if len(flagged) > 10:
+        evidence.append(f"+{len(flagged) - 10} more state-changing route(s) with no resolved auth control")
+    return [
+        Finding(
+            title="State-changing routes are reachable without an authentication control",
+            rule_id="unauth-state-change",
+            severity="high",
+            evidence=evidence,
+            locations=[FindingLocation(file=route.file, line=route.line) for route, _ in flagged],
+            mitigation=(
+                "Require authentication (and server-side authorization) on every "
+                "state-changing endpoint — attach an auth middleware/guard to the "
+                "route or its router, a dependency/decorator on the handler, or a "
+                "global policy that defaults to deny. Confirm the control actually "
+                "runs before the handler mutates state."
+            ),
+            confidence="medium",
+            tags=["exposed-endpoint", "auth-missing", "state-changing"],
+            attack_techniques=[
+                AttackTechnique(
+                    technique_id="T1190",
+                    name="Exploit Public-Facing Application",
+                    tactic="Initial Access",
+                    url="https://attack.mitre.org/techniques/T1190/",
+                )
+            ],
+        )
+    ]
+
+
+def _declared_anonymous_evidence(route: Route) -> str:
+    where = f"{route.file}:{route.line}" if route.line else route.file
+    source = f" by {route.source_analyzer}" if route.source_analyzer else ""
+    basis = f" ({route.guard_evidence})" if route.guard_evidence else ""
+    return f"{route.method} {route.path} ({where}) — declared anonymous{source}{basis}"
+
+
+def _read(root: Path, rel: str, cache: dict[str, str | None]) -> str | None:
+    if rel not in cache:
+        try:
+            cache[rel] = read_repo_text(root, rel, errors="replace")
+        except OSError:
+            cache[rel] = None
+    return cache[rel]
+
+
+def resolve_control(route: Route, content: str, java_global_auth: bool) -> str | None:
+    """Return a short description of the control guarding `route`, or None."""
+    suffix = Path(route.file).suffix.lower()
+    lines = split_lines(content)
+    if suffix in _JS_SUFFIXES:
+        return _resolve_js(route, content, lines)
+    if suffix in _PY_SUFFIXES:
+        return _resolve_py(route, lines)
+    if suffix in _JAVA_SUFFIXES:
+        return _resolve_java(route, lines, java_global_auth)
+    return None
+
+
+def _line_index(route: Route) -> int | None:
+    return (route.line - 1) if route.line else None
+
+
+def _resolve_js(route: Route, content: str, lines: list[str]) -> str | None:
+    # Global middleware: app.use(requireAuth) / router.use(passport...).
+    for m in re.finditer(r"\b(?:app|router|server)\s*\.\s*use\s*\(([^)]*)\)", content):
+        if _JS_AUTH_TOKEN.search(m.group(1)):
+            return f"global middleware: {m.group(0).strip()[:80]}"
+
+    idx = _line_index(route)
+    if idx is None:
+        return None
+    # The route registration may span a few lines; take up to the start of the
+    # handler body so we inspect the middleware list, not the handler code.
+    region = "\n".join(lines[idx : idx + 4])
+    handler_start = re.search(r"=>|function\b|\(\s*req\b|\(\s*request\b", region)
+    mw_region = region[: handler_start.start()] if handler_start else region
+    # Drop the path string literal so a path like '/authenticate' can't match.
+    mw_region = _STRING_LITERAL_RE.sub("", mw_region, count=1)
+    if _JS_AUTH_TOKEN.search(mw_region):
+        return f"route middleware on {route.path}"
+    return None
+
+
+def _resolve_py(route: Route, lines: list[str]) -> str | None:
+    idx = _line_index(route)
+    if idx is None:
+        return None
+    # Decorators can sit above or below the route decorator; scan a small
+    # window above, then the handler signature below.
+    start = max(0, idx - 4)
+    # Find the handler `def`/`async def` at or after the route decorator, then
+    # read through the end of its signature (the line with the closing `):`).
+    def_line = None
+    for i in range(idx, min(len(lines), idx + 6)):
+        if re.match(r"\s*(?:async\s+)?def\s+\w+\s*\(", lines[i]):
+            def_line = i
+            break
+    sig_end = def_line if def_line is not None else idx
+    if def_line is not None:
+        depth = 0
+        for i in range(def_line, min(len(lines), def_line + 30)):
+            depth += lines[i].count("(") - lines[i].count(")")
+            sig_end = i
+            if depth <= 0 and "(" in "".join(lines[def_line : i + 1]):
+                break
+    window = "\n".join(lines[start : sig_end + 1])
+    if _PY_AUTH_DECORATOR.search(window):
+        return f"auth decorator on {route.path}"
+    if _PY_DEPENDS_AUTH.search(window) or _PY_SECURITY_CALL.search(window):
+        return f"auth dependency on {route.path} handler"
+    # Router-level dependency (applies to every route on the router).
+    return _py_router_dependency(lines)
+
+
+def _py_router_dependency(lines: list[str]) -> str | None:
+    text = "\n".join(lines)
+    for m in re.finditer(r"(?:APIRouter|include_router)\s*\(([^)]*)\)", text, re.DOTALL):
+        if "dependencies" in m.group(1) and _PY_DEPENDS_AUTH.search(m.group(1)):
+            return "router-level auth dependency"
+    return None
+
+
+def _resolve_java(route: Route, lines: list[str], java_global_auth: bool) -> str | None:
+    if java_global_auth:
+        return "global Spring Security policy requires authentication"
+    idx = _line_index(route)
+    if idx is None:
+        return None
+    # Method-level annotations sit just above the mapping (after any preceding
+    # method's closing brace). Only scan up to that boundary so a *different*
+    # method's @PreAuthorize doesn't leak onto this route.
+    method_start = 0
+    for i in range(idx - 1, -1, -1):
+        if "}" in lines[i] or re.search(r"\b(?:public|private|protected)\b.*\)", lines[i]):
+            method_start = i + 1
+            break
+    window = "\n".join(lines[method_start : idx + 1])
+    if _JAVA_AUTH_ANNOTATION.search(window):
+        return f"method security annotation on {route.path}"
+    # Class-level annotations: only those directly above the class declaration.
+    for i, line in enumerate(lines):
+        if re.search(r"\b(?:class|interface)\s+\w+", line):
+            class_head = "\n".join(lines[max(0, i - 6) : i])
+            if _JAVA_AUTH_ANNOTATION.search(class_head):
+                return "class-level security annotation"
+            break
+    return None
+
+
+def repo_has_java_global_auth(
+    scan: ScanResult, root: Path, cache: dict[str, str | None]
+) -> bool:
+    """True when a Spring Security config requires auth for every request —
+    then per-route method annotations aren't needed and routes aren't flagged."""
+    java_files = {r.file for r in scan.routes if Path(r.file).suffix.lower() in _JAVA_SUFFIXES}
+    # Config usually lives elsewhere; check route files plus any *Security*.java.
+    candidates = set(java_files)
+    for path in (p for p in walk_repo(root) if p.suffix == ".java" and "Security" in p.name):
+        try:
+            candidates.add(str(path.relative_to(root)))
+        except ValueError:
+            continue
+    for rel in candidates:
+        content = _read(root, rel, cache)
+        if content and "anyRequest" in content and _JAVA_GLOBAL_AUTH.search(content):
+            # Require an explicit authenticated()/hasRole() to avoid matching a
+            # config that permits all.
+            if re.search(r"\.(?:authenticated|hasRole|hasAuthority|hasAnyRole|fullyAuthenticated)\s*\(", content):
+                return True
+    return False
+
+
+def _chain_evidence(route: Route, content: str) -> str:
+    """Describe what the control-chain resolution found (i.e. nothing)."""
+    loc = f"{route.file}:{route.line}" if route.line else route.file
+    suffix = Path(route.file).suffix.lower()
+    if suffix in _JS_SUFFIXES:
+        has_any = bool(_JS_AUTH_TOKEN.search(content))
+    elif suffix in _PY_SUFFIXES:
+        has_any = bool(_PY_AUTH_DECORATOR.search(content) or _PY_DEPENDS_AUTH.search(content))
+    elif suffix in _JAVA_SUFFIXES:
+        has_any = bool(_JAVA_AUTH_ANNOTATION.search(content))
+    else:
+        has_any = False
+    tail = (
+        "auth controls exist in the file but none guard this route"
+        if has_any
+        else "no authentication/authorization control found on the route's chain"
+    )
+    return f"{route.method} {route.path} in {loc} — {tail}"