attackmap 0.6.4__py3-none-any.whl

attackmap/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.6.4"

attackmap/analyzer.py

@@ -0,0 +1,449 @@
+from __future__ import annotations
+
+import re
+from collections import Counter
+
+import networkx as nx
+
+from .md import md_text
+from .models import AttackSurface, AuthHint, Route, ScanResult
+from .webhook_verification import assess_webhook_surfaces, reclaim_receivers, webhook_management_routes
+
+
+# Bounded line window used to attribute auth hints to a specific route
+# handler. Chosen so a hint at the top of the handler body still lands
+# on the route even if the handler is 40 lines long. Bigger than a typical
+# handler; smaller than the distance between two adjacent routes. See #41
+# / Bluesky FINDINGS §55 for the noise problem this fixes.
+_ROUTE_AUTH_LINE_WINDOW = 40
+
+# An authentication path segment (#340): the term starts the segment and is
+# followed by the end of the segment, a non-letter (`login-form`, `oauth2`,
+# `auth_callback`, `authCallback`) or one of its own word forms
+# (`authenticate`, `authorize`, `sessions`, `tokens`). A substring match made
+# `/api/authorities` and `/authors` auth routes.
+_AUTH_SEGMENT = re.compile(
+    r"\A(?i:login|signin|signup|auth|session|token|oauth)"
+    r"(?i:s|enticate|entication|orize|orization)?"
+    r"(?![a-z])"
+)
+
+
+def is_auth_path(path: str) -> bool:
+    """Whether a route path has an authentication segment (see `_AUTH_SEGMENT`)."""
+    return any(_AUTH_SEGMENT.match(segment) for segment in path.split("/")[1:] if segment)
+
+
+# Authentication entry points (#328). The route that authenticates the caller
+# has to be reachable without authentication, so `POST /admin/login` is an
+# `auth` surface (brute force, lockout), not an unguarded admin action. Matched
+# on whole path segments, and only when every segment before the action is
+# admin/auth vocabulary: `/admin/users/:id/logout` (forcing another user out)
+# and `/admin/login-as/:id` (impersonation) stay admin actions.
+_LOGIN_SEGMENTS = frozenset({
+    "login", "log-in", "log_in", "logon", "signin", "sign-in", "sign_in", "authenticate",
+    "logout", "log-out", "log_out", "logoff", "signout", "sign-out", "sign_out",
+    "forgot-password", "forgot_password", "forgotpassword", "reset-password", "reset_password",
+    "resetpassword", "password-reset", "password_reset", "passwordreset",
+})
+# `/admin/password/reset`, `/admin/password/email` (Laravel).
+_PASSWORD_ACTIONS = frozenset({"reset", "forgot", "email"})
+# Token and callback actions count only under an auth segment
+# (`/admin/auth/token`, `/admin/oauth/callback`): `/admin/api/token` may mint
+# API tokens for others.
+_TOKEN_SEGMENTS = frozenset({"token", "refresh", "refresh-token", "refresh_token", "callback"})
+_AUTH_SEGMENTS = frozenset({
+    "auth", "authentication", "oauth", "oauth2", "oidc", "openid", "sso", "saml", "jwt", "token",
+})
+# Exact words only: `administrators`, `admin-users`, `accounts`, `staff` or
+# `sessions` name a resource an admin acts on (`/admin/accounts/reset-password`
+# resets someone else's password).
+_ADMIN_PREFIX_SEGMENTS = frozenset({
+    "admin", "manage", "root", "api", "dashboard", "backend", "backoffice", "panel", "console", "password",
+})
+_VERSION_SEGMENT_RE = re.compile(r"v\d{1,3}")
+_PLAIN_SEGMENT_RE = re.compile(r"[a-z0-9_-]{1,40}")
+_ENTRY_SUFFIXES = (".php", ".aspx", ".asp", ".jsp", ".html", ".htm", ".do")
+
+
+def _prefix_segment(segment: str) -> bool:
+    return (
+        segment in _ADMIN_PREFIX_SEGMENTS
+        or segment in _AUTH_SEGMENTS
+        or _VERSION_SEGMENT_RE.fullmatch(segment) is not None
+    )
+
+
+def is_auth_entry_point(path: str) -> bool:
+    """Whether `path` is a login/logout/password-reset/token/OAuth-callback
+    endpoint rather than an action behind authentication (#328)."""
+    segments = [seg for seg in path.lower().split("?", 1)[0].split("/") if seg]
+    if not segments or len(segments) > 8:
+        return False
+    action = segments[-1]
+    for suffix in _ENTRY_SUFFIXES:
+        if action.endswith(suffix):
+            action = action[: -len(suffix)]
+            break
+    before = segments[:-1]
+    if action in _LOGIN_SEGMENTS:
+        pass
+    elif action in _PASSWORD_ACTIONS:
+        if not before or before[-1] != "password":
+            return False
+    elif action in _TOKEN_SEGMENTS:
+        # One provider segment may sit before a callback: /admin/auth/google/callback.
+        if action == "callback" and len(before) >= 2 and before[-2] in _AUTH_SEGMENTS:
+            if _PLAIN_SEGMENT_RE.fullmatch(before[-1]) is None:
+                return False
+            before = before[:-1]
+        if not any(seg in _AUTH_SEGMENTS for seg in before):
+            return False
+    else:
+        return False
+    return all(_prefix_segment(seg) for seg in before)
+
+
+def _auth_hints_for_route(
+    route: Route,
+    scan_auth_hints: list[AuthHint],
+    hints_by_file: dict[str, list[AuthHint]],
+) -> list[str]:
+    """Return the auth-hint strings that plausibly attach to `route`.
+
+    If the route has a known `line`, only hints in the same file whose
+    line falls within `_ROUTE_AUTH_LINE_WINDOW` above OR below the
+    route are counted. If the route lacks line info (framework
+    config-driven routes commonly do), fall back to file-scoped
+    attribution — same as the old behavior.
+
+    Deliberately no global fallback: the "if no hints in this file,
+    inherit every auth hint in the repo" behavior was the biggest
+    noise source per FINDINGS §55. Downstream code handles empty
+    auth_signals correctly.
+    """
+    file_hints = hints_by_file.get(route.file, [])
+    if not file_hints:
+        return []
+    if route.line is None:
+        return sorted({hint.hint for hint in file_hints})
+    lo = route.line - _ROUTE_AUTH_LINE_WINDOW
+    hi = route.line + _ROUTE_AUTH_LINE_WINDOW
+    windowed = {
+        hint.hint
+        for hint in file_hints
+        if hint.line is None or lo <= hint.line <= hi
+    }
+    if windowed:
+        return sorted(windowed)
+    # Hints exist in the file but none are within the window. That's the
+    # signal-to-noise fix: the previous route in this file had auth code,
+    # this one doesn't. Return empty — the surface's rationale below will
+    # say "no auth indicators near this route".
+    return []
+
+
+def identify_attack_surfaces(scan: ScanResult) -> list[AttackSurface]:
+    surfaces: list[AttackSurface] = []
+    auth_hints_by_file: dict[str, list[AuthHint]] = {}
+    for hint in scan.auth_hints:
+        auth_hints_by_file.setdefault(hint.file, []).append(hint)
+
+    supporting_hints_by_file: dict[str, set[str]] = {}
+    all_supporting_hints = [
+        *scan.auth_hints,
+        *scan.service_hints,
+        *scan.edge_hints,
+        *scan.entrypoint_hints,
+        *scan.protocol_hints,
+        *scan.framework_hints,
+    ]
+
+    for hint in all_supporting_hints:
+        supporting_hints_by_file.setdefault(hint.file, set()).add(hint.hint)
+
+    management = webhook_management_routes(scan)
+    management_surfaces: list[tuple[AttackSurface, str]] = []
+
+    for route in scan.routes:
+        path_lower = route.path.lower()
+        management_reason = management.get((route.method, route.path, route.file))
+        # A plugin-declared route auth state (#256) beats the ±40-line file
+        # window, which lets a route inherit its neighbour's guard.
+        if route.auth == "required":
+            auth_signals = sorted(set(route.guards)) or ["plugin_declared_auth"]
+        elif route.auth == "anonymous":
+            auth_signals = []
+        else:
+            auth_signals = _auth_hints_for_route(route, scan.auth_hints, auth_hints_by_file)
+        supporting_signals = sorted(supporting_hints_by_file.get(route.file, set())) or sorted(
+            {hint.hint for hint in all_supporting_hints}
+        )
+        rationale: list[str] = []
+        exposure: AttackSurface["exposure"] = "public"
+        internal_handler_markers = {
+            "handler_visibility:internal",
+            "handler_type:internal_handler",
+            "service_role:worker",
+            "service_role:event_consumer",
+            "service_role:internal_handler",
+        }
+        has_explicit_public_visibility = "handler_visibility:public" in supporting_signals
+        has_internal_handler_hint = any(marker in supporting_signals for marker in internal_handler_markers) and not has_explicit_public_visibility
+
+        admin_path = any(segment in path_lower for segment in ("/admin", "/manage", "/root"))
+        if management_reason is not None:
+            # CRUD for the app's own outgoing webhooks is an ordinary route (#365).
+            rationale.append(
+                f"Manages the application's own webhook configuration ({management_reason}); "
+                "not an inbound event receiver."
+            )
+        if "webhook" in path_lower and management_reason is None:
+            category = "webhook"
+            risk = "high"
+            rationale.append("Webhook endpoints commonly accept attacker-controlled input from the internet.")
+        elif admin_path and not is_auth_entry_point(path_lower):
+            category = "admin"
+            risk = "high"
+            rationale.append("Administrative routes are high-value targets because they expose privileged actions.")
+        elif admin_path or is_auth_path(route.path):  # an admin path here is its login/logout/token endpoint (#328)
+            category = "auth"
+            risk = "high" if not auth_signals else "medium"
+            rationale.append("Authentication endpoints are common targets for brute force, token abuse, and session attacks.")
+        elif any(segment in path_lower for segment in ("/upload", "/import", "/file")):
+            category = "upload"
+            risk = "high"
+            rationale.append("Upload and import flows often lead to parser abuse or untrusted file handling.")
+        elif any(segment in path_lower for segment in ("/internal", "/debug")):
+            category = "internal"
+            exposure = "internal"
+            risk = "medium"
+            rationale.append("Internal or debug routes are risky if they become reachable from untrusted networks.")
+        elif any(segment in path_lower for segment in ("/health", "/ready", "/live", "/metrics")):
+            category = "health"
+            risk = "low"
+            rationale.append("Operational endpoints reveal limited attack surface but may disclose useful reconnaissance details.")
+        else:
+            category = "public_api"
+            risk = "medium" if scan.databases or scan.external_calls else "low"
+            rationale.append("Public application routes are initial footholds for probing input handling and authorization gaps.")
+
+        if has_internal_handler_hint and category not in {"admin", "auth", "webhook"}:
+            exposure = "internal"
+            if category == "public_api":
+                category = "internal"
+            risk = "medium" if category != "health" else "low"
+            rationale.append("Service-level handler metadata suggests this route is internal-facing (worker/event/internal handler path).")
+
+        if auth_signals:
+            rationale.append(f"Auth indicators observed: {', '.join(auth_signals)}.")
+        else:
+            rationale.append("No auth indicators were observed near this route.")
+
+        if scan.databases:
+            rationale.append("Datastore usage was detected elsewhere in the repository, so route-to-data flows are plausible.")
+        if scan.external_calls:
+            rationale.append("Outbound HTTP calls were detected, creating trust boundaries to third-party systems.")
+
+        surface = AttackSurface(
+            route=route.path,
+            method=route.method,
+            file=route.file,
+            line=route.line,
+            category=category,
+            exposure=exposure,
+            risk=risk,
+            auth_signals=auth_signals,
+            data_store_interaction=bool(scan.databases),
+            outbound_integration=bool(scan.external_calls),
+            rationale=rationale,
+            )
+        surfaces.append(surface)
+        if management_reason is not None:
+            management_surfaces.append((surface, category))
+
+    # Precision first: a management candidate whose handler reaches signature
+    # verification is a receiver after all.
+    for surface in reclaim_receivers(scan, [s for s, _ in management_surfaces]):
+        surface.category = "webhook"
+        surface.risk = "high"
+        surface.exposure = "public"
+        surface.rationale = [
+            r for r in surface.rationale if not r.startswith("Manages the application's own webhook")
+        ]
+        surface.rationale.insert(0, "Webhook endpoints commonly accept attacker-controlled input from the internet.")
+
+    assess_webhook_surfaces(scan, surfaces)
+    return surfaces
+
+
+def summarize_architecture(scan: ScanResult, graph: nx.DiGraph) -> str:
+    route_count = len(scan.routes)
+    dbs = sorted({db.kind for db in scan.databases})
+    external_targets = sorted({call.target for call in scan.external_calls})
+    auth_summary = sorted({hint.hint for hint in scan.auth_hints})
+    secret_count = len(scan.secret_hints)
+    graph_edges = sorted(
+        f"{source} -> {target} ({data['relation']})"
+        for source, target, data in graph.edges(data=True)
+        if "relation" in data
+    )
+
+    lines = [
+        "# Architecture Summary",
+        "",
+        "## Overview",
+        f"- AttackMap inferred a {'web-facing' if route_count else 'non-web'} repository with {route_count} entry point{'s' if route_count != 1 else ''}.",
+        f"- Files scanned: {scan.files_scanned}",
+        f"- Languages detected: {', '.join(scan.languages) if scan.languages else 'none'}",
+        f"- Inferred entry points: {route_count}",
+        f"- Datastores detected: {', '.join(dbs) if dbs else 'none'}",
+        f"- External targets detected: {', '.join(external_targets) if external_targets else 'none'}",
+        f"- Auth hints observed: {', '.join(auth_summary) if auth_summary else 'none'}",
+        f"- Secret-like env references: {secret_count}",
+    ]
+
+    if scan.routes:
+        common = Counter(route.file for route in scan.routes).most_common(3)
+        lines.extend(
+            [
+                "",
+                "## Entry Point Concentration",
+                *[f"- {file}: {count} routes" for file, count in common],
+            ]
+        )
+        busiest_file, busiest_count = common[0]
+        lines.extend(
+            [
+                "",
+                "## Likely Review Starting Point",
+                f"- Start with `{busiest_file}`. It contains {busiest_count} of the detected routes and is the fastest place to validate exposure and trust boundaries.",
+            ]
+        )
+
+    if graph_edges:
+        lines.extend(
+            [
+                "",
+                "## Inferred Trust Boundaries",
+                *[f"- {edge}" for edge in graph_edges[:10]],
+            ]
+        )
+
+    lines.extend(
+        [
+            "",
+            "## Analyst Notes",
+            "- AttackMap inferred this system shape heuristically from framework patterns, dependencies, and code hints.",
+            "- Treat this as an initial map for security review, then validate the highest-risk routes and boundaries manually.",
+        ]
+    )
+
+    return "\n".join(lines)
+
+
+def _risk_rank(value: str) -> int:
+    return {"high": 0, "medium": 1, "low": 2}.get(value, 3)
+
+
+def _surface_summary(surface: AttackSurface) -> str:
+    traits: list[str] = []
+    if surface.auth_signals:
+        traits.append(f"auth signals: {', '.join(md_text(signal) for signal in surface.auth_signals)}")
+    else:
+        traits.append("no auth signals observed")
+
+    if surface.data_store_interaction:
+        traits.append("data store reachable")
+    if surface.outbound_integration:
+        traits.append("external trust boundary")
+    if surface.webhook_verification is not None:
+        traits.append(f"webhook signature: {surface.webhook_verification.state.replace('_', ' ')}")
+
+    return "; ".join(traits)
+
+
+def _surface_label(surface: AttackSurface) -> str:
+    """``METHOD route (file)`` with the repo-derived parts escaped: a route
+    string is attacker-controlled text in a scanned repository."""
+    return f"{md_text(surface.method)} {md_text(surface.route)} ({md_text(surface.file)})"
+
+
+def summarize_attack_surface(scan: ScanResult, attack_surfaces: list[AttackSurface] | None = None) -> str:
+    surfaces = attack_surfaces if attack_surfaces is not None else identify_attack_surfaces(scan)
+    ordered_surfaces = sorted(surfaces, key=lambda surface: (_risk_rank(surface.risk), surface.route, surface.method))
+    external_targets = sorted({call.target for call in scan.external_calls})
+    auth_summary = sorted({a.hint for a in scan.auth_hints})
+    high_risk = [surface for surface in ordered_surfaces if surface.risk == "high"]
+    auth_and_admin = [surface for surface in ordered_surfaces if surface.category in {"auth", "admin"}]
+    public_entry_points = [surface for surface in ordered_surfaces if surface.exposure == "public" and surface.category not in {"auth", "admin", "health"}]
+    operational_routes = [surface for surface in ordered_surfaces if surface.category in {"health", "internal"}]
+
+    lines = [
+        "# Attack Surface",
+        "",
+        "## Priority View",
+        f"- High-risk entry points: {len(high_risk)}",
+        f"- Public routes detected: {sum(1 for surface in ordered_surfaces if surface.exposure == 'public')}",
+        f"- Internal-only routes detected: {sum(1 for surface in ordered_surfaces if surface.exposure == 'internal')}",
+        f"- Routes with likely data access: {sum(1 for surface in ordered_surfaces if surface.data_store_interaction)}",
+        f"- Routes with outbound trust boundaries: {sum(1 for surface in ordered_surfaces if surface.outbound_integration)}",
+    ]
+
+    lines.extend(["", "## Highest-Risk Entry Points"])
+    if high_risk:
+        for surface in high_risk[:10]:
+            lines.append(f"- {_surface_label(surface)} -> {surface.category}; {_surface_summary(surface)}")
+    else:
+        lines.append("- No high-risk entry points were classified")
+
+    lines.extend(["", "## Auth And Privileged Routes"])
+    if auth_and_admin:
+        for surface in auth_and_admin[:10]:
+            lines.append(
+                f"- [{surface.risk.upper()}] {_surface_label(surface)} "
+                f"-> {surface.category}, {surface.exposure}; {_surface_summary(surface)}"
+            )
+    else:
+        lines.append("- No dedicated auth or admin routes were classified")
+
+    lines.extend(["", "## Public Application Routes"])
+    if public_entry_points:
+        for surface in public_entry_points[:10]:
+            lines.append(
+                f"- [{surface.risk.upper()}] {_surface_label(surface)} "
+                f"-> {surface.category}, {surface.exposure}; {_surface_summary(surface)}"
+            )
+    else:
+        lines.append("- No additional public application routes were classified")
+
+    lines.extend(["", "## Operational And Internal Routes"])
+    if operational_routes:
+        for surface in operational_routes[:10]:
+            lines.append(
+                f"- [{surface.risk.upper()}] {_surface_label(surface)} "
+                f"-> {surface.category}, {surface.exposure}; {_surface_summary(surface)}"
+            )
+    else:
+        lines.append("- No health, metrics, debug, or internal routes were classified")
+
+    lines.extend(["", "## External Dependencies"])
+    if external_targets:
+        for target in external_targets[:25]:
+            lines.append(f"- {md_text(target)}")
+    else:
+        lines.append("- No explicit outbound HTTP calls detected")
+
+    lines.extend(["", "## Secrets And Auth Hints"])
+    if scan.secret_hints:
+        for hint in scan.secret_hints[:25]:
+            lines.append(f"- Secret-related env usage: {md_text(hint.name)} ({md_text(hint.file)})")
+    else:
+        lines.append("- No secret-like environment variable usage detected")
+
+    if auth_summary:
+        lines.append(f"- Auth-related keywords observed: {', '.join(md_text(hint) for hint in auth_summary)}")
+    else:
+        lines.append("- No auth-related keywords observed")
+
+    return "\n".join(lines)

