attackmap-analyzer-python 0.2.0__py3-none-any.whl

attackmap_analyzer_python/litestar_routes.py

@@ -0,0 +1,358 @@
+"""Litestar / Starlite route handlers, controllers and routers (#2).
+
+- ``@get("/x")`` / ``@post()`` (no path → ``/``) / ``@get(path=["/a", "/b"])``
+  / ``@route("/x", http_method=["GET", "POST"])`` / ``@websocket("/ws")``,
+  at any indentation — module level, inside a ``Controller``, or inside a
+  factory function.
+- ``class UserController(Controller): path = "/users"`` joins the controller
+  path onto each handler path.
+- ``Router(path="/api", route_handlers=[UserController, health])`` joins the
+  router path onto what it lists; nested routers chain.
+- Route auth (#256): ``guards=[...]`` on the handler, controller or router →
+  ``required``; ``exclude_from_auth=True`` (or ``opt={"exclude_from_auth":
+  True}``) with no guard → ``anonymous``. Anything else stays ``unknown``.
+
+Decorators only count when their name is imported from ``litestar``/``starlite``
+(so a project's own ``get`` decorator never fires).
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+from ._pyast import call_name, dotted, expr_names, keyword, safe_parse, str_const, str_list
+
+_HANDLER_KINDS = {
+    "get": ["GET"],
+    "post": ["POST"],
+    "put": ["PUT"],
+    "patch": ["PATCH"],
+    "delete": ["DELETE"],
+    "head": ["HEAD"],
+    "route": None,  # methods come from http_method=
+    "websocket": ["WS"],
+    "websocket_listener": ["WS"],
+}
+_LITESTAR_MODULES = ("litestar", "starlite")
+_MAX_NEST = 32
+_MAX_ROUTER_DEPTH = 8
+_MAX_PREFIXES = 32
+
+
+@dataclass
+class Handler:
+    file: str
+    line: int
+    name: str
+    paths: list[str]
+    methods: list[str]
+    module_level: bool
+    guards: list[str] = field(default_factory=list)
+    excluded: bool = False
+
+
+@dataclass
+class Controller:
+    file: str
+    name: str
+    path: str
+    guards: list[str]
+    handlers: list[Handler] = field(default_factory=list)
+
+
+@dataclass
+class Router:
+    file: str
+    var: str | None
+    path: str
+    members: list[str]
+    guards: list[str]
+
+
+@dataclass
+class LitestarFile:
+    rel: str
+    handlers: list[Handler] = field(default_factory=list)  # not inside a controller
+    controllers: list[Controller] = field(default_factory=list)
+    routers: list[Router] = field(default_factory=list)
+
+
+@dataclass
+class LitestarRoute:
+    path: str
+    method: str
+    file: str
+    line: int
+    auth: str = "unknown"
+    guards: list[str] = field(default_factory=list)
+    evidence: str | None = None
+
+
+def _is_litestar_module(module: str | None) -> bool:
+    return bool(module) and module.split(".")[0] in _LITESTAR_MODULES
+
+
+def parse_litestar(content: str, rel: str) -> LitestarFile | None:
+    """The file's handlers/controllers/routers; ``None`` only when it can't be
+    parsed (the caller then falls back to the decorator regex)."""
+    tree = safe_parse(content)
+    if tree is None:
+        return None
+    aliases: dict[str, str] = {}
+    module_aliases: set[str] = set()
+    router_names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and _is_litestar_module(node.module):
+            for alias in node.names:
+                bound = alias.asname or alias.name
+                if alias.name in _HANDLER_KINDS:
+                    aliases[bound] = alias.name
+                elif alias.name in {"Router", "Litestar", "Starlite"}:
+                    router_names.add(bound)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if _is_litestar_module(alias.name):
+                    module_aliases.add(alias.asname or alias.name.split(".")[0])
+    out = LitestarFile(rel=rel)
+    if not aliases and not module_aliases and not router_names:
+        # Mentions litestar but imports no handler decorator from it — e.g. a
+        # test using `unittest.mock.patch("...")`, which is not a route.
+        return out
+    try:
+        _visit(tree.body, None, True, out, aliases, module_aliases, 0)
+        _collect_routers(tree, out, router_names, module_aliases)
+    except RecursionError:
+        return None
+    return out
+
+
+def _decorator_kind(dec: ast.expr, aliases: dict[str, str], module_aliases: set[str]) -> str | None:
+    if not isinstance(dec, ast.Call):
+        return None
+    func = dec.func
+    if isinstance(func, ast.Name):
+        return aliases.get(func.id)
+    if isinstance(func, ast.Attribute) and func.attr in _HANDLER_KINDS:
+        base = dotted(func.value)
+        if base and base.split(".")[0] in module_aliases:
+            return func.attr
+    return None
+
+
+def _handler_from(fn: ast.FunctionDef | ast.AsyncFunctionDef, dec: ast.Call, kind: str, rel: str, module_level: bool) -> Handler | None:
+    path_node = dec.args[0] if dec.args else keyword(dec, "path")
+    if path_node is None:
+        paths = ["/"]
+    else:
+        single = str_const(path_node)
+        paths = [single] if single is not None else (str_list(path_node) or [])
+    if not paths:
+        return None  # a computed path: nothing reliable to report
+    methods = _HANDLER_KINDS[kind]
+    if methods is None:
+        methods = _http_methods(keyword(dec, "http_method")) or ["ANY"]
+    guards = expr_names(keyword(dec, "guards"))
+    return Handler(
+        file=rel,
+        line=dec.lineno,
+        name=fn.name,
+        paths=paths,
+        methods=list(methods),
+        module_level=module_level,
+        guards=guards,
+        excluded=_excluded_from_auth(dec),
+    )
+
+
+def _http_methods(node: ast.expr | None) -> list[str]:
+    if node is None:
+        return []
+    elts = node.elts if isinstance(node, (ast.List, ast.Tuple, ast.Set)) else [node]
+    out: list[str] = []
+    for elt in elts[:16]:
+        value = str_const(elt)
+        if value is None and isinstance(elt, ast.Attribute):
+            value = elt.attr  # HttpMethod.GET
+        if value and value.isalpha():
+            out.append(value.upper())
+    return out
+
+
+def _excluded_from_auth(dec: ast.Call) -> bool:
+    flag = keyword(dec, "exclude_from_auth")
+    if isinstance(flag, ast.Constant) and flag.value is True:
+        return True
+    opt = keyword(dec, "opt")
+    if isinstance(opt, ast.Dict):
+        for key, value in zip(opt.keys, opt.values):
+            if str_const(key) == "exclude_from_auth" and isinstance(value, ast.Constant) and value.value is True:
+                return True
+    return False
+
+
+def _visit(body, controller: Controller | None, module_level: bool, out: LitestarFile, aliases, module_aliases, depth: int) -> None:
+    if depth > _MAX_NEST:
+        return
+    for stmt in body:
+        if isinstance(stmt, ast.ClassDef):
+            ctrl = None
+            if any((dotted(base) or "").endswith("Controller") for base in stmt.bases):
+                ctrl = Controller(file=out.rel, name=stmt.name, path="", guards=[])
+                for item in stmt.body:
+                    if isinstance(item, (ast.Assign, ast.AnnAssign)):
+                        targets = item.targets if isinstance(item, ast.Assign) else [item.target]
+                        for target in targets:
+                            if isinstance(target, ast.Name) and target.id == "path":
+                                ctrl.path = str_const(item.value) or ""
+                            elif isinstance(target, ast.Name) and target.id == "guards":
+                                ctrl.guards = expr_names(item.value)
+                out.controllers.append(ctrl)
+            _visit(stmt.body, ctrl, False, out, aliases, module_aliases, depth + 1)
+        elif isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for dec in stmt.decorator_list:
+                kind = _decorator_kind(dec, aliases, module_aliases)
+                if kind is None:
+                    continue
+                handler = _handler_from(stmt, dec, kind, out.rel, module_level)
+                if handler is None:
+                    continue
+                if controller is not None:
+                    controller.handlers.append(handler)
+                else:
+                    out.handlers.append(handler)
+            _visit(stmt.body, None, False, out, aliases, module_aliases, depth + 1)
+        elif isinstance(stmt, (ast.If, ast.With, ast.Try, ast.For, ast.While)) or type(stmt).__name__ == "TryStar":
+            for block in ("body", "orelse", "finalbody"):
+                _visit(getattr(stmt, block, []) or [], controller, module_level, out, aliases, module_aliases, depth + 1)
+            for handler in getattr(stmt, "handlers", []) or []:
+                _visit(handler.body, controller, module_level, out, aliases, module_aliases, depth + 1)
+
+
+def _collect_routers(tree: ast.Module, out: LitestarFile, router_names: set[str], module_aliases: set[str]) -> None:
+    assigned: dict[int, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Assign) and isinstance(node.value, ast.Call):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    assigned[id(node.value)] = target.id
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        func = node.func
+        if isinstance(func, ast.Name) and func.id in router_names:
+            pass
+        elif isinstance(func, ast.Attribute) and func.attr in {"Router", "Litestar", "Starlite"} and (dotted(func.value) or "").split(".")[0] in module_aliases:
+            pass
+        else:
+            continue
+        is_app = call_name(node) in {"Litestar", "Starlite"}
+        path_node = None if is_app else (node.args[0] if node.args else keyword(node, "path"))
+        path = str_const(path_node) or "" if path_node is not None else ""
+        members_node = keyword(node, "route_handlers")
+        if members_node is None and not is_app and len(node.args) > 1:
+            members_node = node.args[1]
+        if members_node is None and is_app and node.args:
+            members_node = node.args[0]
+        members = [name.split(".")[-1] for name in expr_names(members_node, limit=256)]
+        out.routers.append(
+            Router(file=out.rel, var=assigned.get(id(node)), path=path, members=members, guards=expr_names(keyword(node, "guards")))
+        )
+
+
+def _join(*parts: str) -> str:
+    pieces = [p.strip("/") for p in parts if p and p.strip("/")]
+    return "/" + "/".join(pieces) if pieces else "/"
+
+
+def resolve_litestar(files: list[LitestarFile]) -> list[LitestarRoute]:
+    """Join router and controller paths onto every handler, repo-wide."""
+    routers = [r for f in files for r in f.routers]
+    # member name → routers that list it
+    listed_by: dict[str, list[Router]] = {}
+    for router in routers:
+        for member in router.members:
+            listed_by.setdefault(member, []).append(router)
+    defined: dict[str, set[str]] = {}
+    for f in files:
+        for ctrl in f.controllers:
+            defined.setdefault(ctrl.name, set()).add(f.rel)
+        for handler in f.handlers:
+            defined.setdefault(handler.name, set()).add(f.rel)
+        for router in f.routers:
+            if router.var:
+                defined.setdefault(router.var, set()).add(f.rel)
+
+    def owners(name: str, file: str) -> list[Router]:
+        # A router listing `name` counts when it's in the same file or the name
+        # is defined exactly once in the repo (an unambiguous import).
+        unique = len(defined.get(name, ())) == 1
+        return [r for r in listed_by.get(name, []) if r.file == file or unique]
+
+    memo: dict[tuple[str, str], list[tuple[str, list[str]]]] = {}
+
+    def mounts(name: str, file: str, stack: frozenset = frozenset()) -> list[tuple[str, list[str]]]:
+        """(prefix, inherited guards) for each way `name` is mounted. Memoized;
+        a router cycle or a chain deeper than _MAX_ROUTER_DEPTH stops there."""
+        key = (name, file)
+        if key in memo:
+            return memo[key]
+        if key in stack or len(stack) >= _MAX_ROUTER_DEPTH:
+            return [("", [])]
+        result: list[tuple[str, list[str]]] = []
+        for router in owners(name, file):
+            parents = mounts(router.var, router.file, stack | {key}) if router.var else [("", [])]
+            for parent_prefix, parent_guards in parents:
+                result.append((_join(parent_prefix, router.path), parent_guards + router.guards))
+                if len(result) >= _MAX_PREFIXES:
+                    break
+            if len(result) >= _MAX_PREFIXES:
+                break
+        memo[key] = result = result or [("", [])]
+        return result
+
+    routes: list[LitestarRoute] = []
+
+    def emit(handler: Handler, prefix: str, ctrl_path: str, inherited: list[str]) -> None:
+        guards = inherited + handler.guards
+        if guards:
+            auth, evidence = "required", f"guards=[{', '.join(guards)}]"
+        elif handler.excluded:
+            auth, evidence = "anonymous", "exclude_from_auth=True"
+        else:
+            auth, evidence = "unknown", None
+        for hpath in handler.paths:
+            for method in handler.methods:
+                routes.append(
+                    LitestarRoute(
+                        path=_join(prefix, ctrl_path, hpath),
+                        method=method,
+                        file=handler.file,
+                        line=handler.line,
+                        auth=auth,
+                        guards=list(guards),
+                        evidence=evidence,
+                    )
+                )
+
+    for f in files:
+        for ctrl in f.controllers:
+            for prefix, inherited in mounts(ctrl.name, f.rel):
+                for handler in ctrl.handlers:
+                    emit(handler, prefix, ctrl.path, inherited + ctrl.guards)
+        for handler in f.handlers:
+            for prefix, inherited in (mounts(handler.name, f.rel) if handler.module_level else [("", [])]):
+                emit(handler, prefix, "", inherited)
+    # One handler mounted twice at the same path with different auth (a
+    # guarded and an unguarded router) collapses to one route downstream, so
+    # its auth isn't known.
+    auth_by_key: dict[tuple[str, str, str], set[str]] = {}
+    for route in routes:
+        auth_by_key.setdefault((route.path, route.method, route.file), set()).add(route.auth)
+    for route in routes:
+        if len(auth_by_key[(route.path, route.method, route.file)]) > 1:
+            route.auth, route.guards, route.evidence = "unknown", [], None
+    return routes
+
+
+__all__ = ["LitestarFile", "LitestarRoute", "parse_litestar", "resolve_litestar"]

attackmap_analyzer_python/sanic_routes.py

@@ -0,0 +1,77 @@
+"""Sanic ``@app.route(...)`` / ``@bp.websocket(...)`` decorators (#2).
+
+The verb decorators (``@app.get``) stay with the regex extractor. ``route``
+takes its verbs from ``methods=[...]`` and defaults to ``GET`` (Sanic's own
+default, and what core's ``@x.route`` pattern assumes, so the two analyzers'
+routes merge instead of duplicating). The receiver must be ``app``/``bp``/
+``blueprint`` or a name assigned from ``Sanic(...)`` / ``Blueprint(...)``.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from ._pyast import call_name, keyword, safe_parse, str_const
+
+_RECEIVERS = {"app", "bp", "blueprint"}
+
+
+def _normalize(path: str) -> str:
+    """Leading slash, no `//` runs: the shape core gives the same decorator."""
+    path = "/" + path.strip().lstrip("/")
+    while "//" in path:
+        path = path.replace("//", "/")
+    return path
+
+
+def _methods(node: ast.expr | None) -> list[str]:
+    """`methods=["GET", "post"]`, a tuple/set, or `HTTPMethod.DELETE` enums."""
+    if node is None:
+        return []
+    elts = node.elts if isinstance(node, (ast.List, ast.Tuple, ast.Set)) else [node]
+    out: list[str] = []
+    for elt in elts[:16]:
+        value = str_const(elt)
+        if value is None and isinstance(elt, ast.Attribute):
+            value = elt.attr  # HTTPMethod.DELETE
+        if value and value.isalpha():
+            out.append(value.upper())
+    return out
+
+
+def sanic_routes(content: str) -> list[tuple[str, str, int]] | None:
+    """[(path, method, line)], or ``None`` when the file can't be parsed."""
+    tree = safe_parse(content)
+    if tree is None:
+        return None
+    receivers = set(_RECEIVERS)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Assign) and call_name(node.value) in {"Sanic", "Blueprint"}:
+            receivers.update(t.id for t in node.targets if isinstance(t, ast.Name))
+    out: list[tuple[str, str, int]] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for dec in node.decorator_list:
+            if not (isinstance(dec, ast.Call) and isinstance(dec.func, ast.Attribute)):
+                continue
+            owner = dec.func.value
+            if not (isinstance(owner, ast.Name) and owner.id in receivers):
+                continue
+            kind = dec.func.attr
+            if kind not in {"route", "websocket"}:
+                continue
+            path = str_const(dec.args[0] if dec.args else keyword(dec, "uri"))
+            if path is None:
+                continue
+            path = _normalize(path)
+            if kind == "websocket":
+                out.append((path, "WS", dec.lineno))
+                continue
+            methods = _methods(keyword(dec, "methods")) or ["GET"]
+            for method in dict.fromkeys(methods):
+                out.append((path, method, dec.lineno))
+    return out
+
+
+__all__ = ["sanic_routes"]

