Skip to content

[Feature]: Add workspace-admin mode (Azure) — run SAT without account-admin credentials#359

Open
dinbab1984 wants to merge 9 commits into
databricks-industry-solutions:release/0.9.0from
dinbab1984:feature/workspace-admin-support
Open

[Feature]: Add workspace-admin mode (Azure) — run SAT without account-admin credentials#359
dinbab1984 wants to merge 9 commits into
databricks-industry-solutions:release/0.9.0from
dinbab1984:feature/workspace-admin-support

Conversation

@dinbab1984

@dinbab1984 dinbab1984 commented Jun 19, 2026

Copy link
Copy Markdown

Description

Add workspace-admin mode to SAT (Azure), allowing it to run without account-admin credentials. When account-level secrets are not configured in the secret scope, SAT detects this and automatically disables account-level data collection (accounts_bootstrap). Users must additionally disable the 13 account-level checks in security_best_practices.csv to avoid false-positive violations — see the [Workspace Admin Limitations](https://databricks-industry-solutions.github.io/security-analysis-tool/docs/workspace-admin-limitations) doc for instructions.

Relates to #358

Design principle: If the runner is an account admin with secret scope configured → original behavior preserved exactly. If not → account-level data collection is skipped automatically, and users configure which checks to disable. No breaking changes.

Key changes:

  • ENABLE_ACCOUNT_CHECKS flag auto-detects based on account-console-id presence in secret scope
  • Secrets-first config resolution with widget parameter fallback
  • SP token fallback (Azure) via getContext().apiToken() when client-secret is absent
  • accounts_bootstrap call guarded by ENABLE_ACCOUNT_CHECKS
  • Single-workspace bootstrap registers the current workspace via MERGE
  • Dashboard portability — removed hardcoded catalog/schema references
  • Documentation listing all 13 non-workspace checks with disable instructions

This is a new feature with no matching open issue. A feature request issue will be created separately.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation Update (non-code changes like README or docs)

How Has This Been Tested?

  • Static tests pass: test_csv_health.py (3 passed), test_rule_hygiene.py (2 passed) — no regressions
  • New test suite added: tests/automated/test_workspace_admin_mode.py (10 tests) validates:
    • Workspace-level connectivity without account credentials
    • Account-level checks correctly absent (SAT_MISSING) in workspace-admin runs
    • Workspace-level checks produce results
    • Single-workspace bootstrap registers the current workspace
  • Manual validation: Ran SAT as a workspace-admin Service Principal on Azure — confirmed 52+ checks succeed, 13 account-level checks produce false violations when left enabled (as documented), and produce no results when disabled via CSV.
  • Environment: Azure Databricks, serverless compute, Service Principal with workspace-admin role only
  • Rebased cleanly onto release/0.9.0 — no conflicts with the BrickHound dedup fix (fix: deduplicate BrickHound vertices by id before write #352)

Checklist

Screenshots (If Applicable)

N/A — logic-only changes with no UI modifications. Dashboard renders identically when the 13 account-level checks are disabled via CSV.

Additional Notes

  • Target branch: release/0.9.0 (rebased from upstream/release/0.9.0)
  • Backward compatible: Account-admin deployments are unaffected — ENABLE_ACCOUNT_CHECKS defaults to True when account-console-id exists in the secret scope.
  • User action required in workspace-admin mode: Disable the 13 account-level checks in security_best_practices.csv (or via SQL UPDATE) to avoid false-positive violations. This is documented in workspace-admin-limitations.mdx with a ready-to-run SQL statement.
  • Azure-only SP token fallback: The getContext().apiToken() path is Azure-specific. AWS/GCP credential paths are preserved as-is from main.
  • 13 checks affected: 12 Account Admin (GOV-3, GOV-20, GOV-21, GOV-34, GOV-37, NS-3, NS-4, NS-6, NS-8, NS-9, NS-12, NS-13) + 1 Metastore Admin (INFO-38).
  • Removed WIP scaffolding: databricks.yml, bundle resource configs, azure-pipelines.yml, and Azure DevOps runbook were exploratory and not part of this feature scope.

- Add workspace-admin-limitations.mdx to Docusaurus docs (sidebars.ts updated)
- Add test_workspace_admin_mode.py validating skip behavior for 13 account-level checks
- Update CHANGELOG.md with [Unreleased] section for workspace-admin feature
- Update README.md with Deployment Modes section (account-admin vs workspace-admin)
- Register 'requires_run' pytest mark in conftest.py
- Remove CHANGES_feat_poc.md (content moved to proper docs location)
…urces, azure-pipelines)

These files were exploratory and not part of the workspace-admin feature scope:
- databricks.yml
- deployment/bundle/resources/ (dashboard, jobs, warehouse configs)
- deployment/pipelines/azure-pipelines.yml
…void false positives

The 13 account-level checks are not automatically skipped at evaluation time —
only account-level data collection (accounts_bootstrap) is skipped. Without
disabling these checks in security_best_practices.csv, they will report false
violations against missing intermediate tables.

Added Required Configuration section with SQL and CSV instructions.
@CLAassistant

CLAassistant commented Jun 19, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@dinbab1984

Copy link
Copy Markdown
Author

@arunpamulapati and @dleiva04 Could you please suggest reviewer assignment for this PR? Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants