reachdiff 0.9.0__tar.gz

reachdiff-0.9.0/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

reachdiff-0.9.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: reachdiff
+Version: 0.9.0
+Summary: Effective Unity Catalog access diff for Terraform plans
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/reachdiff/reachdiff
+Project-URL: Issues, https://github.com/reachdiff/reachdiff/issues
+Project-URL: Changelog, https://github.com/reachdiff/reachdiff/blob/main/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk==0.140.0; extra == "databricks"
+Dynamic: license-file
+
+# reachdiff
+
+**Who gains or loses access to what when this Terraform plan is applied?**
+
+reachdiff reads `terraform show -json` output for Databricks Unity Catalog grants
+(`databricks_grants`, `databricks_grant`), group memberships (`databricks_group_member`)
+and owners. It reports the **effective-access diff**, with the route behind each change, and
+returns an exit code a pipeline can act on.
+
+Status: beta. Live mode has been exercised against one Azure Databricks workspace; see
+[Validated scope](#validated-scope) for what that covers and what it doesn't. The demo and tests use synthetic plans.
+
+## Install
+
+Python 3.11 or newer:
+
+```bash
+pip install reachdiff                  # offline mode, no dependencies
+pip install 'reachdiff[databricks]'    # live mode, adds databricks-sdk
+```
+
+## Try the synthetic demo
+
+Python 3.11 or newer, no dependencies:
+
+```bash
+python3 -m reachdiff plan --tfplan examples/schema-grant.plan.json --offline
+```
+
+It reports `analysts` gaining READ on all of `prod.sales` (3 members: 2 new, 1 already had it)
+and `bob@example.com` losing WRITE on `prod.sales.orders`. Offline runs report what they couldn't
+see, so the status is WARN.
+
+![The synthetic demo in a terminal: reachdiff reports WARN, analysts gaining READ and bob losing WRITE](docs/demo/offline.gif)
+
+The recording is made with [vhs](https://github.com/charmbracelet/vhs) from [`docs/demo/offline.tape`](docs/demo/offline.tape).
+
+## Use it on a plan
+
+```bash
+terraform plan -out plan.bin
+terraform show -json plan.bin > local/plan.json   # real plans can contain secrets: keep them out of Git
+python3 -m venv .venv && .venv/bin/pip install -e '.[databricks]'
+.venv/bin/reachdiff plan --tfplan local/plan.json --profile PROFILE --format md --output local/report.md
+```
+
+| Option | Meaning |
+|---|---|
+| `--offline` | Use only data in the plan. Anything Terraform doesn't manage is reported as a gap. |
+| `--profile NAME` | Databricks SDK profile for live mode. Live mode only reads, and only the objects and groups the plan touches. Without a profile, live mode logs in from the SDK's environment variables and needs `DATABRICKS_AUTH_TYPE` (see [CI](#ci)). |
+| `--deep` | Also read the child tables of changed schemas and catalogs. Live mode only: `--offline --deep` is a usage error (exit 3). |
+| `--config FILE` | TOML rules (see below). |
+| `--format text\|json\|md` | `md` is meant for PR comments. |
+| `--fail-on block\|warn\|never` | Default `block`. |
+
+Exit codes: `0` below the fail threshold, `1` WARN, `2` BLOCK, `3` invalid input, config or
+authentication error, or any other operational failure. A live run in which no Databricks read
+succeeds (a total outage) is exit 3, not a report full of gaps.
+
+## Live mode setup
+
+Live mode runs as a dedicated identity, usually a service principal in CI. It needs:
+
+- **Workspace access:** assigned to the workspace with an entitlement. New workspaces give the `users` group none, and
+  without one every API reachdiff calls is refused. `workspace-consume` is the least of the three the API accepts.
+- **`READ METADATA`** on the metastore (it inherits to every object) or on each catalog in scope, so the permissions
+  API returns every grant, not only the caller's own. Without it, reachdiff discards the list and reports
+  `unreadable_object`, so the run cannot pass. `MANAGE` and ownership also work, but `MANAGE` lets the scanner grant
+  itself data access.
+- **An OAuth secret.** For a secret limited to API scopes (`unity-catalog`, `scim`, `access-management`), set the same
+  `scopes` in the profile; the SDK otherwise requests `all-apis` and is refused. Set `auth_type = oauth-m2m`: without
+  it the Databricks CLI silently falls back to other credentials, such as an `az login` session.
+- **Group membership** comes from workspace SCIM, which shows members only to workspace admins. Without admin,
+  reachdiff reports one `membership_incomplete` gap and "members not read", and runs that touch groups stay
+  unverified. Making the scanner a workspace admin gives complete member counts but lets it change workspace settings
+  and identities.
+
+On Azure, the account console rejects personal Microsoft accounts: use a member user of your Entra ID directory.
+`az login --allow-no-subscriptions` is enough for a user without an Azure subscription role.
+
+## CI
+
+Run reachdiff in the job that ran `terraform plan`, on the plan JSON in the runner's temporary directory. Never upload
+the plan JSON as an artifact: it shows sensitive values in plain text.
+
+The GitHub Action (`action.yml`) and the Azure DevOps template (`ci/azure-pipelines/reachdiff.yml`) install reachdiff
+from their own checkout, run it, write the report to the run summary and, if asked, post one pull-request comment that
+later runs update. reachdiff itself never posts. `ci/publish.py` does, and only:
+
+- in private repositories and projects. Anywhere else, including GitHub `internal` repositories or when the
+  visibility can't be read, the log gets only the status line, unless `allow-public` is set.
+- on pull requests. On GitHub it never posts for a `pull_request_target` run from a fork.
+
+An error replaces the comment with "reachdiff: ERROR", and a failed post fails the step with exit 3, so a comment never
+shows an earlier, better status. A report too long for a comment (65,536 characters on GitHub, 150,000 on Azure
+DevOps) is replaced by its status and a pointer to the run summary.
+
+| Status | Exit code (default `fail_on = block`) | GitHub | Azure DevOps |
+|---|---|---|---|
+| PASS | 0 | success | succeeded |
+| WARN below the threshold | 0 | success with a warning | succeeded with issues |
+| WARN at the threshold, or BLOCK | 1 or 2 | failed | failed |
+| ERROR | 3 | failed | failed |
+
+**Login.** Without `--profile`, live mode logs in from the SDK's environment variables. Set them on the reachdiff step
+only: `DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID` and always `DATABRICKS_AUTH_TYPE`. reachdiff refuses live mode without
+a profile or `DATABRICKS_AUTH_TYPE` (exit 3): the SDK would otherwise try every login it finds, such as the Terraform
+deployer's `ARM_*` secrets or an `az login` session, and run with more visibility than the scanner has.
+
+To store no secret in CI, use token federation (`github-oidc` or `azure-devops-oidc`) with a federation policy on the
+scanning service principal. An account admin creates it in the account console or with the Terraform resource
+`databricks_service_principal_federation_policy`:
+
+| Platform | Issuer | Subject | Audience |
+|---|---|---|---|
+| GitHub Actions | `https://token.actions.githubusercontent.com` | `<prefix>:pull_request` | `https://<workspace host>/oidc/v1/token` |
+| Azure DevOps | `https://vstoken.dev.azure.com/<organization ID>` | `p://ORGANIZATION/PROJECT/PIPELINE` | `api://AzureADTokenExchange` |
+
+On GitHub, `<prefix>` is `sub_claim_prefix` from `gh api repos/OWNER/REPO/actions/oidc/customization/sub`. With
+GitHub's immutable subject it includes the IDs, for example `repo:OWNER@OWNER_ID/REPO@REPO_ID`. The audience is the
+one the workspace advertises (`token_federation_default_oidc_audiences` in
+`https://<workspace host>/.well-known/databricks-config`), which the SDK requests. To use another audience, set the
+same value in the policy and in `DATABRICKS_TOKEN_AUDIENCE`.
+
+The scanning identity needs the privileges in [Live mode setup](#live-mode-setup). With a scoped OAuth secret
+(`oauth-m2m`) instead: the SDK has no environment variable for `scopes`. Point `DATABRICKS_CONFIG_FILE` at a file that
+holds only a profile with `scopes` and `auth_type = oauth-m2m`, set `DATABRICKS_CONFIG_PROFILE` to that profile, and
+keep the secret in `DATABRICKS_CLIENT_SECRET`.
+
+**If the login fails,** reachdiff exits 3 with "Databricks login failed" and the settings to check. It never prints
+the SDK's message, which can name the host, the client ID and the token subject. To see it, add a temporary step
+before reachdiff with the same `env:` (GitHub shown), in a private repository only, and remove it afterwards:
+
+```yaml
+- name: debug login (temporary)
+  env: # the same DATABRICKS_* values as the reachdiff step
+    DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
+    DATABRICKS_CLIENT_ID: ${{ vars.SCANNER_CLIENT_ID }}
+    DATABRICKS_AUTH_TYPE: github-oidc
+  run: |
+    python3 -m venv "$RUNNER_TEMP/dbg" && "$RUNNER_TEMP/dbg/bin/pip" install --quiet databricks-sdk==0.140.0
+    "$RUNNER_TEMP/dbg/bin/python" - <<'EOF'
+    import base64, json, os, urllib.parse, urllib.request
+    host = os.environ['DATABRICKS_HOST'].rstrip('/')
+    audience = json.load(urllib.request.urlopen(host + '/.well-known/databricks-config'))['token_federation_default_oidc_audiences'][0]
+    url = os.environ['ACTIONS_ID_TOKEN_REQUEST_URL'] + '&audience=' + urllib.parse.quote(audience, safe='')
+    request = urllib.request.Request(url, headers={'Authorization': 'Bearer ' + os.environ['ACTIONS_ID_TOKEN_REQUEST_TOKEN']})
+    claims = json.loads(base64.urlsafe_b64decode(json.load(urllib.request.urlopen(request))['value'].split('.')[1] + '=='))
+    print({k: claims.get(k) for k in ('iss', 'sub', 'aud')}, 'aud is the advertised audience:', claims.get('aud') == audience)
+    from databricks.sdk import WorkspaceClient
+    try:
+        print('logged in:', WorkspaceClient().current_user.me().active)
+    except Exception as exc:
+        print(type(exc).__name__, exc)
+    EOF
+```
+
+### GitHub Actions
+
+```yaml
+permissions:
+  contents: read
+  pull-requests: write # the comment
+  id-token: write # github-oidc
+steps:
+  # ... terraform plan -out "$RUNNER_TEMP/plan.bin" and show -json into "$RUNNER_TEMP/plan.json"
+  - uses: reachdiff/reachdiff@FULL_COMMIT_SHA
+    with:
+      plan-json: ${{ runner.temp }}/plan.json
+      comment: true
+    env:
+      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
+      DATABRICKS_CLIENT_ID: ${{ vars.SCANNER_CLIENT_ID }}
+      DATABRICKS_AUTH_TYPE: github-oidc
+```
+
+| Input | Default | Meaning |
+|---|---|---|
+| `plan-json` | required | Path to the `terraform show -json` output |
+| `mode` | `live` | `live` or `offline` |
+| `deep`, `config`, `fail-on` | off | As the CLI options |
+| `comment` | `false` | Post or update the pull-request comment |
+| `allow-public` | `false` | Write the summary and comment even if the repository is not private |
+| `comment-key` | `default` | Keeps separate comments for several plans in one pull request |
+| `github-token` | `github.token` | Used only for the comment |
+
+Outputs: `status` (`PASS`, `WARN`, `BLOCK` or `ERROR`), `exit-code` and `report-path`. Pin the action to a full commit
+SHA. While this repository is private, only repositories with the same owner can use it (Settings → Actions →
+General → Access). Pull requests from forks get no secrets and no OIDC token, so live mode stops there with exit 3. A
+full workflow is in [`examples/ci/github-workflow.yml`](examples/ci/github-workflow.yml).
+
+### Azure DevOps
+
+Check out this repository as a repository resource next to your own, with explicit paths (a second checkout otherwise
+moves yours to `s/<repo name>`), then include the template after `terraform show -json`:
+
+```yaml
+resources:
+  repositories:
+    - repository: reachdiff
+      type: github
+      endpoint: GITHUB_CONNECTION
+      name: reachdiff/reachdiff
+      ref: FULL_COMMIT_SHA
+steps:
+  - checkout: self
+    path: self
+  - checkout: reachdiff
+    path: reachdiff
+  # ... terraform plan and show -json into $(Agent.TempDirectory)/plan.json
+  - template: ci/azure-pipelines/reachdiff.yml@reachdiff
+    parameters:
+      planJson: $(Agent.TempDirectory)/plan.json
+      reachdiffPath: $(Pipeline.Workspace)/reachdiff
+      host: $(DATABRICKS_HOST)
+      clientId: $(SCANNER_CLIENT_ID)
+      comment: true
+```
+
+The parameters match the action's inputs (`planJson`, `mode`, `deep`, `config`, `failOn`, `comment`, `allowPublic`,
+`commentKey`), plus `python` (default `python3`, 3.11 or newer) and the login: `host`, `clientId` and `authType`
+(default `azure-devops-oidc`). They are set on the reachdiff step only, so they never change how your Terraform steps
+log in. Use the template once per job. Outputs: `reachdiff.status`, `reachdiff.exitCode`, `reachdiff.reportPath`.
+
+The project's build service needs **Contribute to pull requests** on the repository (Project settings →
+Repositories → Security). Pull requests run the pipeline through a build validation branch policy. A full pipeline is
+in [`examples/ci/azure-pipelines.yml`](examples/ci/azure-pipelines.yml).
+
+## Validated scope
+
+Live mode was exercised from 1 to 3 October 2026 against one Azure Databricks trial workspace (Premium, classic compute)
+with Terraform 1.16.4, provider `databricks/databricks` 1.135.0, Databricks CLI 1.19.0, databricks-sdk 0.140.0 and
+Python 3.14. The objects, groups and grants were synthetic. The scenarios and predictions are in
+[`validation/azure/`](validation/azure/); real plans and results stay outside the repository. These runs used the code
+before its rename to reachdiff on 3 October 2026 (see [CHANGELOG.md](CHANGELOG.md)). From 4 to 6 October 2026 the
+renamed code ran against the same workspace again, as the GitHub Action, the Azure DevOps template and the CLI, and
+produced the predicted WARN and BLOCK reports.
+
+Covered:
+
+- Plan reading for `databricks_grants`, `databricks_grant`, `databricks_group_member` and owners on catalogs, schemas
+  and tables, including replaced resources, values known only after apply and a literal provider host.
+- Runs as the workspace's admin user and as a service principal with `workspace-consume` at four privilege levels on
+  the catalog: none, `BROWSE`, `READ METADATA`, and `READ METADATA` with `BROWSE`, `USE CATALOG` and `USE SCHEMA`.
+  `READ METADATA` on the catalog alone gave complete grant, owner and tag reads. Below it, every grant list was
+  discarded and no run passed.
+- The visibility self-check against real SCIM `Me` and effective-permissions responses.
+- Ownership: a service principal that owned a table without a `SELECT` grant could read it, and was refused `SELECT`
+  on a table it did not own.
+- A plan that only changes the case of a schema name reports no change.
+- Group membership read without workspace admin: one `membership_incomplete` gap, "members not read".
+- Paginated listings with `--deep`, tags on tables and columns, and the SDK errors `Unauthenticated`,
+  `PermissionDenied` and `NotFound`.
+- CI, on 2 and 3 October 2026: the GitHub Action on a GitHub-hosted Ubuntu runner (Python 3.11) and the Azure DevOps
+  template on a self-hosted macOS agent (Python 3.14). reachdiff logged in as the scanning service principal by token
+  federation (`github-oidc`, `azure-devops-oidc`) with the policy settings under [CI](#ci); no fallback login was
+  needed. The pull request comment (a thread on Azure DevOps) was created once, then updated in place, and the job
+  results matched WARN, BLOCK and ERROR. With a wrong client ID for reachdiff only, the run ended in ERROR without
+  falling back to another login, also on the self-hosted agent, where a CLI profile and an Azure CLI login existed.
+- Data classification, on 3 October 2026: with automatic tagging on for the class, it tagged an email column
+  `class.email_address`, which the default `[sensitive].tags` pattern `class.*` matches. Without automatic tagging,
+  classification only reports its detections and writes no tags.
+
+Not covered:
+
+- AWS and GCP, serverless workspaces, and more than one workspace or metastore.
+- `READ METADATA` granted on the metastore rather than the catalog; visibility through `MANAGE`, ownership or
+  metastore admin (unit tests only); a scanner that is workspace admin.
+- Terraform's own token federation login in CI: the sample plan only created resources, so `terraform plan` made no
+  Databricks request.
+- Microsoft-hosted Azure DevOps agents, GitHub pull requests from forks, and public repositories or projects (the
+  refusal is covered by unit tests only).
+- Everything under [Not evaluated](#not-evaluated), including runtime behavior such as the gap between destroying and
+  recreating a replaced `databricks_grants` resource.
+
+## Rules
+
+Built-in rules default to WARN: `broad_principal`, `broad_privilege`, `individual_owner`, `sensitive_access` and
+`unverified`. `grant_resource_conflict` defaults to BLOCK: it fires when a plan changes access and more than one
+resource sets the grants on one securable (`conflicting_grant_resources` below). The applied result then depends on
+apply order, and grants can be lost without an error: in the live session, moving grants from `databricks_grants` to
+`databricks_grant` removed every grant on a table. `unverified` reports what reachdiff couldn't see. It can be raised
+to BLOCK but never turned off. Among the gaps it reports:
+
+- `latent_grants` and `deactivated_grants`: a usage privilege (`USE_CATALOG`, `USE_SCHEMA`,
+  `ALL_PRIVILEGES`) is granted or revoked on a catalog or schema, so grants below it may start or
+  stop working. Without `--deep` they are not enumerated. With `--deep` they appear as gains and
+  losses.
+- `conflicting_grant_resources`: more than one resource sets the grants on one securable
+  (`databricks_grants` with `databricks_grant`, two `databricks_grants`, or two `databricks_grant` for the same
+  principal), so the applied result depends on apply order.
+- `sensitivity_not_evaluated`: a schema- or catalog-level gain without `--deep`, or, with `--deep`,
+  a gain over tables the plan doesn't change. Column tags are read only for changed tables, so child
+  column tags are reported as a gap.
+
+```toml
+fail_on = "block"
+
+[sensitive]
+tags = ["pii*", "sensitive*", "class.*"]
+
+[[rule]]
+id = "pii-only-approved-groups"
+severity = "BLOCK"
+sensitive = true
+unless_via = ["pii-readers"]
+message = "New access to PII outside approved groups"
+```
+
+Configured rules fail closed. They match every row before child rows collapse into parent rows. An
+`objects` glob also matches rows on a parent of the objects it names (`prod.*` matches a
+catalog-level row on `prod`). `principal_kinds` also matches principals whose kind is unknown.
+
+## Handle reports with care
+
+Reports contain principal and object names. Don't post them as comments in public repositories.
+reachdiff never posts anywhere itself; the CI publish script withholds reports outside private repositories (see
+[CI](#ci)).
+
+## Not evaluated
+
+- ABAC policies, row filters and column masks
+- volumes, functions and external locations
+- workspace-level ACLs
+- metastore and workspace admin powers
+- identity-provider membership completeness
+- runtime behavior
+
+## Development
+
+```bash
+python3 -m unittest discover -v
+```
+
+`pre-commit install` adds hooks that run ruff (`ruff check`, `ruff format`) and gitleaks on every commit; gitleaks must
+be on your PATH (for example `brew install gitleaks`). CI runs the tests on Python 3.11 and 3.14, the same ruff checks
+and a gitleaks scan of the history. Fake values that look like secrets go into `.gitleaks.toml`, with their source.
+
+Tests also run on sanitized plans and API responses from the live sessions (`tests/fixtures/real/`). To refresh them
+from the ignored `local/validation/`, run `python3 -m validation.sanitize`; it copies only what reachdiff reads,
+replaces identifiers with placeholders and refuses to write output that still looks like it holds one. Read each
+fixture diff before committing.
+
+## Licence and trademarks
+
+Apache License 2.0, see [LICENSE](LICENSE).
+
+reachdiff is an independent project, not affiliated with or endorsed by Databricks or HashiCorp. Databricks, Unity
+Catalog and Terraform are trademarks of their owners.