{
  "markdown": "---\ntype: Overview\ntitle: Platform Compass\ndescription: Read-only assessment toolkit for brownfield Databricks platforms on Azure — fit, install, access tiers, domains, and standards coverage.\ntimestamp: 2026-07-22T00:00:00Z\n---\n\n# Platform Compass\n\nRead-only assessment toolkit for brownfield Databricks platforms on Azure:\ninventory collectors, a convention-aware rules engine, coverage-honest\nreporting. It turns an inherited, organically-grown estate from \"we think it's\nfine\" into a dated, re-runnable assessment. A mismatch with the client's own\nconventions becomes a risk or a recorded choice, never a tool failure. Strictly\nread-only — the dossier directory is the only thing it writes. Apache-2.0,\npre-1.0 (not yet on PyPI).\n\n## Is this for you?\n\n| Your estate looks like | Compass fit | What to do |\n|---|---|---|\n| One shared workspace — everyone works in the same place | Overkill | Scoped-down run below |\n| Workspace-per-environment — one delivery stream, dev/test/prod | Good fit | Full flow; scope collectors to what matters |\n| Hub-and-spoke — platform team, domain workspaces, central metastore | Good fit | Full flow; strategy/plan where drift shows |\n| Organic sprawl — workspaces per BU/project, nobody holds the whole map | Built for it | Full `assess → strategy → plan` |\n| Greenfield — nothing built yet | Wrong tool | Define desired state in IaC + cluster policies; Compass grades what exists |\n| Second opinion / pre-audit snapshot | Good fit | Run `assess`, read the report, stop |\n\n**The scoped-down run.** Same tool, fewer collectors:\n`compass collect --domains <the few that matter>`, then `analyze` and `report`,\nand read the report yourself — no strategy/plan sessions. A coverage-honest\nsnapshot in an afternoon. There is no separate \"lite\" build.\n\n## Where it sits\n\nCompass makes published governance catalogues executable and re-runnable:\n\n- **Rules:** SAT (Databricks Security Analysis Tool), MCSB, Azure Policy\n  built-ins, UC governance best practices, DASF.\n- **Principles:** the Databricks Well-Architected Lakehouse framework.\n\nIt is not IaC — it grades the as-built estate and never changes it. It is not\na CSPM — it covers Databricks and its Azure substrate deeply, not multi-cloud\nposture broadly. And it is not a one-off scan — snapshots are dated and\nre-runnable, so movement between assessments is visible (`compass diff`). The\ncheck-by-check mapping is the\n[rules coverage ledger](docs/rules-coverage-ledger.md); neighbouring tools\n(SAT, UCX, Lakebridge, the Terraform exporter, system tables) are in\n[the ecosystem doc](docs/ecosystem.md).\n\n## Install\n\nAs a CLI on PATH:\n\n```\nuv tool install git+https://github.com/CauchyIO/platform-compass-public\n```\n\nAs a library dependency of a uv project:\n\n```\nuv add \"platform-compass @ git+https://github.com/CauchyIO/platform-compass-public\"\n```\n\nFrom a checkout (development):\n\n```\nuv venv --python 3.12 .venv\nuv pip install -e . pytest --python .venv/bin/python\n.venv/bin/pytest\n```\n\nFrom a provided wheel (client install), into a venv created as above:\n\n```\nuv pip install --python .venv/bin/python platform_compass-*.whl\n```\n\nTroubleshooting: on Intel macOS the `cryptography` 49.x wheel can fail to load\n(`symbol not found ... _BIO_ADDR_free`), surfacing at the first\n`preflight`/`collect`. Fix:\n`uv pip install --python .venv/bin/python 'cryptography<44'`.\n\n## Agent skills & plugins\n\nThe skill family (assess → strategy → plan) lives in\n[`.agents/skills/`](.agents/skills/) and is consumable three ways:\n\n- **Claude Code plugin** — `/plugin marketplace add CauchyIO/platform-compass-public`,\n  then `/plugin install platform-compass`. Skills invoke as\n  `/platform-compass:compass-assess` (strategy and plan likewise).\n- **Pi package** — `pi install git:github.com/CauchyIO/platform-compass-public`;\n  update with `pi update git:github.com/CauchyIO/platform-compass-public`.\n  In a checkout, Pi auto-discovers `.agents/skills/` — no install needed.\n- **In-repo Claude Code** — sessions in a checkout auto-load the stubs in\n  `.claude/skills/`.\n\nThe skills drive the `compass` CLI, so install the Python package as well\n(`uv tool install` above; update with `uv tool upgrade platform-compass`).\nAt client sites prefer these installs over a clone: assessment sessions then\nrun in a plain engagement directory, not inside a git checkout the agent might\ntreat as its working repo.\nSkill edits belong in `.agents/skills/`; re-mirror the stubs with\n`python3 tools/gather.py` (CI enforces sync via `--check`).\n\n## Quick start\n\n```\ncompass init       --dossier ./compass    # scaffold engagement.yaml (account id, scope)\ncompass preflight  --dossier ./compass    # verify credentials (diagnosed fixes) + record the granted access tier\ncompass collect    --dossier ./compass    # run the read-only collectors into a dated snapshot\ncompass analyze    --dossier ./compass    # evaluate rules -> findings.json\ncompass report     --dossier ./compass    # render the coverage-first markdown report\n```\n\nUseful afterwards: `collect --domains infrastructure` re-fills one domain into\nthe same snapshot; `collect … --seal` freezes a finished snapshot;\n`query \"<sql>\"` reads it back; `infer` detects de-facto conventions;\n`diff --findings <old> <new>` renders movement between two assessments.\n\n**The dossier holds real tenant identifiers, names, and cost figures. It never\nbelongs in a git repository.**\n\n## engagement.yaml\n\nWritten by `compass init`; edit directly for anything the prompts didn't cover\n(schema: `compass.dossier.Engagement`):\n\n```yaml\nschema_version: 1\nclient: acme                       # client name\nengagement: acme-2026              # engagement slug\ndatabricks:\n  account_host: https://accounts.azuredatabricks.net\n  account_id: <databricks account id>\n  profile: null                    # a `databricks auth` profile, OR null to use\n                                   # env/SPN auth (see docs/AUTH.md)\nazure:\n  subscriptions:                   # every subscription that hosts in-scope workspaces\n    - <subscription id>\nusage:\n  warehouse_id: null               # a running SQL warehouse for usage/cost extraction\n  workspace_id: null               # numeric id of the workspace that warehouse lives in\n  window_days: 90\naccess_tier: null                  # filled by `compass preflight`\n```\n\n## Access tiers & coverage\n\nCoverage scales with what is granted; nothing fails or degrades silently:\n\n| Granted | What Compass can assess |\n|---|---|\n| Databricks **account admin** | account plane (workspaces, metastores, principals), UC governance across every metastore |\n| Databricks **workspace admin** | per-workspace tokens, secret scopes, cluster/job detail on those workspaces |\n| Azure **Reader** on the in-scope subscriptions | workspace network posture, storage, private endpoints (via Azure Resource Graph) |\n| A usable **SQL warehouse** | usage & cost overlay over system tables |\n\nAnything not granted is reported as `not_assessed` or a coverage gap with the\nreason preserved — never a silent pass. Credentials and the service-principal\npath: [docs/AUTH.md](docs/AUTH.md).\n\n## Domains & collectors\n\nEach collector reports `ok | partial | denied | skipped` per plane; every\nzero-evidence result renders as `not_assessed` or a gap with its reason.\n\n| Domain | Collector(s) | What it inventories |\n|---|---|---|\n| D0 settings | `workspace_settings`, `account_settings`, `http_probe` | workspace-conf keys, IP access lists, Settings-v2 toggles, artifact allowlists; log delivery, compliance defaults; login-page security-header probe |\n| D1 account/identity | `account` | workspaces, metastores, users/groups/service principals |\n| D2 compute | `compute` | clusters, jobs + task graphs, pools, pipelines, policy definitions, global/cluster init scripts, tags, disk-encryption, libraries |\n| D3 SQL estate | `sql_estate` | SQL warehouses, Lakeview dashboards |\n| D4 governance | `governance`, `governance_sql` | grants (table/volume/routine/schema), admins, metastore grants, entitlements, workspace-local groups, group membership, secret ACLs, Delta Sharing, row filters/column masks, catalog bindings |\n| D5 data | `data_estate` | external locations, storage credentials, table inventory, DBFS mounts |\n| D6 infrastructure | `resource_graph` (ARG), `account_network` | workspaces/storage/PE chain, NSGs, VNets/subnets, route tables, NAT, firewalls, private DNS, Key Vaults, public IPs; NCCs + serverless network policies + workspace↔NCC bindings |\n| D7 usage/cost | `system_tables` | DBU + currency spend by workspace/SKU, per-principal attribution, warehouse/Genie/dashboard usage, long-running clusters, principal activity |\n| D8 devops | `devops` | repos, git credentials, bundle-deploy jobs |\n| D9 ML/AI | `ml_estate` | serving endpoints, vector search, registered models, experiments |\n| D10 blast radius | `blast_radius` | OAuth app integrations, user-agent classification, ADF reach |\n| workspace content | `workspace_content` | workspace objects (notebooks, dirs, repos) and their object-level ACLs |\n| lakebase | `lakebase` | Lakebase (managed Postgres) instances and Postgres-native login posture |\n| effective access | *engine view* | direct + group-expanded grants, privilege-class weighting, granted-vs-used deltas |\n\n`--concurrency` (default auto: one worker per workspace up to 24) bounds per-workspace\nparallelism; explicit `--concurrency N` overrides auto. A killed run resumes at the\nfirst incomplete workspace. Per-API request budgets: [docs/RATE-LIMITS.md](docs/RATE-LIMITS.md).\n\n## Standards & coverage\n\nEvery check in every catalogue Compass draws from is accounted for — nothing is\n\"not in the ledger\". The receipts:\n\n| Ledger | What it accounts for |\n|---|---|\n| [Rules coverage ledger](docs/rules-coverage-ledger.md) | Every SAT, MCSB, Azure Policy, and UC-best-practice check mapped to exactly one disposition, with the cloud adaptation named |\n| [Principles coverage ledger](docs/principles-coverage-ledger.md) | Every Well-Architected Lakehouse principle mapped to a shipped compass principle, an out-of-scope reason, or a named width-gap |\n| [Depth-gap review](docs/depth-gaps.md) | Known depth limits in access management, data architecture, and the network stack, per item |\n| [Width-gap review](docs/width-gaps.md) | The Databricks SDK surface diffed against the collected schema: every plane not yet seen, with the resolving endpoint |\n\nBackground research: [deep-research reports](docs/deep_research/index.md).\nFull docs index: [docs/index.md](docs/index.md).\n\n## Design\n\nTwo layers: a deterministic, read-only toolkit (collectors → versioned\ninventory → rules engine → unbranded report), and the skills that drive it and\ninterpret findings with the client. Code owns the boundaries; judgement stays\nin the skills. No LLM in the collect/rules/render path. Every report carries a\nCoverage-limits chapter — read it before trusting any aggregate.\n\n## Contributing\n\nAll development happens in this repository. Ground rules (synthetic data only,\nstrictly read-only, coverage honesty): [CONTRIBUTING.md](CONTRIBUTING.md).\nVulnerabilities: [SECURITY.md](SECURITY.md).\n",
  "bytes": 11104,
  "sha": "3e499eb826b439240fa8e32d0fa41e067af4ead4e9ac3eb5cb80ed6d7c798122",
  "repo_slug": "cauchyio/platform-compass-public",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_cauchyio_platform_compass_public_index_m_5bcbe3ec/readme"
}