@datasynx/agentic-ai-cartography 1.1.1 → 2.2.0

package/llms-full.txt

@@ -0,0 +1,758 @@
+# @datasynx/agentic-ai-cartography — full documentation
+
+> MCP-first infrastructure & agentic-AI cartography — install once, every AI agent knows your system landscape. Read-only discovery exposed over the Model Context Protocol.
+
+
+---
+
+<!-- source: docs/tutorials/index.md -->
+
+# Tutorial: from zero to an agent that knows your system
+
+A guided, first-run walkthrough. By the end you'll have discovered your local
+landscape and queried it from an AI client.
+
+## 1. Discover (read-only, no LLM required)
+
+```bash
+npx -y --package @datasynx/agentic-ai-cartography datasynx-cartography discover
+```
+
+This scans your machine deterministically — installed apps, listening ports,
+browser bookmarks — and writes a catalog. Nothing leaves your machine.
+
+## 2. Run the MCP server
+
+```bash
+npx -y --package @datasynx/agentic-ai-cartography cartography-mcp
+```
+
+The server speaks the Model Context Protocol over stdio.
+
+## 3. Connect a client
+
+Let the harness write the config for you:
+
+```bash
+datasynx-cartography install --client claude-code
+```
+
+Restart the host, then ask it: *"Read cartography://graph/summary and describe my system."*
+
+Next: the [How-to guides](/how-to/) for specific tasks, or the [Reference](/reference/).
+
+
+---
+
+<!-- source: docs/how-to/install.md -->
+
+# How to install Cartography into a client
+
+## Claude Code — one-step plugin (recommended)
+
+Cartography ships as a Claude Code plugin in the shared Datasynx marketplace, so
+no manual config editing is needed:
+
+```text
+/plugin marketplace add datasynx/claude-plugins
+/plugin install cartography@datasynx
+```
+
+Verify the server is live with `/mcp`. This is the same flow as the
+[`shadowing`](https://github.com/datasynx/agentic-ai-shadowing) plugin; the
+plugin manifest lives in [`plugin/`](https://github.com/datasynx/agentic-ai-cartography/tree/main/plugin)
+of this repository.
+
+## Every other host — the `install` harness
+
+The `install` command parses your host's existing config and merges in the
+Cartography MCP server **without clobbering** your other servers.
+
+```bash
+datasynx-cartography list-clients                 # see supported hosts
+datasynx-cartography install --client <id>        # write the config
+datasynx-cartography install --client <id> --dry-run   # preview the merge diff
+```
+
+## Scopes
+
+- `--global` (default) — your user-level config.
+- `--project` — a project-local config (e.g. `.mcp.json`, `.vscode/mcp.json`).
+
+## Options
+
+| Flag | Purpose |
+| --- | --- |
+| `--dry-run` | Print the merge diff; write nothing. |
+| `--name <server>` | Server key to register (default `cartography`). |
+| `--http` / `--url <url>` | Register the Streamable HTTP endpoint instead of stdio. |
+| `--db <path>` | Serve a specific catalog. |
+| `--session <id>` | Serve a specific discovery session. |
+| `--deeplink` | Print a one-click Cursor/VS Code install link instead of writing. |
+
+## One-click deeplinks
+
+```bash
+datasynx-cartography install --client cursor --deeplink
+datasynx-cartography install --client vscode --deeplink
+```
+
+See the full host matrix in the [Reference → Supported clients](/reference/clients).
+
+
+---
+
+<!-- source: docs/reference/mcp.md -->
+
+# MCP tools & resources
+
+The Cartography MCP server exposes read-only **resources**, query **tools** and
+reusable **prompts**.
+
+## Resources
+
+| URI | Description |
+| --- | --- |
+| `cartography://graph/summary` | Low-token aggregate index — read this first. |
+| `cartography://nodes` | Lightweight list of all nodes. |
+| `cartography://nodes/{id}` | Full node record plus incident edges. |
+| `cartography://services` | Service-type nodes. |
+| `cartography://databases` | Data-store nodes. |
+| `cartography://dependencies/{id}` | Transitive downstream dependencies. |
+| `cartography://sessions` | Discovery sessions in the catalog. |
+
+## Tools
+
+<!-- AUTO-GENERATED:tools START — regenerated by `npm run docs:tables` -->
+| Tool | Read-only | Description |
+| --- | --- | --- |
+| `classify_drift` | ✅ | Compare two discovery sessions and return a severity-classified drift alert (info|warning|critical per item plus an overall severity). Defaults to the two most recent. Read-only: never dispatches to sinks. |
+| `diff_topology` | ✅ | Compare two discovery sessions and report added/removed/changed nodes and added/removed edges, plus newly-appearing structural anomalies (3.6). Defaults to the two most recent sessions (base = second-most-recent, current = most-recent). |
+| `get_activity_events` | ✅ | Recent executed tool calls and their result sizes for the current session. |
+| `get_cost_summary` | ✅ | FinOps rollup: cost by domain and owner, currency/period-bucketed (3.3). |
+| `get_dependencies` | ✅ | Traverse the dependency graph from a node (downstream/upstream/both) with a depth limit. |
+| `get_node` | ✅ | Fetch a single node with its incident edges. |
+| `get_summary` | ✅ | Low-token overview of the whole landscape (counts, types, domains, most-connected, anomalies). |
+| `list_services` | ✅ | List discovered services or data stores. |
+| `query_infrastructure` | ✅ | Search the topology by name/id/domain (optionally filtered by node type). Returns compact node records. |
+| `query_natural_language` | ✅ | Answer a plain-English topology question (e.g. "services that depend on the payments DB"). Deterministically parses the question into a structured intent, then anchors via search and traverses dependencies, applying any node-type filter to the results. Echoes the parsed intent for explainability. Read-only, LLM-free. |
+| `run_discovery` | — | Scan the local system (read-only) and update the catalog. Returns counts of nodes/edges found. Pass `update: true` to rescan the served session in place and return the delta (2.1 incremental discovery). |
+| `score_compliance` | ✅ | Grade the served session against a compliance ruleset (baseline/cis/soc2/iso27001 starter sets) and list gaps with the node ids that caused them. Read-only; never throws. |
+| `search_topology` | ✅ | Find nodes related to a concept by meaning (semantic search when available, lexical otherwise). |
+<!-- AUTO-GENERATED:tools END -->
+
+## Prompts
+
+| Prompt | Description |
+| --- | --- |
+| `audit-attack-surface` | Review externally-reachable services and risky dependencies. |
+| `map-service-dependencies` | Produce a dependency map for a given service. |
+| `onboard-to-system` | Explain the system landscape to a new engineer. |
+
+
+---
+
+<!-- source: docs/reference/cli.md -->
+
+# CLI reference
+
+`datasynx-cartography <command>` (the discovery/management CLI) and
+`cartography-mcp` (the MCP server binary).
+
+| Command | Purpose |
+| --- | --- |
+| `discover` | Scan and map your infrastructure (`--output-format text\|json\|stream-json`, `--name <name>`). |
+| `diff [base] [current]` | Compare two sessions for drift (`--format text\|json\|mermaid`). |
+| `schedule --config <file>` | Run discovery recurringly and record per-run drift (`--once` / `--watch`, config-file driven). |
+| `seed` | Manually add known tools/DBs/APIs. |
+| `install --client <id>` | Register the MCP server into a host's config. |
+| `list-clients` | List supported hosts. |
+| `mcp` | Run the MCP server (stdio by default; `--http` for Streamable HTTP). |
+| `export [session]` | Export Mermaid / JSON / YAML / HTML. |
+| `show [session]` | Show session details. |
+| `sessions` | List all sessions. |
+| `overview` | Aggregate overview across sessions. |
+| `bookmarks` | View browser bookmarks. |
+| `doctor` | Check requirements (kubectl, aws, gcloud, az). |
+| `prune` | Remove old sessions. |
+| `docs` | Full in-terminal feature reference. |
+
+## `mcp` flags
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--http` | off | Use Streamable HTTP instead of stdio. |
+| `--port <n>` | `3737` | HTTP port. |
+| `--host <h>` | `127.0.0.1` | HTTP host. |
+| `--allowed-hosts <list>` | — | Host allowlist (required for non-loopback `--host`). |
+| `--db <path>` | default catalog | Catalog to serve. |
+| `--session <id>` | `latest` | Session to serve. |
+| `--no-semantic` | — | Disable semantic (vector) search. |
+
+
+---
+
+<!-- source: docs/reference/clients.md -->
+
+# Supported clients
+
+The `install` harness writes the correct config for each host. Run
+`datasynx-cartography list-clients` for the live list.
+
+<!-- AUTO-GENERATED:clients START — regenerated by `npm run docs:tables` -->
+| id | Host | Format | Notes |
+| --- | --- | --- | --- |
+| `claude-code` | Claude Code | json |  |
+| `cursor` | Cursor | json |  |
+| `vscode` | VS Code (Copilot) | json | Uses the `servers` key (not `mcpServers`) — the most common copy-paste mistake. |
+| `codex` | Codex CLI | toml | Project scope only loads in "trusted" projects. |
+| `windsurf` | Windsurf | json |  |
+| `cline` | Cline | json |  |
+| `roo` | Roo Code | json | Project .roo/mcp.json takes precedence over the global settings. |
+| `zed` | Zed | json | Manual servers need "source": "custom"; remote uses an mcp-remote bridge. |
+| `junie` | JetBrains / Junie | json |  |
+| `gemini` | Gemini CLI | json |  |
+| `goose` | Goose | yaml | Verify the extension shape against current Goose docs; built-ins are left untouched. |
+| `openhands` | OpenHands | toml | SHTTP is preferred; SSE is legacy. Only api_key is supported (no arbitrary headers). |
+| `claude-desktop` | Claude Desktop | json | One-click install is also available via the .mcpb bundle (npm run build:mcpb). |
+<!-- AUTO-GENERATED:clients END -->
+
+## Copy-paste config per host
+
+The exact entry the `install` harness writes for each host (global scope shown).
+
+<!-- AUTO-GENERATED:quickstarts START — regenerated by `npm run docs:tables` -->
+### Claude Code (`claude-code`)
+
+`~/.claude.json`
+
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Cursor (`cursor`)
+
+`~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+### VS Code (Copilot) (`vscode`)
+
+`~/.config/Code/User/mcp.json`
+
+```json
+{
+  "servers": {
+    "cartography": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Codex CLI (`codex`)
+
+`~/.codex/config.toml`
+
+```toml
+[mcp_servers.cartography]
+command = "npx"
+args = [ "-y", "--package", "@datasynx/agentic-ai-cartography", "cartography-mcp" ]
+```
+
+### Windsurf (`windsurf`)
+
+`~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Cline (`cline`)
+
+`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ],
+      "alwaysAllow": [],
+      "disabled": false
+    }
+  }
+}
+```
+
+### Roo Code (`roo`)
+
+`~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`
+
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Zed (`zed`)
+
+`~/.config/zed/settings.json`
+
+```json
+{
+  "context_servers": {
+    "cartography": {
+      "source": "custom",
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+### JetBrains / Junie (`junie`)
+
+`~/.junie/mcp/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Gemini CLI (`gemini`)
+
+`~/.gemini/settings.json`
+
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Goose (`goose`)
+
+`~/.config/goose/config.yaml`
+
+```yaml
+extensions:
+  cartography:
+    name: cartography
+    type: stdio
+    enabled: true
+    command: npx
+    args:
+      - -y
+      - --package
+      - "@datasynx/agentic-ai-cartography"
+      - cartography-mcp
+```
+
+### OpenHands (`openhands`)
+
+`~/.openhands/config.toml`
+
+```toml
+[[mcp.stdio_servers]]
+name = "cartography"
+command = "npx"
+args = [ "-y", "--package", "@datasynx/agentic-ai-cartography", "cartography-mcp" ]
+```
+
+### Claude Desktop (`claude-desktop`)
+
+`~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package",
+        "@datasynx/agentic-ai-cartography",
+        "cartography-mcp"
+      ]
+    }
+  }
+}
+```
+
+<!-- AUTO-GENERATED:quickstarts END -->
+
+
+---
+
+<!-- source: docs/adapters.md -->
+
+# Native adapters for non-MCP frameworks
+
+Some agent frameworks don't read a config file — they load MCP tools through their
+own adapter classes. Cartography needs **no special support** for these; point them
+at the standard stdio command and they'll pick up every tool, just like an MCP host.
+
+Standard launch command (used in every snippet below):
+
+```
+npx -y --package @datasynx/agentic-ai-cartography cartography-mcp
+```
+
+> Run a discovery first (`datasynx-cartography discover`) so the catalog has a
+> topology to serve. Cartography's MCP **prompts** and **resources** are available
+> in full MCP hosts; some adapters below load **tools only** (noted inline).
+
+---
+
+## LangGraph / LangChain (Python)
+
+```bash
+pip install langchain-mcp-adapters
+```
+
+```python
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+client = MultiServerMCPClient({
+    "cartography": {
+        "command": "npx",
+        "args": ["-y", "--package", "@datasynx/agentic-ai-cartography", "cartography-mcp"],
+        "transport": "stdio",
+    },
+    # or a remote Streamable HTTP server:
+    # "cartography": {"url": "http://127.0.0.1:3737/mcp", "transport": "streamable_http"},
+})
+tools = await client.get_tools()  # hand `tools` to create_react_agent / create_agent
+```
+
+`MultiServerMCPClient` is stateless by default (a new session per tool call); use
+`client.session("cartography")` for a stateful session. JS: `@langchain/mcp-adapters`.
+
+## Microsoft AutoGen (Python)
+
+```bash
+pip install "autogen-ext[mcp]"
+```
+
+```python
+from autogen_ext.tools.mcp import McpWorkbench, StdioServerParams
+
+params = StdioServerParams(
+    command="npx",
+    args=["-y", "--package", "@datasynx/agentic-ai-cartography", "cartography-mcp"],
+    read_timeout_seconds=60,
+)
+async with McpWorkbench(params) as mcp:
+    agent = AssistantAgent("assistant", model_client=..., workbench=mcp)
+```
+
+> AutoGen is in maintenance mode; for new projects Microsoft points to the
+> **Microsoft Agent Framework (MAF)**, which speaks MCP + A2A.
+
+## CrewAI (Python)
+
+```bash
+pip install "crewai-tools[mcp]"
+```
+
+```python
+from crewai_tools import MCPServerAdapter
+from mcp import StdioServerParameters
+
+server_params = StdioServerParameters(
+    command="npx",
+    args=["-y", "--package", "@datasynx/agentic-ai-cartography", "cartography-mcp"],
+)
+with MCPServerAdapter(server_params) as tools:
+    agent = Agent(role="SRE", goal="Map the system", backstory="...", tools=tools)
+```
+
+> `MCPServerAdapter` exposes **tools only** (no prompts/resources).
+
+## Pydantic AI (Python)
+
+```bash
+pip install "pydantic-ai-slim[mcp]"
+```
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.mcp import MCPServerStdio
+
+server = MCPServerStdio("npx", args=["-y", "--package", "@datasynx/agentic-ai-cartography", "cartography-mcp"])
+agent = Agent("openai:gpt-5.2", toolsets=[server])
+```
+
+`load_mcp_servers("config.json")` also reads an `mcpServers` JSON block directly.
+
+## OpenAI Agents SDK (Python)
+
+MCP support is built in:
+
+```python
+from agents import Agent
+from agents.mcp import MCPServerStdio
+
+async with MCPServerStdio(
+    name="Cartography",
+    params={"command": "npx", "args": ["-y", "--package", "@datasynx/agentic-ai-cartography", "cartography-mcp"]},
+) as server:
+    agent = Agent(name="Assistant", instructions="...", mcp_servers=[server])
+```
+
+Options: `cache_tools_list`, `tool_filter`, `max_retry_attempts`, `require_approval`.
+
+## Smolagents (Python)
+
+```bash
+pip install "smolagents[mcp]"
+```
+
+```python
+from smolagents import ToolCollection, CodeAgent
+from mcp import StdioServerParameters
+
+params = StdioServerParameters(
+    command="npx",
+    args=["-y", "--package", "@datasynx/agentic-ai-cartography", "cartography-mcp"],
+)
+with ToolCollection.from_mcp(params, trust_remote_code=True) as tc:
+    agent = CodeAgent(tools=[*tc.tools], model=...)
+```
+
+## Vercel AI SDK (TypeScript)
+
+```ts
+import { experimental_createMCPClient as createMCPClient } from 'ai';
+import { Experimental_StdioMCPTransport as StdioMCPTransport } from 'ai/mcp-stdio';
+
+const mcp = await createMCPClient({
+  transport: new StdioMCPTransport({
+    command: 'npx',
+    args: ['-y', '--package', '@datasynx/agentic-ai-cartography', 'cartography-mcp'],
+  }),
+});
+const tools = await mcp.tools(); // MCP tools → AI SDK tools, any model
+```
+
+> Define your **own** tools with `inputSchema` (renamed from `parameters` in AI SDK
+> **v5** — using `parameters` yields an empty schema / 400 errors). The MCP client
+> is lightweight: **tools only**, no session management or resources.
+
+
+---
+
+<!-- source: docs/explanation/index.md -->
+
+# Why MCP-first?
+
+Cartography's primary interface is a **Model Context Protocol** server, not a CLI or
+a library. That choice is deliberate.
+
+## One integration surface, every host
+
+The [Model Context Protocol](https://modelcontextprotocol.io) is the common
+denominator across AI hosts and agent frameworks. By exposing discovery as an MCP
+server, Cartography works in Claude Code, Cursor, VS Code, Cline, Windsurf, Zed,
+LangGraph, CrewAI and more — without bespoke integrations for each.
+
+## Read-only by construction
+
+Every tool is annotated `readOnlyHint: true`; the command allowlist rejects anything
+that mutates. The server *describes* your landscape — it never changes it.
+
+## Progressive disclosure
+
+Agents read `cartography://graph/summary` first (a low-token index), then drill into
+specific nodes. This keeps token usage bounded even for large landscapes — important
+where hosts cap tool output or total tool count.
+
+## The CLI and SDK are adapters
+
+The `datasynx-cartography` CLI and the embeddable library are thin layers over the
+same core. The MCP server is the headline; everything else is convenience.
+
+## See also
+
+- [Threat model](./threat-model.md) — attacker model, trust boundaries, and the mitigation
+  enforced at each, mapped to the code.
+
+
+---
+
+<!-- source: docs/explanation/threat-model.md -->
+
+# Threat model
+
+Cartography performs **read-only** infrastructure discovery and exposes the result over the Model
+Context Protocol. Its safety boundary is the read-only allowlist in
+[`src/allowlist.ts`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/allowlist.ts),
+enforced for every command spawned by `run()`
+([`src/platform.ts`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/platform.ts))
+regardless of origin — scanner template, agent, or MCP tool. This page makes the model behind that
+boundary explicit: who the attacker is, what is worth protecting, where trust changes hands, and
+which mechanism defends each crossing.
+
+It complements the guarantee list in
+[`SECURITY.md`](https://github.com/datasynx/agentic-ai-cartography/blob/main/SECURITY.md); that file
+is the contract, this one is the reasoning.
+
+## Attacker model
+
+Three attackers are in scope:
+
+1. **A malicious or compromised MCP client / agent.** It can call any exposed tool with any
+   arguments and is assumed to *want* to run destructive commands, inject extra shell commands
+   through scan parameters, or exfiltrate credentials. It is *not* trusted.
+2. **Untrusted scanned content.** Bookmark titles, browser-history entries, and the stdout of host
+   CLIs (`aws`, `gcloud`, `az`, `kubectl`, database clients) are attacker-influenceable data. A
+   payload hidden there may try to smuggle instructions into the agent's context (prompt injection)
+   or blow up the context window.
+3. **A network attacker against the HTTP transport.** When the Streamable HTTP transport is bound to
+   a non-loopback address, an unauthenticated peer or a DNS-rebinding origin may try to reach it.
+
+Out of scope: an attacker who already has the user's shell, the host CLIs' own credential stores, or
+the integrity of the operating system. Cartography trusts the host it runs on (see *Residual risk*).
+
+## Assets
+
+- **The local command-execution surface.** The single most valuable target — code that can run
+  shell commands on the user's machine.
+- **Cloud and cluster credentials.** AWS/GCP/Azure/Kubernetes configs the host CLIs read on
+  Cartography's behalf.
+- **Scanned personal data.** Browser bookmarks and history, installed applications.
+- **The catalog.** Node ids, metadata, and edge evidence persisted to SQLite — which later re-enter
+  an LLM context when an agent queries the topology.
+
+## Trust boundaries
+
+| # | Boundary | Untrusted side → trusted side |
+|---|----------|-------------------------------|
+| B1 | Agent/client → command execution | Tool calls and their string arguments → `run()` shell |
+| B2 | Scanner output → catalog / LLM context | CLI stdout, bookmark/history text → persisted nodes, agent context |
+| B3 | Network → HTTP transport | Remote requests → the MCP server |
+| B4 | Catalog persistence | Node ids/metadata containing secrets → durable storage |
+
+## Mitigations per boundary
+
+Each mitigation is enforced in code; the citations point at the implementing lines.
+
+| Boundary / threat | Mitigation | Location |
+|---|---|---|
+| **B1** Arbitrary / destructive command execution | Positive read-only **allowlist** (known-read-only binaries + per-tool verb rules), not a denylist — anything not provably read-only is rejected | [`src/allowlist.ts:14-29,44-65,181-222`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/allowlist.ts#L14-L222) |
+| **B1** Command injection via substitution | `$()` and backticks rejected before execution | [`src/allowlist.ts:211`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/allowlist.ts#L211) |
+| **B1** Shell-arg injection through scan parameters | `assertSafeScanArg` validates region/profile/project/namespace/etc. against strict regexes before they are spliced into a command | [`src/tools.ts:83-114`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/tools.ts#L83-L114) |
+| **B1** Defense-in-depth at the execution chokepoint | `run()` re-checks `checkReadOnly()` immediately before `execSync`, regardless of origin | [`src/platform.ts:77-95`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/platform.ts#L77-L95) |
+| **B1** Secret env leaking into child processes | `safeEnv()` passes only an allowlist of environment keys to spawned commands | [`src/platform.ts:60-75`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/platform.ts#L60-L75) |
+| **B1** Agent-driven Bash in the optional Claude loop | `safetyHook` PreToolUse denies non-read-only Bash before it runs | [`src/safety.ts:1-42`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/safety.ts#L1-L42) |
+| **B2** Hidden prompt-injection in untrusted text | `sanitizeUntrusted` strips invisible/bidi/format/control Unicode (NFC-normalized) before text enters the catalog or an LLM context | [`src/sanitize.ts:18-45`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/sanitize.ts#L18-L45), applied at [`src/db.ts:475-492,539-550`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/db.ts#L475-L550) |
+| **B2** Context-window exhaustion from large output | `clampText` caps a single tool response at `maxToolResponseBytes` (default 100 000) | [`src/tools.ts:48-65`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/tools.ts#L48-L65), [`src/types.ts:194,213`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/types.ts#L194-L213) |
+| **B3** Unauthenticated HTTP access | Non-loopback bind requires a bearer token; tokens are compared in constant time | [`src/mcp/transports.ts:36-107`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/mcp/transports.ts#L36-L107) |
+| **B3** DNS-rebinding (CVE-2025-66414) | Non-loopback bind requires an explicit `allowedHosts` Host allowlist | [`src/mcp/transports.ts:36-107`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/mcp/transports.ts#L36-L107) |
+| **B4** Credentials persisted in node ids / metadata | `stripSensitive`, `redactSecrets`, `redactValue` remove `user:password@` and query/path secrets before persistence | [`src/tools.ts:67-81,111-126`](https://github.com/datasynx/agentic-ai-cartography/blob/main/src/tools.ts#L67-L126) |
+
+These mechanisms are exercised by `test/safety.test.ts`, `test/tools-hardening.test.ts`,
+`test/sanitize.test.ts`, and `test/transports.test.ts`.
+
+## Residual risk and assumptions
+
+- **The host is trusted.** Cartography assumes the machine it runs on, its installed CLIs
+  (`aws`/`gcloud`/`az`/`kubectl`/database clients), and those CLIs' credential stores are not already
+  compromised. It reads through them; it does not sandbox them.
+- **Allowlist correctness is the trust root.** The read-only guarantee is exactly as strong as
+  `checkReadOnly()`. A gap there is a vulnerability — see *Reporting* below.
+- **Out-of-process secret hygiene is the operator's job.** Cartography redacts secrets it persists,
+  but it does not manage how cloud credentials are stored on the host.
+- **Hosted Smithery runs are read-only.** The managed runtime serves a catalog with no host CLIs and
+  no secrets (`smithery.yaml` declares `env: {}`); the cloud scanners are intended for
+  local/self-hosted use only.
+
+If you find a way around any boundary above, it is a vulnerability — please report it privately via
+[`SECURITY.md`](https://github.com/datasynx/agentic-ai-cartography/blob/main/SECURITY.md).
+