governor-audit 0.1.0

Read-only BigQuery cost-audit tool — single-user, gcloud ADC only, no GCS / no GitHub / no dbt installation.

governor-audit

Read-only BigQuery cost-audit tool for single-user production audits.

Posture: Single-user. gcloud ADC only. No GCS, no GitHub, no service-account JSON, no dbt installation, no shadow validation. The only thing it talks to over the network is BigQuery — and only to query INFORMATION_SCHEMA.JOBS_BY_PROJECT.

When to use this vs. the other governor packages

• governor-audit (this package): you have read access to a prod BigQuery project. You want a fast cost audit + detection findings without touching the dbt source code, running dbt, or setting up cloud infrastructure.
• governor-cli: you have the dbt project source on your machine and want to run dbt + propose fixes locally.
• governor-web: you operate the platform; you want shared infrastructure (GCS-backed manifests, GitHub PRs, scheduled syncs) for a team.

What you get

• Dashboard — Total / Build / Consumption / Flagged spend KPI cards, top-20 spenders bar chart, paginated cost-drivers table with click-to-sort columns and a per-row issue count.
• Detection engine — every enabled rule from governor_core.opportunities.rules (partition_pruning, shuffle_spill, slot_contention, join_explosion, dead_cte, dead_column, dead_window_expression, redundant_order_by, unused_aggregation_output, unused_join) runs on each cached job; opportunities feed the Active Issues pane.
• Job detail — full SQL viewer with expand / copy buttons, metadata panes, and the list of detection-rule findings for that job.
• Settings — Account (gcloud principal + ADC probe), Appearance (light / dark / system), AI / LLM (provider, model, params — reviewer code lands in v0.0.2), Detection Rules (per-rule enable/disable).
• Reset cache — wipe everything INFORMATION_SCHEMA collected without losing your config.

Quickstart

gcloud auth application-default login
uv tool install governor-audit
governor-audit init --project prod-warehouse-123 --region us
governor-audit scan --days 30
governor-audit start
# open http://localhost:8765

The web UI exposes the same actions as the CLI plus the dashboard / settings views. After the first init you can do everything from the browser.

See the spec's quickstart for the full first-audit walkthrough.

Architecture

• Storage: SQLite at ~/.governor-audit/state.db via governor_core.db.sqlite_compat.
• Auth: gcloud Application Default Credentials only — google.auth.default(). No service-account JSON. No browser OAuth.
• Workload classification: manifest-free heuristic — dbt-originated CTAS / MERGE / INSERT / UPDATE / DELETE → build; non-dbt SELECT → consumption; ambiguous → other. Driven by the /* {"app": "dbt" comment-prefix the dbt-bigquery adapter prepends.
• Loopback only: the FastAPI app rejects any request whose Host: header isn't a localhost variant. Not a public service.

See spec 141 for the complete spec set:

• spec.md — feature spec
• plan.md — implementation plan
• data-model.md — schemas
• contracts/cli.md — CLI contract
• contracts/web-routes.md — web routes contract

Versioning

governor-audit ships on its own version track, decoupled from the cloud bundle (governor-core / governor-web / governor-cli / governor-bq). Audit v0.0.1 and cloud v0.7.x coexist. See scripts/release-audit.sh for the release flow.

License

MIT.