agent-capmap 0.1.0__py3-none-any.whl

agentcapmap/redact.py

@@ -0,0 +1,268 @@
+"""Secret redaction for everything agent-capmap prints or logs.
+
+Config files routinely embed credentials (env values, headers, CLI flags, connection
+strings). Nothing derived from a config may reach output or logs without passing
+through this module. Redaction is deliberately aggressive: a false positive costs a
+little readability, a false negative leaks a credential.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+REDACTED = "<redacted>"
+
+# Shortest value we register as a known secret. Shorter values ("1", "true") would
+# scrub unrelated text without protecting anything meaningful.
+_MIN_KNOWN_SECRET_LEN = 6
+
+_TOKEN_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(p)
+    for p in (
+        r"gh[pousr]_[A-Za-z0-9]{20,}",
+        r"github_pat_[A-Za-z0-9_]{20,}",
+        r"glpat-[A-Za-z0-9_\-]{20,}",
+        r"sk-ant-[A-Za-z0-9_\-]{10,}",
+        r"sk-[A-Za-z0-9_\-]{20,}",
+        r"xox[abposr]-[A-Za-z0-9\-]{10,}",
+        r"(?:AKIA|ASIA)[0-9A-Z]{16}",
+        r"AIza[0-9A-Za-z_\-]{35}",
+        r"npm_[A-Za-z0-9]{36}",
+        r"eyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}",  # JWT
+        r"-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----[\s\S]{0,16384}?"
+        r"-----END [A-Z ]{0,40}PRIVATE KEY-----",
+    )
+]
+# Every quantifier below is bounded, and matches may only start at an identifier
+# boundary, so hostile input (e.g. a malicious server's stderr) cannot trigger
+# catastrophic backtracking.
+_BEARER = re.compile(r"(?i)(?<![a-z])(bearer|basic|token)[ \t]{1,8}[A-Za-z0-9._~+/=\-]{8,4096}")
+_URL_USERINFO = re.compile(
+    r"(?i)(?<![a-z0-9+.\-])([a-z][a-z0-9+.\-]{0,30}://[^/\s:@]{1,256}):[^@\s/]{1,256}@"
+)
+_ASSIGNMENT_IN_TEXT = re.compile(
+    r"(?<![A-Za-z0-9_.\-])([A-Za-z0-9_.\-]{1,128})([ \t]{0,8}[:=][ \t]{0,8})"
+    r"(\"[^\"\n]{0,1024}\"|'[^'\n]{0,1024}'|[^\s,;&\"']{1,1024})"
+)
+_SECRET_KEYWORD = re.compile(
+    r"(?i)token|secret|passw(?:or)?d|api[_\-]?key|apikey|authorization|credential|"
+    r"private[_\-]?key|access[_\-]?key"
+)
+# C0/C1 control characters (except tab/newline): could drive a terminal via escape codes.
+_CONTROL_CHARS = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+
+_SENSITIVE_SUBSTRINGS = (
+    "token",
+    "secret",
+    "password",
+    "passwd",
+    "pwd",
+    "apikey",
+    "api_key",
+    "api-key",
+    "auth",
+    "credential",
+    "privatekey",
+    "private_key",
+    "private-key",
+    "accesskey",
+    "access_key",
+    "access-key",
+    "cookie",
+    "session",
+    "signature",
+    "dsn",
+)
+_SENSITIVE_WORDS = re.compile(r"(?i)(?:^|[_\-.])(?:pat|key|pass|sig|jwt)(?:$|[_\-.])")
+_VAR_REFERENCE = re.compile(r"^\$\{[^}]+\}$|^\$[A-Za-z_][A-Za-z0-9_]*$|^%[A-Za-z_][A-Za-z0-9_]*%$")
+_ANY_VAR_REFERENCE = re.compile(r"\$\{[^}]+\}|\$[A-Za-z_][A-Za-z0-9_]*|%[A-Za-z_][A-Za-z0-9_]*%")
+
+
+class _KnownSecrets:
+    """Raw secret values seen in configs, scrubbed verbatim from any text."""
+
+    def __init__(self) -> None:
+        self._values: set[str] = set()
+        self._lock = threading.Lock()
+
+    def add(self, value: str) -> None:
+        if len(value) >= _MIN_KNOWN_SECRET_LEN and not is_variable_reference(value):
+            with self._lock:
+                self._values.add(value)
+
+    def scrub(self, text: str) -> str:
+        with self._lock:
+            values = sorted(self._values, key=len, reverse=True)
+        for value in values:
+            if value in text:
+                text = text.replace(value, REDACTED)
+        return text
+
+    def clear(self) -> None:
+        with self._lock:
+            self._values.clear()
+
+
+known_secrets = _KnownSecrets()
+
+
+def is_sensitive_name(name: str) -> bool:
+    """Whether a key, header, flag or parameter name likely holds a credential."""
+    lowered = name.strip().lstrip("-").lower()
+    if not lowered:
+        return False
+    return any(s in lowered for s in _SENSITIVE_SUBSTRINGS) or bool(
+        _SENSITIVE_WORDS.search(lowered)
+    )
+
+
+def is_variable_reference(value: str) -> bool:
+    """`${VAR}`, `${env:VAR}`, `${input:id}`, `$VAR` or `%VAR%`: a pointer, not a secret."""
+    return bool(_VAR_REFERENCE.match(value.strip()))
+
+
+def looks_like_secret(value: str) -> bool:
+    """High-entropy-looking opaque string (long, mixes letters and digits)."""
+    if len(value) < 24 or any(c in value for c in " ./\\"):
+        return False
+    return any(c.isdigit() for c in value) and any(c.isalpha() for c in value)
+
+
+def _redact_assignment(m: re.Match[str]) -> str:
+    key, sep, _value = m.groups()
+    if _SECRET_KEYWORD.search(key):
+        return f"{key}{sep}{REDACTED}"
+    return m.group(0)
+
+
+def redact_text(text: str) -> str:
+    """Scrub known secrets and secret-shaped substrings from free text."""
+    if not text:
+        return text
+    text = known_secrets.scrub(text)
+    for pattern in _TOKEN_PATTERNS:
+        text = pattern.sub(REDACTED, text)
+    text = _BEARER.sub(lambda m: f"{m.group(1)} {REDACTED}", text)
+    text = _URL_USERINFO.sub(lambda m: f"{m.group(1)}:{REDACTED}@", text)
+    text = _ASSIGNMENT_IN_TEXT.sub(_redact_assignment, text)
+    return text
+
+
+def escape_control_chars(text: str) -> str:
+    """Make control characters visible (`\\x1b`) so untrusted text cannot drive a terminal."""
+    return _CONTROL_CHARS.sub(lambda m: f"\\x{ord(m.group(0)):02x}", text)
+
+
+def redact_value(value: str) -> str:
+    """Redact a value whose key is already known (env var, header): keep only references.
+
+    `Bearer ${input:pat}` is kept too: an auth scheme plus a reference holds no secret.
+    """
+    remainder = _ANY_VAR_REFERENCE.sub("", value).strip().lower()
+    if remainder in ("", "bearer", "basic", "token"):
+        return value
+    return REDACTED
+
+
+def redact_url(url: str) -> str:
+    """Redact userinfo passwords, sensitive query params and opaque path segments."""
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return redact_text(url)
+    if not parts.scheme or not parts.netloc:
+        return redact_text(url)
+
+    netloc = parts.netloc
+    if "@" in netloc:
+        userinfo, host = netloc.rsplit("@", 1)
+        user = userinfo.split(":", 1)[0]
+        netloc = f"{user}:{REDACTED}@{host}" if ":" in userinfo else f"{REDACTED}@{host}"
+
+    path = "/".join(REDACTED if looks_like_secret(seg) else seg for seg in parts.path.split("/"))
+    query_pairs = parse_qsl(parts.query, keep_blank_values=True)
+    query = urlencode(
+        [
+            (k, REDACTED if is_sensitive_name(k) or looks_like_secret(v) else v)
+            for k, v in query_pairs
+        ],
+        safe="<>",
+    )
+    return redact_text(urlunsplit((parts.scheme, netloc, path, query, parts.fragment)))
+
+
+_FLAG_WITH_VALUE = re.compile(r"^(--?[A-Za-z0-9_.\-]+)=(.*)$", re.DOTALL)
+_ASSIGNMENT = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$", re.DOTALL)
+
+
+def redact_args(args: list[str]) -> list[str]:
+    """Redact a command line: values of sensitive flags, KEY=VALUE pairs, URLs, tokens."""
+    out: list[str] = []
+    redact_next = False
+    for arg in args:
+        if redact_next:
+            out.append(redact_value(arg))
+            redact_next = False
+            continue
+        if m := _FLAG_WITH_VALUE.match(arg):
+            flag, value = m.groups()
+            if is_sensitive_name(flag):
+                out.append(f"{flag}={redact_value(value)}")
+            else:
+                out.append(f"{flag}={_redact_free_value(value)}")
+            continue
+        if arg.startswith("-") and is_sensitive_name(arg):
+            out.append(arg)
+            redact_next = True
+            continue
+        if (m := _ASSIGNMENT.match(arg)) and is_sensitive_name(m.group(1)):
+            out.append(f"{m.group(1)}={redact_value(m.group(2))}")
+            continue
+        out.append(_redact_free_value(arg))
+    return out
+
+
+def sensitive_arg_names(args: list[str]) -> list[str]:
+    """Names of credential-carrying args, for auth evidence (never values)."""
+    names: list[str] = []
+    for i, arg in enumerate(args):
+        if m := _FLAG_WITH_VALUE.match(arg):
+            if is_sensitive_name(m.group(1)):
+                names.append(m.group(1))
+        elif arg.startswith("-") and is_sensitive_name(arg) and i + 1 < len(args):
+            names.append(arg)
+        elif (m := _ASSIGNMENT.match(arg)) and is_sensitive_name(m.group(1)):
+            names.append(m.group(1))
+        elif redact_text(arg) != arg or ("://" in arg and redact_url(arg) != arg):
+            names.append(f"arg[{i}]")
+    return names
+
+
+def _redact_free_value(value: str) -> str:
+    if "://" in value:
+        return redact_url(value)
+    return redact_text(value)
+
+
+class RedactingFilter(logging.Filter):
+    """Logging filter that scrubs the fully formatted message before any handler sees it."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.msg = escape_control_chars(redact_text(record.getMessage()))
+        record.args = None
+        if record.exc_info and record.exc_info[1] is not None:
+            formatted = logging.Formatter().formatException(record.exc_info)
+            record.exc_text = escape_control_chars(redact_text(formatted))
+            record.exc_info = None
+        return True
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Logger with redaction attached at the logger level, so every handler is covered."""
+    logger = logging.getLogger(name)
+    if not any(isinstance(f, RedactingFilter) for f in logger.filters):
+        logger.addFilter(RedactingFilter())
+    return logger

agentcapmap/report/__init__.py

@@ -0,0 +1,36 @@
+"""Render an evaluation as JSON, Markdown or SARIF, and decide the exit status."""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+
+from agentcapmap.findings import Evaluation, Severity
+from agentcapmap.report import markdown, sarif
+
+
+class Format(StrEnum):
+    JSON = "json"
+    MARKDOWN = "markdown"
+    SARIF = "sarif"
+
+
+def render(evaluation: Evaluation, fmt: Format) -> str:
+    if fmt is Format.MARKDOWN:
+        return markdown.render(evaluation)
+    if fmt is Format.SARIF:
+        return json.dumps(sarif.render(evaluation), indent=2, ensure_ascii=False) + "\n"
+    return evaluation.model_dump_json(indent=2) + "\n"
+
+
+def should_fail(
+    evaluation: Evaluation, fail_on: Severity | None, fail_on_not_assessed: bool = False
+) -> bool:
+    """True when a finding is at or above `fail_on`, or anything was not assessed and
+    `fail_on_not_assessed` is set."""
+    if fail_on is not None and any(f.severity.rank >= fail_on.rank for f in evaluation.findings):
+        return True
+    return fail_on_not_assessed and bool(evaluation.not_assessed)
+
+
+__all__ = ["Format", "render", "should_fail"]

agentcapmap/report/_text.py

@@ -0,0 +1,62 @@
+"""Helpers for putting untrusted text (tool names, descriptions, evidence, policy
+messages) into reports.
+
+Everything that came from an MCP server, a config file or a policy file is treated as
+hostile: redacted again (defense in depth), stripped of control characters, collapsed
+to one line, and truncated. In Markdown it is rendered only inside code spans, where
+links, HTML and emphasis are inert.
+"""
+
+from __future__ import annotations
+
+import re
+
+from agentcapmap.redact import redact_text
+
+# C0/C1 controls, line/paragraph separators, zero-width and bidi-override characters
+# ("Trojan Source"). Built from code points so this source file stays ASCII.
+_INVISIBLE_RANGES = (
+    (0x00, 0x1F),
+    (0x7F, 0x9F),
+    (0x200B, 0x200F),
+    (0x2028, 0x2029),
+    (0x202A, 0x202E),
+    (0x2066, 0x2069),
+)
+_CONTROL = re.compile(
+    "["
+    + "".join(f"{re.escape(chr(lo))}-{re.escape(chr(hi))}" for lo, hi in _INVISIBLE_RANGES)
+    + "]"
+)
+_SPACE = re.compile(r"\s+")
+_BACKTICKS = re.compile(r"`+")
+ELLIPSIS = chr(0x2026)  # horizontal ellipsis
+
+
+def clean(text: object, limit: int = 300) -> str:
+    """One line of plain text: redacted, no control or bidi characters, bounded length."""
+    value = redact_text(str(text))
+    value = _CONTROL.sub(" ", value)
+    value = _SPACE.sub(" ", value).strip()
+    if len(value) > limit:
+        value = value[: limit - 1].rstrip() + ELLIPSIS
+    return value
+
+
+def md_code(text: object, limit: int = 300, *, in_table: bool = False) -> str:
+    """Render untrusted text as an inline code span.
+
+    The fence is one backtick longer than the longest backtick run inside, so the text
+    cannot close the span early. In tables `|` is escaped, which GFM honours even inside
+    code spans.
+    """
+    value = clean(text, limit)
+    if not value:
+        return "-"
+    longest = max((len(m.group(0)) for m in _BACKTICKS.finditer(value)), default=0)
+    fence = "`" * (longest + 1)
+    if value.startswith("`") or value.endswith("`"):
+        value = f" {value} "
+    if in_table:
+        value = value.replace("|", "\\|")
+    return f"{fence}{value}{fence}"

agentcapmap/report/markdown.py

@@ -0,0 +1,152 @@
+"""Markdown report (also used for the GitHub Actions job summary).
+
+Only constant labels, numbers and severities appear outside code spans; every value
+derived from configs, servers or policy files goes through `md_code`.
+"""
+
+from __future__ import annotations
+
+from agentcapmap.findings import Evaluation, Finding, Severity
+from agentcapmap.report._text import md_code
+
+_SEVERITY_LABEL = {
+    Severity.CRITICAL: "Critical",
+    Severity.HIGH: "High",
+    Severity.MEDIUM: "Medium",
+    Severity.LOW: "Low",
+    Severity.INFO: "Info",
+}
+_MAX_FINDINGS = 200
+_MAX_ROWS = 50
+
+
+def _finding(index: int, finding: Finding) -> list[str]:
+    where = finding.location
+    location = f"{where.path}:{where.line}" if where and where.line else finding.config_path
+    lines = [
+        f"### {index}. {md_code(finding.rule_id, 40)} | {_SEVERITY_LABEL[finding.severity]}",
+        "",
+        md_code(finding.message, 500),
+        "",
+        f"- **Agent:** {md_code(finding.agent_id, 200)} at {md_code(location, 200)}",
+        f"- **Servers:** {', '.join(md_code(s, 100) for s in finding.servers)}",
+    ]
+    if finding.tools:
+        lines.append(
+            f"- **Tools:** {', '.join(md_code(t, 120) for t in finding.tools[:_MAX_ROWS])}"
+        )
+    if finding.maps_to:
+        lines.append(f"- **Maps to:** {', '.join(md_code(m, 64) for m in finding.maps_to)}")
+    if finding.details:
+        for key in ("changed", "added", "removed"):
+            names = finding.details.get(key)
+            if names:
+                rendered = ", ".join(md_code(n, 120) for n in names[:_MAX_ROWS])
+                lines.append(f"- **Tools {key}:** {rendered}")
+    if finding.evidence:
+        lines += ["", "| Server | Tool | Matched | Evidence |", "|---|---|---|---|"]
+        for ev in finding.evidence[:_MAX_ROWS]:
+            matched = ", ".join(f"{k}={str(v).lower()}" for k, v in ev.matched.items())
+            phrases = "; ".join(f"{k}: {v}" for k, v in ev.phrases.items())
+            if ev.unverified:
+                phrases += f" (unverified: {', '.join(ev.unverified)})"
+            lines.append(
+                "| "
+                + " | ".join(
+                    [
+                        md_code(ev.server, 100, in_table=True),
+                        md_code(ev.tool or "", 100, in_table=True),
+                        md_code(matched, 200, in_table=True),
+                        md_code(phrases, 300, in_table=True),
+                    ]
+                )
+                + " |"
+            )
+        if len(finding.evidence) > _MAX_ROWS:
+            lines.append(f"\n_{len(finding.evidence) - _MAX_ROWS} more evidence rows omitted._")
+    return [*lines, ""]
+
+
+def render(evaluation: Evaluation) -> str:
+    summary = evaluation.summary
+    lines = [
+        "# agent-capmap report",
+        "",
+        f"**Policy:** {md_code(evaluation.policy.source, 200)} "
+        f"(sha256 {md_code(evaluation.policy.sha256[:12], 12)}) | "
+        f"**Baseline:** {'used' if evaluation.baseline_used else 'not used'} | "
+        f"**Agents:** {len(evaluation.agents)}",
+        "",
+        "| Severity | Findings |",
+        "|---|---|",
+        *(f"| {_SEVERITY_LABEL[s]} | {summary.get(s.value, 0)} |" for s in Severity),
+        "",
+    ]
+    not_assessed = len(evaluation.not_assessed)
+    if not_assessed:
+        lines += [
+            f"> [!WARNING]\n> {not_assessed} server(s) or tool(s) were **not assessed**, so "
+            "findings may be incomplete. See the table at the end.",
+            "",
+        ]
+    if evaluation.skipped_rules:
+        skipped = ", ".join(
+            f"{md_code(s.rule_id, 40)} ({md_code(s.reason, 100)})" for s in evaluation.skipped_rules
+        )
+        lines += [f"Skipped rules: {skipped}", ""]
+
+    lines += ["## Findings", ""]
+    if not evaluation.findings and not_assessed:
+        lines += [
+            "No findings, but this is **not an all-clear**: some tools were not assessed. "
+            "To assess them, run `agentcapmap scan <path> --enumerate --classify --evaluate` "
+            "(this starts the configured servers and needs an API key), or use a saved "
+            "inventory whose tools are already classified.",
+            "",
+        ]
+    elif not evaluation.findings:
+        lines += ["No findings.", ""]
+    for index, finding in enumerate(evaluation.findings[:_MAX_FINDINGS], start=1):
+        lines += _finding(index, finding)
+    if len(evaluation.findings) > _MAX_FINDINGS:
+        lines += [
+            f"_{len(evaluation.findings) - _MAX_FINDINGS} more findings omitted; "
+            "see the JSON output._",
+            "",
+        ]
+
+    if not_assessed:
+        lines += ["## Not assessed", "", "| Agent | Server | Tool | Reason |", "|---|---|---|---|"]
+        for item in evaluation.not_assessed[:_MAX_FINDINGS]:
+            lines.append(
+                "| "
+                + " | ".join(
+                    [
+                        md_code(item.agent_id, 120, in_table=True),
+                        md_code(item.server, 100, in_table=True),
+                        md_code(item.tool or "", 100, in_table=True),
+                        md_code(item.reason, 200, in_table=True),
+                    ]
+                )
+                + " |"
+            )
+        lines.append("")
+
+    lines += ["## Capabilities by agent", ""]
+    for agent in evaluation.agents:
+        lines += [
+            f"### {md_code(agent.agent_id, 200)}",
+            "",
+            f"{agent.tools_assessed} of {agent.tools_total} tool(s) assessed.",
+            "",
+        ]
+        if not agent.capabilities:
+            lines += ["No capabilities beyond the defaults.", ""]
+            continue
+        lines += ["| Capability | Tools |", "|---|---|"]
+        for capability, refs in agent.capabilities.items():
+            tools = ", ".join(f"{r.server}/{r.tool}" for r in refs[:_MAX_ROWS])
+            cap_cell = md_code(capability, 60, in_table=True)
+            lines.append(f"| {cap_cell} | {md_code(tools, 500, in_table=True)} |")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"