{"id":44667119,"url":"https://github.com/ulsc/governor","last_synced_at":"2026-02-21T01:00:37.207Z","repository":{"id":338520304,"uuid":"1158086686","full_name":"ulsc/governor","owner":"ulsc","description":"Extensible CLI for security-auditing AI-generated applications. Let's make vibe coding safe.","archived":false,"fork":false,"pushed_at":"2026-02-14T23:59:27.000Z","size":494,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-15T06:29:09.545Z","etag":null,"topics":["ai","security"],"latest_commit_sha":null,"homepage":"https://governor.sh","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ulsc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-14T19:20:19.000Z","updated_at":"2026-02-14T23:59:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ulsc/governor","commit_stats":null,"previous_names":["ulsc/governor"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ulsc/governor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulsc%2Fgovernor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulsc%2Fgovernor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulsc%2Fgovernor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulsc%2Fgovernor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ulsc","download_url":"https://codeload.github.com/ulsc/governor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulsc%2Fgovernor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29637398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","security"],"created_at":"2026-02-15T01:07:47.210Z","updated_at":"2026-02-20T00:14:57.121Z","avatar_url":"https://github.com/ulsc.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/governor_logo.webp\" alt=\"Governor\" width=\"200\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eGovernor\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eLet's make vibe coding safe.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ulsc/governor/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ulsc/governor/ci.yml?branch=main\u0026style=for-the-badge\u0026label=build%20%26%20test\" alt=\"Build \u0026 Test\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ulsc/governor/actions/workflows/release.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ulsc/governor/release.yml?style=for-the-badge\u0026label=release%20artifacts\" alt=\"Release Artifacts\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nGovernor is an extensible CLI for security-auditing AI-generated applications.\n\nIt's designed to give you:\n- repeatable security audits with machine-readable output,\n- built-in + organization-specific custom checks,\n- a check-extraction workflow from internal security documents,\n- terminal-native progress UI while workers run.\n\nLicense note:\n- Governor is released under the **MIT License**.\n\nDisclaimer note:\n- Governor is an AI-assisted security tool and may produce incorrect, incomplete, or misleading output.\n- You are solely responsible for validating findings and for any security, legal, compliance, or operational decisions made from its output.\n\n## Table of Contents\n\n- [Who It Is For](#who-it-is-for)\n- [How It Works](#how-it-works)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Quickstart Command](#quickstart-command)\n- [Init Command](#init-command)\n- [CI/CD](#cicd)\n- [Audit Command](#audit-command)\n- [Matrix Command](#matrix-command)\n- [Policy Command](#policy-command)\n- [Isolated Runs](#isolated-runs)\n- [Checks Command](#checks-command)\n- [Scan Command](#scan-command)\n- [Diff Command](#diff-command)\n- [Hooks Command](#hooks-command)\n- [Ignore File](#ignore-file)\n- [Custom Check Format](#custom-check-format)\n- [Extractor (Docs to Checks)](#extractor-docs-to-checks)\n- [Checks Docs](#checks-docs)\n- [TUI and Progress](#tui-and-progress)\n- [Output Artifacts](#output-artifacts)\n- [License](#license)\n- [Disclaimer](#disclaimer)\n- [Contributing](#contributing)\n\n## Who It Is For\n\nGovernor is built for organizations that receive many source folders/zips and need:\n- consistent security review quality,\n- audit evidence in markdown + JSON + HTML,\n- reusable security policy checks across teams.\n\n## How It Works\n\n1. Intake:\n- Accepts a local folder or `.zip`.\n- Builds a filtered staging workspace with only allowed source files.\n- Applies file-count and byte limits to the staged set before workers run.\n\n2. Check selection:\n- Uses built-in checks by default.\n- Adds enabled custom checks from `./.governor/checks` and `~/.governor/checks` (repo-local takes precedence on duplicate IDs).\n- Supports `engine: ai` and deterministic `engine: rule` check types.\n\n3. Execution:\n- Runs checks with bounded concurrency (`--workers`, default `3`).\n- `engine: ai` checks execute via the configured AI profile/provider (`--ai-profile`, `--ai-provider`).\n- For `codex-cli` provider, sandbox behavior is controlled by `--execution-mode` and `--ai-sandbox`.\n- `engine: rule` checks execute deterministically without model calls.\n- Worker subprocesses run with a constrained environment allowlist.\n- AI binaries are resolved and attested only when selected checks require `codex-cli`.\n\n4. Reporting:\n- Merges and de-duplicates findings.\n- Writes `audit.md`, `audit.json`, and `audit.html`.\n\n## Quick Start\n\n```bash\n# 1) Install\ncurl -fsSL https://governor.sh/install.sh | bash\n\n# 2) Run your first audit (works immediately, no config needed)\ngovernor audit .\n```\n\nThat's it. Governor auto-detects that no AI provider is configured and runs all rule-engine checks (hardcoded credentials, command injection, prompt injection, etc.) instantly. No API keys, no setup.\n\n### Guided setup (optional)\n\nFor a complete interactive setup in ~30 seconds:\n\n```bash\ngovernor quickstart\n```\n\nThis walks you through project detection, `.governor/` initialization, pre-commit hook installation, optional AI configuration, and your first audit.\n\n### Full workflow\n\n```bash\n# Initialize the .governor/ workspace\ngovernor init\n\n# Run audit on a folder\ngovernor audit /path/to/app\n\n# Initialize a draft custom check from a template\ngovernor checks init \\\n  --id authz-missing-role-check \\\n  --template authz-missing-checks \\\n  --name \"Missing role checks\"\n\n# Enable it\ngovernor checks enable authz-missing-role-check\n\n# Re-run audit with built-ins + enabled custom checks\ngovernor audit /path/to/app\n```\n\n## Installation\n\n### Install script (recommended)\n\n```bash\ncurl -fsSL https://governor.sh/install.sh | bash\n```\n\nOverride the install directory:\n\n```bash\nINSTALL_DIR=/opt/bin curl -fsSL https://governor.sh/install.sh | bash\n```\n\nThe script detects your OS and architecture, downloads the latest release binary, verifies the SHA-256 checksum, and installs to `/usr/local/bin` (or `~/.local/bin` if not writable).\n\nSupported platforms: Linux (amd64, arm64), macOS (amd64, arm64), Windows (amd64 via WSL/Git Bash/MSYS2).\n\n### Requirements\n\n- Go `1.22+` (only if building from source)\n- `codex` CLI in `PATH` when using `--ai-provider codex-cli`\n\n### Built-in AI Profiles\n\nGovernor includes built-in profiles you can select via `--ai-profile`, including:\n- `codex`, `codex-api`\n- `openai`, `openrouter`, `vercel-ai-gateway`\n- `claude`, `gemini`, `minimax`, `chatglm`\n- `mistral`, `deepseek`, `grok`, `perplexity`, `huggingface`\n- `local-openai` (for local OpenAI-compatible endpoints such as Ollama)\n\nProfiles can be overridden or extended via:\n- `~/.governor/ai/profiles.yaml`\n- `./.governor/ai/profiles.yaml`\n\n### Build from source\n\n```bash\nmake build\n```\n\nBinary:\n\n```text\n./bin/governor\n```\n\n### Install to local bin\n\n```bash\nmake install\n```\n\nDefault install path:\n\n```text\n~/.local/bin/governor\n```\n\n## Quickstart Command\n\n```bash\ngovernor quickstart\n```\n\nInteractive guided setup wizard for new users. Completes in about 30 seconds.\n\nThe wizard:\n\n1. **Detects project type** — automatically identifies Next.js, Express, Go, FastAPI, Django, Rust, and other project types from marker files.\n2. **Initializes `.governor/`** — creates config, gitignore, and checks directory. `[Y/n]`\n3. **Installs pre-commit hook** — adds a git hook that runs `governor audit --staged --quick --fail-on high` before every commit. Only offered when `.git/` exists. `[Y/n]`\n4. **AI setup instructions** — shows provider-specific instructions for Codex, OpenAI, or Claude. `[y/N]`\n5. **Runs first audit** — executes `governor audit --quick` for instant rule-engine results. `[Y/n]`\n\nEach step is a Y/n prompt. Press Enter to accept the default (shown in uppercase).\n\n### Supported project types\n\n| Type | Detection signal |\n|------|-----------------|\n| Next.js | `next.config.{js,mjs,ts}` |\n| Supabase | `supabase/config.toml` |\n| Express | `express` in `package.json` deps |\n| Fastify | `fastify` in `package.json` deps |\n| FastAPI | `fastapi` in `requirements.txt` |\n| Flask | `flask` in `requirements.txt` |\n| Django | `django` in `requirements.txt` |\n| Go | `go.mod` |\n| Rust | `Cargo.toml` |\n| Node.js | `package.json` (fallback) |\n| Python | `requirements.txt` / `pyproject.toml` / `setup.py` (fallback) |\n\n## Init Command\n\n```bash\ngovernor init [flags]\n```\n\nScaffolds the `.governor/` workspace in the current repository:\n\n- `.governor/` and `.governor/checks/` directories\n- `.governor/.gitignore` (keeps checks in git, ignores runs)\n- `.governor/config.yaml` (commented template with sensible defaults)\n\nThe command is idempotent — it skips files that already exist unless `--force` is used.\n\n### Flags\n\n- `--force`: overwrite existing files\n- `--ai-profile \u003cname\u003e`: set the default AI profile in the generated config\n\n### Examples\n\n```bash\n# Initialize with defaults\ngovernor init\n\n# Initialize with a specific AI profile\ngovernor init --ai-profile openai\n\n# Re-initialize, overwriting existing files\ngovernor init --force\n```\n\nIf run outside a git repository, Governor warns and initializes in the current directory.\n\n## CI/CD\n\n### GitHub Action\n\nThe easiest way to run Governor in CI is with the official GitHub Action:\n\n```yaml\nname: Security Audit\non: [push, pull_request]\n\npermissions:\n  security-events: write\n\njobs:\n  audit:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: ulsc/governor-action@v1\n        with:\n          fail-on: high\n```\n\nThis installs Governor, runs the audit, uploads SARIF results to GitHub Code Scanning, and saves audit artifacts. See [governor-action](https://github.com/ulsc/governor-action) for full documentation.\n\n### Internal workflows\n\nGovernor uses GitHub Actions with two maintained workflows:\n\n- `CI` (`.github/workflows/ci.yml`)\n- Trigger: push to `main` and all pull requests.\n- Runtime: Go `1.25`.\n- Steps: `go test -mod=readonly ./...`, `govulncheck`, and `go build -mod=readonly -o bin/governor .`\n- GitHub Actions are pinned to immutable commit SHAs.\n\n- `Release Artifacts` (`.github/workflows/release.yml`)\n- Trigger: tags matching `v*` (for example `v0.1.0`).\n- Runtime: Go `1.25`.\n- Builds cross-platform binaries for:\n  - linux/amd64\n  - darwin/arm64\n- windows/amd64\n- Uploads packaged artifacts (`.tar.gz` for linux/macOS, `.zip` for windows) to the workflow run.\n- Generates SHA-256 checksum files for release archives.\n- Emits build provenance attestations for release artifacts.\n- Verifies release tag commits are reachable from `main`.\n\nTo trigger release artifacts:\n\n```bash\ngit tag v0.1.0\ngit push origin v0.1.0\n```\n\n## Audit Command\n\n```bash\ngovernor audit \u003cpath-or-zip\u003e [flags]\n```\n\n### Important flags\n\n- `--workers \u003c1-3\u003e`: max concurrent worker processes (default `3`)\n- `--ai-profile \u003cname\u003e`: AI profile (default `codex`)\n- `--ai-provider \u003cname\u003e`: provider override (`codex-cli|openai-compatible`)\n- `--ai-model \u003cid\u003e`: model override\n- `--ai-auth-mode \u003cmode\u003e`: auth override (`auto|account|api-key`)\n- `--ai-base-url \u003curl\u003e`: base URL override for openai-compatible providers\n- `--ai-api-key-env \u003cname\u003e`: API key env var override\n- `--ai-bin \u003cpath\u003e`: AI CLI executable path for `codex-cli` provider\n- `--execution-mode \u003csandboxed|host\u003e`: worker execution mode (default `sandboxed`)\n- `--ai-sandbox \u003cmode\u003e`: sandbox mode for sandboxed execution (`read-only` default)\n- `--checks-dir \u003cdir\u003e`: custom checks directory override\n  - Read defaults (when omitted): `./.governor/checks` + `~/.governor/checks` (repo first)\n  - Write defaults for `checks add`/`checks extract` (when omitted): `./.governor/checks` in repo, otherwise `~/.governor/checks`\n- `--only-check \u003cid\u003e`: run only specified check IDs (repeatable)\n- `--skip-check \u003cid\u003e`: skip specified check IDs (repeatable)\n- `--no-custom-checks`: run built-in checks only\n- `--quick`: run only rule-engine checks (no AI, no network)\n- `--policy \u003cpath\u003e`: apply policy file (defaults to `./.governor/policy.yaml` when present)\n- `--require-policy`: fail when no policy file can be resolved\n- `--changed-only`: scan only files with uncommitted changes (vs HEAD)\n- `--changed-since \u003cref\u003e`: scan only files changed since a git ref (branch, tag, or commit)\n- `--staged`: scan only staged files (for pre-commit use)\n- `--tui`: force interactive TUI\n- `--no-tui`: force plain mode\n- `--timeout \u003cduration\u003e`: per-check timeout (default `4m`, set `0` to disable)\n- `--out \u003cdir\u003e`: custom output directory\n- `--ignore-file \u003cpath\u003e`: path to a `.governorignore` file (auto-detected in input root if omitted)\n- `--keep-workspace-error`: keep staged `workspace/` only for warning/failed runs (default deletes)\n\nNotes:\n- `--quick` and AI flags (`--ai-profile`, etc.) are mutually exclusive.\n- `--changed-only`, `--changed-since`, and `--staged` are mutually exclusive. All three require a git repository.\n- **Auto-quick:** When no AI configuration is present (no AI flags, no `ai_profile` in config), Governor automatically falls back to `--quick` mode and prints a hint showing how to enable AI checks.\n\n### Examples\n\n```bash\n# Zero-config — works immediately, auto-detects no AI and runs rule checks\ngovernor audit .\n\n# Built-ins only\ngovernor audit ./my-app --no-custom-checks\n\n# Run only a specific check\ngovernor audit ./my-app --only-check appsec\n\n# Run selected custom check\ngovernor audit ./my-app --only-check authz-missing-role-check\n\n# Quick rule-only scan (no AI, instant)\ngovernor audit ./my-app --quick\n\n# Scan only uncommitted changes\ngovernor audit ./my-app --changed-only\n\n# Scan only changes since a branch point\ngovernor audit ./my-app --changed-since main\n\n# Quick scan of staged files (ideal for pre-commit)\ngovernor audit ./my-app --staged --quick --fail-on high\n\n# Enforce policy-as-code gates\ngovernor audit ./my-app --policy ./.governor/policy.yaml --require-policy\n```\n\n## Matrix Command\n\n```bash\ngovernor matrix run [flags]\n```\n\nRuns multiple audits from a single matrix file (monorepo-friendly), then writes aggregate summary artifacts.\n\nFlags:\n- `--config \u003cpath\u003e`: matrix config path (default `./.governor/matrix.yaml`)\n- `--out \u003cdir\u003e`: output directory for matrix summaries and target runs\n- `--json`: print matrix summary JSON to stdout\n\nConfig schema:\n\n```yaml\napi_version: governor/matrix/v1\ndefaults:\n  fail_on: high\n  ai_profile: codex\n  policy: ./.governor/policy.yaml\n  require_policy: true\ntargets:\n  - name: api\n    path: ./services/api\n    quick: true\n  - name: web\n    path: ./apps/web\n    fail_on: medium\naggregation:\n  fail_fast: false\n  overall_fail_on: high\n  require_all_targets: true\n```\n\nNotes:\n- Target options merge as `defaults` then per-target override.\n- Each target runs as an audit subprocess (`governor audit \u003ctarget.path\u003e --no-tui ...`).\n- Matrix writes `matrix-summary.json` and `matrix-summary.md` plus per-target audit artifacts under the matrix output dir.\n\n## Policy Command\n\n```bash\ngovernor policy \u003cvalidate|explain\u003e [flags]\n```\n\nCommands:\n- `governor policy validate --file ./.governor/policy.yaml`\n- `governor policy explain --file ./.governor/policy.yaml`\n\nFlag:\n- `--file \u003cpath\u003e`: policy file path (default `./.governor/policy.yaml`)\n\nExample policy:\n\n```yaml\napi_version: governor/policy/v1\ndefaults:\n  fail_on_severity: high\n  max_suppression_ratio: 0.40\n  max_new_findings: 0\n  require_checks: [appsec]\nrules:\n  - name: backend-relaxed\n    when:\n      paths: [\"api/**\"]\n    enforce:\n      fail_on_severity: medium\nwaivers:\n  - id: waiver-123\n    reason: accepted risk pending redesign\n    expires: \"2099-01-01\"\n    match:\n      checks: [\"appsec\"]\n```\n\nPolicy behavior:\n- `audit` and `ci` accept `--policy` and `--require-policy`.\n- If policy is applied, Governor evaluates violations after audit execution.\n- Unwaived policy violations fail command exit status (`audit`/`ci`) and are included in `audit.json`, `audit.md`, and `audit.html`.\n\n## Isolated Runs\n\nRun Governor in a disposable container with strict mounts and runtime limits:\n\n```bash\n# Optional: build local runner image first\nmake build-isolation-image IMAGE=governor-runner:local\n\ngovernor isolate audit ./my-app \\\n  --runtime auto \\\n  --network unrestricted \\\n  --pull never \\\n  --image governor-runner:local\n```\n\nKey behavior:\n- Input is mounted read-only (`/input`).\n- Output is mounted read/write at a fresh host output directory (`--out` or default `./.governor/runs/\u003ctimestamp\u003e`) and mapped to `/output` in-container.\n- Container root filesystem is read-only with restricted capabilities.\n- Worker execution inside container defaults to host mode (`--execution-mode host`) for reliable repository access.\n- If you explicitly choose sandboxed execution, Governor can auto-rerun sandbox-denied tracks in host mode.\n- CLI prints final artifact paths using host filesystem paths.\n\nAccount auth (no API key):\n- `--auth-mode account` (default for `codex-cli`) uses host account state from `~/.codex/auth.json`.\n- Governor stages a minimal read-only auth bundle from `--ai-home` into an ephemeral directory and mounts it into the container.\n- No write-back is performed to host `--ai-home`.\n\nUseful flags:\n- `--auth-mode auto|account|api-key`\n- `--ai-home ~/.codex`\n- `--ai-profile \u003cname\u003e`\n- `--ai-provider codex-cli|openai-compatible`\n- `--ai-model \u003cid\u003e`\n- `--ai-auth-mode auto|account|api-key`\n- `--ai-base-url \u003curl\u003e`\n- `--ai-api-key-env \u003cname\u003e`\n- `--ai-bin \u003cpath\u003e`\n- `--runtime auto|docker|podman`\n- `--image \u003crunner-image\u003e`\n- `--pull always|if-missing|never`\n- `--network unrestricted|none`\n- `--execution-mode sandboxed|host`\n- `--ai-sandbox read-only|workspace-write|danger-full-access`\n- `--clean-image`\n- `--keep-workspace-error`\n\nNotes:\n- `--out` is optional; default is `./.governor/runs/\u003ctimestamp\u003e`.\n- Isolated defaults are hardened while remaining practical: `--network none`, `--pull never`, `--auth-mode account`, `--execution-mode host`.\n- `--network unrestricted` allows normal outbound network for model/tool calls; `none` is fully offline.\n- For `codex-cli`, isolated preflight includes endpoint reachability and a short CLI exec probe.\n- Worker tracks retryable AI transport failures (for example stream/network disconnects) and emits a fallback non-empty JSON output when retries are exhausted.\n- If `--pull` is `always` or `if-missing`, `--image` must be digest pinned (`name@sha256:...`).\n- Container runtime/image caches are external to Governor output and may persist unless cleaned (`--clean-image`).\n- If you do not have a published runner image, use `Dockerfile.isolate-runner` with `make build-isolation-image`.\n\n### Isolated Troubleshooting\n\nCommon diagnostic labels in worker/preflight errors:\n\n- `[infra.tls_trust]`: Runner image CA trust is missing or broken. Rebuild image from `Dockerfile.isolate-runner` and ensure `ca-certificates` are installed.\n- `[auth.account]`: Account/API auth is unavailable in the isolated environment. Re-run `codex login` on host or use `--auth-mode api-key`.\n- `[infra.network]`: Network/DNS/connectivity issue to AI endpoints.\n- `[stream.transient]`: Stream dropped mid-response; Governor retries and may fall back to non-empty JSON output.\n\n## Checks Command\n\n```bash\ngovernor checks [\u003ctui|init|add|extract|list|validate|doctor|explain|enable|disable|lock|update-packs|trust\u003e]\n```\n\nDefault behavior:\n- Interactive terminal: `governor checks` opens the checks workspace TUI.\n- Non-interactive shell (CI/pipes): `governor checks` falls back to `governor checks list`.\n\n### `checks tui`\n\nInteractive checks workspace for enterprise operations.\n\n```bash\ngovernor checks\ngovernor checks tui\n```\n\nKey actions:\n- `j`/`k`: move selection\n- `/`: search\n- `s`: cycle status filter\n- `o`: cycle source filter\n- `1..5`: sort by id/status/source/severity/path\n- `e` / `d`: enable/disable selected mutable custom check (with confirmation)\n- `n`: duplicate selected check as draft\n- `p`: show selected check path\n- `r`: refresh from disk\n- `h`: toggle details pane\n\n### `checks init` (recommended)\n\nGuided/template-based check authoring for production teams.\n\n```bash\n# List templates\ngovernor checks init --list-templates\n\n# Non-interactive creation\ngovernor checks init \\\n  --non-interactive \\\n  --template authz-missing-checks \\\n  --id insecure-admin-surface \\\n  --name \"Insecure admin surface\"\n```\n\nInteractive usage:\n\n```bash\ngovernor checks init\n```\n\nBy default this writes to:\n- `./.governor/checks` when inside a git repo.\n- `~/.governor/checks` otherwise.\n\nKey flags:\n- `--template \u003cid\u003e`: template ID (`blank`, `authz-missing-checks`, `secrets-handling`, etc.)\n- `--overwrite`: replace existing file with same ID\n- `--status draft|enabled|disabled`\n\n### `checks add`\n\nCreates a draft check YAML quickly (backward-compatible path).\nFor new checks, prefer `checks init`.\n\n```bash\ngovernor checks add \\\n  --id insecure-admin-surface \\\n  --name \"Insecure admin surface\" \\\n  --description \"Detect admin endpoints without authorization checks\" \\\n  --instructions \"Identify admin routes and verify role/permission checks.\" \\\n  --include-glob \"**/*.go\" \\\n  --category auth\n```\n\n### `checks list`\n\nLists built-in/custom checks and statuses.\n\n```bash\ngovernor checks list\ngovernor checks list --source custom\ngovernor checks list --status enabled\n```\n\n### `checks validate`\n\nValidates check files and duplicate IDs.\n\n```bash\ngovernor checks validate\n```\n\n### `checks doctor`\n\nRuns diagnostics on effective and shadowed checks.\n\n```bash\ngovernor checks doctor\ngovernor checks doctor --strict\ngovernor checks doctor --format json\n```\n\nReports:\n- invalid YAML/schema issues,\n- duplicate/shadowed IDs,\n- authoring quality warnings (weak instructions, broad scope, missing scope hints).\n\n### `checks explain`\n\nExplains exactly which check definition is active and why.\n\n```bash\ngovernor checks explain insecure-admin-surface\ngovernor checks explain insecure-admin-surface --format json\n```\n\nShows:\n- searched directories,\n- effective check file path,\n- shadowed alternatives,\n- invalid candidates.\n\n### `checks enable` / `checks disable`\n\n```bash\ngovernor checks enable insecure-admin-surface\ngovernor checks disable insecure-admin-surface\n```\n\nDefault behavior without `--checks-dir`:\n- Searches `./.governor/checks` first, then `~/.governor/checks`.\n- Enables/disables the first matching check by that precedence.\n\n### `checks trust validate` / `checks trust pin`\n\nValidate or pin check-pack trust policy for taps/lockfile workflows.\n\n```bash\n# Validate all locked packs against trust policy and taps\ngovernor checks trust validate --trust-policy ./.governor/check-trust.yaml --strict\n\n# Pin one pack (creates trust policy file if missing)\ngovernor checks trust pin web\n```\n\nTrust policy schema:\n\n```yaml\napi_version: governor/check-trust/v1\nmode: warn # off|warn|strict\ntrusted_sources:\n  - name: acme/checks\n    url: https://example.com/acme/checks.git\npinned_packs:\n  - pack: web\n    source: acme/checks\n    version: 1.2.3\n    digest: sha256:...\n    commit: abcdef123456\nrequirements:\n  require_digest: true\n  require_lock_entry: true\n  allow_major_updates: false\n```\n\nMode behavior:\n- `off`: trust checks never block install/update.\n- `warn`: emits warnings/errors but does not block install/update.\n- `strict`: blocks install/update when trust errors exist.\n\nPack install/update integration:\n- `governor checks install-pack` and `governor checks update-packs` accept `--trust-policy` and `--strict-trust`.\n- `--strict-trust` forces blocking behavior regardless of policy mode.\n\n## Hooks Command\n\n```bash\ngovernor hooks \u003cinstall|remove|status\u003e\n```\n\nManage a git pre-commit hook that runs Governor automatically on every commit.\n\n### `hooks install`\n\nInstalls a pre-commit hook that runs `governor audit --staged --quick --fail-on high`:\n\n```bash\ngovernor hooks install\n```\n\nThe hook runs rule-engine checks against staged files and blocks the commit if any high-severity findings are detected. This provides instant security feedback without AI calls or network access.\n\nIf a pre-commit hook already exists, `install` refuses to overwrite it unless `--force` is passed:\n\n```bash\ngovernor hooks install --force\n```\n\nInstalling again when the Governor hook is already present is a no-op (idempotent).\n\n### `hooks remove`\n\nRemoves the Governor pre-commit hook:\n\n```bash\ngovernor hooks remove\n```\n\nOnly removes hooks installed by Governor (identified by a marker comment). Refuses to remove hooks not installed by Governor.\n\n### `hooks status`\n\nShows whether the Governor pre-commit hook is currently installed:\n\n```bash\ngovernor hooks status\n```\n\n## Scan Command\n\n```bash\ngovernor scan \u003cfile\u003e [file2 ...] [flags]\n```\n\nLightweight single-file scanning that runs rule-engine checks against one or more files and prints findings to stdout. No workspace, no manifest, no output directory -- ideal for quick checks during development.\n\n### Flags\n\n- `--json`: output findings as a JSON array\n- `--only-check \u003cid\u003e`: run only specified check IDs (repeatable)\n- `--skip-check \u003cid\u003e`: skip specified check IDs (repeatable)\n- `--no-custom-checks`: run built-in rule checks only\n- `--checks-dir \u003cdir\u003e`: custom checks directory\n- `--fail-on \u003cseverity\u003e`: exit non-zero if findings meet or exceed severity\n\n### Examples\n\n```bash\n# Scan a single file\ngovernor scan config.go\n\n# Scan multiple files\ngovernor scan main.go config.go auth/handler.go\n\n# JSON output for tooling\ngovernor scan --json src/*.go\n\n# Run only credential checks\ngovernor scan --only-check hardcoded_credentials config.go\n\n# Gate on severity (useful in scripts)\ngovernor scan --fail-on high config.go\n```\n\nNotes:\n- Only accepts files, not directories. Use `governor audit` for directory scanning.\n- Runs only `engine: rule` checks (deterministic, no AI, no network).\n- Default exit code: 0 = no findings, 1 = findings exist (or `--fail-on` threshold met).\n- In interactive terminals, output is color-coded and sorted by severity (critical first). In piped/redirected output, plain text is used.\n\n## Diff Command\n\n```bash\ngovernor diff \u003cold.json\u003e \u003cnew.json\u003e [flags]\n```\n\nCompares two `audit.json` files and reports new, resolved, and unchanged findings. This is useful for tracking security posture changes between audits without running a new audit.\n\n### Flags\n\n- `--json`: output the full diff report as JSON\n- `--fail-on \u003cseverity\u003e`: exit non-zero if new findings (regressions) meet or exceed severity\n- `--out \u003cfile\u003e`: write the diff JSON to a file\n\n### Examples\n\n```bash\n# Compare two audit reports\ngovernor diff baseline/audit.json latest/audit.json\n\n# JSON output for CI integration\ngovernor diff --json old.json new.json\n\n# Fail CI if there are new high+ findings\ngovernor diff --fail-on high old.json new.json\n\n# Save diff to a file\ngovernor diff --out diff-report.json old.json new.json\n```\n\nNotes:\n- `--fail-on` applies only to new findings (regressions), not unchanged findings.\n- Findings are matched by title + category + file refs + evidence (first 200 chars).\n\n## Ignore File\n\nGovernor supports a `.governorignore` file for excluding paths from scanning during intake, using gitignore-style patterns.\n\n### Location\n\nPlace a `.governorignore` file in the root of the input being audited. Governor auto-detects it when present. You can also specify an explicit path:\n\n```bash\ngovernor audit ./my-app --ignore-file /path/to/.governorignore\n```\n\n### Syntax\n\n```text\n# Comments start with #\n# Blank lines are ignored\n\n# Glob patterns\n*.generated.go\n*.min.js\n\n# Directory patterns (trailing slash)\nfixtures/\ntest_data/\n\n# Double-star for recursive matching\n**/migrations/**\ndocs/**/*.pdf\n\n# Negation to re-include\n!important.generated.go\n```\n\nRules:\n- Lines starting with `#` are comments.\n- Patterns without a `/` match against the file basename anywhere in the tree.\n- Patterns with a `/` match against the relative path from the input root.\n- A trailing `/` matches directories only.\n- `!` prefix negates a pattern (re-includes previously excluded paths).\n- Last matching pattern wins (standard gitignore semantics).\n- If the file is missing, scanning proceeds normally with no exclusions.\n\nExcluded files are tracked in `manifest.json` under the `\"governorignore\"` skip reason.\n\n## Custom Check Format\n\nCustom checks live in:\n\n```text\n./.governor/checks/\u003cid\u003e.check.yaml   # default write target when inside a git repo\n~/.governor/checks/\u003cid\u003e.check.yaml   # fallback/global location\n```\n\nLoad precedence:\n- Governor merges both locations and uses repo-local definitions first when duplicate IDs exist.\n\nExample:\n\n```yaml\napi_version: governor/v1\nid: insecure-admin-surface\nname: Insecure admin surface\nstatus: draft # draft | enabled | disabled\nsource: custom\nengine: ai # ai | rule\ndescription: Detect admin endpoints without authorization checks\ninstructions: |\n  Identify admin and privileged routes, then verify role/permission checks\n  are present before any sensitive action.\nscope:\n  include_globs:\n    - \"**/*.go\"\n    - \"**/*.ts\"\n  exclude_globs:\n    - \"**/vendor/**\"\n    - \"**/node_modules/**\"\ncategories_hint:\n  - auth\nseverity_hint: high\nconfidence_hint: 0.8\norigin:\n  method: manual # manual | extracted\n```\n\nDeterministic rule example:\n\n```yaml\napi_version: governor/v1\nid: prompt-injection-local\nname: Prompt Injection Local Rule\nstatus: enabled\nsource: custom\nengine: rule\ndescription: Detect prompt-injection override phrases in prompt-bearing files.\nrule:\n  target: file_content\n  detectors:\n    - id: ignore-previous\n      kind: contains\n      pattern: ignore previous instructions\n      title: Prompt override phrase detected\n      category: prompt_injection\n      severity: high\n      confidence: 0.75\n      max_matches: 5\n      remediation: Reject prompt content that attempts to override system instructions.\nscope:\n  include_globs:\n    - \"**/*.md\"\n    - \"**/*.txt\"\n```\n\nBehavior:\n- `draft`: not executed during audits.\n- `enabled`: included in audits.\n- `disabled`: ignored.\n\n## Extractor (Docs to Checks)\n\nGenerate draft checks from local documents:\n\n```bash\ngovernor checks extract --input ./security-policies --max-checks 10\n```\n\nSupported inputs:\n- `.md`\n- `.txt`\n- `.pdf` only with `--allow-pdf` (requires `pdftotext` in `PATH`)\n\nNotes:\n- Extracted checks are written as `draft` by default.\n- Review and enable only the checks you trust.\n- PDF parsing is disabled by default to reduce local parser attack surface.\n\n## Checks Docs\n\n- `docs/checks/authoring.md`: day-1 check creation workflow.\n- `docs/checks/templates.md`: template catalog and usage guidance.\n- `docs/checks/troubleshooting.md`: resolving common check issues quickly.\n- `docs/checks/reference.md`: schema/reference for check fields and behaviors.\n- `docs/checks/tui.md`: interactive checks workspace usage and keymap.\n\n## TUI and Progress\n\n- Interactive terminal: TUI is enabled by default.\n- Non-interactive (pipe/CI): plain progress logs are used.\n- Audit TUI shows worker-level status, durations, error badges, and a filterable/pauseable events panel.\n- Controls: `d` toggle details, `p` pause/resume events panel, `f` cycle event-track filter, `q` close when run completes.\n\n## Output Artifacts\n\nDefault output directory:\n\n```text\n./.governor/runs/\u003ctimestamp\u003e/\n```\n\nContents:\n\n```text\naudit.md\naudit.json\naudit.html\nmanifest.json\nworker-output-schema.json\nworker-\u003ccheck-id\u003e.log\nworker-\u003ccheck-id\u003e-output.json\nworkspace/                 # deleted by default; kept for warning/failed runs with --keep-workspace-error\n```\n\n`audit.json` is intended for automation. `audit.md` and `audit.html` are intended for humans. The HTML report is interactive -- it includes severity/category/check filtering, text search, collapsible finding cards, and a dark mode toggle.\n\nWhen policy is enabled (`--policy`), audit artifacts also include a `policy_decision` section with violations and waiver status.\n\nMatrix runs additionally write:\n\n```text\nmatrix-summary.json\nmatrix-summary.md\n\u003ctarget-name\u003e/audit.{json,md,html}\n```\n\nGit hygiene:\n- Keep `.governor/.gitignore` tracked so `runs/` artifacts stay out of git while `.governor/checks/` can be versioned.\n\n## License\n\nThis project is licensed under the **MIT License**.\n\nSee `LICENSE` for full legal terms.\n\n## Disclaimer\n\nGovernor is provided on an \"as is\" and \"as available\" basis.\n\n- It is an AI-assisted tool and can produce false positives, false negatives, incomplete analysis, or incorrect recommendations.\n- It does not provide legal, compliance, or professional security assurance.\n- You are solely responsible for independently validating all output before acting on it.\n- By using Governor, you accept full responsibility for outcomes related to its use, including security, compliance, data handling, and operational impact.\n- The maintainers and contributors disclaim liability for any direct, indirect, incidental, special, consequential, or exemplary damages arising from use of the tool or reliance on its output.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulsc%2Fgovernor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fulsc%2Fgovernor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulsc%2Fgovernor/lists"}