attackmap_analyzer_python/tornado_routes.py

@@ -0,0 +1,182 @@
+"""Tornado URLSpec routing paired with RequestHandler methods (#2).
+
+``tornado.web.Application([(r"/users/(\\d+)", UserHandler), url(r"/x", X)])``
+(or a ``handlers = [...]`` list handed to it, or ``add_handlers``) maps a
+regex to a handler class; the HTTP methods are the ``get``/``post``/... the
+class defines. A ``WebSocketHandler`` subclass is a ``WS`` route. A handler
+that defines no verb itself (inherits them) is ``ANY``.
+
+A URL spec counts only when it sits in a list/tuple literal, its pattern
+starts with ``/``, and its handler is a known ``*Handler`` class (anywhere in
+the repo) or at least named like one. Route auth (#256): a verb method
+decorated with ``@tornado.web.authenticated`` is ``required``.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+from ._pyast import call_name, dotted, safe_parse, str_const
+
+_VERBS = ("get", "post", "put", "patch", "delete", "head", "options")
+_MAX_INHERIT = 3
+_MAX_SPECS = 5_000
+
+
+@dataclass
+class HandlerClass:
+    file: str
+    name: str
+    bases: list[str]
+    methods: dict[str, bool] = field(default_factory=dict)  # VERB → @authenticated
+    websocket: bool = False
+    direct: bool = False  # a base is named *Handler
+
+
+@dataclass
+class UrlSpec:
+    file: str
+    line: int
+    pattern: str
+    handler: str  # last dotted component of the handler expression
+
+
+@dataclass
+class TornadoFile:
+    rel: str
+    classes: list[HandlerClass] = field(default_factory=list)
+    specs: list[UrlSpec] = field(default_factory=list)
+
+
+@dataclass
+class TornadoRoute:
+    path: str
+    method: str
+    file: str
+    line: int
+    auth: str = "unknown"
+    guards: list[str] = field(default_factory=list)
+    evidence: str | None = None
+
+
+def parse_tornado(content: str, rel: str) -> TornadoFile | None:
+    tree = safe_parse(content)
+    if tree is None:
+        return None
+    out = TornadoFile(rel=rel)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            bases = [dotted(b) or "" for b in node.bases]
+            # Every class is recorded: one that subclasses RequestHandler only
+            # through a project base (`class Api(BaseView)`) is resolved later.
+            cls = HandlerClass(
+                file=rel,
+                name=node.name,
+                bases=[b.split(".")[-1] for b in bases if b],
+                websocket=any("WebSocket" in b for b in bases),
+                direct=any(b.endswith("Handler") for b in bases),
+            )
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and item.name in _VERBS:
+                    cls.methods[item.name.upper()] = any(
+                        (dotted(d) or "").split(".")[-1] == "authenticated" for d in item.decorator_list
+                    )
+            out.classes.append(cls)
+        elif isinstance(node, (ast.List, ast.Tuple)) and len(out.specs) < _MAX_SPECS:
+            for elt in node.elts:
+                spec = _spec(elt, rel)
+                if spec is not None:
+                    out.specs.append(spec)
+    return out
+
+
+def _spec(node: ast.expr, rel: str) -> UrlSpec | None:
+    if isinstance(node, ast.Tuple) and len(node.elts) >= 2:
+        pattern, handler = node.elts[0], node.elts[1]
+    elif isinstance(node, ast.Call) and call_name(node) in {"url", "URLSpec"} and len(node.args) >= 2:
+        pattern, handler = node.args[0], node.args[1]
+    else:
+        return None
+    text = str_const(pattern)
+    name = dotted(handler)
+    if text is None or name is None or not text.lstrip("^").startswith("/"):
+        return None
+    return UrlSpec(file=rel, line=node.lineno, pattern=text, handler=name.split(".")[-1])
+
+
+def _path(pattern: str) -> str:
+    path = pattern.lstrip("^")
+    while path.endswith("$") and not path.endswith("\\$"):
+        path = path[:-1]
+    return path or "/"
+
+
+def resolve_tornado(files: list[TornadoFile]) -> list[TornadoRoute]:
+    by_name: dict[str, list[HandlerClass]] = {}
+    for f in files:
+        for cls in f.classes:
+            by_name.setdefault(cls.name, []).append(cls)
+
+    def lookup(name: str, file: str) -> HandlerClass | None:
+        found = by_name.get(name, [])
+        same = [c for c in found if c.file == file]
+        if same:
+            return same[0]
+        return found[0] if len(found) == 1 else None
+
+    def verbs(cls: HandlerClass) -> tuple[dict[str, bool], bool, bool]:
+        """(verb → authenticated, websocket, is a handler) through up to
+        _MAX_INHERIT levels of bases."""
+        methods: dict[str, bool] = {}
+        websocket = cls.websocket
+        handler = cls.direct
+        seen: set[int] = set()
+        current: list[HandlerClass] = [cls]
+        for _ in range(_MAX_INHERIT + 1):
+            nxt: list[HandlerClass] = []
+            for c in current:
+                if id(c) in seen:
+                    continue
+                seen.add(id(c))
+                websocket = websocket or c.websocket
+                handler = handler or c.direct
+                for verb, authed in c.methods.items():
+                    methods.setdefault(verb, authed)
+                for base in c.bases:
+                    parent = lookup(base, c.file)
+                    if parent is not None:
+                        nxt.append(parent)
+            current = nxt
+        return methods, websocket, handler
+
+    routes: list[TornadoRoute] = []
+    for f in files:
+        for spec in f.specs:
+            cls = lookup(spec.handler, spec.file)
+            methods, websocket, handler = verbs(cls) if cls is not None else ({}, False, False)
+            if not handler and not spec.handler.endswith("Handler"):
+                continue
+            path = _path(spec.pattern)
+            if websocket:
+                routes.append(TornadoRoute(path, "WS", spec.file, spec.line))
+                continue
+            if not methods:
+                routes.append(TornadoRoute(path, "ANY", spec.file, spec.line))
+                continue
+            for verb in sorted(methods):
+                if methods[verb]:
+                    routes.append(
+                        TornadoRoute(
+                            path, verb, spec.file, spec.line,
+                            auth="required",
+                            guards=["@tornado.web.authenticated"],
+                            evidence=f"@tornado.web.authenticated on {spec.handler}.{verb.lower()}",
+                        )
+                    )
+                else:
+                    routes.append(TornadoRoute(path, verb, spec.file, spec.line))
+    return routes
+
+
+__all__ = ["TornadoFile", "TornadoRoute", "parse_tornado", "resolve_tornado"]