attackmap 0.6.4__py3-none-any.whl

attackmap/models.py

@@ -0,0 +1,1284 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal, get_args
+
+from pydantic import BaseModel, Field, model_validator
+
+from .redact import redact_list, redact_text
+
+
+# Provenance field. Present on every analyzer-emitted signal so downstream
+# consumers can trace a signal back to the analyzer that produced it.
+# Excluded from serialization by default (see #14) so JSON/CLI reports are
+# byte-for-byte unchanged; access it via Python attribute for debugging,
+# confidence scoring, or future finder logic.
+_PROVENANCE_FIELD = Field(default=None, exclude=True, repr=False)
+
+
+RouteAuth = Literal["required", "anonymous", "unknown"]
+
+
+# Package ecosystems a `DependencyHint` / `Vulnerability` may carry (#255).
+# Exported from `attackmap.sdk`; `cve.py` maps each to its OSV.dev ecosystem
+# (or marks it inventory-only when OSV has none).
+DependencyEcosystem = Literal[
+    "pypi",
+    "npm",
+    "go",
+    "cargo",
+    "composer",
+    "swiftpm",
+    "maven",
+    "nuget",
+    "conan",
+    "vcpkg",
+    # CMake `FetchContent` / `find_package` dependencies (#191): no package
+    # registry behind them, so inventory only (never CVE-matched).
+    "cmake",
+    "gem",
+    "cocoapods",
+    # Carthage pins git repositories (`github "owner/repo" "1.2.3"`); CVE-matched
+    # like SwiftPM, by source URL (#188).
+    "carthage",
+    "hex",
+    "pub",
+]
+DEPENDENCY_ECOSYSTEMS: tuple[str, ...] = get_args(DependencyEcosystem)
+
+
+class Route(BaseModel):
+    path: str
+    method: str = "ANY"
+    file: str
+    line: int | None = None
+    source_analyzer: str | None = _PROVENANCE_FIELD
+    # Route-level auth as the plugin resolved it (#256): `required` (a guard
+    # such as [Authorize] / @PreAuthorize / an auth middleware applies),
+    # `anonymous` (explicitly public, e.g. [AllowAnonymous]), or `unknown`
+    # (not determined — core falls back to its own resolution).
+    auth: RouteAuth = "unknown"
+    # Names of the guards that apply, e.g. ["[Authorize(Policy=Admin)]"].
+    guards: list[str] = Field(default_factory=list)
+    # Source text that established `auth` (redacted like other evidence).
+    guard_evidence: str | None = None
+
+    @model_validator(mode="after")
+    def _redact_guard_evidence(self) -> "Route":
+        if self.guard_evidence:
+            object.__setattr__(self, "guard_evidence", redact_text(self.guard_evidence))
+        return self
+
+
+# Fields that carry text copied out of the scanned repository. Every model
+# with one of these redacts it at construction time (#235), so no detector —
+# core or plugin — can put a raw credential into a report, SARIF, PR comment
+# or LLM pack.
+_EVIDENCE_TEXT_FIELDS = ("evidence_text", "db_evidence", "sanitizer_evidence", "target")
+_EVIDENCE_LIST_FIELDS = ("evidence",)
+
+
+class _RedactedEvidence(BaseModel):
+    @model_validator(mode="after")
+    def _redact_evidence(self):  # type: ignore[no-untyped-def]
+        fields = type(self).model_fields
+        for name in _EVIDENCE_TEXT_FIELDS:
+            if name in fields:
+                value = getattr(self, name)
+                if isinstance(value, str):
+                    redacted = redact_text(value)
+                    if redacted != value:
+                        object.__setattr__(self, name, redacted)
+        for name in _EVIDENCE_LIST_FIELDS:
+            if name in fields:
+                value = getattr(self, name)
+                if isinstance(value, list) and value and all(isinstance(v, str) for v in value):
+                    redacted_list = redact_list(value)
+                    if redacted_list != value:
+                        object.__setattr__(self, name, redacted_list)
+        return self
+
+
+class ExternalCall(_RedactedEvidence):
+    target: str
+    file: str
+    line: int | None = None
+    # HTTP verb of the outbound call, upper-cased (GET/POST/…), when the call
+    # syntax carries one (`requests.get`, `axios.post`). `None` when unknown
+    # (e.g. bare `fetch(url)`). Used by cross-repo contract linking (#146b) to
+    # match an outbound call to another repo's route by method + path.
+    method: str | None = None
+    evidence_text: str | None = None
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class DatabaseHint(_RedactedEvidence):
+    kind: str
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class AuthHint(_RedactedEvidence):
+    hint: str
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    confidence: float = 0.7
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class ServiceHint(_RedactedEvidence):
+    hint: str
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    confidence: float = 0.7
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class EdgeHint(_RedactedEvidence):
+    hint: str
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    confidence: float = 0.7
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class EntrypointHint(_RedactedEvidence):
+    hint: str
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    confidence: float = 0.7
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class ProtocolHint(_RedactedEvidence):
+    hint: str
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    confidence: float = 0.7
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class FrameworkHint(_RedactedEvidence):
+    hint: str
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    confidence: float = 0.7
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class SecretHint(_RedactedEvidence):
+    name: str
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    confidence: float = 0.85
+    source_analyzer: str | None = _PROVENANCE_FIELD
+    # Optional classification. `env_reference` means we spotted a call
+    # like `os.getenv("API_KEY")` — the value is at runtime. Anything
+    # else identifies a literal secret pasted directly into code or
+    # config (#39). Consumers can elevate hardcoded-literal findings
+    # since exposure is broader than env references.
+    kind: str = "env_reference"
+
+
+class SecretHistoryHit(_RedactedEvidence):
+    """A hard-coded secret found in git history (#252, ``--secrets-history``).
+
+    ``name`` is the masked value; ``introduced_in`` is the oldest scanned
+    commit that added it; ``still_in_head`` is False when a later commit
+    removed it from the file (it remains in every clone's history).
+    """
+
+    name: str
+    kind: str
+    file: str
+    line: int | None = None
+    introduced_in: str
+    still_in_head: bool
+    evidence_text: str | None = None
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class DependencyHint(_RedactedEvidence):
+    """A single third-party dependency declared in a manifest or lockfile.
+
+    Manifests (#48) carry version *ranges* verbatim (``^4.16.0``, ``>=2,<3``,
+    ``latest``) and only direct dependencies. Lockfiles (#143) carry *exact*
+    resolved versions and the full transitive tree — those hints set
+    ``resolved=True`` and populate ``direct`` / ``via``.
+    """
+
+    name: str
+    version: str
+    # One of `DEPENDENCY_ECOSYSTEMS`, typed `str` so a plugin built against a
+    # newer core still validates here: core drops a hint with an ecosystem it
+    # doesn't know (noted under `analyzer_errors`) and keeps the rest.
+    ecosystem: str = Field(min_length=1, max_length=32)
+    file: str
+    line: int | None = None
+    # dev / build-only dependency (``devDependencies``, ``require-dev``,
+    # PEP-621 ``optional-dependencies[dev]``). Runtime consumers weight
+    # these differently: a dev-time RCE still matters, but a dev-only
+    # dep isn't part of the shipped attack surface.
+    dev: bool = False
+    # Lockfile-sourced provenance (#143). ``resolved`` marks an exact pinned
+    # version (skip range-guessing in the CVE lookup). ``direct`` is False for
+    # a transitive dependency; ``via`` is its resolution path from a direct
+    # dependency, e.g. ``"express > body-parser > qs"``.
+    resolved: bool = False
+    direct: bool = True
+    via: str | None = None
+    evidence_text: str | None = None
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+# Kinds of `CodeWeakness` this core turns into findings (#77, #189).
+CodeWeaknessKind = Literal[
+    "prototype_pollution",
+    "mass_assignment",
+    "jwt_weakness",
+    "jwt_alg_confusion",
+    "jwt_unverified_decode",
+    "jwt_claims_unchecked",
+    "jwt_header_trust",
+    "jwt_weak_secret",
+    "oauth_missing_state",
+    "oauth_implicit_flow",
+    "oauth_redirect_uri_loose",
+    "oauth_missing_pkce",
+    "session_fixation",
+    "session_weak_secret",
+    "xxe",
+    "redos",
+    "insecure_upload",
+    "graphql_exposure",
+    "graphql_no_query_limits",
+    "graphql_batching",
+    "prompt_injection_attempt",
+    # Native (C/C++) memory-safety and command-exec sinks (#189), emitted
+    # by the C/C++ analyzer plugins. See `NATIVE_WEAKNESS_KINDS`.
+    "unbounded_copy",
+    "format_string",
+    "native_command_exec",
+    "tainted_copy_length",
+    "alloc_size_overflow",
+]
+
+
+class CodeWeakness(_RedactedEvidence):
+    """A novel vulnerability-class weakness in source (#77).
+
+    Emitted by the built-in `weaknesses` finder — bug classes beyond the
+    taint/crypto/web-hardening families, detected from concrete risky
+    constructs (not absence).
+    """
+
+    # One of `CODE_WEAKNESS_KINDS`, typed `str` so a plugin built against a
+    # newer core still validates here: core drops a record with a kind it
+    # doesn't know (noted under `analyzer_errors`) and keeps the rest (#189).
+    kind: str = Field(min_length=1, max_length=64)
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    severity: Literal["low", "medium", "high"] = "medium"
+    # Optional per-instance confidence (#189). When set, the finding takes the
+    # highest confidence among its instances instead of the default `medium`.
+    confidence: Literal["low", "medium", "high"] | None = None
+    # The input that reaches the weakness in the same function, when the
+    # emitter traced one (#189): `request`, `network`, `stdin`, `argv`, `env`,
+    # `file`. None means no source was traced.
+    # A value outside `NATIVE_SOURCE_KINDS` is kept as `other` (never as
+    # free text); a non-positive line is dropped.
+    source_kind: str | None = None
+    source_line: int | None = None
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+    @model_validator(mode="after")
+    def _clean_source(self) -> "CodeWeakness":
+        if self.source_kind is not None and self.source_kind not in NATIVE_SOURCE_KINDS:
+            object.__setattr__(self, "source_kind", "other")
+        if self.source_line is not None and self.source_line < 1:
+            object.__setattr__(self, "source_line", None)
+        if self.source_kind is None:
+            object.__setattr__(self, "source_line", None)
+        return self
+
+
+CODE_WEAKNESS_KINDS: tuple[str, ...] = get_args(CodeWeaknessKind)
+# Kinds whose severity and confidence are set per instance by the emitter
+# (they depend on whether an input source reaches the sink), so findings are
+# grouped per severity tier instead of taking the kind's fixed severity.
+# Inputs a native weakness's emitter may name in `source_kind`.
+NATIVE_SOURCE_KINDS: frozenset[str] = frozenset({"request", "network", "stdin", "argv", "env", "file", "other"})
+NATIVE_WEAKNESS_KINDS: tuple[str, ...] = (
+    "unbounded_copy",
+    "format_string",
+    "native_command_exec",
+    "tainted_copy_length",
+    "alloc_size_overflow",
+)
+
+
+class Anomaly(BaseModel):
+    """A within-repo consistency outlier — the odd-one-out in a peer group (#78).
+
+    Emitted by the `anomalies` analyzer. Rather than matching a known-bad
+    signature, it flags a route that deviates from the norm its siblings
+    establish: peers in the same resource cohort carry an auth/validation
+    signal (or are read-only) and this one doesn't. The bigger and more
+    consistent the peer group, the more likely the deviation is a mistake —
+    so `confidence` scales with `consistent_peers`.
+
+    `invariant_violation` (#149a) is the mined-invariant variant: the cohort
+    is not a route-path prefix but the set of handlers that reach the same
+    dangerous sink kind, and the norm they establish is a *behavioural*
+    invariant ("guard the request before the sink") rather than a static
+    signal. When set, `invariant` states the mined rule as evidence.
+    """
+
+    kind: Literal[
+        "auth_outlier",
+        "validation_outlier",
+        "method_outlier",
+        "invariant_violation",
+    ]
+    route_path: str
+    route_method: str
+    route_file: str
+    route_line: int | None = None
+    peer_group: str  # the shared path-prefix cohort key (e.g. "api/users")
+    peer_group_size: int  # total sibling routes in the cohort
+    consistent_peers: int  # siblings that exhibit the norm this route breaks
+    deviation: str  # human-readable description of what is odd
+    # The mined invariant the flagged site violates (invariant_violation only) —
+    # e.g. "9 of 10 handlers that reach a database (SQL execute) sink apply an
+    # auth/validation guard before it". Cited as evidence.
+    invariant: str | None = None
+    peer_examples: list[str] = Field(default_factory=list)  # sample "METHOD path" peers
+    severity: Literal["low", "medium", "high"] = "medium"
+    confidence: float = 0.5
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class WebHardeningIssue(_RedactedEvidence):
+    """A web-hardening misconfiguration (#71).
+
+    Emitted by the built-in web-hardening finder. Detects
+    positively-present misconfigurations (wildcard CORS with credentials,
+    explicit CSRF disable, insecure cookie flags, unsafe-inline/eval CSP,
+    debug enabled) rather than hard-to-judge absences.
+    """
+
+    kind: Literal[
+        "cors_wildcard_credentials",
+        "cors_wildcard_origin",
+        "cors_untrusted_origin",
+        "csrf_disabled",
+        "csrf_unprotected_session",
+        "insecure_cookie",
+        "weak_csp",
+        "debug_enabled",
+    ]
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    severity: Literal["low", "medium", "high"] = "medium"
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+# Kinds of `AppSurfaceIssue` (#188, #190). Prefixed by platform so their
+# rule ids (`apple-...`) never collide with a core detector family.
+AppSurfaceIssueKind = Literal[
+    "apple_ats_insecure_loads",
+    "apple_custom_url_scheme",
+    "apple_webview_js_injection",
+    "apple_insecure_secret_storage",
+    "apple_pasteboard_secret",
+    "apple_hardened_runtime_exception",
+    "apple_debuggable_entitlement",
+    "apple_xpc_unvalidated_peer",
+    "apple_dynamic_dispatch",
+]
+APP_SURFACE_ISSUE_KINDS: tuple[str, ...] = get_args(AppSurfaceIssueKind)
+
+
+class AppSurfaceIssue(_RedactedEvidence):
+    """A mobile/desktop app attack-surface issue emitted by a platform plugin
+    (#188, #190): the Apple analyzers (Swift, Objective-C) report App Transport
+    Security exceptions, custom URL-scheme handlers, weakening entitlements,
+    WKWebView script built from strings, secrets in UserDefaults or on the
+    pasteboard, unvalidated XPC peers, and classes, selectors or libraries
+    resolved from runtime strings. Native format-string and command-exec
+    constructs are `CodeWeakness` kinds shared with the C/C++ plugins.
+
+    Core owns the findings: one aggregated finding per kind (rule id = the
+    kind, dashed), at the most severe instance's severity. Like the other
+    issue families, every instance is a positively-present construct, never
+    an absence.
+
+    ``kind`` is one of ``APP_SURFACE_ISSUE_KINDS`` but typed ``str``, so a
+    plugin built against a newer core still validates: core drops records
+    with a kind it doesn't know (noted under ``analyzer_errors``) and keeps
+    the rest of the plugin's result.
+    """
+
+    kind: str = Field(min_length=1, max_length=64)
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    severity: Literal["low", "medium", "high"] = "medium"
+    # How sure the emitter is (0-1). On a duplicate report of the same
+    # instance the merge keeps the more severe, then the more confident one.
+    confidence: float = Field(default=0.8, ge=0.0, le=1.0)
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class SupplyChainIssue(_RedactedEvidence):
+    """A dependency supply-chain risk beyond CVEs (#247).
+
+    Emitted by the built-in, offline ``supply_chain`` pass over manifests,
+    lockfiles and package-manager configs: dependency confusion, typosquat
+    candidates, mutable VCS/URL dependencies, install scripts, unlocked
+    manifests and insecure registries.
+    """
+
+    kind: Literal[
+        "dependency_confusion",
+        "typosquat_candidate",
+        "mutable_vcs_dependency",
+        "install_script",
+        "unlocked_manifest",
+        "insecure_registry",
+    ]
+    file: str
+    line: int | None = None
+    package: str | None = None
+    ecosystem: str | None = None
+    evidence_text: str | None = None
+    severity: Literal["low", "medium", "high"] = "medium"
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+# Cloud / IaC / container-runtime misconfiguration kinds (`CloudMisconfig`).
+# Exported from `attackmap.sdk`; each kind is a core rule id (dashed) with a
+# finding spec in `threat_model` and a taxonomy entry in `taxonomy.py`.
+CloudMisconfigKind = Literal[
+    # Cloud resources (Terraform)
+    "iac_module_unpinned",
+    "public_network_access",
+    "public_cluster_endpoint",
+    "plaintext_listener",
+    "api_no_authorizer",
+    "unencrypted_storage",
+    "public_data_access",
+    "public_invoker",
+    # Workloads (Kubernetes / Helm / compose / Dockerfile)
+    "privileged_container",
+    "privilege_escalation_allowed",
+    "container_runs_as_root",
+    "missing_security_context",
+    "host_path_mount",
+    "host_namespace_shared",
+    "dangerous_capability",
+    "security_profile_disabled",
+    "exposed_service",
+    "unpinned_container_image",
+    "dockerfile_remote_add",
+    "dockerfile_curl_pipe_shell",
+    # Kubernetes RBAC
+    "rbac_wildcard",
+    "rbac_escalation",
+    "rbac_secret_access",
+    "cluster_admin_binding",
+]
+CLOUD_MISCONFIG_KINDS: tuple[str, ...] = get_args(CloudMisconfigKind)
+
+
+# Where a CloudMisconfig's resource lives. `terraform` is for module blocks.
+CloudMisconfigPlatform = Literal["aws", "azure", "gcp", "kubernetes", "helm", "compose", "docker", "terraform"]
+CLOUD_MISCONFIG_PLATFORMS: tuple[str, ...] = get_args(CloudMisconfigPlatform)
+
+# Free-text fields are copied from the scanned repo: one line, capped.
+_CLOUD_TEXT_CAPS = {"evidence_text": 300, "resource": 200, "context": 300, "escalation_path": 300}
+_CLOUD_KIND_MAX = 64
+
+
+class CloudMisconfig(_RedactedEvidence):
+    """A cloud, IaC or container-runtime misconfiguration (terraform#4, iac#1).
+
+    Emitted by IaC plugins (Terraform, Kubernetes / Helm, compose,
+    Dockerfile). Like the other issue families, each one is a
+    positively-present setting (or a documented insecure default that the
+    file leaves in place) at a file and line. Core turns each `kind` into
+    findings, one per (kind, severity) tier, so a low `/var/log` mount never
+    inherits the severity of a `docker.sock` mount of the same kind.
+
+    - `kind`: one of `CLOUD_MISCONFIG_KINDS`. Typed `str` so a plugin built
+      against a newer core still validates here; core drops records with a
+      kind it doesn't know (noted under `analyzer_errors`) and keeps the rest
+      of the plugin's result.
+    - `resource`: what the setting belongs to, e.g. `aws_eks_cluster.main`,
+      `Deployment/web container app`, `module.vpc`.
+    - `platform`: one of `CLOUD_MISCONFIG_PLATFORMS`.
+    - `context`: how the resource is instantiated — `for_each`/`count`,
+      the calling module of a local module, a Helm template.
+    - `escalation_path`: what an attacker gets from it, in one line, e.g.
+      `hostPath / → node root → kubelet credentials`.
+
+    The free-text fields are redacted, folded to one line and capped.
+    """
+
+    kind: str = Field(min_length=1, max_length=_CLOUD_KIND_MAX)
+    file: str
+    line: int | None = None
+    resource: str | None = None
+    platform: CloudMisconfigPlatform | None = None
+    context: str | None = None
+    escalation_path: str | None = None
+    evidence_text: str | None = None
+    severity: Literal["low", "medium", "high"] = "medium"
+    confidence: float = Field(default=0.8, ge=0.0, le=1.0)
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+    @model_validator(mode="after")
+    def _clean_text_fields(self) -> "CloudMisconfig":
+        # Redact first (a module source URL can carry a token), then fold to
+        # one line and cap, so a cut never leaves half a secret unredacted.
+        for name, cap in _CLOUD_TEXT_CAPS.items():
+            value = getattr(self, name)
+            if not value:
+                continue
+            value = " ".join(redact_text(value).split())
+            if len(value) > cap:
+                value = value[: cap - 1] + "…"
+            object.__setattr__(self, name, value)
+        return self
+
+    @property
+    def known_kind(self) -> bool:
+        return self.kind in CLOUD_MISCONFIG_KINDS
+
+
+class WorkflowIssue(_RedactedEvidence):
+    """A CI-workflow security issue in a GitHub Actions file (#142).
+
+    Emitted by the built-in workflow scanner over ``.github/workflows/*.yml``.
+    Every issue is a positively-present misconfiguration (an unpinned action,
+    an untrusted-code checkout under ``pull_request_target``, a secret or an
+    attacker-controlled context interpolated into a shell step, ``write-all``
+    permissions, a self-hosted runner on a PR trigger) — a hardened workflow
+    produces nothing.
+    """
+
+    kind: Literal[
+        "unpinned_action",
+        "pr_target_checkout",
+        "secret_in_run",
+        "script_injection",
+        "broad_permissions",
+        "self_hosted_pr",
+        # #246
+        "workflow_run_artifact_poisoning",
+        "issue_comment_pr_checkout",
+        "github_script_injection",
+        "github_env_injection",
+        "default_token_permissions",
+        "oidc_on_untrusted_trigger",
+        "secrets_inherit",
+        "checkout_persist_credentials",
+        "cache_poisoning_pr_target",
+        "docker_action_unpinned",
+        "curl_pipe_shell",
+    ]
+    file: str
+    line: int | None = None
+    # Human-readable location within the workflow (job / step) so evidence
+    # points somewhere actionable even when a precise line isn't available.
+    context: str | None = None
+    evidence_text: str | None = None
+    severity: Literal["low", "medium", "high"] = "medium"
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class CryptoWeakness(_RedactedEvidence):
+    """An insecure-cryptography or weak-randomness usage (#70).
+
+    Emitted by the built-in crypto finder. Heuristic and regex-based;
+    the noisy families (weak hash, insecure RNG) are gated on a
+    security-context identifier to keep precision high.
+    """
+
+    kind: Literal[
+        "weak_password_hash",
+        "weak_cipher",
+        "ecb_mode",
+        "static_iv_salt",
+        "insecure_random",
+        "insecure_tls",
+    ]
+    file: str
+    line: int | None = None
+    evidence_text: str | None = None
+    severity: Literal["low", "medium", "high"] = "medium"
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class BolaCandidate(_RedactedEvidence):
+    """A route that may be missing object-level authorization (#69).
+
+    Emitted by the authz analyzer when a route takes a resource
+    identifier and reaches a datastore, but no ownership/authorization
+    check is visible near the handler. Heuristic — the ownership-marker
+    scan is the main false-positive reducer; confidence stays honest.
+    """
+
+    route_path: str
+    route_method: str
+    route_file: str
+    route_line: int | None = None
+    id_param: str  # the resource-id parameter/method detected
+    # Where the object identifier arrives (#139): a path template param, an
+    # id-bearing query parameter, an RPC method (XRPC/tRPC), or a GraphQL field.
+    surface: Literal["path_param", "query_param", "rpc_method", "graphql_field"] = "path_param"
+    reaches_db: bool = False
+    db_evidence: str = ""  # how DB reachability was established
+    has_ownership_check: bool = False  # True → suppressed (not a candidate)
+    # How the route is authenticated, "" when it isn't (#242). Authentication
+    # without an object check is the classic IDOR, so it raises confidence.
+    authn_evidence: str = ""
+    confidence: Literal["high", "medium", "low"] = "medium"
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class TaintFlowStep(_RedactedEvidence):
+    """One step of an intra-procedural flow (#239): where the tainted value
+    came from, each assignment it passed through, any sanitizer/guard bound to
+    it, and the sink. Rendered as SARIF ``codeFlows``. ``evidence_text`` is
+    the code at that step (redacted like other evidence)."""
+
+    file: str
+    line: int | None = None
+    kind: Literal["source", "propagation", "sanitizer", "guard", "sink"]
+    evidence_text: str | None = None
+
+
+class TaintChain(_RedactedEvidence):
+    """Cross-file data-flow evidence: a route reaches a sink via imports.
+
+    Emitted by the lite taint analyzer (see #45). Each entry names the
+    starting route, the sink kind and location, and the chain of files
+    the import-walk traversed. Confidence encodes that import-edge is a
+    heuristic proxy for call-edge — real dispatch may not hit the sink.
+    """
+
+    route_path: str
+    route_method: str
+    route_file: str
+    sink_kind: Literal[
+        "sql_execute",
+        "subprocess_shell",
+        "eval",
+        "exec",
+        "dynamic_open",
+        "unsafe_deserialization",
+        "ssti",
+        "ssrf",
+        "nosql_injection",
+        "open_redirect",
+        # #240 — `dynamic_open` stays as the schema-compatible alias of
+        # `path_traversal` (#200).
+        "path_traversal",
+        "zip_slip",
+        "code_injection",
+        "expression_injection",
+        "jndi_injection",
+        "ldap_injection",
+        "xpath_injection",
+        "header_injection",
+        "regex_injection",
+    ]
+    sink_file: str
+    sink_line: int | None = None
+    # Number of import edges walked. 0 = same file, 1 = direct import,
+    # 2 = transitive (imported module imports the sink module).
+    hops: int
+    # Chain of files walked, ordered [route_file, ..., sink_file].
+    files: list[str] = Field(default_factory=list)
+    evidence_text: str | None = None
+    confidence: float = 0.6
+    # Sanitizer awareness (#137). When a known neutralizer for this sink kind
+    # is present in the sink file (escaper/validator/parameter-binder/
+    # allow-lister), the chain is marked sanitized and its confidence is
+    # downgraded — the tainted value is likely neutralized before the sink.
+    # `sanitizer_evidence` names the neutralizer so the chain stays auditable.
+    sanitized: bool = False
+    sanitizer_evidence: str | None = None
+    # Recall mode (#148a). A chain surfaced only because an aggressive knob was
+    # relaxed — beyond the default hop depth, or through a gate the default pass
+    # keeps closed (a static-literal-looking sink argument) — is marked
+    # speculative with downgraded confidence. Speculative chains are discovery
+    # leads for the verifier to adjudicate, not asserted flows: they are kept
+    # out of the `--fail-on-new-high` gate and clearly labelled in reports.
+    speculative: bool = False
+    # Intra-procedural flow (#239). Set when a request-derived value is traced
+    # (through local assignments) into the sink's dangerous argument — or, for
+    # a sanitized chain, into the sanitizer/guard that neutralizes it.
+    # `source_kind` is the catalog kind (query, body, path_param, header,
+    # cookie, upload_filename, message); `source_line` is in `sink_file`.
+    # None when no flow was established (reachability-only chain).
+    source_kind: str | None = None
+    source_line: int | None = None
+    flow: list[TaintFlowStep] = Field(default_factory=list)
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+class Vulnerability(BaseModel):
+    """A known CVE / advisory affecting a resolved dependency (#60).
+
+    One entry per (dep × advisory). ``package_version`` is the concrete
+    lower-bound the CVE lookup resolved from the manifest spec — it may
+    differ from the DependencyHint's raw ``version`` string.
+    """
+
+    id: str  # OSV entry id — CVE-2023-1234, GHSA-xxxx-xxxx, etc.
+    aliases: list[str] = Field(default_factory=list)
+    summary: str = ""
+    severity: Literal["low", "medium", "high"] = "medium"
+    cvss_score: float | None = None
+    references: list[str] = Field(default_factory=list)
+    affected_range: str = ""  # human-readable "affected [lower, upper)" text
+    package_name: str
+    package_version: str
+    ecosystem: DependencyEcosystem
+    # Lockfile provenance (#143): False when the vulnerable package is a
+    # transitive dependency; ``resolution_path`` is its chain from a direct
+    # dependency (``"express > body-parser > qs"``) so the finding can say how
+    # the vulnerable code was pulled in.
+    direct: bool = True
+    resolution_path: str = ""
+    source_analyzer: str | None = _PROVENANCE_FIELD
+
+
+SignalKind = Literal[
+    "route",
+    "external_call",
+    "database",
+    "auth",
+    "service",
+    "edge",
+    "entrypoint",
+    "protocol",
+    "framework",
+    "secret",
+    "taint",
+    "dependency",
+]
+
+
+class Signal(_RedactedEvidence):
+    """Unified view of a single static-analysis signal.
+
+    Synthesized from the typed hint lists on `ScanResult` via `all_signals()`.
+    Existing analyzer plugins keep populating the typed hint lists; downstream
+    consumers (insights, controls, asset detection, prompts) can iterate over
+    the unified Signal stream to reason uniformly about location, confidence,
+    and evidence.
+    """
+
+    kind: SignalKind
+    label: str
+    file: str
+    line: int | None = None
+    confidence: float = 0.7
+    evidence_text: str | None = None
+    properties: dict[str, str] = Field(default_factory=dict)
+
+    def location(self) -> str:
+        """Stable `file:line` reference if line known, else just file."""
+        return f"{self.file}:{self.line}" if self.line is not None else self.file
+
+
+WebhookVerificationState = Literal["verified", "weak_compare", "no_replay_guard", "absent", "unknown"]
+
+
+class WebhookVerification(BaseModel):
+    """How a webhook handler authenticates the events it receives (#243, part B).
+
+    ``verified``: a provider SDK verifier, or an HMAC checked with a
+    constant-time compare (and, for schemes that sign a timestamp, a freshness
+    check). ``weak_compare``: an HMAC compared with ``==``. ``no_replay_guard``:
+    a timestamped scheme whose timestamp is never checked. ``absent``: nothing
+    that verifies the payload. ``unknown``: the handler couldn't be read, or it
+    hands the signature to code we couldn't follow.
+    """
+
+    state: WebhookVerificationState
+    provider: str | None = None  # stripe, github, slack, twilio, shopify, svix, sns, hmac
+    evidence: str | None = None  # file:line — the line that decided the state
+    notes: list[str] = Field(default_factory=list)
+    # The handler only answers 404/410 (a stub, e.g. a feature disabled in this
+    # edition): nothing is processed, so it isn't a live receiver (#366).
+    inert: bool = False
+
+
+class AttackSurface(BaseModel):
+    route: str
+    method: str
+    file: str
+    category: Literal["webhook", "admin", "auth", "upload", "internal", "health", "public_api"]
+    exposure: Literal["public", "internal", "unknown"] = "public"
+    risk: Literal["low", "medium", "high"]
+    auth_signals: list[str] = Field(default_factory=list)
+    data_store_interaction: bool = False
+    outbound_integration: bool = False
+    rationale: list[str] = Field(default_factory=list)
+    line: int | None = None
+    # Set on webhook surfaces only (#243, part B).
+    webhook_verification: WebhookVerification | None = None
+
+    def location(self) -> str:
+        return f"{self.file}:{self.line}" if self.line is not None else self.file
+
+
+class AttackTechnique(BaseModel):
+    """Reference to a MITRE ATT&CK technique (Enterprise matrix)."""
+
+    technique_id: str  # e.g., "T1190", "T1078.004"
+    name: str  # e.g., "Exploit Public-Facing Application"
+    tactic: str  # e.g., "Initial Access"
+    url: str | None = None  # https://attack.mitre.org/techniques/T1190/
+
+
+ExploitabilityTier = Literal["critical", "high", "medium", "low"]
+
+
+class ExploitabilityFactor(BaseModel):
+    """One named, signed contribution to an exploitability score (#79).
+
+    Kept explicit so every score is explainable — the report shows exactly
+    which signals raised (or, at 0 points, notably did not raise) the number.
+    """
+
+    name: str  # e.g. "public exposure", "no auth at entry", "reaches sql_execute sink"
+    points: int
+    detail: str = ""  # concrete evidence for this factor
+
+
+class ExploitabilityScore(BaseModel):
+    """A fused 'exploitable now' score for one route→sink combination (#79).
+
+    Deterministic: the same scan always yields the same score, and `factors`
+    sums (before the 0–100 clamp) to `raw_score`, so nothing is hidden.
+    """
+
+    subject: str  # human label, e.g. "GET /search → sql_execute"
+    route: str
+    method: str
+    sink_kind: str
+    location: str  # sink file:line
+    score: int  # 0–100 (clamped)
+    raw_score: int  # pre-clamp sum of factor points
+    tier: ExploitabilityTier
+    factors: list[ExploitabilityFactor] = Field(default_factory=list)
+
+
+def title_slug(title: str) -> str:
+    """Legacy rule id: the slugified finding title (pre-#223)."""
+    import re as _re
+
+    slug = _re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
+    return slug or "finding"
+
+
+def finding_rule_id(finding: "Finding") -> str:
+    """The finding's stable rule id, or its title slug when it has none."""
+    return finding.rule_id or title_slug(finding.title)
+
+
+class FindingLocation(BaseModel):
+    """A file (and line, when known) a finding applies to (#214). Carried
+    structurally so SARIF, suppression and diffing don't have to parse
+    evidence prose."""
+
+    file: str
+    line: int | None = None
+    # Instance identity across runs (#222): rule + file + normalized source
+    # line, without the line number. Set by `fingerprint.assign_fingerprints`.
+    fingerprint: str | None = None
+    # What tells this instance apart from others on the same line (a
+    # severity-tiered record's resource and evidence). Set only by tiered
+    # findings; when set it is mixed into the fingerprint, so an instance's
+    # fingerprint doesn't depend on its position among same-line instances
+    # (adding one, or re-tiering one, doesn't move dismissals). Not serialized.
+    instance: str | None = Field(default=None, exclude=True, repr=False)
+
+
+class FindingTaxonomy(BaseModel):
+    """Standard ids for a finding's rule (#250), looked up by `rule_id` in
+    `attackmap.taxonomy` — never inferred from title or evidence text."""
+
+    cwe: list[str] = Field(default_factory=list)  # ["CWE-918"]
+    owasp: list[str] = Field(default_factory=list)  # ["A10:2021", "API7:2023"]
+    asvs: list[str] = Field(default_factory=list)  # ASVS 4.0.3, ["V12.6.1"]
+    attack: list[str] = Field(default_factory=list)  # ["T1190", "T1552.005"]
+
+
+class Finding(_RedactedEvidence):
+    title: str
+    severity: Literal["low", "medium", "high"]
+    # Stable, short detector id (#223) — SARIF ruleId and suppress `rule:`.
+    # Titles are prose and may be reworded; this never changes. `None` for
+    # findings from callers that don't set one (falls back to the title slug).
+    rule_id: str | None = None
+    evidence: list[str] = Field(default_factory=list)
+    # Every location the finding covers — not capped like `evidence` (#214).
+    locations: list[FindingLocation] = Field(default_factory=list)
+    mitigation: str
+    confidence: Literal["low", "medium", "high"] = "medium"
+    attack_techniques: list[AttackTechnique] = Field(default_factory=list)
+    # Optional categorization tags. Vocabulary (see #4): exposed-endpoint,
+    # auth-missing, data-risk, secret-exposure, integration-risk,
+    # framework-chain, service-chain, atproto-chain, weak-signal. Multiple
+    # tags may apply per finding.
+    tags: list[str] = Field(default_factory=list)
+    # Numeric prioritization score (higher = triage first within the same
+    # severity band). Computed from severity + confidence; used as a
+    # secondary sort key. `None` means "not scored" for backward compat.
+    score: int | None = None
+    # Fused 'exploitable now' score (#79), 0–100, with a tier. Set on
+    # findings that sit on a route→sink path; `None` when not applicable.
+    exploitability: int | None = None
+    exploitability_tier: ExploitabilityTier | None = None
+    # Source→sink steps behind a taint finding (#239), one list per traced
+    # flow; emitted as SARIF `codeFlows` on the matching sink result.
+    code_flows: list[list[TaintFlowStep]] = Field(default_factory=list)
+    # CWE / OWASP / ASVS / ATT&CK ids for `rule_id` (#250). Filled from the
+    # registry on construction; `None` for rules it doesn't know.
+    taxonomy: FindingTaxonomy | None = None
+
+    @model_validator(mode="after")
+    def _apply_rule_taxonomy(self) -> "Finding":
+        from .taxonomy import ATTACK_TECHNIQUES, attack_url, taxonomy_for
+
+        entry = taxonomy_for(self.rule_id)
+        if entry is None:
+            return self
+        if self.taxonomy is None:
+            object.__setattr__(
+                self,
+                "taxonomy",
+                FindingTaxonomy(
+                    cwe=entry.cwe_ids, owasp=list(entry.owasp), asvs=list(entry.asvs), attack=list(entry.attack)
+                ),
+            )
+        if entry.attack:
+            # The registry is authoritative for ATT&CK on registered rules.
+            object.__setattr__(
+                self,
+                "attack_techniques",
+                [
+                    AttackTechnique(technique_id=tid, name=name, tactic=tactic, url=attack_url(tid))
+                    for tid in entry.attack
+                    for name, tactic in [ATTACK_TECHNIQUES[tid]]
+                ],
+            )
+        return self
+
+
+class AttackPath(BaseModel):
+    name: str
+    steps: list[str]
+    impact: str
+
+
+AssetKind = Literal[
+    "credentials",
+    "session",
+    "user_pii",
+    "payment",
+    "internal_secret",
+    "audit_log",
+    "business_data",
+    "configuration",
+]
+
+
+class Asset(_RedactedEvidence):
+    id: str
+    kind: AssetKind
+    name: str
+    criticality: Literal["critical", "high", "medium", "low"]
+    locations: list[str] = Field(default_factory=list)
+    evidence: list[str] = Field(default_factory=list)
+
+
+ControlKind = Literal[
+    "authentication",
+    "authorization",
+    "input_validation",
+    "output_encoding",
+    "rate_limiting",
+    "csrf_protection",
+    "encryption_at_rest",
+    "encryption_in_transit",
+    "audit_logging",
+    "rbac",
+    "mfa",
+    "secret_management",
+    "security_headers",
+]
+
+
+ControlStrength = Literal["strong", "moderate", "weak", "absent"]
+
+
+class Control(_RedactedEvidence):
+    id: str
+    kind: ControlKind
+    name: str
+    strength: ControlStrength
+    scope: Literal["global", "module", "route", "service", "asset"]
+    placements: list[str] = Field(default_factory=list)
+    evidence: list[str] = Field(default_factory=list)
+    notes: str | None = None
+
+
+InsightKind = Literal[
+    "shared_secret_blast_radius",
+    "sensitive_asset_reachability",
+    "control_bypass",
+    "defense_gap_in_chain",
+    "asymmetric_protection",
+    "trust_boundary_violation",
+    "audit_gap",
+    "control_strength_mismatch",
+    "single_point_of_failure",
+    "stale_or_contradictory_signal",
+    "admin_action_without_auth",
+]
+
+
+class Insight(_RedactedEvidence):
+    id: str
+    kind: InsightKind
+    title: str
+    narrative: str
+    severity: Literal["critical", "high", "medium", "low", "informational"]
+    confidence: Literal["high", "medium", "low"]
+    evidence: list[str] = Field(default_factory=list)
+    related_assets: list[str] = Field(default_factory=list)
+    related_controls: list[str] = Field(default_factory=list)
+    related_routes: list[str] = Field(default_factory=list)
+    suggested_action: str | None = None
+    attack_techniques: list[AttackTechnique] = Field(default_factory=list)
+
+
+class DetectionLogsource(BaseModel):
+    """Sigma `logsource` of a generated rule (#251)."""
+
+    product: str | None = None
+    service: str | None = None
+    category: str | None = None
+
+    def label(self) -> str:
+        return self.category or "/".join(p for p in (self.product, self.service) if p) or "unknown"
+
+
+class DetectionTestEvents(BaseModel):
+    """Sample log events for a generated rule (#251): `positive` events match
+    it, `negative` ones don't."""
+
+    positive: list[dict[str, Any]] = Field(default_factory=list)
+    negative: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class DetectionOpportunity(BaseModel):
+    """A defender-facing detection-engineering hint produced from an insight or finding.
+
+    Designed to answer: "given this static-analysis finding, what runtime
+    detection signal would catch the same condition in production?"
+    """
+
+    id: str
+    title: str
+    rationale: str
+    signal_kind: Literal["log", "metric", "trace", "network", "config_audit"]
+    suggested_rule: str  # human-readable rule sketch (Sigma/KQL/Splunk-style)
+    related_insight_ids: list[str] = Field(default_factory=list)
+    related_finding_titles: list[str] = Field(default_factory=list)
+    # Rule ids of the linked findings (#250), linked via the taxonomy registry.
+    related_rule_ids: list[str] = Field(default_factory=list)
+    attack_techniques: list[AttackTechnique] = Field(default_factory=list)
+    # Deployable rule (#251), set on opportunities generated per finding
+    # class: a structurally valid Sigma rule (deterministic `id`, status
+    # experimental), its log source, the log fields it reads, false-positive
+    # notes and sample events (positives match the rule, negatives don't).
+    # `sigma_correlation` is a Sigma correlation rule over `sigma` (BOLA
+    # cardinality). All `None`/empty on prose-only opportunities.
+    sigma: dict[str, Any] | None = None
+    sigma_correlation: dict[str, Any] | None = None
+    logsource: DetectionLogsource | None = None
+    fields_required: list[str] = Field(default_factory=list)
+    false_positive_notes: list[str] = Field(default_factory=list)
+    test_events: DetectionTestEvents | None = None
+
+
+class AnalyzerError(BaseModel):
+    """An analyzer whose ``analyze()`` raised or returned something unusable
+    (#220). The scan carries on without it; this records the gap."""
+
+    analyzer: str
+    error_type: str
+    message: str = ""
+
+
+class ScanResult(BaseModel):
+    root: str
+    languages: list[str] = Field(default_factory=list)
+    routes: list[Route] = Field(default_factory=list)
+    external_calls: list[ExternalCall] = Field(default_factory=list)
+    databases: list[DatabaseHint] = Field(default_factory=list)
+    auth_hints: list[AuthHint] = Field(default_factory=list)
+    service_hints: list[ServiceHint] = Field(default_factory=list)
+    edge_hints: list[EdgeHint] = Field(default_factory=list)
+    entrypoint_hints: list[EntrypointHint] = Field(default_factory=list)
+    protocol_hints: list[ProtocolHint] = Field(default_factory=list)
+    framework_hints: list[FrameworkHint] = Field(default_factory=list)
+    secret_hints: list[SecretHint] = Field(default_factory=list)
+    taint_chains: list[TaintChain] = Field(default_factory=list)
+    dependencies: list[DependencyHint] = Field(default_factory=list)
+    vulnerabilities: list[Vulnerability] = Field(default_factory=list)
+    authz_candidates: list[BolaCandidate] = Field(default_factory=list)
+    crypto_weaknesses: list[CryptoWeakness] = Field(default_factory=list)
+    web_hardening_issues: list[WebHardeningIssue] = Field(default_factory=list)
+    code_weaknesses: list[CodeWeakness] = Field(default_factory=list)
+    workflow_issues: list[WorkflowIssue] = Field(default_factory=list)
+    supply_chain_issues: list[SupplyChainIssue] = Field(default_factory=list)
+    cloud_misconfigs: list[CloudMisconfig] = Field(default_factory=list)
+    # Plugin-emitted app attack surface (#188, #190).
+    app_surface_issues: list[AppSurfaceIssue] = Field(default_factory=list)
+    secret_history: list[SecretHistoryHit] = Field(default_factory=list)
+    anomalies: list[Anomaly] = Field(default_factory=list)
+    # What the scan deliberately did not analyze (e.g. symlinks that point out
+    # of the repo, #234) — so a clean report isn't mistaken for full coverage.
+    limitations: list[str] = Field(default_factory=list)
+    # Analyzers that failed and were skipped (#220).
+    analyzer_errors: list[AnalyzerError] = Field(default_factory=list)
+    files_scanned: int = 0
+
+    @property
+    def root_path(self) -> Path:
+        return Path(self.root)
+
+    def all_signals(self) -> list[Signal]:
+        """Synthesize the unified Signal stream from typed hint lists.
+
+        Cheap O(n) view — does not mutate `self`. Order: routes, external calls,
+        databases, then the hint families (auth, service, edge, entrypoint,
+        protocol, framework, secret) in that order.
+        """
+        signals: list[Signal] = []
+        for r in self.routes:
+            signals.append(
+                Signal(
+                    kind="route",
+                    label=f"{r.method} {r.path}",
+                    file=r.file,
+                    line=r.line,
+                    properties={"method": r.method, "path": r.path},
+                )
+            )
+        for ext in self.external_calls:
+            signals.append(
+                Signal(
+                    kind="external_call",
+                    label=ext.target,
+                    file=ext.file,
+                    line=ext.line,
+                    evidence_text=ext.evidence_text,
+                )
+            )
+        for db in self.databases:
+            signals.append(
+                Signal(
+                    kind="database",
+                    label=db.kind,
+                    file=db.file,
+                    line=db.line,
+                    evidence_text=db.evidence_text,
+                    properties={"kind": db.kind},
+                )
+            )
+        _hint_kind_pairs: tuple[tuple[SignalKind, list], ...] = (
+            ("auth", self.auth_hints),
+            ("service", self.service_hints),
+            ("edge", self.edge_hints),
+            ("entrypoint", self.entrypoint_hints),
+            ("protocol", self.protocol_hints),
+            ("framework", self.framework_hints),
+        )
+        for kind, hints in _hint_kind_pairs:
+            for h in hints:
+                signals.append(
+                    Signal(
+                        kind=kind,
+                        label=h.hint,
+                        file=h.file,
+                        line=getattr(h, "line", None),
+                        evidence_text=getattr(h, "evidence_text", None),
+                        confidence=getattr(h, "confidence", 0.7),
+                    )
+                )
+        for s in self.secret_hints:
+            signals.append(
+                Signal(
+                    kind="secret",
+                    label=s.name,
+                    file=s.file,
+                    line=s.line,
+                    evidence_text=s.evidence_text,
+                    confidence=getattr(s, "confidence", 0.85),
+                )
+            )
+        for tc in self.taint_chains:
+            signals.append(
+                Signal(
+                    kind="taint",
+                    label=f"{tc.route_method} {tc.route_path} → {tc.sink_kind}",
+                    file=tc.sink_file,
+                    line=tc.sink_line,
+                    evidence_text=tc.evidence_text,
+                    confidence=tc.confidence,
+                    properties={
+                        "hops": str(tc.hops),
+                        "sink_kind": tc.sink_kind,
+                        "route_file": tc.route_file,
+                    },
+                )
+            )
+        for dep in self.dependencies:
+            signals.append(
+                Signal(
+                    kind="dependency",
+                    label=f"{dep.ecosystem}:{dep.name}@{dep.version}",
+                    file=dep.file,
+                    line=dep.line,
+                    evidence_text=dep.evidence_text,
+                    confidence=0.9,  # manifest declarations are hard evidence
+                    properties={
+                        "ecosystem": dep.ecosystem,
+                        "name": dep.name,
+                        "version": dep.version,
+                        "dev": "true" if dep.dev else "false",
+                    },
+                )
+            )
+        return signals