attackmap 0.1.0__tar.gz → 0.1.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: attackmap
-Version: 0.1.0
+Version: 0.1.1
 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,19 @@ 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"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: build>=1.2.0; extra == "dev"
@@ -107,7 +107,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:
@@ -187,7 +187,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 +205,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

{attackmap-0.1.0 → attackmap-0.1.1}/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:
@@ -129,7 +129,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 +147,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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "attackmap"
-version = "0.1.0"
+version = "0.1.1"
 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,19 @@ 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",
 ]
 dev = [
   "pytest>=8.0.0",

{attackmap-0.1.0 → attackmap-0.1.1}/src/attackmap/analyzers.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable
+from collections.abc import Iterable
 from dataclasses import dataclass
 from importlib.metadata import entry_points
 import json
@@ -8,15 +8,14 @@ import logging
 from pathlib import Path
 import subprocess
 import sys
-from typing import Protocol, TypeVar
-
-_T = TypeVar("_T")
-_K = TypeVar("_K")
+from typing import Protocol
 from urllib.error import URLError
 from urllib.request import urlopen
 
 from pydantic import BaseModel, Field
 
+from .merge import MERGE_SCHEMA, initial_seen, merge_into
+
 from .sdk.contracts import (
     AnalyzerMetadata,
     AnalyzerProtocol,
@@ -166,23 +165,22 @@ def get_builtin_analyzers() -> tuple[FileAnalyzer, ...]:
 
 
 def merge_analyzer_signals(scan: ScanResult, signals: AnalyzerSignals) -> None:
+    """Apply file-by-file analyzer signals onto a running scan result.
+
+    `AnalyzerSignals` is the narrow per-file shape used by the built-in
+    micro-analyzers in this module. Dedup follows :data:`merge.MERGE_SCHEMA`
+    for the field families it covers; routes, external calls, and secrets
+    have always been straight extend (intentional: per-file analyzers emit
+    one batch per file, dedup happens at the result-level merge step).
+    """
     scan.routes.extend(signals.routes)
     scan.external_calls.extend(signals.external_calls)
     scan.secret_hints.extend(signals.secret_hints)
 
-    seen_databases = {(hint.kind, hint.file) for hint in scan.databases}
-    for hint in signals.databases:
-        key = (hint.kind, hint.file)
-        if key not in seen_databases:
-            scan.databases.append(hint)
-            seen_databases.add(key)
-
-    seen_auth_hints = {(hint.hint, hint.file) for hint in scan.auth_hints}
-    for hint in signals.auth_hints:
-        key = (hint.hint, hint.file)
-        if key not in seen_auth_hints:
-            scan.auth_hints.append(hint)
-            seen_auth_hints.add(key)
+    rules = {r.attr: r for r in MERGE_SCHEMA}
+    for attr in ("databases", "auth_hints"):
+        rule = rules[attr]
+        merge_into(scan, getattr(signals, attr), rule, initial_seen(scan, rule))
 
 
 # Backward-compatible alias for existing imports from attackmap.analyzers.
@@ -505,6 +503,11 @@ def merge_analyzer_results(
     results: Iterable[AnalyzerResult],
     root: str | Path | None = None,
 ) -> AnalyzerResult:
+    """Combine multiple whole-repo analyzer results into one.
+
+    Field-by-field merge behavior is declared in :data:`merge.MERGE_SCHEMA`
+    and applied uniformly here. See `merge.py` for the rules.
+    """
     result_list = list(results)
     if not result_list:
         resolved_root = Path(root).resolve() if root is not None else Path(".").resolve()
@@ -512,50 +515,15 @@ def merge_analyzer_results(
 
     resolved_root = Path(root).resolve() if root is not None else Path(result_list[0].root).resolve()
     merged = AnalyzerResult(root=str(resolved_root))
-    route_keys: set[tuple[str, str, str]] = set()
-    external_keys: set[tuple[str, str]] = set()
-    database_keys: set[tuple[str, str]] = set()
-    auth_keys: set[tuple[str, str]] = set()
-    service_keys: set[tuple[str, str]] = set()
-    edge_keys: set[tuple[str, str]] = set()
-    entrypoint_keys: set[tuple[str, str]] = set()
-    protocol_keys: set[tuple[str, str]] = set()
-    framework_keys: set[tuple[str, str]] = set()
-    secret_keys: set[tuple[str, str]] = set()
+    seen_by_attr: dict[str, set] = {rule.attr: set() for rule in MERGE_SCHEMA}
 
     for result in result_list:
         merged.files_scanned += result.files_scanned
         for language in result.languages:
             if language not in merged.languages:
                 merged.languages.append(language)
-        _merge_unique_items(merged.routes, route_keys, result.routes, lambda item: (item.path, item.method, item.file))
-        _merge_unique_items(merged.external_calls, external_keys, result.external_calls, lambda item: (item.target, item.file))
-        _merge_unique_items(merged.databases, database_keys, result.databases, lambda item: (item.kind, item.file))
-        _merge_unique_items(merged.auth_hints, auth_keys, result.auth_hints, lambda item: (item.hint, item.file))
-        _merge_unique_items(merged.service_hints, service_keys, result.service_hints, lambda item: (item.hint, item.file))
-        _merge_unique_items(merged.edge_hints, edge_keys, result.edge_hints, lambda item: (item.hint, item.file))
-        _merge_unique_items(
-            merged.entrypoint_hints, entrypoint_keys, result.entrypoint_hints, lambda item: (item.hint, item.file)
-        )
-        _merge_unique_items(merged.protocol_hints, protocol_keys, result.protocol_hints, lambda item: (item.hint, item.file))
-        _merge_unique_items(
-            merged.framework_hints, framework_keys, result.framework_hints, lambda item: (item.hint, item.file)
-        )
-        _merge_unique_items(merged.secret_hints, secret_keys, result.secret_hints, lambda item: (item.name, item.file))
+        for rule in MERGE_SCHEMA:
+            merge_into(merged, getattr(result, rule.attr), rule, seen_by_attr[rule.attr])
 
     merged.languages.sort()
     return merged
-
-
-def _merge_unique_items(
-    destination: list[_T],
-    seen: set[_K],
-    items: Iterable[_T],
-    key_fn: Callable[[_T], _K],
-) -> None:
-    for item in items:
-        key = key_fn(item)
-        if key in seen:
-            continue
-        seen.add(key)
-        destination.append(item)

attackmap-0.1.1/src/attackmap/merge.py

@@ -0,0 +1,91 @@
+"""Centralized merge behavior for analyzer outputs.
+
+This module is the single source of truth for **how** analyzer-emitted
+signals are combined into a single ScanResult. It is loaded by both the
+public `merge_analyzer_results` (whole-repo analyzers) and the internal
+`merge_analyzer_signals` (file-by-file built-in micro-analyzers).
+
+A new structured signal type is added in one place: append a row to
+:data:`MERGE_SCHEMA` describing the field name and its dedup key. All
+merge / dedup behavior follows automatically.
+
+## Merge rules
+
+- **Deterministic ordering**: first-seen wins. The order signals appear
+  in the merged result is the order they first appeared across the input
+  results, walked in input order. We do not reorder.
+- **Deduplication**: each list field has a stable key extracted from the
+  signal itself (e.g. `(path, method, file)` for routes). Two signals
+  that hash to the same key are treated as duplicates; only the first is
+  kept.
+- **`languages`**: union, then sorted alphabetically for stable display.
+- **`files_scanned`**: summed across results.
+- **`root`**: taken from the explicit `root` argument when supplied,
+  otherwise from the first result.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class MergeRule:
+    """How one list field on `ScanResult` is merged across analyzer outputs.
+
+    - `attr`: the attribute name on `ScanResult` (e.g. `"routes"`).
+    - `key`: a callable that returns a hashable dedup key for one signal.
+    """
+
+    attr: str
+    key: Callable[[Any], tuple]
+
+    def __post_init__(self) -> None:
+        if not self.attr.isidentifier():
+            raise ValueError(f"MergeRule.attr must be a valid identifier, got {self.attr!r}")
+
+
+# The complete schema of list fields on `ScanResult` that get merged
+# across analyzer outputs. Order is preserved in the merged result;
+# duplicates (by key) are suppressed.
+MERGE_SCHEMA: tuple[MergeRule, ...] = (
+    MergeRule("routes", lambda item: (item.path, item.method, item.file)),
+    MergeRule("external_calls", lambda item: (item.target, item.file)),
+    MergeRule("databases", lambda item: (item.kind, item.file)),
+    MergeRule("auth_hints", lambda item: (item.hint, item.file)),
+    MergeRule("service_hints", lambda item: (item.hint, item.file)),
+    MergeRule("edge_hints", lambda item: (item.hint, item.file)),
+    MergeRule("entrypoint_hints", lambda item: (item.hint, item.file)),
+    MergeRule("protocol_hints", lambda item: (item.hint, item.file)),
+    MergeRule("framework_hints", lambda item: (item.hint, item.file)),
+    MergeRule("secret_hints", lambda item: (item.name, item.file)),
+)
+
+
+def merge_into(destination: Any, items: Iterable[Any], rule: MergeRule, seen: set) -> None:
+    """Append `items` onto `destination.<rule.attr>` deduping against `seen`.
+
+    `seen` is mutated to include the keys of items that were appended.
+    Pre-populate `seen` with keys from the existing destination if you
+    want to merge across multiple sources without rescanning the list.
+    """
+    target = getattr(destination, rule.attr)
+    for item in items:
+        k = rule.key(item)
+        if k in seen:
+            continue
+        seen.add(k)
+        target.append(item)
+
+
+def initial_seen(destination: Any, rule: MergeRule) -> set:
+    """Compute the `seen` set for items already on `destination.<rule.attr>`.
+
+    Used by callers that merge into a non-empty destination.
+    """
+    return {rule.key(item) for item in getattr(destination, rule.attr)}
+
+
+__all__ = ["MergeRule", "MERGE_SCHEMA", "merge_into", "initial_seen"]

attackmap-0.1.1/src/attackmap/sdk/__init__.py

@@ -0,0 +1,105 @@
+"""Public, stable contract surface for AttackMap analyzers.
+
+Anything you can import from ``attackmap.sdk`` is part of the stable analyzer
+contract. Anything you cannot is an internal implementation detail of the
+``attackmap`` package and may change without a major-version bump.
+
+## What an analyzer is
+
+An analyzer is a Python object that satisfies :class:`AnalyzerProtocol`:
+
+- exposes ``metadata: AnalyzerMetadata``
+- exposes a ``name`` property
+- implements ``detect(root) -> bool`` — does this repo look like something
+  the analyzer should run on?
+- implements ``analyze(root) -> AnalyzerResult`` — extract structured
+  signals (routes, external calls, hints, …) from the repo
+
+External analyzers register themselves via the ``attackmap.analyzers``
+Python entry-point group. See the README of any official analyzer (e.g.
+``attackmap-analyzer-python``) for a working example.
+
+## Responsibilities
+
+Analyzers emit **structured signals** — small, evidence-bearing data points
+with a file/line citation. They do *not* generate findings, attack paths,
+or reports. Specifically:
+
+| Owned by analyzers | Owned by core |
+|---|---|
+| Detecting whether they should run | Discovering and loading analyzers |
+| Extracting routes, external calls, databases | Merging results across analyzers |
+| Emitting auth/secret/service/edge/protocol/framework/entrypoint hints | Building the system graph |
+| Surface-level normalization (path canonicalization, etc.) | Generating findings + severity |
+| | Generating attack paths and threat-model output |
+| | Rendering CLI / JSON / markdown reports |
+
+If you find yourself wanting to add finding generation or report rendering
+to an analyzer, the answer is almost always "emit a richer signal and let
+core do the reasoning."
+
+## Merge semantics
+
+When multiple analyzers run against the same repo, their results are
+merged by `attackmap.analyzers.merge_analyzer_results`. The schema is
+declared in `attackmap.merge.MERGE_SCHEMA`; the rules are:
+
+- **Order**: first-seen wins. Order across analyzers is the order
+  `entry_points()` returns them in (Python's discovery order, by entry
+  point name).
+- **Dedup**: each list field has a stable tuple key, e.g. routes are
+  deduped by ``(path, method, file)`` and auth hints by ``(hint, file)``.
+- **Languages**: union, sorted for stable display.
+- **Files scanned**: summed.
+
+Two analyzers that both emit a route for the same ``(path, method, file)``
+produce one route in the merged result — whichever was emitted first.
+
+## Versioning
+
+The names exported below are stable across minor releases of the
+``attackmap`` package. Breaking changes to this surface only happen on
+a major-version bump; deprecations get one release of overlap.
+"""
+
+from __future__ import annotations
+
+from .contracts import (
+    AnalyzerMetadata,
+    AnalyzerProtocol,
+    AnalyzerRepositoryModule,
+    AnalyzerResult,
+    normalize_analyzer_metadata,
+)
+from .models import (
+    AuthHint,
+    DatabaseHint,
+    EdgeHint,
+    EntrypointHint,
+    ExternalCall,
+    FrameworkHint,
+    ProtocolHint,
+    Route,
+    ScanResult,
+    SecretHint,
+    ServiceHint,
+)
+
+__all__ = [
+    "AnalyzerResult",
+    "AnalyzerMetadata",
+    "AnalyzerRepositoryModule",
+    "AnalyzerProtocol",
+    "normalize_analyzer_metadata",
+    "Route",
+    "ExternalCall",
+    "DatabaseHint",
+    "AuthHint",
+    "ServiceHint",
+    "EdgeHint",
+    "EntrypointHint",
+    "ProtocolHint",
+    "FrameworkHint",
+    "SecretHint",
+    "ScanResult",
+]