toolprint 0.1.0__py3-none-any.whl

toolprint/__init__.py

@@ -0,0 +1,10 @@
+"""toolprint - what your agent's tool surface costs, and what it can do.
+
+Footprint: the tokens tool definitions consume on every request. Fingerprint:
+what those definitions are, and whether they changed without review.
+"""
+
+# The public name is spelled here and in cli.py's argparse prog only, which is
+# what made the rename from the mcpdrift placeholder a two-line change.
+TOOL_NAME = "toolprint"
+__version__ = "0.1.0"

toolprint/auth.py

@@ -0,0 +1,219 @@
+"""Auth posture classification and literal-credential detection.
+
+Client configs support variable expansion (`${VAR}`, `${VAR:-default}`), so a
+header of `Bearer ${API_KEY}` is hygienic while the same header holding the token
+itself is a plaintext credential sitting in a dotfile. Telling those apart is a
+string test, which means we get it for free in --no-connect mode. It becomes
+finding HYG-002 in M2.
+
+Everything here reports *locations*, never values. A detector that quotes the
+secret it found has recreated the problem it was looking for.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+from urllib.parse import parse_qsl, urlsplit
+
+from .model import (
+    AUTH_ENV_VAR,
+    AUTH_HELPER_COMMAND,
+    AUTH_LITERAL_SECRET,
+    AUTH_NONE,
+    AUTH_OAUTH,
+    SecretLocation,
+)
+
+# ${VAR}, ${VAR:-default} and bare $VAR expansions.
+ENV_REF = re.compile(r"\$\{[^}]*\}|\$[A-Za-z_][A-Za-z0-9_]*")
+
+# Auth scheme words that legitimately sit next to a reference and are not secrets.
+SCHEME_WORDS = re.compile(r"\b(bearer|basic|token|apikey|api_key|key)\b", re.I)
+
+# Field names that are credential-carrying by convention.
+CREDENTIAL_HEADERS = {
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "x-api-key",
+    "api-key",
+    "apikey",
+    "x-auth-token",
+    "x-access-token",
+    "x-goog-api-key",
+    "token",
+    "secret",
+}
+CREDENTIAL_WORDS = frozenset({
+    "TOKEN", "KEY", "APIKEY", "SECRET", "PASSWORD", "PASSWD", "PASS",
+    "CREDENTIAL", "CREDENTIALS", "AUTH", "PAT", "SESSION", "BEARER", "SIGNATURE",
+})
+
+# Split on separators and camelCase, so CONTEXT7_API_KEY and apiKey both yield a
+# "KEY" token while X-Monkey-Id does not. A substring test would match "MONKEY".
+_NAME_TOKENS = re.compile(r"[^A-Za-z0-9]+|(?<=[a-z0-9])(?=[A-Z])")
+
+# High-precision issuer prefixes. These identify a credential regardless of what
+# the surrounding field is called, which catches secrets in oddly-named fields.
+SECRET_PREFIXES = (
+    "sk-ant-",
+    "sk-",
+    "ghp_",
+    "gho_",
+    "ghu_",
+    "ghs_",
+    "github_pat_",
+    "glpat-",
+    "xoxb-",
+    "xoxp-",
+    "xoxa-",
+    "AKIA",
+    "ASIA",
+    "AIza",
+    "npm_",
+    "dop_v1_",
+    "hf_",
+    "pk_live_",
+    "rk_live_",
+    "eyJ",  # JWT
+)
+
+# A credential-shaped residue this long is a token, not a scheme word or a path.
+MIN_SECRET_RESIDUE = 12
+
+
+def _residue(value: str) -> str:
+    """What is left of a value once expansions and scheme words are removed."""
+    without_refs = ENV_REF.sub("", value)
+    without_scheme = SCHEME_WORDS.sub("", without_refs)
+    return re.sub(r"[^A-Za-z0-9]", "", without_scheme)
+
+
+def has_env_reference(value: str) -> bool:
+    return bool(ENV_REF.search(value))
+
+
+# Auth schemes a token may legitimately sit behind: "Authorization: Bearer ghp_...".
+SCHEME_PREFIX = re.compile(r"^(?:bearer|basic|token|apikey)\s+", re.I)
+
+
+def _has_issuer_prefix(value: str) -> bool:
+    """True if the value *starts* with a known credential prefix.
+
+    Anchored deliberately. An unanchored substring test matches "sk-" inside
+    ordinary strings such as "task-runner" or "disk-cache", and it also misfires
+    on vendor keys that merely embed a known prefix (Context7's "ctx7sk-..." is
+    a real credential, but it is caught by the credential-named-field rule below
+    with an accurate reason rather than by a bogus prefix match).
+    """
+    candidate = SCHEME_PREFIX.sub("", value.strip())
+    return any(candidate.startswith(prefix) for prefix in SECRET_PREFIXES)
+
+
+def looks_like_secret(value: object, credential_field: bool) -> Optional[str]:
+    """Return a reason string if this value looks like a literal credential."""
+    if not isinstance(value, str) or not value.strip():
+        return None
+    stripped = value.strip()
+
+    # A prefix in front of a ${VAR} reference is hygienic, not a secret. Slack
+    # tokens are configured as "xoxb-${SLACK_TOKEN}", and flagging that as a
+    # plaintext credential is a false accusation about a config that is doing
+    # exactly the right thing. Checked before the prefix rule, which would
+    # otherwise match on "xoxb-" alone.
+    if has_env_reference(stripped) and len(_residue(stripped)) < MIN_SECRET_RESIDUE:
+        return None
+
+    if _has_issuer_prefix(stripped):
+        return "value begins with a recognised credential prefix"
+    if credential_field and len(_residue(stripped)) >= MIN_SECRET_RESIDUE:
+        return "credential-named field holds a literal value, not a ${VAR} reference"
+    return None
+
+
+def is_credential_name(name: str) -> bool:
+    """True if a header or env var name conventionally carries a credential.
+
+    Token-based rather than substring-based: CONTEXT7_API_KEY and apiKey are
+    credentials, X-Monkey-Id and CACHE_DIR are not.
+    """
+    if name.lower() in CREDENTIAL_HEADERS:
+        return True
+    tokens = {t.upper() for t in _NAME_TOKENS.split(name) if t}
+    return bool(tokens & CREDENTIAL_WORDS)
+
+
+def scan_for_secrets(
+    headers: Optional[dict],
+    env: Optional[dict],
+    args: Optional[list],
+    url: Optional[str],
+) -> List[SecretLocation]:
+    """Locate literal credentials. Records field paths only, never values."""
+    found: List[SecretLocation] = []
+
+    for name, value in (headers or {}).items():
+        reason = looks_like_secret(value, is_credential_name(name))
+        if reason:
+            found.append(SecretLocation("headers.{}".format(name), reason))
+
+    for name, value in (env or {}).items():
+        reason = looks_like_secret(value, is_credential_name(name))
+        if reason:
+            found.append(SecretLocation("env.{}".format(name), reason))
+
+    for index, value in enumerate(args or []):
+        if not isinstance(value, str):
+            continue
+        # Both "--token=VALUE" and a bare token positional.
+        flag_match = re.match(r"--?([A-Za-z0-9_-]*(?:key|token|secret|password|auth)[A-Za-z0-9_-]*)=(.+)$", value, re.I)
+        if flag_match:
+            reason = looks_like_secret(flag_match.group(2), True)
+        else:
+            reason = looks_like_secret(value, False)
+        if reason:
+            found.append(SecretLocation("args[{}]".format(index), reason))
+
+    if url:
+        try:
+            query = urlsplit(url).query
+        except ValueError:
+            query = ""
+        for name, value in parse_qsl(query, keep_blank_values=True):
+            credential_field = is_credential_name(name)
+            reason = looks_like_secret(value, credential_field)
+            if reason:
+                found.append(
+                    SecretLocation("url.query.{}".format(name), reason)
+                )
+    return found
+
+
+def classify(
+    secret_locations: List[SecretLocation],
+    headers: Optional[dict],
+    env: Optional[dict],
+    headers_helper: Optional[str],
+    has_oauth: bool,
+) -> Tuple[str, List[str]]:
+    """Return (auth_method, notes). Worst posture wins; see model.py for order."""
+    notes: List[str] = []
+
+    if secret_locations:
+        return AUTH_LITERAL_SECRET, notes
+    if headers_helper:
+        notes.append("auth headers are minted by an external command; posture is not statically determinable")
+        return AUTH_HELPER_COMMAND, notes
+    if has_oauth:
+        return AUTH_OAUTH, notes
+
+    referenced = [n for n, v in (headers or {}).items() if isinstance(v, str) and has_env_reference(v)]
+    credential_env = [n for n in (env or {}) if is_credential_name(n)]
+    if referenced or credential_env:
+        return AUTH_ENV_VAR, notes
+
+    if headers:
+        # Headers present but none credential-shaped: informational, not auth.
+        notes.append("headers present but none carry a credential")
+    return AUTH_NONE, notes

toolprint/baseline.py

@@ -0,0 +1,241 @@
+"""The approved baseline: what the tool surface looked like when someone reviewed it.
+
+A baseline records component hashes plus just enough schema shape to say *how* a
+schema changed - whether a parameter was removed, a type narrowed, or a required
+field added - because "the schema hash changed" is not actionable on its own.
+
+Identity is `name@transport:endpoint`, not the config key. Moving a server from
+user scope to project scope is not tool drift and must not read as any, whereas
+the same name pointing at a different endpoint is a different server and should.
+
+False-positive management is not optional here. `approve` records who accepted
+what and when; `exceptions` carry a reason and an expiry so a standing exception
+cannot become permanent by neglect. Without both, this recreates certificate
+warning fatigue and users will --fail-on none it into irrelevance.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from . import __version__, canonical, effects, lexical
+from .model import Inventory, Server
+
+BASELINE_VERSION = 1
+DEFAULT_PATH = ".toolprint-baseline.json"
+
+
+def server_identity(server: Server) -> str:
+    endpoint = server.url_host or server.command_basename or "?"
+    return "{}@{}:{}".format(server.name, server.transport, endpoint)
+
+
+def _schema_shape(schema: Any) -> Dict[str, Any]:
+    """Enough of a schema to classify a later change, and no more.
+
+    Storing the whole schema would make the baseline a second copy of the tool
+    surface; storing only a hash would make every change indistinguishable.
+    """
+    resolved, _ = canonical.canonicalise(schema, resolve=True)
+    if not isinstance(resolved, dict):
+        return {"required": [], "properties": {}}
+    properties = resolved.get("properties")
+    shape: Dict[str, List[str]] = {}
+    if isinstance(properties, dict):
+        for name in sorted(properties):
+            value = properties[name]
+            declared = value.get("type") if isinstance(value, dict) else None
+            if isinstance(declared, str):
+                shape[name] = [declared]
+            elif isinstance(declared, list):
+                shape[name] = sorted(str(t) for t in declared)
+            else:
+                shape[name] = []
+    required = resolved.get("required")
+    return {
+        "required": sorted(str(r) for r in required) if isinstance(required, list) else [],
+        "properties": shape,
+    }
+
+
+def tool_record(tool: Dict[str, Any]) -> Dict[str, Any]:
+    hashes = canonical.hash_tool(tool)
+    classified = effects.classify(tool)
+    record = OrderedDict(sorted(hashes.items()))
+    record["effect"] = classified["effect"]
+    record["declared_ceiling"] = classified["declared_ceiling"]
+    record["annotations"] = {
+        key: tool.get("annotations", {}).get(key)
+        for key in ("readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint")
+        if isinstance(tool.get("annotations"), dict)
+        and key in tool.get("annotations", {})
+    }
+    record["schema_shape"] = _schema_shape(tool.get("inputSchema"))
+    return record
+
+
+def snapshot(inventory: Inventory) -> Dict[str, Any]:
+    """Current state, in the same shape a baseline stores. One entry per server."""
+    servers: Dict[str, Any] = {}
+    for server in sorted(inventory.servers, key=lambda s: s.key):
+        if server.fetch_status != "ok" or not server.tools:
+            continue
+        identity = server_identity(server)
+        if identity in servers:
+            continue  # the same running server registered twice
+        tools = OrderedDict()
+        for tool in sorted(server.tools, key=lambda t: str(t.get("name"))):
+            name = tool.get("name")
+            if isinstance(name, str):
+                tools[name] = tool_record(tool)
+        record = OrderedDict(sorted(canonical.hash_server(server.tools).items()))
+        record["transport"] = server.transport
+        record["auth_method"] = server.auth_method
+        record["tools"] = tools
+        servers[identity] = record
+    return OrderedDict(sorted(servers.items()))
+
+
+def now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def build(inventory: Inventory, approved_by: Optional[str] = None,
+          note: Optional[str] = None) -> Dict[str, Any]:
+    stamp = now()
+    return OrderedDict([
+        ("baseline_version", BASELINE_VERSION),
+        ("generator", "toolprint/{}".format(__version__)),
+        # Bumping the effect-class verb lists changes classifications, which would
+        # otherwise be indistinguishable from real drift. A bump is a re-approval
+        # event, not a finding.
+        ("heuristics_version", effects.HEURISTICS_VERSION),
+        ("created_at", stamp),
+        ("approved_at", stamp),
+        ("approved_by", approved_by),
+        ("note", note),
+        ("exceptions", []),
+        ("servers", _stamp_first_observed(snapshot(inventory), stamp)),
+    ])
+
+
+def _stamp_first_observed(servers: Dict[str, Any], stamp: str) -> Dict[str, Any]:
+    """Record when each server entered the watch.
+
+    Without this, a server added in week six looks like it had six quiet weeks.
+    Any rate computed across the whole file would then be wrong in the direction
+    that flatters the result, which is the worst direction for it to be wrong in.
+    """
+    for record in servers.values():
+        record.setdefault("first_observed", stamp)
+    return servers
+
+
+def adopt_new(document: Dict[str, Any], current: Dict[str, Any],
+              stamp: Optional[str] = None) -> List[str]:
+    """Add servers that are being watched but were never baselined.
+
+    Adding a server to the watchlist is an intentional act, not drift, so it
+    produces no change to approve - which meant it never entered the baseline and
+    was compared against nothing, indefinitely.
+    """
+    stamp = stamp or now()
+    stored = document.setdefault("servers", {})
+    added = []
+    for identity in sorted(current):
+        if identity not in stored:
+            record = json.loads(json.dumps(current[identity]))
+            record["first_observed"] = stamp
+            stored[identity] = record
+            added.append(identity)
+    return added
+
+
+def dropped(document: Dict[str, Any], current: Dict[str, Any]) -> List[str]:
+    """Baselined servers no longer being watched or no longer reachable."""
+    return sorted(set(document.get("servers") or {}) - set(current))
+
+
+def load(path: str) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+    """Return (baseline, error). A missing or unreadable baseline is exit code 3."""
+    file = Path(path)
+    if not file.is_file():
+        return None, "no baseline at {}".format(path)
+    try:
+        document = json.loads(file.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        return None, "baseline at {} is unreadable: {}".format(path, exc)
+    if not isinstance(document, dict) or "servers" not in document:
+        return None, "baseline at {} is not a toolprint baseline".format(path)
+    if document.get("baseline_version") != BASELINE_VERSION:
+        return None, "baseline schema version {}, this build writes {}".format(
+            document.get("baseline_version"), BASELINE_VERSION)
+    return document, None
+
+
+def save(path: str, document: Dict[str, Any]) -> None:
+    Path(path).write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+
+
+# --------------------------------------------------------------------------
+# Exceptions
+# --------------------------------------------------------------------------
+
+def active_exceptions(document: Dict[str, Any], today: Optional[str] = None
+                      ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """Split exceptions into (active, expired). Expiry is mandatory by design."""
+    today = today or datetime.date.today().isoformat()
+    active, expired = [], []
+    for item in document.get("exceptions") or []:
+        if not isinstance(item, dict):
+            continue
+        expires = str(item.get("expires") or "")
+        (expired if expires and expires < today else active).append(item)
+    return active, expired
+
+
+def is_excepted(exceptions: Sequence[Dict[str, Any]], server: str, tool: Optional[str],
+                rule: str) -> Optional[Dict[str, Any]]:
+    for item in exceptions:
+        if item.get("rule") not in (rule, "*"):
+            continue
+        if item.get("server") not in (server, "*"):
+            continue
+        if item.get("tool") not in (tool, "*", None):
+            continue
+        return item
+    return None
+
+
+# --------------------------------------------------------------------------
+# First-baseline safety checks
+# --------------------------------------------------------------------------
+
+def first_baseline_objections(inventory: Inventory) -> List[str]:
+    """Reasons to refuse writing a clean baseline over a suspicious state.
+
+    Trust-on-first-use means a baseline blesses whatever is there. Writing one
+    over a description that already contains a bidi override, or a server that
+    already names another server's tools, records the attack as approved and
+    guarantees it is never reported again.
+    """
+    objections: List[str] = []
+    by_server: Dict[str, List[Dict[str, Any]]] = {}
+    for server in inventory.servers:
+        if server.fetch_status == "ok" and server.tools:
+            by_server.setdefault(server_identity(server), []).extend(server.tools)
+
+    for identity in sorted(by_server):
+        for tool in by_server[identity]:
+            for hit in lexical.inspect_tool(tool):
+                objections.append("{} / {}: {} in {} ({})".format(
+                    identity, tool.get("name"), hit["kind"], hit["field"], hit["detail"]))
+
+    for hit in lexical.shadowing(by_server):
+        objections.append("{} / {}: description names {!r}, owned by {}".format(
+            hit["server"], hit["tool"], hit["references"], hit["owned_by"]))
+    return objections

toolprint/bundle.py

@@ -0,0 +1,194 @@
+"""Bundle export: a redacted description of an MCP deployment, for assessment.
+
+The customer runs a collection, reads the file, and sends it. Everything here
+serves that review step, which means the governing question is not "what would be
+useful to have" but "what can a sceptical security engineer approve in five
+minutes".
+
+Redaction is an allowlist, in one visible constant. A denylist - strip anything
+that looks like a secret - fails open and cannot be verified by reading; an
+allowlist fails closed and a reviewer can check it in thirty seconds. If a field
+is not named in EMITTED_FIELDS it never reaches the bundle, including fields
+added to the model later.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import platform
+import sys
+import textwrap
+from collections import OrderedDict
+from typing import Any, Dict, List, Optional, Sequence
+
+from . import __version__
+from .model import Inventory, Server
+
+BUNDLE_VERSION = 1
+
+# ---------------------------------------------------------------------------
+# Everything this export will emit. Nothing else leaves the machine.
+# ---------------------------------------------------------------------------
+EMITTED_FIELDS = {
+    "server": ["name", "source_client", "scope", "transport", "command_basename",
+               "auth_method", "auth_env_names", "auth_header_names", "url_host",
+               "fetch_status", "protocol_version", "protocol_era"],
+    "tool": ["name", "title", "description", "inputSchema", "outputSchema",
+             "annotations", "token_estimate", "token_method"],
+    # No "usage" entry: neither this exporter nor mcp_collect.py collects call
+    # counts yet, and an allowlist naming a field nothing emits misleads the
+    # person reading it. It comes back when --usage lands.
+}
+
+DATA_POLICY = (
+    "This bundle contains: MCP server names, which client they were configured in, "
+    "transport type, the basename of any command (for example 'npx'), the hostname "
+    "of any remote server, the NAMES of environment variables and HTTP headers used "
+    "for authentication, and the full tool definitions each server advertises - tool "
+    "names, descriptions and JSON schemas.\n"
+    "It does NOT contain: environment variable values, HTTP header values, API keys, "
+    "tokens or passwords of any kind; full command lines or arguments; absolute file "
+    "paths; URL paths or query strings; usernames or hostnames of your machine; or "
+    "the contents of any file, request or response.\n"
+    "Tool definitions are included in full because they are the substance of the "
+    "assessment, and because they are already what the language model sees on every "
+    "request."
+)
+
+
+def _digest(salt: str, value: str) -> str:
+    """Stable, salted, non-reversible identifier.
+
+    HMAC rather than a plain hash: server and tool names are drawn from a small
+    public vocabulary, so an unsalted hash of 'github' is recovered instantly by
+    dictionary. The customer keeps the salt, so they can re-identify their own
+    bundle and nobody else can.
+    """
+    return hmac.new(salt.encode("utf-8"), value.encode("utf-8"),
+                    hashlib.sha256).hexdigest()[:12]
+
+
+class Anonymiser:
+    """Replaces identifiers consistently, so the bundle stays analysable."""
+
+    def __init__(self, salt: Optional[str]):
+        self.salt = salt
+
+    @property
+    def active(self) -> bool:
+        return bool(self.salt)
+
+    def name(self, value: Optional[str], prefix: str) -> Optional[str]:
+        if not value or not self.salt:
+            return value
+        return "{}-{}".format(prefix, _digest(self.salt, value))
+
+
+def _tool(tool: Dict[str, Any], tokens: Dict[str, int], method: Optional[str]) -> Dict[str, Any]:
+    name = tool.get("name")
+    out: "OrderedDict[str, Any]" = OrderedDict()
+    for field in EMITTED_FIELDS["tool"]:
+        if field == "token_estimate":
+            out[field] = tokens.get(name) if isinstance(name, str) else None
+        elif field == "token_method":
+            out[field] = method
+        elif field in tool:
+            out[field] = tool[field]
+    return out
+
+
+def _server(server: Server, anon: Anonymiser) -> Dict[str, Any]:
+    # Built field by field from the allowlist, so a new attribute on Server
+    # cannot silently start appearing in bundles.
+    values = {
+        "name": anon.name(server.name, "server") if anon.active else server.name,
+        "source_client": server.client,
+        "scope": server.scope,
+        "transport": server.transport,
+        "command_basename": server.command_basename,
+        "auth_method": server.auth_method,
+        "auth_env_names": server.env_names,
+        "auth_header_names": server.header_names,
+        "url_host": anon.name(server.url_host, "host") if anon.active else server.url_host,
+        "fetch_status": server.fetch_status,
+        "protocol_version": server.protocol_version,
+        "protocol_era": server.protocol_era,
+    }
+    out: "OrderedDict[str, Any]" = OrderedDict(
+        (field, values[field]) for field in EMITTED_FIELDS["server"])
+    out["tools"] = [_tool(t, server.tool_tokens, server.token_method) for t in server.tools]
+    return out
+
+
+def build(
+    inventory: Inventory,
+    collected_at: str,
+    mode: str,
+    salt: Optional[str] = None,
+    usage: Optional[Sequence[Dict[str, Any]]] = None,
+    kit_sha256: Optional[str] = None,
+) -> Dict[str, Any]:
+    anon = Anonymiser(salt)
+    servers = sorted(inventory.servers, key=lambda s: s.key)
+    return OrderedDict([
+        ("bundle_version", BUNDLE_VERSION),
+        ("kit_version", __version__),
+        ("kit_sha256", kit_sha256),
+        ("collected_at", collected_at),
+        ("mode", mode),
+        ("anonymized", anon.active),
+        ("data_policy", DATA_POLICY),
+        ("platform", OrderedDict([
+            ("os", sys.platform),
+            ("python", platform.python_version()),
+        ])),
+        ("clients_found", inventory.clients_found),
+        ("servers", [_server(s, anon) for s in servers]),
+        ("usage", list(usage or [])),
+        # Failures are data. "Three servers were unreachable" is a finding.
+        ("collection_errors", [
+            OrderedDict([("kind", e.kind), ("client", e.client),
+                         ("detail", e.detail)])
+            for e in inventory.errors
+        ]),
+    ])
+
+
+def summarise(document: Dict[str, Any], path: str, size: int) -> str:
+    """What the user sees after a bundle is written. Ends with the review order."""
+    servers = document.get("servers", [])
+    tools = sum(len(s.get("tools", [])) for s in servers)
+    failed = [s for s in servers if s.get("fetch_status") not in ("ok", "not_attempted")]
+    lines = [
+        "",
+        "Bundle written: {} ({:,} bytes)".format(path, size),
+        "  {} server(s), {} tool definition(s) captured".format(len(servers), tools),
+        "  mode: {}{}".format(document.get("mode"),
+                              ", anonymized" if document.get("anonymized") else ""),
+    ]
+    if failed:
+        lines.append("  {} server(s) could not be reached (recorded in the bundle)".format(
+            len(failed)))
+    errors = document.get("collection_errors") or []
+    if errors:
+        lines.append("  {} config file(s) could not be parsed (recorded in the bundle)".format(
+            len(errors)))
+    lines += ["", "DATA POLICY", ""]
+    for paragraph in document.get("data_policy", "").split("\n"):
+        lines.append(textwrap.fill(paragraph, 78, initial_indent="  ",
+                                   subsequent_indent="  "))
+    lines += [
+        "",
+        "Review this file before sending it. It contains exactly what is listed",
+        "above and nothing else.",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def find_secrets(document: Dict[str, Any], needles: Sequence[str]) -> List[str]:
+    """Test helper: does any known secret appear anywhere in the bundle?"""
+    blob = json.dumps(document)
+    return sorted({n for n in needles if n and n in blob})