Vigil is a Go-based GRC (governance, risk, compliance) toolbox for security and compliance teams. It provides framework and requirement tracking, control (measure) management, activity tracking, and a multi-step risk assessment flow with treatment planning and risk register views.

Authorization is policy-based using embedded OPA Rego (cmd/server/policies/authz.rego), not hardcoded role checks in handlers.

Status: Vigil is open-sourced for the common good under Apache 2.0. No commercial support, hosted offering, or maintenance commitments are provided. Parts of this codebase have been developed with the help of AI coding agents (Claude Code, GitHub Copilot CLI); see AGENTS.md for the project conventions agents follow. See LICENSE and the disclaimer at the bottom of this file. Bug reports, ideas, and pull requests are welcome — see CONTRIBUTING.md.

Requirements: mise and Docker or Podman. mise installs and version-pins the rest of the toolchain (Go, the Tailwind CLI, templ, sqlc, air, golangci-lint, …) from mise.toml. Make sure mise is activated in your shell before you start, so the pinned tools land on PATH.

git clone https://github.com/3lbits/vigil.git
cd vigil

make setup            # mise install + git hooks
cp .env.example .env

make generate
make db-up

make run

Open http://localhost:8080.

The Makefile uses podman compose by default. If you run Docker, either alias podman to docker or run docker compose up -d directly in place of make db-up.

To run Vigil from the published container image with PostgreSQL:

docker compose -f demo-compose.yml up -d

Then open http://localhost:8080.

Useful commands:

docker compose -f demo-compose.yml logs -f app
docker compose -f demo-compose.yml down
# remove demo database volume too:
docker compose -f demo-compose.yml down -v

If you prefer running the app from source with live reload:

cp .env.example .env
make setup db-reset-seed
DEV_STUB_AUTH=true make run

golangci-lint, govulncheck, semgrep, and the rest of the dev toolchain are version-pinned in mise.toml and installed by make setup (or mise install directly). No manual installation needed — make pre-commit finds them on PATH once mise is active.

• DEV_STUB_AUTH=true (development only): stub user session, no OAuth app setup needed. This is the easiest way to explore Vigil locally.
• DEV_STUB_AUTH=false: enable one or more real providers via AUTH_PROVIDERS=github,entra,oidc.
• NAIS_AUTH=true: NAIS/Wonderwall bearer-token mode (see below).

Provider callbacks:

When deploying to NAV's NAIS platform, set NAIS_AUTH=true. In this mode the Wonderwall login-proxy sidecar handles the full OAuth2 flow; Vigil's only job is to verify the Authorization: Bearer <token> header the proxy injects on every request.

• No AUTH_PROVIDERS, no OAuth client secret, and no SCS session store needed.
• Login/logout UI delegates to the proxy at /oauth2/login and /oauth2/logout.
• Users are upserted into the same users table as other auth modes (provider="navikt", provider_id=NAVident).
• Members of ADMIN_GROUPS receive the admin role for the duration of the request; all others use the stored DB role.
• The Cloud SQL SSL check is skipped (NAIS connects via a local Unix-socket proxy where sslmode=require is not applicable).
• DATABASE_URL falls back to NAIS_DATABASE_VIGIL_VIGIL_URL when unset (NAIS injects this automatically; the naming depends on the app vigil and database vigil entries in .nais/nais.yaml).

NAIS-specific variables (injected automatically by the platform):

App-managed variables for NAIS:

See .nais/nais.yaml for the full NAIS Application manifest and .github/workflows/nais-deploy.yml for the deploy workflow.

Key environment variables. See .env.example for the full list with comments.

• OAuth callback first tries to claim a pre-provisioned pending user by email.
• If no pending user exists, Vigil creates a new viewer user for that identity.
• When github is enabled, AUTH_ALLOWED_EMAIL_DOMAINS must be set or startup fails.
• In NaisAuth mode, the same claim-then-upsert logic applies keyed on NAVident.

For public deployments, do not expose GitHub login without a strict domain allowlist.

Run make help for the full list.

Ad-hoc load scripts live under scripts/loadtest. These are for occasional manual validation by developers and are not part of CI.

For local UI testing after make db-reset, you can seed a coherent development dataset (5 users, 5 orgs in a hierarchy, 7 frameworks with 5 requirements each, 5 measures, 5 activities, 5 assets, and 7 risk assessments with linked risks/participants):

make dev-seed
# or in one step:
make db-reset-seed

This is manual developer tooling and is intentionally gated to development.

The production image is published to the GitHub Container Registry:

docker pull ghcr.io/3lbits/vigil:latest
# or pin a specific release:
docker pull ghcr.io/3lbits/vigil:v1.0.0

The image is built from a distroless base, runs as non-root (UID 65532), and is multi-arch (amd64 and arm64). Recommended runtime flags:

docker run --rm \
  --cap-drop all \
  --security-opt=no-new-privileges \
  --read-only --tmpfs /tmp \
  --user 65532:65532 \
  -e DATABASE_URL=... \
  -e SESSION_HMAC_KEY=... \
  -p 8080:8080 \
  ghcr.io/3lbits/vigil:latest

Vigil applies its database migrations at startup (via goose) — point it at a PostgreSQL database and it will bring the schema up on first run.

Data extraction: use pg_dump or psql \copy against the database directly.

cmd/server/          app entrypoint, route wiring, embedded static assets/policy
db/migrations/       goose migrations (applied at startup)
db/queries/          sqlc query sources
internal/
  auth/              providers + session user middleware
  authz/             OPA engine + RequirePolicy middleware
  config/            env config loader/validation
  obs/               tracing, metrics, security event logging
  locale/            i18n bundle + language middleware
modules/
  about/
  dashboard/
  compliance/
  measures/
  activities/
  risk/
  admin/
  auth/
cmd/server/policies/authz.rego  source-of-truth authorization policy
templates/layout/    shared templ layout/components

Modules under modules/* implement the module.Module contract and are composed via Registry in cmd/server/main.go. Module-specific dependencies are passed to each module's constructor; the shared Dependencies struct is kept deliberately minimal. See internal/modregistry for the contract.

Handler design. Handlers are intentionally "fat" and query the database directly via sqlc. There is no service layer, no DTOs, and no per-module interfaces — these solve problems this stack does not have. Split a handler only when concerns are genuinely mixed or logic is duplicated.

Generated code is not edited by hand. **/*_templ.go (templ), the sqlc-generated Go, and cmd/server/public/css/output.css (Tailwind) are all produced by make generate. Change the source (.templ, db/queries/*.sql, or the Tailwind input) and regenerate — never edit the output.

The full set of conventions lives in AGENTS.md; contributor-facing highlights are summarised in CONTRIBUTING.md.

cmd/server/policies/authz.rego is the single source of truth for authorization and is embedded into the server binary by cmd/server/main.go.

Handlers must never role-check directly; all authorization goes through authz.RequirePolicy(engine, resource, action).

Tracing is enabled when OTEL_EXPORTER_OTLP_ENDPOINT is set.

We welcome bug reports, feature suggestions, and pull requests. See CONTRIBUTING.md for the development process and AGENTS.md for guidance on using AI coding agents on this codebase.

For security vulnerabilities, please follow the disclosure process in SECURITY.md rather than opening a public issue.

Please do.

Apache License 2.0 — see LICENSE.

Vigil is open-sourced for the common good under the Apache License 2.0 and is developed and supplied outside the course of any commercial activity. No paid support, hosting, consulting, warranties, or maintenance commitments are offered. Use at your own risk.