@datasynx/agentic-ai-cartography 2.10.0 → 2.12.1

package/README.md

@@ -42,6 +42,7 @@
 [What it does](#what-it-does) ·
 [Cross-platform](#cross-platform-support) ·
 [Features](#features) ·
+[Platform & ecosystem](#platform--ecosystem) ·
 [CLI commands](#commands) ·
 [Architecture](#architecture) ·
 [Safety](#safety) ·
@@ -64,7 +65,7 @@ The topology is exposed with **progressive disclosure** so agents never blow the
 context window:
 
 - **Resources** (read-only context): `cartography://graph/summary` (low-token index — read first), `cartography://nodes/{id}`, `cartography://services`, `cartography://databases`, `cartography://dependencies/{id}`.
-- **Tools** (parameterized queries): `query_infrastructure`, `search_topology` (semantic), `get_dependencies` (recursive graph traversal), `list_services`, `get_node`, `get_summary`, `run_discovery`.
+- **Tools** (parameterized queries): `query_infrastructure`, `search_topology` (semantic), `get_dependencies` (recursive graph traversal), `query_natural_language` (plain-English topology questions, LLM-free), `correlate_topology` (collapse the same resource across clouds/on-prem), `get_cost_summary`, `score_compliance`, `classify_drift`, `list_services`, `get_node`, `get_summary`, `run_discovery`.
 - **Prompts**: `audit-attack-surface`, `map-service-dependencies`, `onboard-to-system`.
 
 ### Quick start
@@ -257,11 +258,125 @@ Cartography runs natively on **Linux**, **macOS**, and **Windows** — no WSL re
 | **Database Discovery** | PostgreSQL, MySQL, MongoDB, Redis, SQLite file scan. Windows: `Get-Service` for DB engine detection |
 | **Cloud Scanning** | AWS (EC2/RDS/EKS/S3), GCP (Compute/GKE/Cloud Run), Azure (AKS/WebApps), Kubernetes |
 | **Human-in-the-Loop** | Chat with the agent mid-discovery: type `"hubspot windsurf"` to search for specific tools |
+| **Terraform Import** | First-class `terraform-state` scanner — `*.tfstate` JSON → authoritative IaC nodes/edges, reconciled with observed reality (no `terraform` CLI, no extra credentials) |
+| **Multi-Cloud Correlation** | Collapse the same logical resource discovered across AWS/GCP/Azure/on-prem into canonical entities + confidence-scored `same_as` links (`correlate_topology`, pure & deterministic) |
+| **Intelligence Layer** | Cost attribution (FinOps rollups), compliance scoring (CIS/SOC2/ISO 27001 starters), anomaly detection (orphans / shadow IT), severity-classified drift |
 | **Export Formats** | Mermaid topology, D3.js interactive graph, Backstage YAML, JSON |
 | **Safety First** | Strict read-only **allowlist** (not a denylist): only known-safe commands run — shell-aware for POSIX *and* PowerShell, enforced at the command runner as defense-in-depth. 100% read-only |
 
 ---
 
+## Platform & Ecosystem
+
+Beyond the MCP server, Cartography ships a **read-only platform** for teams and an
+**ecosystem** of integrations. Everything below is opt-in, read-only by default, and never
+phones home — the same locked constraints as the core.
+
+### REST / GraphQL API + web dashboard (Phase 4)
+
+`cartography api` (and the `cartography-api` binary) exposes the topology over a **read-only**
+HTTP API — REST under `/v1/...` with a published **OpenAPI 3.1** document, and **GraphQL** at
+`/graphql` (SDL + introspection, no `Mutation` type). It reuses the MCP transport's constant-time
+bearer auth + DNS-rebinding hardening and the same tenant-scoped query layer — no new runtime
+dependency (Node's built-in `http`).
+
+```bash
+cartography api                         # loopback dev — REST + /graphql + dashboard, no token
+curl -s http://127.0.0.1:3737/v1/summary | jq .totals
+# Exposed: a non-loopback bind REQUIRES both --allowed-hosts and --token
+cartography api --host 0.0.0.0 --allowed-hosts cartograph.internal:3737 --token "$TOKEN"
+cartography api --no-graphql            # REST only
+cartography api --no-dashboard          # disable the / and /app web UI
+```
+
+The same server hosts a self-contained **web dashboard** at `/` and `/app` — a live, interactive
+Canvas topology view with node drill-down (no CDN, no build step, zero new dependency). It fetches
+the live `/v1/*` API, so it inherits the API's auth + RBAC/tenant scoping for free.
+See **[docs/how-to/api-server.md](docs/how-to/api-server.md)** and
+**[docs/how-to/web-dashboard.md](docs/how-to/web-dashboard.md)**.
+
+### Role-based access control (Phase 4)
+
+`cartography auth` layers **identity + roles** over the HTTP surfaces. A bearer token resolves to a
+principal `{ subject, tenant, role }`; the server returns **401** for an unknown token, **403** for
+an insufficient role, and **pins every read to the principal's tenant** — no cross-tenant read by
+spoofing a header. Roles are `viewer` ⊂ `operator` (adds `run_discovery`) ⊂ `admin` (adds credential
+admin). Fully backward-compatible: with no credentials configured, the server behaves exactly as
+before. Tokens are stored **hashed** (sha256), printed once on creation.
+
+```bash
+cartography auth add alice --role operator --tenant acme   # prints the bearer token ONCE
+cartography auth list                                       # subjects/roles/tenants, never the token
+cartography auth revoke alice
+cartography api --auth-required                             # require auth even on loopback
+```
+
+See **[docs/how-to/rbac.md](docs/how-to/rbac.md)**.
+
+### Central collector → production (Phase 4)
+
+`cartography mcp --server-mode` runs the binary as a self-hostable **central collector** that pools
+every employee's *consented* discovery into one org-wide topology — consent-first, never phones home.
+It exposes an authenticated `POST /ingest` write route (the consent-gated push envelope, server-side
+anonymization re-validation via `--anon-mode reject|strip`, per-org rate limit → `429 + Retry-After`)
+and an org-wide merged `get_summary`. Public `GET /healthz` (liveness) / `GET /readyz` (readiness)
+probes and a `deploy/` Docker bundle make it orchestrator-ready.
+
+```bash
+export CARTOGRAPHY_CENTRAL_TOKEN=$(openssl rand -base64 32)
+cartography mcp --server-mode --host 0.0.0.0 \
+  --allowed-hosts cartograph.internal:3737 --org acme --anon-mode reject
+```
+
+For an org-wide store at **10K+ nodes**, opt into a **Neo4j/Memgraph graph-DB backend** for the
+collector's merge + summary path (`neo4j-driver` is an optional dependency; if absent or unreachable
+it **degrades to SQLite**, never fails):
+
+```bash
+cartography mcp --server-mode --store-backend graph \
+  --graph-url bolt://graph.internal:7687 --graph-user neo4j --graph-password "$NEO4J_PASSWORD"
+# or via env: CARTOGRAPHY_GRAPH_URL / _USER / _PASSWORD (kept out of process listings)
+```
+
+See **[docs/how-to/self-host-collector.md](docs/how-to/self-host-collector.md)**.
+
+### Backstage live data source (Phase 4)
+
+Cartography maps discovered infrastructure to **Backstage catalog entities** (`Component`/`API`/
+`Resource` + `dependsOn` relations). Export a static `catalog-info.yaml` snapshot, or consume the
+**live, tenant-scoped** endpoint `GET /v1/backstage/catalog` on the API server (re-mapped on every
+request, RBAC-pinned). A reference `CartographEntityProvider` lives in
+[`examples/backstage-plugin/`](examples/backstage-plugin/). See
+**[docs/how-to/backstage.md](docs/how-to/backstage.md)**.
+
+### Drift alerting — Slack / PagerDuty / Jira (Phase 4)
+
+`cartography drift` classifies topology drift into `info`/`warning`/`critical` and fans it out to
+the **sinks** configured under the `drift` block of `cartography.config.json` — `stdout`, `slack`,
+`pagerduty`, `jira`, or a generic `webhook`. With no config it prints one redacted JSON line and makes
+**no outbound request**. Every sink is hardened identically (`https:`-or-loopback only, bounded
+timeout, body always credential-redacted, only host:port logged, one failing sink never blocks the
+others). See **[docs/how-to/drift-and-ci.md](docs/how-to/drift-and-ci.md)**.
+
+### Kubernetes operator (Phase 5)
+
+`cartography operator` runs the **deterministic, LLM-free** discovery continuously **inside** a
+cluster and reports drift between reconcile cycles — a "continuous CMDB for Kubernetes". It's a thin
+reconcile loop (no CRD, no controller-runtime, no agent loop), read-only (`kubectl get …` via the
+allowlist only). The `deploy/k8s/` manifests ship a **read-only** ServiceAccount + ClusterRole
+(`get/list/watch` only — no write verbs).
+
+```bash
+kubectl apply -f deploy/k8s/operator.yaml          # in-cluster, single-replica Deployment
+cartography operator --once                         # local dev against your kube-context
+cartography operator --interval 300                 # long-running reconcile loop
+```
+
+See **[docs/how-to/k8s-operator.md](docs/how-to/k8s-operator.md)** and
+**[docs/how-to/terraform-import.md](docs/how-to/terraform-import.md)**.
+
+---
+
 ## Requirements
 
 - **Node.js >= 20** (Linux, macOS, or Windows) — that's it for the MCP server and the
@@ -349,10 +464,31 @@ datasynx-cartography drift [base] [current]        Severity-classified drift ale
   --webhook <url>      Outbound webhook sink (opt-in; token via CARTOGRAPHY_DRIFT_TOKEN)
 datasynx-cartography bookmarks                     View all browser bookmarks
 datasynx-cartography seed [--file <path>]          Manually add infrastructure nodes
+datasynx-cartography cost --file <csv>             Enrich nodes with owner/cost (FinOps)
+datasynx-cartography compliance [session] --ruleset <name>   Grade against baseline/cis/soc2/iso27001
+datasynx-cartography consent <…>                   Per-employee sharing policy + anonymization
+datasynx-cartography sync <status|review|push>     Opt-in central-DB outbound pipeline
+datasynx-cartography schedule --config <file>      Recurring headless discovery + drift
+datasynx-cartography prune [--older-than <days>]   Prune old sessions / compact the audit trail
 datasynx-cartography doctor                        Check all requirements + cloud CLIs
 datasynx-cartography docs                          Full feature reference
 ```
 
+### Platform & Ecosystem
+
+```
+datasynx-cartography mcp [--server-mode] [--http]  MCP server / central collector (Phase 4)
+datasynx-cartography api [--no-graphql] [--no-dashboard]   REST + GraphQL + web dashboard (Phase 4)
+  --host <h> --port <n> --token <secret> --allowed-hosts <list>   (non-loopback needs both)
+  --tenant <id> / --org <id>                       Tenant whose topology to serve
+datasynx-cartography auth add <subject> --role <viewer|operator|admin> --tenant <id>   RBAC (Phase 4)
+datasynx-cartography auth list | revoke <subject>
+datasynx-cartography operator [--once] [--interval <sec>]   Kubernetes operator (Phase 5)
+```
+
+> The `cartography-mcp` and `cartography-api` binaries start the MCP server and the API server
+> directly (used by `server.json` / containers via `npx`).
+
 ---
 
 ## Output Files
@@ -380,7 +516,11 @@ datasynx-output/
 
 The **MCP server is the headline interface** — LLM-agnostic and the same SQLite graph
 underneath every entry point. Discovery (deterministic scanners or the optional Claude
-loop) writes the graph; any MCP host reads it.
+loop) writes the graph; any MCP host reads it. The Phase 4 **platform** adds read-only
+HTTP surfaces over that same graph — the REST/GraphQL API (`cartography api`), the web
+dashboard, RBAC (`cartography auth`), the self-hostable central collector
+(`mcp --server-mode`, with an optional Neo4j/Memgraph backend), and a live Backstage
+data source — all sharing the MCP transport's bearer auth + tenant scoping.
 
 ```
                          ┌──────────────────────────────────────────┐

package/dist/api-bin.js

@@ -2,8 +2,8 @@
 import {
   parseApiArgs,
   startApi
-} from "./chunk-W4Q3TXHR.js";
-import "./chunk-YVV6NIT2.js";
+} from "./chunk-PD67MOKR.js";
+import "./chunk-LO6YFS6H.js";
 import "./chunk-QQOQBE2A.js";
 import "./chunk-2SZ5QHGH.js";
 

package/dist/{chunk-YVV6NIT2.js → chunk-LO6YFS6H.js}

@@ -3391,6 +3391,7 @@ export {
   k8sScanner,
   databasesScanner,
   stripSensitive,
+  redactSecrets,
   redactValue,
   buildCartographyToolHandlers,
   createCartographyTools,
@@ -3414,4 +3415,4 @@ export {
   AuthorizationError,
   authorize
 };
-//# sourceMappingURL=chunk-YVV6NIT2.js.map
+//# sourceMappingURL=chunk-LO6YFS6H.js.map