docs: add working with controls tutorial#154
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
…se, and dark controls paragraph
|
Was this released yet? I cannot see this in Kosli 🤔 |
No this is a proposed feature. We are making this documentation ahead of development to facilitate discussions and get early feedback before we build it. |
|
Okay, I assume we're not releasing this to docs yet then? I think it might confuse our customers. |
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…policy/v1 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…identifier Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Update the working-with-controls tutorial to match what is actually built in the server and cli repos, replacing proposal-era guesses: - Mark the feature as beta (available) rather than in development. - Remove the non-existent `kosli create control` / `kosli list controls` CLI commands; document the New control form (identifier, name, description, links, tags) and the controls API instead. - Drop the unbuilt Active/Stale/No-decisions status table. - Fix `--compliant=true` (boolean flag) and add `--no-assert` to the `kosli evaluate` examples, which assert on deny by default. - Replace the imaginary top-level `controls:` policy key with the real `attestations:` rules using `type: decision` and `for_control:`. - Replace Decisions/Deployments/Coverage tabs with the real Decisions/Versions tabs and correct the decisions table columns. - Fix broken /reference/controls link. - Swap proposal mockups for real staging screenshots; add a decision detail screenshot; remove the now-orphaned coverage/deployments images. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Correct details surfaced by the controls project handovers, and switch to US spelling throughout: - Tags are not a create-time field — they are added later from the control detail page and do not version the control; note admin-only writes. - Clarify the validation asymmetry: recording a decision does not require the control to exist, but a policy referencing an unknown control identifier is rejected. - Note that multiple decisions can be recorded for a control on a trail and the most recent is used for enforcement. - Match the decision detail description to the shipped UI: evaluation result and params live in user-data; the Rego policy is the attached evidence file. - State that the feature is rolled out per organization (beta). - organisation -> organization, judgement -> judgment. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Claude finished @pbeckham's task in 2m 45s —— View job Review: docs: add working with controls tutorial
SummaryThe tutorial is well-structured and thorough after its many rounds of review. It covers the full controls lifecycle (create → decide → assert → review) with clear CLI examples, a useful Mermaid sequence diagram, and real staging screenshots. No critical issues found. FindingsCriticalNone. Compliance checks (all pass)
Improvement (2)
Suggestion (2)
Overall assessmentThe tutorial is in good shape for a beta feature. Content is accurate against the shipped implementation, the PDP/PEP separation is clearly explained, and the evidence-attachment workflow with |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…xist Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
| kosli evaluate trail "$TRAIL_NAME" \ | ||
| --policy supply-chain-policy.rego \ | ||
| --flow "$FLOW_NAME" \ | ||
| --no-assert \ | ||
| --output json > eval-report.json |
There was a problem hiding this comment.
Improvement: The --no-assert flag used here is not listed in the kosli evaluate trail CLI reference — that page documents --attestations, --flow, --output, --params, --policy, and --show-input, but no --no-assert. A reader following this example who checks the reference will find no matching flag.
Since the beta callout at the top already sets expectations for undocumented CLI behavior, this isn't blocking — but worth noting for when the reference pages are regenerated.
| --output json > eval-report.json | ||
|
|
||
| # Read the allow/deny result from the report | ||
| is_compliant=$(jq -r '.allow' eval-report.json) |
There was a problem hiding this comment.
Suggestion: The jq -r '.allow' extraction assumes the --output json format from kosli evaluate trail includes a top-level allow field. The evaluate trails with OPA tutorial shows a different JSON output structure (result, violations). If the beta version of kosli evaluate has a different output shape than the GA version, a brief comment or note clarifying the expected JSON structure would help readers who cross-reference the two tutorials.
| From here you can: | ||
|
|
||
| - Learn more about [controls](/understand_kosli/controls) | ||
| - Learn more about [environment policies](/getting_started/policies) | ||
| - Learn more about [attestations](/getting_started/attestations) | ||
| - [Evaluate trails with Rego policies](/tutorials/evaluate_trails_with_opa) to automate decision-making |
There was a problem hiding this comment.
Suggestion (minor): Other tutorials in this site use <CardGroup> / <Card> components for "next steps" navigation (e.g., the Labs landing page). Replacing this bullet list with cards would give the reader visual targets and be consistent with the rest of the site — though this is polish, not critical.
5 participants
Summary
tutorials/working_with_controls.mdx— a tutorial covering how to define controls in Kosli, record decisions against them withkosli attest decision, require controls in environment policies viafor_control, enforce them withkosli assert artifact --environment, and review a control's decisions and version history.config/navigation.jsonto include the new page under a new "Controls" group in the Tutorials section.Aligned with the shipped implementation
POST /api/v2/controls/{org}) — there is nokosli create control/kosli list controlsCLI.attestations:rules withtype: decisionandfor_control:(not a top-levelcontrols:key).kosli evaluateexamples use--no-assert(it asserts on deny by default);--compliantis shown as a boolean flag (--compliant=true).Closes kosli-dev/server#5355