agent-capmap 0.1.0__py3-none-any.whl

agentcapmap/report/sarif.py

@@ -0,0 +1,209 @@
+"""SARIF 2.1.0 output for GitHub code scanning.
+
+- Rules come from the policy; GitHub ranks them by `security-severity`.
+- Each result points at the config file and line where the (first) server is defined.
+- Locations must be repository-relative. Absolute paths, `..` segments and URLs are
+  never emitted; GitHub rejects results without a location, so such findings are left
+  out of the SARIF (still present in JSON/Markdown) and a notification says so.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import quote
+
+from agentcapmap import __version__
+from agentcapmap.findings import Evaluation, Finding, RuleInfo, ServerLocation, Severity
+from agentcapmap.report._text import clean
+
+SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+INFORMATION_URI = "https://github.com/NKwolv/agent-capmap"
+FINGERPRINT_KEY = "agentcapmapFinding/v1"
+
+_LEVEL = {
+    Severity.CRITICAL: "error",
+    Severity.HIGH: "error",
+    Severity.MEDIUM: "warning",
+    Severity.LOW: "note",
+    Severity.INFO: "note",
+}
+# GitHub buckets: >= 9.0 critical, 7.0-8.9 high, 4.0-6.9 medium, 0.1-3.9 low.
+_SECURITY_SEVERITY = {
+    Severity.CRITICAL: "9.5",
+    Severity.HIGH: "8.0",
+    Severity.MEDIUM: "5.5",
+    Severity.LOW: "3.0",
+    Severity.INFO: "0.0",
+}
+_WINDOWS_DRIVE = re.compile(r"^[A-Za-z]:")
+
+
+def safe_uri(path: str | None) -> str | None:
+    """A repository-relative URI reference, or None if the path is not safely relative."""
+    if not path:
+        return None
+    normalized = path.replace("\\", "/")
+    if normalized.startswith("/") or _WINDOWS_DRIVE.match(normalized) or "://" in normalized:
+        return None
+    segments = normalized.split("/")
+    if any(seg in ("", ".", "..") for seg in segments):
+        return None
+    return quote(normalized, safe="/-._~")
+
+
+def _location(loc: ServerLocation | None, path: str, line: int | None) -> dict[str, Any] | None:
+    uri = safe_uri(loc.path if loc else path)
+    if uri is None:
+        return None
+    physical: dict[str, Any] = {"artifactLocation": {"uri": uri, "uriBaseId": "%SRCROOT%"}}
+    start = loc.line if loc else line
+    if start and start > 0:
+        physical["region"] = {"startLine": start}
+    return {"physicalLocation": physical}
+
+
+def _rule(rule: RuleInfo) -> dict[str, Any]:
+    message = clean(rule.message, 1000)
+    refs = ", ".join(clean(m, 64) for m in rule.maps_to)
+    help_text = message + (f" Maps to: {refs}." if refs else "")
+    return {
+        "id": rule.id,
+        "name": rule.id.replace("-", ""),
+        "shortDescription": {"text": clean(rule.message.split(". ")[0], 200)},
+        "fullDescription": {"text": message},
+        "help": {"text": help_text},
+        "helpUri": f"{INFORMATION_URI}/blob/main/docs/threat-model.md",
+        "defaultConfiguration": {"level": _LEVEL[rule.severity]},
+        "properties": {
+            "tags": ["security", "mcp", *(clean(m, 64) for m in rule.maps_to)],
+            "precision": "high",
+            "problem.severity": "error" if _LEVEL[rule.severity] == "error" else "warning",
+            "security-severity": _SECURITY_SEVERITY[rule.severity],
+        },
+    }
+
+
+def _message(finding: Finding) -> str:
+    parts = [clean(finding.message, 600), f"Agent: {clean(finding.agent_id, 200)}."]
+    if finding.tools:
+        parts.append(f"Tools: {clean(', '.join(finding.tools), 400)}.")
+    evidence = [
+        f"{clean(ev.tool or ev.server, 80)} [{clean(k, 40)}]: {clean(v, 160)}"
+        for ev in finding.evidence
+        for k, v in ev.phrases.items()
+    ]
+    if evidence:
+        parts.append(
+            "Evidence: " + "; ".join(evidence[:8]) + ("; ..." if len(evidence) > 8 else "")
+        )
+    return " ".join(parts)
+
+
+def _result(finding: Finding, rule_index: int) -> dict[str, Any] | None:
+    first = finding.server_locations[0] if finding.server_locations else None
+    path = finding.location.path if finding.location else finding.config_path
+    line = finding.location.line if finding.location else None
+    primary = _location(first, path, line)
+    if primary is None:
+        return None
+    related = []
+    for index, loc in enumerate(finding.server_locations[1:], start=1):
+        if (location := _location(loc, loc.path, loc.line)) is not None:
+            location["id"] = index
+            location["message"] = {"text": f"server {clean(loc.server, 100)}"}
+            related.append(location)
+    result: dict[str, Any] = {
+        "ruleId": finding.rule_id,
+        "ruleIndex": rule_index,
+        "level": _LEVEL[finding.severity],
+        "message": {"text": _message(finding)},
+        "locations": [primary],
+        "partialFingerprints": {FINGERPRINT_KEY: finding.fingerprint},
+        "properties": {
+            "severity": finding.severity.value,
+            "agent": clean(finding.agent_id, 200),
+            "servers": [clean(s, 100) for s in finding.servers],
+            "tools": [clean(t, 200) for t in finding.tools],
+        },
+    }
+    if related:
+        result["relatedLocations"] = related
+    return result
+
+
+def render(evaluation: Evaluation) -> dict[str, Any]:
+    rules = [r for r in evaluation.rules if r.enabled]
+    rule_index = {r.id: i for i, r in enumerate(rules)}
+    results: list[dict[str, Any]] = []
+    omitted = 0
+    for finding in evaluation.findings:
+        result = _result(finding, rule_index[finding.rule_id])
+        if result is None:
+            omitted += 1
+        else:
+            results.append(result)
+
+    notifications: list[dict[str, Any]] = []
+    if evaluation.not_assessed:
+        notifications.append(
+            {
+                "level": "warning",
+                "descriptor": {"id": "not-assessed"},
+                "message": {
+                    "text": f"{len(evaluation.not_assessed)} server(s) or tool(s) were not "
+                    "assessed (not enumerated or not classified); findings may be incomplete."
+                },
+            }
+        )
+    for skipped in evaluation.skipped_rules:
+        notifications.append(
+            {
+                "level": "note",
+                "descriptor": {"id": "rule-skipped"},
+                "message": {
+                    "text": f"Rule {skipped.rule_id} skipped: {clean(skipped.reason, 200)}"
+                },
+            }
+        )
+    if omitted:
+        notifications.append(
+            {
+                "level": "warning",
+                "descriptor": {"id": "result-omitted"},
+                "message": {
+                    "text": f"{omitted} finding(s) omitted from SARIF because their config "
+                    "file is outside the repository; see the JSON or Markdown report."
+                },
+            }
+        )
+
+    return {
+        "$schema": SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "agent-capmap",
+                        "version": __version__,
+                        "semanticVersion": __version__,
+                        "informationUri": INFORMATION_URI,
+                        "rules": [_rule(r) for r in rules],
+                    }
+                },
+                "invocations": [
+                    {
+                        "executionSuccessful": True,
+                        "toolExecutionNotifications": notifications,
+                    }
+                ],
+                "results": results,
+                "properties": {
+                    "policy": evaluation.policy.model_dump(mode="json"),
+                    "summary": evaluation.summary,
+                    "baselineUsed": evaluation.baseline_used,
+                },
+            }
+        ],
+    }

agentcapmap/schemas/policy.schema.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/NKwolv/agent-capmap/schemas/policy.schema.json",
+  "title": "agent-capmap policy",
+  "description": "Deterministic rules evaluated per agent over the union of its tools. Policy format version 1, taxonomy version 1.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "taxonomy_version", "rules"],
+  "properties": {
+    "version": { "const": 1 },
+    "taxonomy_version": { "const": "1" },
+    "trusted_sources": {
+      "description": "Vetted server sources. Glob patterns over source ids: npm:<pkg>, pypi:<pkg>, docker:<image>, url:<host>, local:<path>. When set, servers matching none are 'untrusted'.",
+      "type": "array",
+      "maxItems": 1000,
+      "items": {
+        "type": "string",
+        "minLength": 5,
+        "maxLength": 256,
+        "pattern": "^(npm|pypi|docker|url|local):[^\\s]+$"
+      }
+    },
+    "rules": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 500,
+      "items": { "$ref": "#/$defs/rule" }
+    }
+  },
+  "$defs": {
+    "rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "severity", "message"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]{1,31}$" },
+        "severity": { "enum": ["critical", "high", "medium", "low", "info"] },
+        "message": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "enabled": { "type": "boolean" },
+        "maps_to": {
+          "type": "array",
+          "maxItems": 20,
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9.:_-]{1,64}$" }
+        },
+        "when_agent_has_all": { "$ref": "#/$defs/tool_predicates" },
+        "when_agent_has_any": { "$ref": "#/$defs/tool_predicates" },
+        "when_server": {
+          "oneOf": [
+            { "$ref": "#/$defs/server_predicate" },
+            {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 20,
+              "items": { "$ref": "#/$defs/server_predicate" }
+            }
+          ]
+        },
+        "when_hash_changed": { "const": true },
+        "when_tool_name_shadowed": { "const": true }
+      },
+      "anyOf": [
+        { "required": ["when_agent_has_all"] },
+        { "required": ["when_agent_has_any"] },
+        { "required": ["when_server"] },
+        { "required": ["when_hash_changed"] },
+        { "required": ["when_tool_name_shadowed"] }
+      ]
+    },
+    "tool_predicates": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "items": { "$ref": "#/$defs/tool_predicate" }
+    },
+    "tool_predicate": {
+      "description": "All fields must match on the same tool. A list means any of the values.",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "data_access": { "$ref": "#/$defs/data_access" },
+        "untrusted_input": { "$ref": "#/$defs/boolean_or_list" },
+        "egress": { "$ref": "#/$defs/egress" },
+        "mutation": { "$ref": "#/$defs/mutation" },
+        "execution": { "$ref": "#/$defs/execution" },
+        "privilege": { "$ref": "#/$defs/privilege" },
+        "suspicious_description": { "type": "boolean" },
+        "any_capability": { "type": "boolean" },
+        "approval_gate": { "$ref": "#/$defs/approval_gate" }
+      }
+    },
+    "server_predicate": {
+      "description": "All fields must match on the same server. A list means any of the values.",
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "auth": { "$ref": "#/$defs/auth" },
+        "transport": { "$ref": "#/$defs/transport" },
+        "remote": { "type": "boolean" },
+        "version_pinned": { "$ref": "#/$defs/version_pinned" },
+        "source_trust": { "$ref": "#/$defs/source_trust" }
+      }
+    },
+    "boolean_or_list": {
+      "oneOf": [
+        { "type": "boolean" },
+        { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "boolean" } }
+      ]
+    },
+    "data_access": {
+      "oneOf": [
+        { "enum": ["none", "private_read", "secrets_read"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["none", "private_read", "secrets_read"] } }
+      ]
+    },
+    "egress": {
+      "oneOf": [
+        { "enum": ["none", "internal", "external"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["none", "internal", "external"] } }
+      ]
+    },
+    "mutation": {
+      "oneOf": [
+        { "enum": ["none", "reversible_write", "destructive"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["none", "reversible_write", "destructive"] } }
+      ]
+    },
+    "execution": {
+      "oneOf": [
+        { "enum": ["none", "sandboxed", "host"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["none", "sandboxed", "host"] } }
+      ]
+    },
+    "privilege": {
+      "oneOf": [
+        { "enum": ["none", "identity_admin"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["none", "identity_admin"] } }
+      ]
+    },
+    "approval_gate": {
+      "oneOf": [
+        { "enum": ["required", "none", "unknown"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["required", "none", "unknown"] } }
+      ]
+    },
+    "auth": {
+      "oneOf": [
+        { "enum": ["none", "static", "oauth", "unknown"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["none", "static", "oauth", "unknown"] } }
+      ]
+    },
+    "transport": {
+      "oneOf": [
+        { "enum": ["stdio", "http", "sse", "ws"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["stdio", "http", "sse", "ws"] } }
+      ]
+    },
+    "version_pinned": {
+      "oneOf": [
+        { "enum": ["pinned", "unpinned", "local", "not_applicable", "unknown"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["pinned", "unpinned", "local", "not_applicable", "unknown"] } }
+      ]
+    },
+    "source_trust": {
+      "oneOf": [
+        { "enum": ["trusted", "untrusted", "unknown"] },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["trusted", "untrusted", "unknown"] } }
+      ]
+    }
+  }
+}

agentcapmap/schemas/tool-tags.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/NKwolv/agent-capmap/schemas/tool-tags.schema.json",
+  "title": "agent-capmap tool classification",
+  "description": "Classifier output for one MCP tool. taxonomy_version 1.",
+  "x-taxonomy-version": "1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["tool", "tags", "confidence", "evidence", "suspicious_description"],
+  "properties": {
+    "tool": {
+      "type": "string",
+      "description": "Exact tool name being classified."
+    },
+    "tags": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["data_access", "untrusted_input", "egress", "mutation", "execution", "privilege"],
+      "properties": {
+        "data_access": { "type": "string", "enum": ["none", "private_read", "secrets_read"] },
+        "untrusted_input": { "type": "boolean" },
+        "egress": { "type": "string", "enum": ["none", "internal", "external"] },
+        "mutation": { "type": "string", "enum": ["none", "reversible_write", "destructive"] },
+        "execution": { "type": "string", "enum": ["none", "sandboxed", "host"] },
+        "privilege": { "type": "string", "enum": ["none", "identity_admin"] }
+      }
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Overall confidence in the tags, 0 to 1."
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-axis phrase from the tool's description or input schema justifying the tag. Required for every non-default tag.",
+      "properties": {
+        "data_access": { "type": "string" },
+        "untrusted_input": { "type": "string" },
+        "egress": { "type": "string" },
+        "mutation": { "type": "string" },
+        "execution": { "type": "string" },
+        "privilege": { "type": "string" }
+      }
+    },
+    "suspicious_description": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["flag", "reason"],
+      "properties": {
+        "flag": { "type": "boolean" },
+        "reason": { "type": "string" }
+      }
+    }
+  }
+}

agentcapmap/taxonomy.py

@@ -0,0 +1,56 @@
+"""Capability taxonomy v1: the six per-tool axes and their default (no-capability) values.
+
+The JSON schema in `schemas/tool-tags.schema.json` is the source of truth for the
+allowed values; this module mirrors it for typed access and loads the schema file.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib import resources
+from pathlib import Path
+from typing import Any, Final
+
+TAXONOMY_VERSION: Final = "1"
+
+AXES: Final = ("data_access", "untrusted_input", "egress", "mutation", "execution", "privilege")
+
+# The value meaning "this tool has no capability on this axis".
+DEFAULTS: Final[dict[str, str | bool]] = {
+    "data_access": "none",
+    "untrusted_input": False,
+    "egress": "none",
+    "mutation": "none",
+    "execution": "none",
+    "privilege": "none",
+}
+
+_SCHEMA_FILE = "tool-tags.schema.json"
+
+
+def data_file(directory: str, name: str) -> str:
+    """Read a bundled data file (schemas/, policies/): from the wheel, else the checkout."""
+    packaged = resources.files("agentcapmap").joinpath(directory, name)
+    if packaged.is_file():
+        return packaged.read_text(encoding="utf-8")
+    repo_copy = Path(__file__).resolve().parents[2] / directory / name
+    return repo_copy.read_text(encoding="utf-8")
+
+
+@cache
+def tool_tags_schema() -> dict[str, Any]:
+    schema: dict[str, Any] = json.loads(data_file("schemas", _SCHEMA_FILE))
+    if schema.get("x-taxonomy-version") != TAXONOMY_VERSION:
+        raise RuntimeError(
+            f"{_SCHEMA_FILE} is taxonomy version {schema.get('x-taxonomy-version')!r}, "
+            f"code expects {TAXONOMY_VERSION!r}"
+        )
+    return schema
+
+
+def axis_values(axis: str) -> list[str | bool]:
+    spec = tool_tags_schema()["properties"]["tags"]["properties"][axis]
+    if spec["type"] == "boolean":
+        return [False, True]
+    return list(spec["enum"])