Start here
Bundle OKF 0.1 · 7 conceitos · CauchyIO/platform-compass-public
Open source Repository Open in the app JSON README (API)
About
# Start here
* [Platform Compass](README.md) - Read-only assessment toolkit for brownfield Databricks platforms on Azure — install, quick start, access tiers, domains and collectors.
# Documentation
* [docs/](docs/) - Product documentation: authentication and request budgets. See [docs/index.md](docs/index.md).
# Assessment skills
* [.agents/skills/](.agents/skills/) - The compass skill family that drives an engagement: assess → strategy → plan. See [.agents/index.md](.agents/index.md).
# Code layout
* [src/compass/](src/compass/) - Python package: collectors, rule packs (YAML), rules engine, CLI, and report templates. Not OKF concepts — start from the README's Design section.
* [tests/](tests/) - Pytest suite (fixtures generated in-code), the read-only hardening guard, and the OKF conformance validator.
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- cauchyio
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Open pull requests
- 1
- Last push
- 2026-08-14T07:46:59Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-09-08 16:02:35
- Updated
- 2026-09-08 16:02:35
- Origin id
CauchyIO/platform-compass-public:index.md
README
---
type: Overview
title: Platform Compass
description: Read-only assessment toolkit for brownfield Databricks platforms on Azure — fit, install, access tiers, domains, and standards coverage.
timestamp: 2026-07-22T00:00:00Z
---
# Platform Compass
Read-only assessment toolkit for brownfield Databricks platforms on Azure:
inventory collectors, a convention-aware rules engine, coverage-honest
reporting. It turns an inherited, organically-grown estate from "we think it's
fine" into a dated, re-runnable assessment. A mismatch with the client's own
conventions becomes a risk or a recorded choice, never a tool failure. Strictly
read-only — the dossier directory is the only thing it writes. Apache-2.0,
pre-1.0 (not yet on PyPI).
## Is this for you?
| Your estate looks like | Compass fit | What to do |
|---|---|---|
| One shared workspace — everyone works in the same place | Overkill | Scoped-down run below |
| Workspace-per-environment — one delivery stream, dev/test/prod | Good fit | Full flow; scope collectors to what matters |
| Hub-and-spoke — platform team, domain workspaces, central metastore | Good fit | Full flow; strategy/plan where drift shows |
| Organic sprawl — workspaces per BU/project, nobody holds the whole map | Built for it | Full `assess → strategy → plan` |
| Greenfield — nothing built yet | Wrong tool | Define desired state in IaC + cluster policies; Compass grades what exists |
| Second opinion / pre-audit snapshot | Good fit | Run `assess`, read the report, stop |
**The scoped-down run.** Same tool, fewer collectors:
`compass collect --domains <the few that matter>`, then `analyze` and `report`,
and read the report yourself — no strategy/plan sessions. A coverage-honest
snapshot in an afternoon. There is no separate "lite" build.
## Where it sits
Compass makes published governance catalogues executable and re-runnable:
- **Rules:** SAT (Databricks Security Analysis Tool), MCSB, Azure Policy
built-ins, UC governance best practices, DASF.
- **Principles:** the Databricks Well-Architected Lakehouse framework.
It is not IaC — it grades the as-built estate and never changes it. It is not
a CSPM — it covers Databricks and its Azure substrate deeply, not multi-cloud
posture broadly. And it is not a one-off scan — snapshots are dated and
re-runnable, so movement between assessments is visible (`compass diff`). The
check-by-check mapping is the
[rules coverage ledger](docs/rules-coverage-ledger.md); neighbouring tools
(SAT, UCX, Lakebridge, the Terraform exporter, system tables) are in
[the ecosystem doc](docs/ecosystem.md).
## Install
As a CLI on PATH:
```
uv tool install git+https://github.com/CauchyIO/platform-compass-public
```
As a library dependency of a uv project:
```
uv add "platform-compass @ git+https://github.com/CauchyIO/platform-compass-public"
```
From a checkout (development):
```
uv venv --python 3.12 .venv
uv pip install -e . pytest --python .venv/bin/python
.venv/bin/pytest
```
From a provided wheel (client install), into a venv created as above:
```
uv pip install --python .venv/bin/python platform_compass-*.whl
```
Troubleshooting: on Intel macOS the `cryptography` 49.x wheel can fail to load
(`symbol not found ... _BIO_ADDR_free`), surfacing at the first
`preflight`/`collect`. Fix:
`uv pip install --python .venv/bin/python 'cryptography<44'`.
## Agent skills & plugins
The skill family (assess → strategy → plan) lives in
[`.agents/skills/`](.agents/skills/) and is consumable three ways:
- **Claude Code plugin** — `/plugin marketplace add CauchyIO/platform-compass-public`,
then `/plugin install platform-compass`. Skills invoke as
`/platform-compass:compass-assess` (strategy and plan likewise).
- **Pi package** — `pi install git:github.com/CauchyIO/platform-compass-public`;
update with `pi update git:github.com/CauchyIO/platform-compass-public`.
In a checkout, Pi auto-discovers `.agents/skills/` — no install needed.
- **In-repo Claude Code** — sessions in a checkout auto-load the stubs in
`.claude/skills/`.
The skills drive the `compass` CLI, so install the Python package as well
(`uv tool install` above; update with `uv tool upgrade platform-compass`).
At client sites prefer these installs over a clone: assessment sessions then
run in a plain engagement directory, not inside a git checkout the agent might
treat as its working repo.
Skill edits belong in `.agents/skills/`; re-mirror the stubs with
`python3 tools/gather.py` (CI enforces sync via `--check`).
## Quick start
```
compass init --dossier ./compass # scaffold engagement.yaml (account id, scope)
compass preflight --dossier ./compass # verify credentials (diagnosed fixes) + record the granted access tier
compass collect --dossier ./compass # run the read-only collectors into a dated snapshot
compass analyze --dossier ./compass # evaluate rules -> findings.json
compass report --dossier ./compass # render the coverage-first markdown report
```
Useful afterwards: `collect --domains infrastructure` re-fills one domain into
the same snapshot; `collect … --seal` freezes a finished snapshot;
`query "<sql>"` reads it back; `infer` detects de-facto conventions;
`diff --findings <old> <new>` renders movement between two assessments.
**The dossier holds real tenant identifiers, names, and cost figures. It never
belongs in a git repository.**
## engagement.yaml
Written by `compass init`; edit directly for anything the prompts didn't cover
(schema: `compass.dossier.Engagement`):
```yaml
schema_version: 1
client: acme # client name
engagement: acme-2026 # engagement slug
databricks:
account_host: https://accounts.azuredatabricks.net
account_id: <databricks account id>
profile: null # a `databricks auth` profile, OR null to use
# env/SPN auth (see docs/AUTH.md)
azure:
subscriptions: # every subscription that hosts in-scope workspaces
- <subscription id>
usage:
warehouse_id: null # a running SQL warehouse for usage/cost extraction
workspace_id: null # numeric id of the workspace that warehouse lives in
window_days: 90
access_tier: null # filled by `compass preflight`
```
## Access tiers & coverage
Coverage scales with what is granted; nothing fails or degrades silently:
| Granted | What Compass can assess |
|---|---|
| Databricks **account admin** | account plane (workspaces, metastores, principals), UC governance across every metastore |
| Databricks **workspace admin** | per-workspace tokens, secret scopes, cluster/job detail on those workspaces |
| Azure **Reader** on the in-scope subscriptions | workspace network posture, storage, private endpoints (via Azure Resource Graph) |
| A usable **SQL warehouse** | usage & cost overlay over system tables |
Anything not granted is reported as `not_assessed` or a coverage gap with the
reason preserved — never a silent pass. Credentials and the service-principal
path: [docs/AUTH.md](docs/AUTH.md).
## Domains & collectors
Each collector reports `ok | partial | denied | skipped` per plane; every
zero-evidence result renders as `not_assessed` or a gap with its reason.
| Domain | Collector(s) | What it inventories |
|---|---|---|
| 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 |
| D1 account/identity | `account` | workspaces, metastores, users/groups/service principals |
| D2 compute | `compute` | clusters, jobs + task graphs, pools, pipelines, policy definitions, global/cluster init scripts, tags, disk-encryption, libraries |
| D3 SQL estate | `sql_estate` | SQL warehouses, Lakeview dashboards |
| 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 |
| D5 data | `data_estate` | external locations, storage credentials, table inventory, DBFS mounts |
| 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 |
| D7 usage/cost | `system_tables` | DBU + currency spend by workspace/SKU, per-principal attribution, warehouse/Genie/dashboard usage, long-running clusters, principal activity |
| D8 devops | `devops` | repos, git credentials, bundle-deploy jobs |
| D9 ML/AI | `ml_estate` | serving endpoints, vector search, registered models, experiments |
| D10 blast radius | `blast_radius` | OAuth app integrations, user-agent classification, ADF reach |
| workspace content | `workspace_content` | workspace objects (notebooks, dirs, repos) and their object-level ACLs |
| lakebase | `lakebase` | Lakebase (managed Postgres) instances and Postgres-native login posture |
| effective access | *engine view* | direct + group-expanded grants, privilege-class weighting, granted-vs-used deltas |
`--concurrency` (default auto: one worker per workspace up to 24) bounds per-workspace
parallelism; explicit `--concurrency N` overrides auto. A killed run resumes at the
first incomplete workspace. Per-API request budgets: [docs/RATE-LIMITS.md](docs/RATE-LIMITS.md).
## Standards & coverage
Every check in every catalogue Compass draws from is accounted for — nothing is
"not in the ledger". The receipts:
| Ledger | What it accounts for |
|---|---|
| [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 |
| [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 |
| [Depth-gap review](docs/depth-gaps.md) | Known depth limits in access management, data architecture, and the network stack, per item |
| [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 |
Background research: [deep-research reports](docs/deep_research/index.md).
Full docs index: [docs/index.md](docs/index.md).
## Design
Two layers: a deterministic, read-only toolkit (collectors → versioned
inventory → rules engine → unbranded report), and the skills that drive it and
interpret findings with the client. Code owns the boundaries; judgement stays
in the skills. No LLM in the collect/rules/render path. Every report carries a
Coverage-limits chapter — read it before trusting any aggregate.
## Contributing
All development happens in this repository. Ground rules (synthetic data only,
strictly read-only, coverage honesty): [CONTRIBUTING.md](CONTRIBUTING.md).
Vulnerabilities: [SECURITY.md](SECURITY.md).