attackmap/analyzer_contracts.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Protocol
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from .recon_models import ScanResult
+
+# Phase-1 shared repository analyzer contract.
+# Keep AnalyzerResult mapped to ScanResult for backward compatibility.
+AnalyzerResult = ScanResult
+
+# `name` must be a slug: lowercase letters, digits, hyphens. This is the
+# entry-point key AttackMap uses to identify the analyzer, so it needs
+# to be safe in URLs, filesystem paths, and CLI arguments.
+_ANALYZER_NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
+
+class AnalyzerMetadata(BaseModel):
+    """Static, self-describing metadata every analyzer exposes.
+
+    Every analyzer plugin ships a `metadata: AnalyzerMetadata` attribute so
+    core (and future tooling) can reason about the plugin without loading
+    or running it. The field set is stable: adding fields is safe on a
+    minor release, removing or renaming is a major-version break.
+    """
+
+    name: str = Field(
+        description="Slug identifier. Must match /[a-z0-9][a-z0-9-]*/. "
+        "This is the entry-point key AttackMap uses to select the analyzer "
+        "(e.g. from --module) and to attribute signals via provenance.",
+    )
+    display_name: str = Field(
+        default="",
+        description="Human-friendly name shown in `attackmap modules` output "
+        "and reports. Defaults to `name` when omitted.",
+    )
+    version: str = Field(
+        default="0.1.0",
+        description="Semver of the analyzer plugin itself (not attackmap). "
+        "Should match the analyzer package's pyproject.toml version.",
+    )
+    description: str = Field(
+        default="",
+        description="One-sentence summary of what the analyzer detects. "
+        "Shown in module listings and matter briefings.",
+    )
+    scope: str = Field(
+        default="",
+        description="One-sentence description of the kinds of repositories "
+        "this analyzer targets (e.g. 'Node/TypeScript backend service repos').",
+    )
+    targets: list[str] = Field(
+        default_factory=list,
+        description="Frameworks, protocols, or platform tokens this analyzer "
+        "specializes in (e.g. ['react-native', 'expo']). Used with `languages` "
+        "to compute `ecosystems`.",
+    )
+    languages: list[str] = Field(
+        default_factory=list,
+        description="Programming languages this analyzer parses (e.g. "
+        "['javascript', 'typescript']). Used with `targets` to compute "
+        "`ecosystems`.",
+    )
+    priority: int = Field(
+        default=100,
+        ge=0,
+        description="Run order across built-ins and plugins: lower runs first, "
+        "ties broken by analyzer name. Merge is first-seen-wins in that order, "
+        "so a lower value also wins a duplicate signal. Convention: "
+        "0-49 is broad language analyzers (python, node-service); 50-149 is "
+        "framework analyzers (spring, laminas); 150+ is app-specific "
+        "analyzers (omeka-s).",
+    )
+    experimental: bool = Field(
+        default=True,
+        description="Whether this analyzer is still stabilizing. Doesn't "
+        "affect execution, just how core presents it in listings. "
+        "Experimental analyzers should normally leave enabled_by_default False.",
+    )
+    enabled_by_default: bool = Field(
+        default=False,
+        description="Whether to run this analyzer without an explicit "
+        "--module flag. False makes it opt-in: it runs only when selected "
+        "with -m (detect() still gates it), and the CLI notes when an opt-in "
+        "analyzer matched but didn't run. Broad language analyzers set this "
+        "True; specialty framework/app analyzers usually leave it False.",
+    )
+
+    @field_validator("name")
+    @classmethod
+    def _validate_name(cls, value: str) -> str:
+        if not value:
+            raise ValueError("AnalyzerMetadata.name must not be empty")
+        if not _ANALYZER_NAME_PATTERN.match(value):
+            raise ValueError(
+                f"AnalyzerMetadata.name {value!r} must match "
+                f"/{_ANALYZER_NAME_PATTERN.pattern}/ — lowercase letters, "
+                f"digits, and hyphens only, starting with a letter or digit."
+            )
+        return value
+
+    @field_validator("version")
+    @classmethod
+    def _validate_version(cls, value: str) -> str:
+        if not value:
+            raise ValueError("AnalyzerMetadata.version must not be empty")
+        return value
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_legacy_ecosystems(cls, value: object) -> object:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        # Backward-compat: older call sites may pass ecosystems directly.
+        # Use it as a fallback source for languages when newer fields are omitted.
+        ecosystems = payload.pop("ecosystems", None)
+        if ecosystems and not payload.get("languages") and not payload.get("targets"):
+            payload["languages"] = list(ecosystems)
+        if not payload.get("display_name") and payload.get("name"):
+            payload["display_name"] = str(payload["name"])
+        return payload
+
+    @property
+    def ecosystems(self) -> tuple[str, ...]:
+        """Deduplicated tuple of languages + targets, lowercased.
+
+        Convenience view for callers that don't care about the language vs
+        target distinction (e.g. picking analyzers by ecosystem token).
+        """
+        values = [*self.languages, *self.targets]
+        seen: set[str] = set()
+        ordered: list[str] = []
+        for value in values:
+            lowered = value.lower()
+            if lowered in seen:
+                continue
+            seen.add(lowered)
+            ordered.append(lowered)
+        return tuple(ordered)
+
+
+class AnalyzerRepositoryModule(BaseModel):
+    analyzer_name: str
+    repo_name: str
+    web_url: str
+
+
+class AnalyzerProtocol(Protocol):
+    metadata: AnalyzerMetadata
+
+    @property
+    def name(self) -> str: ...
+
+    def detect(self, root: str | Path) -> bool: ...
+
+    def analyze(self, root: str | Path) -> AnalyzerResult: ...
+
+
+__all__ = [
+    "AnalyzerResult",
+    "AnalyzerMetadata",
+    "AnalyzerRepositoryModule",
+    "AnalyzerProtocol",
+    "normalize_analyzer_metadata",
+]
+
+
+def normalize_analyzer_metadata(value: object) -> AnalyzerMetadata:
+    if isinstance(value, AnalyzerMetadata):
+        return value
+    if isinstance(value, dict):
+        return AnalyzerMetadata.model_validate(value)
+
+    payload: dict[str, object] = {}
+    for key in (
+        "name",
+        "display_name",
+        "version",
+        "description",
+        "scope",
+        "targets",
+        "languages",
+        "priority",
+        "experimental",
+        "enabled_by_default",
+        "ecosystems",
+    ):
+        if hasattr(value, key):
+            payload[key] = getattr(value, key)
+    return AnalyzerMetadata.model_validate(payload)