Webhook icon
Schedule icon
WorkingDirectory icon
Commands icon
Docker icon
Script icon
If icon
SlackIncomingWebhook icon
Log icon

Audit Gatekeeper Policy Exceptions Before an Expired Waiver Bypasses Admission

Audit Gatekeeper constraint exceptions for expired and soon expiring waivers, then alert Slack with the expired list and their owners.

Categories
Infrastructure

How it works

  1. exception_registry_webhook (io.kestra.plugin.core.trigger.Webhook, keyed with GATEKEEPER_WEBHOOK_KEY) runs an audit on demand, for example right after a waiver is granted or before an external review. weekly_ttl_audit (io.kestra.plugin.core.trigger.Schedule, cron 0 5 * * 1) is the standing cadence and ships with disabled: true until an operator switches it on.
  2. registry_workspace (io.kestra.plugin.core.flow.WorkingDirectory) gives the export step and the parser one shared directory, a scratch directory outside a WorkingDirectory is purged between tasks and would break the file hand-off.
  3. export_exceptions (io.kestra.plugin.scripts.shell.Commands on the io.kestra.plugin.scripts.runner.docker.Docker runner, image bitnami/kubectl:latest) first writes a bundled snapshot of the ConstraintException registry with a heredoc, then runs kubectl get constraintexceptions -A -o json > registry-snapshot.json || true. When no apiserver or kubeconfig is reachable from the worker the redirect comes up empty and the snapshot is copied in, so the audit behaves the same offline and online.
  4. audit_exceptions (io.kestra.plugin.scripts.python.Script on python:3.12-slim) ages every waiver against audit_date, flags anything already past spec.expires as expired, counts waivers due within warning_window_days, and treats a waiver with no expiry date as expired, it can never age out on its own. An unreadable snapshot becomes SCAN_ERROR instead of a silent pass.
  5. gate_on_expiry (io.kestra.plugin.core.flow.If) branches when verdict is anything but PASS. Over that line alert_expired_exceptions (io.kestra.plugin.slack.notifications.SlackIncomingWebhook) posts the expired list with namespaces, dates, and owners plus the soon expiring count; a clean registry records log_compliant.
  6. The errors block alerts Slack when the container or the parser itself breaks, because a dead auditor looks exactly like a clean registry.

What you get

  • Gateable numbers, verdict, expired_list, expired_count, soon_count, total_exceptions, and snapshot_uri are flow outputs any downstream policy check can branch on.
  • A Slack alert that names each expired waiver, its namespace, its expiry date, and the owner who signed it off, so follow-up lands on a person instead of a list.
  • A warning horizon, soon_count reports waivers about to lapse inside warning_window_days, which is the window a renewal decision can still be made in.
  • Evidence, every execution keeps the exported registry snapshot in internal storage next to the verdict.

Who it's for

  • Kubernetes platform teams that run OPA Gatekeeper with an internal waiver or exception process on top of it.
  • Security and compliance engineers who must show that expired exceptions were found before the review, not after the finding.
  • Cluster operators who inherit waivers nobody owns anymore and need the expiry dates pulled out of YAML into a channel people read.

Why orchestrate this with Kestra

A waiver list lives in a custom resource or a Git file and its dates pass quietly, nobody is paged by an exception that quietly keeps bypassing a policy. Kestra gives the audit a disabled-by-default weekly schedule, a keyed webhook for on-demand runs, a containerized kubectl export with a bundled offline fallback, an explicit aging policy in code, and a branch that turns expired waivers into a named Slack alert, all in one versioned file whose execution history doubles as evidence.

Prerequisites

  • A worker with Docker access, the export runs in the kubectl container and the parser in python:3.12-slim.
  • A cluster and kubeconfig (or service account) allowed to get constraintexceptions for a live export. Without one the flow still completes on the bundled snapshot, which is what makes it safe to run in CI or on a laptop.
  • A Slack incoming webhook for the expiry alert and for the failure alert.

Secrets

  • GATEKEEPER_WEBHOOK_KEY: key segment guarding the webhook URL, anyone holding it can start an audit.
  • SLACK_WEBHOOK_URL: Slack incoming webhook URL used by the expiry alert and by the errors block.

Quick start

  1. Add the two secrets to the Kestra namespace.
  2. Run the flow once with the default inputs. The audit ages the bundled snapshot against today's UTC date, the two waivers dated in the past and the carry-over waiver with no expiry date at all land in expired_list, so expect verdict: FAIL and a Slack message naming each one.
  3. Pin audit_date to an ISO date before a review to reproduce the exact verdict that date produced, and raise or lower warning_window_days to see soon_count react.
  4. Point your ops tooling at /api/v1/{tenant}/executions/webhook/{namespace}/gatekeeper-policy-exception-ttl-audit/{GATEKEEPER_WEBHOOK_KEY} to run an audit right after a waiver is granted.
  5. Enable weekly_ttl_audit once the worker has a kubeconfig with permission to read the exception registry.

How to extend

  • Rename the resource in the kubectl export step when your platform uses its own waiver CRD instead of constraintexceptions.
  • Fan out over a fleet of clusters with io.kestra.plugin.core.flow.Loop, one export and one audit per cluster alias, then merge the expired lists before alerting.
  • Open a GitHub issue per owner with io.kestra.plugin.github.issues.Create inside gate_on_expiry so every expired waiver becomes tracked work.
  • Feed expired_list into a warehouse table with a JDBC query task to trend waiver aging across review cycles.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.