attackmap 0.1.0__tar.gz → 0.2.0__tar.gz

{attackmap-0.1.0/src/attackmap.egg-info → attackmap-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: attackmap
-Version: 0.1.0
+Version: 0.2.0
 Summary: AI-assisted defensive security analyzer for codebases — scans a repository, models assets and controls, finds cross-cutting weaknesses, and generates an evidence-grounded review with MITRE ATT&CK mappings and detection-engineering hints.
 Author: AttackMap Contributors
 Author-email: Matthew Davis <matthewd@matthewd.xyz>
@@ -38,19 +38,20 @@ Provides-Extra: llm
 Requires-Dist: anthropic>=0.40.0; extra == "llm"
 Provides-Extra: all
 Requires-Dist: attackmap[llm]; extra == "all"
-Requires-Dist: attackmap-analyzer-python; extra == "all"
-Requires-Dist: attackmap-analyzer-rust; extra == "all"
-Requires-Dist: attackmap-analyzer-go; extra == "all"
-Requires-Dist: attackmap-analyzer-java-spring; extra == "all"
-Requires-Dist: attackmap-analyzer-dotnet; extra == "all"
-Requires-Dist: attackmap-analyzer-terraform; extra == "all"
-Requires-Dist: attackmap-analyzer-c; extra == "all"
-Requires-Dist: attackmap-analyzer-cpp; extra == "all"
-Requires-Dist: attackmap-analyzer-node-service; extra == "all"
-Requires-Dist: attackmap-analyzer-atproto; extra == "all"
-Requires-Dist: attackmap-analyzer-php-web; extra == "all"
-Requires-Dist: attackmap-analyzer-php-laminas; extra == "all"
-Requires-Dist: attackmap-analyzer-omeka-s; extra == "all"
+Requires-Dist: attackmap-analyzer-python>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-rust>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-go>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-java-spring>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-dotnet>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-terraform>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-c>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-cpp>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-node-service>=0.2.0; extra == "all"
+Requires-Dist: attackmap-analyzer-atproto>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-php-web>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-php-laminas>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-omeka-s>=0.1.0; extra == "all"
+Requires-Dist: attackmap-analyzer-iac>=0.1.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: build>=1.2.0; extra == "dev"
@@ -107,7 +108,7 @@ Read `reports/defensive-review.md` (heuristic) and `reports/defensive-review-llm
 ```bash
 pip install attackmap                  # core only
 pip install "attackmap[llm]"           # add LLM narrative support
-pip install "attackmap[all]"           # core + LLM + all 11 analyzer plugins
+pip install "attackmap[all]"           # core + LLM + all 13 analyzer plugins
 ```
 
 You can also install individual analyzer plugins on demand:
@@ -116,6 +117,17 @@ You can also install individual analyzer plugins on demand:
 pip install attackmap-analyzer-python attackmap-analyzer-go
 ```
 
+Not sure which plugins your repo needs? Let AttackMap tell you:
+
+```bash
+attackmap suggest ./path/to/repo          # print ranked pip lines
+attackmap suggest ./path/to/repo --install # and install them (prompts once)
+```
+
+`suggest` inspects the repo's manifest files, extensions, and directory layout
+and recommends only the plugins that would give it deeper signal — useful
+when you want a smaller install footprint than `[all]`.
+
 ### With Docker
 
 ```bash
@@ -150,9 +162,102 @@ Every `attackmap analyze` run writes:
 | `defensive-review.json` | Structured equivalent (schema v1.2.0) |
 | `review-context-pack.json` | Structured evidence pack consumed by the LLM stage |
 | `attackmap-report.json` | Everything bundled |
+| `attackmap-report.sarif` | SARIF 2.1.0 log — ingestable by GitHub Code Scanning, VS Code, and other SARIF consumers |
+| `attackmap-paths.md` | Mermaid flowcharts of each attack path — renders inline on GitHub |
+| `attackmap-topology.md` | Mermaid graph of the service topology, with edge kinds styled per relationship type |
+| `attackmap-paths.dot` / `attackmap-topology.dot` | Graphviz DOT versions of the two diagrams — feed into `dot -Tsvg` for slide-quality graphics |
 | `defensive-review-llm.md` *(with `--llm`)* | Claude-narrated review |
 | `defensive-review-llm.meta.json` *(with `--llm`)* | Backend, model, token usage |
 
+### GitHub Code Scanning integration
+
+Drop this into `.github/workflows/attackmap.yml` to get AttackMap findings inline on every PR:
+
+```yaml
+name: AttackMap
+on: [pull_request, push]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install "attackmap[all]"
+      - run: attackmap analyze . --output reports
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: reports/attackmap-report.sarif
+          category: attackmap
+```
+
+### Diff mode (PR gating)
+
+For a lighter CI integration than Code Scanning — a bot comment, a JSON delta,
+or a hard fail on newly-introduced HIGH findings — point `--baseline` at a
+prior report and AttackMap will emit a Markdown diff alongside the fresh
+report:
+
+```bash
+attackmap analyze . --output reports \
+  --baseline path/to/previous/attackmap-report.json \
+  --diff-output reports/attackmap-diff.md \
+  --fail-on-new-high        # exit non-zero if the PR introduces any HIGH finding
+```
+
+Findings get a stable id (hash of the finding title) that survives line drift
+on unrelated commits, so a finding that persists across scans has the same id
+in both. The diff has three sections — **New**, **Persisted**, **Resolved** —
+which drop cleanly into a PR comment.
+
+### SBOM inventory
+
+Every scan also produces a lightweight SBOM by parsing direct dependencies out
+of the common manifest files:
+
+| Ecosystem | Files parsed |
+|---|---|
+| PyPI (Python) | `pyproject.toml` (PEP 621 + Poetry), `requirements.txt` |
+| npm (Node.js) | `package.json` (dependencies + devDependencies + peer/optional) |
+| Go | `go.mod` (single-line + block-form `require`, `// indirect` flagged) |
+| Cargo (Rust) | `Cargo.toml` (dependencies + dev-dependencies + build-dependencies) |
+| Composer (PHP) | `composer.json` (require + require-dev; platform reqs skipped) |
+
+Each entry appears in `attackmap-report.json` under `scan.dependencies` with
+`{name, version, ecosystem, file, dev}`. Version ranges are kept verbatim
+(`^4.16.0`, `>=2,<3`, `latest`) — this slice does not resolve lockfiles.
+
+### CVE cross-reference (opt-in)
+
+`attackmap analyze --cve` cross-references every SBOM entry against
+[OSV.dev](https://osv.dev) and emits one finding per vulnerable dependency
+(all known advisories aggregated in the evidence list). CVSS scores map into
+low/medium/high — anything ≥ 7.0 is HIGH.
+
+```bash
+attackmap analyze . --cve
+```
+
+- **Off by default.** The flag exists precisely because CVE lookup does
+  network I/O; regular scans stay offline.
+- **Cached** under `~/.attackmap/cache/osv/` keyed by
+  `sha256(ecosystem+name+version)`. TTL is 24h by default, overridable via
+  `ATTACKMAP_OSV_CACHE_TTL_HOURS`. Repeat scans of the same repo don't hit
+  the network.
+- **Offline-tolerant.** If the network's unavailable but the cache is warm,
+  cached results still surface; only fresh queries are skipped.
+- **Version resolution is best-effort.** Manifest ranges (`^4.16.0`,
+  `>=2.28,<3`) resolve to a queryable lower-bound; OSV does the range math.
+  Unpinned specs (`*`, `latest`) are skipped.
+
+The structured vulnerability list is available under
+`scan.vulnerabilities` in `attackmap-report.json` with
+`{id, aliases, summary, severity, cvss_score, references, affected_range,
+package_name, package_version, ecosystem}`.
+
 ---
 
 ## How it works
@@ -187,7 +292,7 @@ Layered on top: **MITRE ATT&CK technique mappings** on every insight and
 
 ## Supported ecosystems
 
-Eleven official analyzer plugins, each distributable as a separate package:
+Thirteen official analyzer plugins, each distributable as a separate package:
 
 | Plugin | Coverage |
 |---|---|
@@ -205,6 +310,13 @@ Eleven official analyzer plugins, each distributable as a separate package:
 
 `pip install "attackmap[all]"` installs every official plugin.
 
+### Building your own analyzer
+
+The plugin contract is documented in code at
+[`attackmap.sdk`](src/attackmap/sdk/__init__.py); the developer cookbook with
+scaffolding, testing, and publishing instructions is in
+[`docs/external-analyzers.md`](docs/external-analyzers.md).
+
 ---
 
 ## CLI reference
@@ -215,6 +327,8 @@ attackmap analyze <path> --output dir    # write outputs to `dir/`
 attackmap analyze <path> --module python --module rust   # only these analyzers
 attackmap analyze <path> --llm           # add LLM narrative (auto-resolve auth)
 attackmap analyze <path> --llm --llm-backend cli         # force Claude CLI
+attackmap suggest ./repo                 # recommend plugins for a repo shape
+attackmap suggest ./repo --install       # and pip-install the missing ones
 attackmap modules                        # list installed analyzers
 ```
 

{attackmap-0.1.0 → attackmap-0.2.0}/README.md

@@ -49,7 +49,7 @@ Read `reports/defensive-review.md` (heuristic) and `reports/defensive-review-llm
 ```bash
 pip install attackmap                  # core only
 pip install "attackmap[llm]"           # add LLM narrative support
-pip install "attackmap[all]"           # core + LLM + all 11 analyzer plugins
+pip install "attackmap[all]"           # core + LLM + all 13 analyzer plugins
 ```
 
 You can also install individual analyzer plugins on demand:
@@ -58,6 +58,17 @@ You can also install individual analyzer plugins on demand:
 pip install attackmap-analyzer-python attackmap-analyzer-go
 ```
 
+Not sure which plugins your repo needs? Let AttackMap tell you:
+
+```bash
+attackmap suggest ./path/to/repo          # print ranked pip lines
+attackmap suggest ./path/to/repo --install # and install them (prompts once)
+```
+
+`suggest` inspects the repo's manifest files, extensions, and directory layout
+and recommends only the plugins that would give it deeper signal — useful
+when you want a smaller install footprint than `[all]`.
+
 ### With Docker
 
 ```bash
@@ -92,9 +103,102 @@ Every `attackmap analyze` run writes:
 | `defensive-review.json` | Structured equivalent (schema v1.2.0) |
 | `review-context-pack.json` | Structured evidence pack consumed by the LLM stage |
 | `attackmap-report.json` | Everything bundled |
+| `attackmap-report.sarif` | SARIF 2.1.0 log — ingestable by GitHub Code Scanning, VS Code, and other SARIF consumers |
+| `attackmap-paths.md` | Mermaid flowcharts of each attack path — renders inline on GitHub |
+| `attackmap-topology.md` | Mermaid graph of the service topology, with edge kinds styled per relationship type |
+| `attackmap-paths.dot` / `attackmap-topology.dot` | Graphviz DOT versions of the two diagrams — feed into `dot -Tsvg` for slide-quality graphics |
 | `defensive-review-llm.md` *(with `--llm`)* | Claude-narrated review |
 | `defensive-review-llm.meta.json` *(with `--llm`)* | Backend, model, token usage |
 
+### GitHub Code Scanning integration
+
+Drop this into `.github/workflows/attackmap.yml` to get AttackMap findings inline on every PR:
+
+```yaml
+name: AttackMap
+on: [pull_request, push]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install "attackmap[all]"
+      - run: attackmap analyze . --output reports
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: reports/attackmap-report.sarif
+          category: attackmap
+```
+
+### Diff mode (PR gating)
+
+For a lighter CI integration than Code Scanning — a bot comment, a JSON delta,
+or a hard fail on newly-introduced HIGH findings — point `--baseline` at a
+prior report and AttackMap will emit a Markdown diff alongside the fresh
+report:
+
+```bash
+attackmap analyze . --output reports \
+  --baseline path/to/previous/attackmap-report.json \
+  --diff-output reports/attackmap-diff.md \
+  --fail-on-new-high        # exit non-zero if the PR introduces any HIGH finding
+```
+
+Findings get a stable id (hash of the finding title) that survives line drift
+on unrelated commits, so a finding that persists across scans has the same id
+in both. The diff has three sections — **New**, **Persisted**, **Resolved** —
+which drop cleanly into a PR comment.
+
+### SBOM inventory
+
+Every scan also produces a lightweight SBOM by parsing direct dependencies out
+of the common manifest files:
+
+| Ecosystem | Files parsed |
+|---|---|
+| PyPI (Python) | `pyproject.toml` (PEP 621 + Poetry), `requirements.txt` |
+| npm (Node.js) | `package.json` (dependencies + devDependencies + peer/optional) |
+| Go | `go.mod` (single-line + block-form `require`, `// indirect` flagged) |
+| Cargo (Rust) | `Cargo.toml` (dependencies + dev-dependencies + build-dependencies) |
+| Composer (PHP) | `composer.json` (require + require-dev; platform reqs skipped) |
+
+Each entry appears in `attackmap-report.json` under `scan.dependencies` with
+`{name, version, ecosystem, file, dev}`. Version ranges are kept verbatim
+(`^4.16.0`, `>=2,<3`, `latest`) — this slice does not resolve lockfiles.
+
+### CVE cross-reference (opt-in)
+
+`attackmap analyze --cve` cross-references every SBOM entry against
+[OSV.dev](https://osv.dev) and emits one finding per vulnerable dependency
+(all known advisories aggregated in the evidence list). CVSS scores map into
+low/medium/high — anything ≥ 7.0 is HIGH.
+
+```bash
+attackmap analyze . --cve
+```
+
+- **Off by default.** The flag exists precisely because CVE lookup does
+  network I/O; regular scans stay offline.
+- **Cached** under `~/.attackmap/cache/osv/` keyed by
+  `sha256(ecosystem+name+version)`. TTL is 24h by default, overridable via
+  `ATTACKMAP_OSV_CACHE_TTL_HOURS`. Repeat scans of the same repo don't hit
+  the network.
+- **Offline-tolerant.** If the network's unavailable but the cache is warm,
+  cached results still surface; only fresh queries are skipped.
+- **Version resolution is best-effort.** Manifest ranges (`^4.16.0`,
+  `>=2.28,<3`) resolve to a queryable lower-bound; OSV does the range math.
+  Unpinned specs (`*`, `latest`) are skipped.
+
+The structured vulnerability list is available under
+`scan.vulnerabilities` in `attackmap-report.json` with
+`{id, aliases, summary, severity, cvss_score, references, affected_range,
+package_name, package_version, ecosystem}`.
+
 ---
 
 ## How it works
@@ -129,7 +233,7 @@ Layered on top: **MITRE ATT&CK technique mappings** on every insight and
 
 ## Supported ecosystems
 
-Eleven official analyzer plugins, each distributable as a separate package:
+Thirteen official analyzer plugins, each distributable as a separate package:
 
 | Plugin | Coverage |
 |---|---|
@@ -147,6 +251,13 @@ Eleven official analyzer plugins, each distributable as a separate package:
 
 `pip install "attackmap[all]"` installs every official plugin.
 
+### Building your own analyzer
+
+The plugin contract is documented in code at
+[`attackmap.sdk`](src/attackmap/sdk/__init__.py); the developer cookbook with
+scaffolding, testing, and publishing instructions is in
+[`docs/external-analyzers.md`](docs/external-analyzers.md).
+
 ---
 
 ## CLI reference
@@ -157,6 +268,8 @@ attackmap analyze <path> --output dir    # write outputs to `dir/`
 attackmap analyze <path> --module python --module rust   # only these analyzers
 attackmap analyze <path> --llm           # add LLM narrative (auto-resolve auth)
 attackmap analyze <path> --llm --llm-backend cli         # force Claude CLI
+attackmap suggest ./repo                 # recommend plugins for a repo shape
+attackmap suggest ./repo --install       # and pip-install the missing ones
 attackmap modules                        # list installed analyzers
 ```
 

{attackmap-0.1.0 → attackmap-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "attackmap"
-version = "0.1.0"
+version = "0.2.0"
 description = "AI-assisted defensive security analyzer for codebases — scans a repository, models assets and controls, finds cross-cutting weaknesses, and generates an evidence-grounded review with MITRE ATT&CK mappings and detection-engineering hints."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -59,19 +59,20 @@ llm = [
 ]
 all = [
   "attackmap[llm]",
-  "attackmap-analyzer-python",
-  "attackmap-analyzer-rust",
-  "attackmap-analyzer-go",
-  "attackmap-analyzer-java-spring",
-  "attackmap-analyzer-dotnet",
-  "attackmap-analyzer-terraform",
-  "attackmap-analyzer-c",
-  "attackmap-analyzer-cpp",
-  "attackmap-analyzer-node-service",
-  "attackmap-analyzer-atproto",
-  "attackmap-analyzer-php-web",
-  "attackmap-analyzer-php-laminas",
-  "attackmap-analyzer-omeka-s",
+  "attackmap-analyzer-python>=0.1.0",
+  "attackmap-analyzer-rust>=0.1.0",
+  "attackmap-analyzer-go>=0.1.0",
+  "attackmap-analyzer-java-spring>=0.1.0",
+  "attackmap-analyzer-dotnet>=0.1.0",
+  "attackmap-analyzer-terraform>=0.1.0",
+  "attackmap-analyzer-c>=0.1.0",
+  "attackmap-analyzer-cpp>=0.1.0",
+  "attackmap-analyzer-node-service>=0.2.0",
+  "attackmap-analyzer-atproto>=0.1.0",
+  "attackmap-analyzer-php-web>=0.1.0",
+  "attackmap-analyzer-php-laminas>=0.1.0",
+  "attackmap-analyzer-omeka-s>=0.1.0",
+  "attackmap-analyzer-iac>=0.1.0",
 ]
 dev = [
   "pytest>=8.0.0",

{attackmap-0.1.0 → attackmap-0.2.0}/src/attackmap/__init__.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{attackmap-0.1.0 → attackmap-0.2.0}/src/attackmap/analyzer.py

@@ -4,15 +4,61 @@ from collections import Counter
 
 import networkx as nx
 
-from .models import AttackSurface, ScanResult
+from .models import AttackSurface, AuthHint, Route, ScanResult
+
+
+# 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
+
+
+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, set[str]] = {}
+    auth_hints_by_file: dict[str, list[AuthHint]] = {}
     for hint in scan.auth_hints:
-        auth_hints_by_file.setdefault(hint.file, set()).add(hint.hint)
-    global_auth_hints = sorted({hint.hint 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 = [
@@ -29,8 +75,7 @@ def identify_attack_surfaces(scan: ScanResult) -> list[AttackSurface]:
 
     for route in scan.routes:
         path_lower = route.path.lower()
-        file_auth_hints = sorted(auth_hints_by_file.get(route.file, set()))
-        auth_signals = file_auth_hints or global_auth_hints
+        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}
         )

attackmap-0.2.0/src/attackmap/analyzer_contracts.py

@@ -0,0 +1,190 @@
+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="Discovery ordering hint. Lower runs first when multiple "
+        "analyzers match. Ties are broken by entry-point name. 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.",
+    )
+    enabled_by_default: bool = Field(
+        default=False,
+        description="Whether to run this analyzer without an explicit "
+        "--module flag. 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)