agent-capmap 0.1.0__py3-none-any.whl

agentcapmap/policies/default.yaml

@@ -0,0 +1,113 @@
+# agent-capmap default policy.
+#
+# Rules are evaluated per agent (one client config) over the union of the tools it can
+# reach. Copy this file and pass it with --policy to customize. Format reference:
+# schemas/policy.schema.json and docs/threat-model.md.
+#
+# Condition semantics:
+#   when_server            filters which servers count (a dict: all fields match; a list
+#                          of dicts: any one matches). Alone, it reports matching servers.
+#   when_agent_has_all     every predicate is satisfied by at least one tool
+#   when_agent_has_any     at least one predicate is satisfied by at least one tool
+#                          (fields inside one predicate must match on the same tool;
+#                          a list value means "any of these values")
+#   when_hash_changed      tool definitions differ from the --baseline file
+#   when_tool_name_shadowed  the same tool name is exposed by more than one server
+version: 1
+taxonomy_version: "1"
+
+# Uncomment and list your vetted sources to make CAP-007 also flag unvetted servers.
+# trusted_sources:
+#   - npm:@modelcontextprotocol/*
+#   - docker:ghcr.io/github/github-mcp-server
+#   - url:mcp.sentry.dev
+
+rules:
+  - id: CAP-001
+    severity: critical
+    when_agent_has_all:
+      - data_access: [private_read, secrets_read]
+      - untrusted_input: true
+      - egress: external
+    message: >-
+      Lethal trifecta: the agent can read private data, ingest attacker-controlled
+      content, and send data externally, so injected instructions can exfiltrate data.
+    maps_to: [OWASP-LLM01, OWASP-LLM02, OWASP-LLM06, MITRE-ATLAS-AML.T0051.001, MITRE-ATLAS-AML.T0086]
+
+  - id: CAP-002
+    severity: critical
+    when_agent_has_all:
+      - untrusted_input: true
+      - execution: host
+    message: >-
+      Untrusted content can reach host-level code execution: an injected instruction
+      can run commands on the machine.
+    maps_to: [OWASP-LLM01, OWASP-LLM06, MITRE-ATLAS-AML.T0051.001, MITRE-ATLAS-AML.T0053]
+
+  - id: CAP-003
+    severity: high
+    when_agent_has_any:
+      - mutation: destructive
+        approval_gate: [none, unknown]
+      - execution: host
+        approval_gate: [none, unknown]
+    message: >-
+      Destructive or host-execution tool without a detectable human approval gate.
+      ("unknown" means the config does not show one; set approval_gate to [none] to
+      flag only explicit auto-approval.)
+    maps_to: [OWASP-LLM06, MITRE-ATLAS-AML.T0101, MITRE-ATLAS-AML.T0053]
+
+  - id: CAP-004
+    severity: high
+    when_agent_has_all:
+      - data_access: secrets_read
+      - egress: external
+    message: The agent can read secrets and send data externally.
+    maps_to: [OWASP-LLM02, OWASP-LLM06, MITRE-ATLAS-AML.T0098, MITRE-ATLAS-AML.T0086]
+
+  - id: CAP-005
+    severity: high
+    # Remote servers only: a local stdio server runs as the user rather than being
+    # reachable without authentication.
+    when_server:
+      remote: true
+      auth: none
+    when_agent_has_any:
+      - any_capability: true
+    message: Remote MCP server answers without authentication and exposes capabilities.
+    maps_to: [OWASP-LLM06, MITRE-ATLAS-AML.T0053]
+
+  - id: CAP-006
+    severity: high
+    when_hash_changed: true
+    message: >-
+      Tool definitions changed since the pinned baseline (possible rug pull). Review
+      the change before trusting this server again.
+    maps_to: [OWASP-LLM03, MITRE-ATLAS-AML.T0109, MITRE-ATLAS-AML.T0010.005]
+
+  - id: CAP-007
+    severity: medium
+    when_server:
+      - version_pinned: unpinned
+      - source_trust: untrusted
+    message: >-
+      Server is not pinned to an exact version or digest, or does not come from a
+      vetted source, so its code can change without review.
+    maps_to: [OWASP-LLM03, MITRE-ATLAS-AML.T0010.005]
+
+  - id: CAP-008
+    severity: high
+    when_agent_has_any:
+      - suspicious_description: true
+    message: >-
+      Tool description contains instructions aimed at the model (possible tool
+      poisoning).
+    maps_to: [OWASP-LLM01, OWASP-LLM03, MITRE-ATLAS-AML.T0110]
+
+  - id: CAP-009
+    severity: medium
+    when_tool_name_shadowed: true
+    message: >-
+      The same tool name is exposed by more than one server on this agent; one can
+      shadow or intercept the other.
+    maps_to: [OWASP-LLM03, OWASP-LLM06, MITRE-ATLAS-AML.T0110]

