docs: rewrite evaluate_trails_with_opa tutorial to fix false-positive…#220
Merged
Merged
Conversation
… compliance footgun
The previous tutorial used `allow if { count(violations) == 0 }` throughout.
This pattern silently grants compliance when the violations rule body fails to
fire -- for example when the attestation key is wrong. The kosli-public/cli
flow names its pull-request attestation "pr", not "pull-request". Under the
old policy, those trails were shown as ALLOWED not because PRs had approvers,
but because the violations rule never matched and the empty set vacuously
passed. The tutorial was demonstrating the exact footgun it should have warned
against.
Rewrites all policies to drive `allow` through positive assertions (`every`)
rather than absence of violations. Parameterises the attestation name via
--params so the policy works across orgs with different naming conventions.
Explains the three design rules (fail-safe default, positive assertion,
violations as diagnostics only) and adds a missing-param fail-safe test.
Also fixes a Rego v1 strict-mode compile error: unused iteration variable
replaced with `_`.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
mbevc1
approved these changes
May 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
… compliance footgun
The previous tutorial used
allow if { count(violations) == 0 }throughout. This pattern silently grants compliance when the violations rule body fails to fire -- for example when the attestation key is wrong. The kosli-public/cli flow names its pull-request attestation "pr", not "pull-request". Under the old policy, those trails were shown as ALLOWED not because PRs had approvers, but because the violations rule never matched and the empty set vacuously passed. The tutorial was demonstrating the exact footgun it should have warned against.Rewrites all policies to drive
allowthrough positive assertions (every) rather than absence of violations. Parameterises the attestation name via --params so the policy works across orgs with different naming conventions. Explains the three design rules (fail-safe default, positive assertion, violations as diagnostics only) and adds a missing-param fail-safe test. Also fixes a Rego v1 strict-mode compile error: unused iteration variable replaced with_.