agentcapmap/policy/__init__.py

@@ -0,0 +1,24 @@
+"""Policy-as-code: YAML rules evaluated deterministically over per-agent capabilities."""
+
+from agentcapmap.policy.engine import evaluate, evaluate_rule
+from agentcapmap.policy.loader import (
+    DEFAULT_POLICY_NAME,
+    Policy,
+    PolicyError,
+    Predicate,
+    Rule,
+    load_policy,
+    parse_policy,
+)
+
+__all__ = [
+    "DEFAULT_POLICY_NAME",
+    "Policy",
+    "PolicyError",
+    "Predicate",
+    "Rule",
+    "evaluate",
+    "evaluate_rule",
+    "load_policy",
+    "parse_policy",
+]

agentcapmap/policy/engine.py

@@ -0,0 +1,229 @@
+"""Deterministic rule evaluation (design rule 1: no LLM calls here, ever).
+
+Every finding carries its evidence: the agent, servers, tools, the fields that matched
+with their actual values, and the source phrases backing them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterator
+from typing import Any
+
+from agentcapmap.baseline import Baseline, diff_server
+from agentcapmap.findings import (
+    Evaluation,
+    Finding,
+    FindingEvidence,
+    NotAssessed,
+    RuleInfo,
+    ServerLocation,
+    Severity,
+    SkippedRule,
+)
+from agentcapmap.graph import AgentView, ServerView, ToolView, build_views, capabilities
+from agentcapmap.models import Inventory
+from agentcapmap.policy.loader import Policy, Predicate, Rule
+from agentcapmap.redact import get_logger
+
+log = get_logger(__name__)
+
+
+def _fingerprint(rule: Rule, agent_id: str, servers: list[str], tools: list[str]) -> str:
+    material = json.dumps([rule.id, agent_id, sorted(servers), sorted(tools)], ensure_ascii=False)
+    return hashlib.sha256(material.encode("utf-8")).hexdigest()[:32]
+
+
+def _tool_evidence(predicate: Predicate, tv: ToolView) -> FindingEvidence:
+    phrases = {name: p for name in predicate.names if (p := tv.phrase(name))}
+    return FindingEvidence(
+        server=tv.server.name,
+        tool=tv.tool.name,
+        matched={name: tv.field(name) for name in predicate.names},
+        phrases=phrases,
+        unverified=[name for name in predicate.names if tv.unverified(name)],
+    )
+
+
+def _server_evidence(rule: Rule, sv: ServerView) -> FindingEvidence | None:
+    if rule.server_filter is None:
+        return None
+    predicate = next(p for p in rule.server_filter if p.matches(sv))
+    return FindingEvidence(
+        server=sv.name,
+        matched={name: sv.field(name) for name in predicate.names},
+        phrases={name: sv.phrase(name) for name in predicate.names},
+    )
+
+
+def _finding(
+    rule: Rule,
+    view: AgentView,
+    servers: list[ServerView],
+    tools: list[str],
+    evidence: list[FindingEvidence],
+    details: dict[str, Any] | None = None,
+) -> Finding:
+    ordered = sorted(servers, key=lambda s: (s.server.location.line or 0, s.name))
+    names = sorted({s.name for s in servers})
+    unique_tools = sorted(set(tools))
+    return Finding(
+        rule_id=rule.id,
+        severity=rule.severity,
+        message=rule.message,
+        maps_to=list(rule.maps_to),
+        agent_id=view.agent.id,
+        config_path=view.agent.config_path,
+        location=ordered[0].server.location if ordered else None,
+        server_locations=[
+            ServerLocation(server=s.name, path=s.server.location.path, line=s.server.location.line)
+            for s in ordered
+        ],
+        servers=names,
+        tools=unique_tools,
+        evidence=evidence,
+        details=details or {},
+        fingerprint=_fingerprint(rule, view.agent.id, names, unique_tools),
+    )
+
+
+def _tag_rule(rule: Rule, view: AgentView, eligible: list[ServerView]) -> Iterator[Finding]:
+    names = {s.name for s in eligible}
+    candidates = [t for t in view.tools if t.server.name in names]
+    matched: list[tuple[Predicate, list[ToolView]]] = []
+
+    for predicate in rule.has_all:
+        hits = [t for t in candidates if predicate.matches(t)]
+        if not hits:
+            return
+        matched.append((predicate, hits))
+    if rule.has_any:
+        any_hits = [
+            (p, hits) for p in rule.has_any if (hits := [t for t in candidates if p.matches(t)])
+        ]
+        if not any_hits:
+            return
+        matched.extend(any_hits)
+
+    evidence: list[FindingEvidence] = []
+    involved: dict[str, ServerView] = {}
+    tools: list[str] = []
+    for predicate, hits in matched:
+        for tv in sorted(hits, key=lambda t: t.ref):
+            evidence.append(_tool_evidence(predicate, tv))
+            involved[tv.server.name] = tv.server
+            tools.append(tv.ref)
+    for sv in sorted(involved.values(), key=lambda s: s.name):
+        if (server_ev := _server_evidence(rule, sv)) is not None:
+            evidence.append(server_ev)
+    yield _finding(rule, view, list(involved.values()), tools, evidence)
+
+
+def _server_rule(rule: Rule, view: AgentView, eligible: list[ServerView]) -> Iterator[Finding]:
+    for sv in eligible:
+        server_ev = _server_evidence(rule, sv)
+        yield _finding(rule, view, [sv], [], [server_ev] if server_ev else [])
+
+
+def _hash_rule(
+    rule: Rule, view: AgentView, eligible: list[ServerView], baseline: Baseline
+) -> Iterator[Finding]:
+    for sv in eligible:
+        diff = diff_server(baseline, sv.server)
+        if not diff:
+            continue
+        summary = ", ".join(
+            f"{label}: {', '.join(items)}"
+            for label, items in (
+                ("changed", diff.changed),
+                ("added", diff.added),
+                ("removed", diff.removed),
+            )
+            if items
+        )
+        evidence = [
+            FindingEvidence(
+                server=sv.name, matched={"definitions_changed": True}, phrases={"diff": summary}
+            )
+        ]
+        tools = [f"{sv.name}/{n}" for n in (*diff.changed, *diff.added, *diff.removed)]
+        yield _finding(rule, view, [sv], tools, evidence, details=diff.model_dump())
+
+
+def _shadow_rule(rule: Rule, view: AgentView, eligible: list[ServerView]) -> Iterator[Finding]:
+    by_name: dict[str, list[ServerView]] = {}
+    for sv in eligible:
+        for tool_name in sorted(set(view.tool_names.get(sv.name, []))):
+            by_name.setdefault(tool_name, []).append(sv)
+    for tool_name, servers in sorted(by_name.items()):
+        if len(servers) < 2:
+            continue
+        evidence = [
+            FindingEvidence(
+                server=sv.name,
+                tool=tool_name,
+                matched={"tool_name_shadowed": True},
+                phrases={"servers": ", ".join(s.name for s in servers)},
+            )
+            for sv in servers
+        ]
+        tools = [f"{sv.name}/{tool_name}" for sv in servers]
+        yield _finding(rule, view, servers, tools, evidence, details={"tool_name": tool_name})
+
+
+def evaluate_rule(rule: Rule, view: AgentView, baseline: Baseline | None) -> list[Finding]:
+    filters = rule.server_filter
+    eligible = [s for s in view.servers if filters is None or any(p.matches(s) for p in filters)]
+    if rule.hash_changed:
+        return list(_hash_rule(rule, view, eligible, baseline)) if baseline else []
+    if rule.shadowed:
+        return list(_shadow_rule(rule, view, eligible))
+    if rule.tag_based:
+        return list(_tag_rule(rule, view, eligible))
+    return list(_server_rule(rule, view, eligible))
+
+
+def evaluate(inventory: Inventory, policy: Policy, baseline: Baseline | None = None) -> Evaluation:
+    views = build_views(inventory, list(policy.trusted_sources))
+    findings: list[Finding] = []
+    skipped: list[SkippedRule] = []
+    for rule in policy.rules:
+        if not rule.enabled:
+            skipped.append(SkippedRule(rule_id=rule.id, reason="disabled in policy"))
+            continue
+        if rule.hash_changed and baseline is None:
+            skipped.append(SkippedRule(rule_id=rule.id, reason="no baseline provided (--baseline)"))
+            continue
+        for view in views:
+            findings.extend(evaluate_rule(rule, view, baseline))
+
+    findings.sort(key=lambda f: (-f.severity.rank, f.rule_id, f.agent_id, f.servers, f.tools))
+    not_assessed: list[NotAssessed] = [na for v in views for na in v.not_assessed]
+    if not_assessed:
+        log.warning(
+            "%d server(s) or tool(s) were not assessed; findings may be incomplete "
+            "(see 'not_assessed' in the output)",
+            len(not_assessed),
+        )
+    summary = {s.value: sum(1 for f in findings if f.severity is s) for s in Severity}
+    summary["not_assessed"] = len(not_assessed)
+    return Evaluation(
+        policy=policy.info,
+        rules=[
+            RuleInfo(
+                id=r.id,
+                severity=r.severity,
+                message=r.message,
+                maps_to=list(r.maps_to),
+                enabled=r.enabled,
+            )
+            for r in policy.rules
+        ],
+        baseline_used=baseline is not None,
+        agents=[capabilities(v) for v in views],
+        findings=findings,
+        not_assessed=not_assessed,
+        skipped_rules=skipped,
+        summary=summary,
+    )

agentcapmap/policy/loader.py

@@ -0,0 +1,223 @@
+"""Load and validate policy files.
+
+Policy files may come from a repository being scanned, so they are untrusted input:
+- size-capped before parsing;
+- parsed with PyYAML's safe loader only (no arbitrary object construction);
+- anchors and aliases rejected (no "billion laughs" expansion, no merge-key tricks);
+- duplicate keys rejected (YAML would otherwise silently keep the last one);
+- validated against schemas/policy.schema.json, with unknown fields rejected;
+- checked for duplicate rule ids and contradictory condition combinations.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import best_match
+
+from agentcapmap.findings import PolicyInfo, Severity
+from agentcapmap.taxonomy import TAXONOMY_VERSION, data_file
+
+DEFAULT_POLICY_NAME = "builtin:default.yaml"
+# Policies are small (the default is ~4 KB); a tight cap also bounds parser work.
+_MAX_POLICY_BYTES = 256 * 1024
+_MAX_FLOW_DEPTH = 32
+
+
+class PolicyError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Predicate:
+    """Field -> allowed values. Every field must match on the same tool or server."""
+
+    fields: tuple[tuple[str, frozenset[str | bool]], ...]
+
+    def matches(self, view: Any) -> bool:
+        return all(view.field(name) in allowed for name, allowed in self.fields)
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        return tuple(name for name, _ in self.fields)
+
+    def describe(self) -> dict[str, Any]:
+        return {
+            name: sorted(allowed, key=str) if len(allowed) > 1 else next(iter(allowed))
+            for name, allowed in self.fields
+        }
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    severity: Severity
+    message: str
+    maps_to: tuple[str, ...]
+    enabled: bool
+    has_all: tuple[Predicate, ...]
+    has_any: tuple[Predicate, ...]
+    server_filter: tuple[Predicate, ...] | None
+    hash_changed: bool
+    shadowed: bool
+
+    @property
+    def tag_based(self) -> bool:
+        return bool(self.has_all or self.has_any)
+
+
+@dataclass(frozen=True)
+class Policy:
+    rules: tuple[Rule, ...]
+    trusted_sources: tuple[str, ...]
+    info: PolicyInfo
+
+
+class _StrictSafeLoader(yaml.SafeLoader):
+    """SafeLoader that refuses duplicate mapping keys."""
+
+    def construct_mapping(self, node: yaml.MappingNode, deep: bool = False) -> dict[Any, Any]:
+        seen: set[Any] = set()
+        for key_node, _value in node.value:
+            key = self.construct_object(key_node, deep=deep)
+            try:
+                duplicate = key in seen
+            except TypeError:
+                raise PolicyError(
+                    f"unsupported mapping key at line {key_node.start_mark.line + 1}"
+                ) from None
+            if duplicate:
+                raise PolicyError(f"duplicate key {key!r} at line {key_node.start_mark.line + 1}")
+            seen.add(key)
+        return super().construct_mapping(node, deep=deep)
+
+
+def _check_flow_depth(text: str) -> None:
+    """Reject deep [ / { nesting before PyYAML sees it.
+
+    PyYAML's parser is super-linear in flow-collection depth (8,000 nested brackets take
+    ~50 s), so a small hostile file could stall a scan. Brackets inside quoted strings
+    are counted too: that is conservative (it can only reject, never let through), and
+    no sensible policy comes close to the limit.
+    """
+    depth = 0
+    for index, char in enumerate(text):
+        if char in "[{":
+            depth += 1
+            if depth > _MAX_FLOW_DEPTH:
+                line = text.count("\n", 0, index) + 1
+                raise PolicyError(f"YAML nested more than {_MAX_FLOW_DEPTH} levels (line {line})")
+        elif char in "]}" and depth:
+            depth -= 1
+
+
+def _parse_yaml(text: str) -> Any:
+    _check_flow_depth(text)
+    try:
+        for event in yaml.parse(text, Loader=yaml.SafeLoader):
+            if isinstance(event, yaml.AliasEvent) or getattr(event, "anchor", None):
+                line = event.start_mark.line + 1 if event.start_mark else "?"
+                raise PolicyError(f"YAML anchors and aliases are not allowed (line {line})")
+        loader = _StrictSafeLoader(text)
+        try:
+            return loader.get_single_data()
+        finally:
+            loader.dispose()
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        where = f" at line {mark.line + 1}" if mark is not None else ""
+        raise PolicyError(f"invalid YAML{where}") from None
+    except RecursionError:
+        raise PolicyError("YAML nested too deeply") from None
+
+
+@functools.cache
+def _validator() -> Draft202012Validator:
+    schema = json.loads(data_file("schemas", "policy.schema.json"))
+    Draft202012Validator.check_schema(schema)
+    return Draft202012Validator(schema)
+
+
+def _predicates(raw: Any) -> tuple[Predicate, ...]:
+    if raw is None:
+        return ()
+    items = raw if isinstance(raw, list) else [raw]
+    return tuple(
+        Predicate(
+            fields=tuple(
+                (name, frozenset(value if isinstance(value, list) else [value]))
+                for name, value in sorted(item.items())
+            )
+        )
+        for item in items
+    )
+
+
+def _build_rule(raw: dict[str, Any]) -> Rule:
+    rule = Rule(
+        id=raw["id"],
+        severity=Severity(raw["severity"]),
+        message=" ".join(raw["message"].split()),
+        maps_to=tuple(raw.get("maps_to", [])),
+        enabled=raw.get("enabled", True),
+        has_all=_predicates(raw.get("when_agent_has_all")),
+        has_any=_predicates(raw.get("when_agent_has_any")),
+        server_filter=_predicates(raw["when_server"]) if "when_server" in raw else None,
+        hash_changed=raw.get("when_hash_changed", False),
+        shadowed=raw.get("when_tool_name_shadowed", False),
+    )
+    special = [flag for flag in (rule.hash_changed, rule.shadowed) if flag]
+    if len(special) > 1 or (special and rule.tag_based):
+        raise PolicyError(
+            f"rule {rule.id}: when_hash_changed / when_tool_name_shadowed cannot be combined "
+            "with each other or with when_agent_has_* conditions"
+        )
+    return rule
+
+
+def parse_policy(text: str, source: str) -> Policy:
+    data = _parse_yaml(text)
+    error = best_match(_validator().iter_errors(data))
+    if error is not None:
+        where = "/".join(str(p) for p in error.absolute_path) or "(root)"
+        raise PolicyError(f"{source}: invalid policy at {where}: {error.message}")
+    if data["taxonomy_version"] != TAXONOMY_VERSION:
+        raise PolicyError(f"{source}: policy targets taxonomy {data['taxonomy_version']!r}")
+
+    rules = tuple(_build_rule(raw) for raw in data["rules"])
+    ids = [r.id for r in rules]
+    if len(ids) != len(set(ids)):
+        dupes = sorted({i for i in ids if ids.count(i) > 1})
+        raise PolicyError(f"{source}: duplicate rule id(s): {', '.join(dupes)}")
+    return Policy(
+        rules=rules,
+        trusted_sources=tuple(data.get("trusted_sources", [])),
+        info=PolicyInfo(
+            source=source,
+            version=data["version"],
+            taxonomy_version=data["taxonomy_version"],
+            sha256=hashlib.sha256(text.encode("utf-8")).hexdigest(),
+        ),
+    )
+
+
+def load_policy(path: Path | None = None) -> Policy:
+    """Load a policy file, or the built-in default policy when `path` is None."""
+    if path is None:
+        return parse_policy(data_file("policies", "default.yaml"), DEFAULT_POLICY_NAME)
+    try:
+        if path.stat().st_size > _MAX_POLICY_BYTES:
+            raise PolicyError(f"{path}: policy file larger than {_MAX_POLICY_BYTES} bytes")
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise PolicyError(f"cannot read policy {path}: {exc.strerror}") from None
+    except UnicodeDecodeError:
+        raise PolicyError(f"{path}: policy is not UTF-8 text") from None
+    return parse_policy(text, path.as_posix())