docs: update CLI and helm reference for v2.52.0

client_reference/kosli_diff_snapshots.md

@@ -66,7 +66,7 @@ kosli diff snapshots aws-beta aws-prod --output=json
 ```json
 {
   "snappish1": {
-    "snapshot_id": "aws-beta#8810",
+    "snapshot_id": "aws-beta#8812",
     "artifacts": [
       {
         "fingerprint": "8446d65644ec150a1951d54b6d98d3b16f9601b3286453f9b71e9bc0f51a36db",
@@ -79,7 +79,7 @@ kosli diff snapshots aws-beta aws-prod --output=json
     ]
   },
   "snappish2": {
-    "snapshot_id": "aws-prod#5544",
+    "snapshot_id": "aws-prod#5547",
     "artifacts": [
       {
         "fingerprint": "e16d7a10b27f5946e0c4ab8914f0b9e421b626854592692c5db5592eaebc7203",

client_reference/kosli_evaluate_policy.md

@@ -0,0 +1,180 @@
+---
+title: "kosli evaluate policy"
+tag: "BETA"
+description: "Evaluate a policy against a trail in Kosli."
+---
+
+import CliBetaNotice from "/snippets/cli-beta-notice.mdx";
+
+<CliBetaNotice />
+
+## Synopsis
+
+```shell
+kosli evaluate policy [flags]
+```
+
+Evaluate a policy against a trail in Kosli.
+The policy is evaluated where the trail is stored, against the trail as Kosli
+recorded it, and the verdict is printed here.
+
+Name what to evaluate with `--context trail=`flow`/`trail``, repeated once per
+trail. Trails named in one command are all evaluated at the same instant.
+
+Name the policy with one of:
+  - `--identifier`: a rego policy published to Kosli. Its current version, the
+    highest-numbered valid one, is evaluated, and the evaluation cites that version.
+    Append `@v`n``, as in `pr-approved@v2`, to evaluate version n instead, which
+    must be valid; publishing a newer version does not change what it runs.
+  - `--path`: the policy's files on this machine, sent with the evaluation.
+
+`--path` takes a Rego file or a directory, and can be given more than once,
+so a policy and a shared library are sent together from wherever each is kept.
+Every `--path` joins one bundle. A file is keyed by its own name, and a file
+in a directory by its path relative to that directory. Files in dot-directories,
+such as `.git`, are left out; every other file travels, so notes such as
+`README.md` stay with the policy.
+
+Of what travels, the evaluator loads only:
+  - Rego modules: `*.rego`, other than tests (`*_test.rego`). Modules import
+    each other by package, so where each file sits does not matter.
+  - Data files: `data.json`, `data.yaml`, `data.yml`, `*.ergo.yaml` and
+    `*.ergo.yml`. Each is read into `data` at its directory's path in the
+    bundle, so `controls/x/data.yaml` becomes `data.controls.x`. A data file
+    cannot write `data.params`, which belongs to `--params`.
+Every other file is carried but not read.
+
+Two loaded files under one name are refused, naming both. For any other file the
+first `--path` given wins, and the copy left behind is named on stderr.
+
+The policy package is the one that declares `allow`; every other package is a
+library. Where several packages declare `allow`, annotate an entrypoint in exactly
+one of them to say which is the policy. In the policy package:
+  - `allow` is always evaluated, whether annotated or not. It must be a boolean
+    for every input, so give it a default (`default allow := false`): an undefined
+    `allow` fails the evaluation rather than denying.
+  - Every rule annotated with `# METADATA` and `# entrypoint: true` is evaluated
+    too, and returned under its rule name in `result.outputs`, such as
+    `violations` or `report`. A rule undefined for this input is left out.
+  - Every other rule is evaluated only as far as those rules need it.
+An entrypoint annotated outside the policy package, or on a function, is refused.
+
+Pass `--control` to record the outcome as a decision against that control, in the
+`--flow` and `--trail` given. The decision is recorded where the policy runs, so
+the verdict is never asserted from here. Without `--control` nothing is recorded.
+Only a published policy can record a decision, so `--control` needs `--identifier`.
+
+Use `--params` to pass values the policy reads as `data.params`. For a
+published policy, they must match the params schema of the version evaluated.
+Pass `--assert` to exit with a non-zero status when the policy denies.
+The policy that ran is printed with the verdict: a published policy by its
+identifier, version and digest, and an inline one by its digest.
+Use `--output json` to print the evaluation as Kosli returns it.
+
+## Flags
+| Flag | Type | Description |
+| :--- | :--- | :--- |
+| `--assert` | bool | [optional] Exit with a non-zero status when the policy denies. Without it the verdict is printed and the command exits 0. |
+| `--context` | stringArray | What to evaluate, as trail=`flow`/`trail`. Repeat it to evaluate several trails at one instant. |
+| `--control` | string | [optional] Record the outcome as a decision against this control. Only a published policy (`--identifier`) can record one. Without it nothing is recorded. |
+| `--fingerprint` | string | [optional] The SHA256 fingerprint of the artifact the decision is about. Without it the decision is about the trail. |
+| `-f`, `--flow` | string | [conditional] The Kosli flow the decision is recorded in. Only required with `--control`. |
+| `-h`, `--help` | bool | help for policy |
+| `--identifier` | string | Identifier of a rego policy published to Kosli. Its current version is evaluated, or version n given as `identifier`@v`n`. |
+| `--name` | string | [defaulted] The attestation name the decision is recorded under. Defaults to `control`-decision. |
+| `-o`, `--output` | string | [defaulted] The format of the output. Valid formats are: [table, json]. (default "table") |
+| `--params` | string | [optional] Policy parameters as inline JSON or @file.json. Available in policies as data.params. |
+| `-p`, `--path` | stringArray | Path of a Rego policy file, or of a directory sent as one bundle. Repeat it to send a policy with libraries kept elsewhere. |
+| `--policy` | stringArray | Deprecated alias of `--path`. (DEPRECATED: use `--path` instead) |
+| `--trail` | string | [conditional] The Kosli trail the decision is recorded in. Only required with `--control`. |
+
+
+## Flags inherited from parent commands
+| Flag | Type | Description |
+| :--- | :--- | :--- |
+| `-a`, `--api-token` | string | The Kosli API token. |
+| `-c`, `--config-file` | string | [optional] The Kosli config file path. Config is read from this path or the default only, never implicitly from the current directory. (default "$HOME/.kosli.yml") |
+| `--debug` | bool | [optional] Print debug logs to stdout. |
+| `-H`, `--host` | string | [defaulted] The Kosli endpoint. (default "https://app.kosli.com") |
+| `--http-proxy` | string | [optional] The HTTP proxy URL including protocol and port number. e.g. `http://proxy-server-ip:proxy-port` |
+| `-r`, `--max-api-retries` | int | [defaulted] How many times should API calls be retried when the API host is not reachable. (default 3) |
+| `--org` | string | The Kosli organization. |
+| `-q`, `--quiet` | bool | [optional] Suppress non-critical warning messages. Errors and normal output are not affected. If both `--quiet` and `--debug` are set, `--debug` wins. |
+
+
+## Examples Use Cases
+
+These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](/getting_started/install/#assigning-flags-via-environment-variables). 
+
+<AccordionGroup>
+<Accordion title="evaluate a policy against a trail">
+```shell
+kosli evaluate policy 
+	--context trail=yourFlowName/yourTrailName 
+	--path yourPolicyFile.rego 
+
+```
+</Accordion>
+<Accordion title="evaluate the current version of a published rego policy against a trail">
+```shell
+kosli evaluate policy 
+	--context trail=yourFlowName/yourTrailName 
+	--identifier yourPolicyIdentifier 
+
+```
+</Accordion>
+<Accordion title="evaluate version 2 of a published rego policy, whatever its current version">
+```shell
+kosli evaluate policy 
+	--context trail=yourFlowName/yourTrailName 
+	--identifier yourPolicyIdentifier@v2 
+
+```
+</Accordion>
+<Accordion title="evaluate a policy directory with a shared library kept elsewhere">
+```shell
+kosli evaluate policy 
+	--context trail=yourFlowName/yourTrailName 
+	--path yourPolicyDirectory 
+	--path path/to/ergo/ergo.rego 
+
+```
+</Accordion>
+<Accordion title="evaluate several trails at one instant">
+```shell
+kosli evaluate policy 
+	--context trail=yourFlowName/yourTrailName 
+	--context trail=anotherFlowName/anotherTrailName 
+	--path yourPolicyFile.rego 
+
+```
+</Accordion>
+<Accordion title="evaluate a policy with parameters (inline JSON or @file.json)">
+```shell
+kosli evaluate policy 
+	--context trail=yourFlowName/yourTrailName 
+	--path yourPolicyFile.rego 
+	--params '{"protected_branch": "master"}' 
+
+```
+</Accordion>
+<Accordion title="evaluate a published policy and record the outcome as a decision">
+```shell
+kosli evaluate policy 
+	--context trail=yourFlowName/yourTrailName 
+	--identifier yourPolicyIdentifier 
+	--control yourControlIdentifier 
+	--fingerprint yourArtifactFingerprint 
+
+```
+</Accordion>
+<Accordion title="evaluate a policy and fail the step when it denies">
+```shell
+kosli evaluate policy 
+	--context trail=yourFlowName/yourTrailName 
+	--path yourPolicyFile.rego 
+	--assert 
+```
+</Accordion>
+</AccordionGroup>
+

client_reference/kosli_evaluate_trail.md

@@ -35,6 +35,7 @@ and `--output-rule` to add other rules of the policy, like a report, to it.
 | `--output-rule` | strings | [optional] [experimental] Name of a policy rule to add to the JSON output, next to allow and violations. Can be repeated, or given as a comma-separated list. Subject to change. |
 | `--params` | string | [optional] Policy parameters as inline JSON or @file.json. Available in policies as data.params. |
 | `-p`, `--policy` | string | Path or http(s):// URL of a Rego policy to evaluate against the trail. |
+| `--server-side` | bool | [optional] Evaluate the policy on the Kosli server rather than on this machine. Cannot be combined with `--attestations`, `--show-input` or `--output-rule`. |
 | `--show-input` | bool | [optional] Include the policy input data in the output. |
 
 

client_reference/kosli_evaluate_trails.md

@@ -36,6 +36,7 @@ and `--output-rule` to add other rules of the policy, like a report, to it.
 | `--output-rule` | strings | [optional] [experimental] Name of a policy rule to add to the JSON output, next to allow and violations. Can be repeated, or given as a comma-separated list. Subject to change. |
 | `--params` | string | [optional] Policy parameters as inline JSON or @file.json. Available in policies as data.params. |
 | `-p`, `--policy` | string | Path or http(s):// URL of a Rego policy to evaluate against the trails. |
+| `--server-side` | bool | [optional] Evaluate the policy on the Kosli server rather than on this machine. Cannot be combined with `--attestations`, `--show-input` or `--output-rule`. |
 | `--show-input` | bool | [optional] Include the policy input data in the output. |
 
 

client_reference/kosli_get_environment.md

@@ -50,9 +50,9 @@ kosli get environment aws-prod --output=json
   "name": "aws-prod",
   "type": "ECS",
   "description": "The ECS cluster for production cyber-dojo",
-  "last_modified_at": 1793274898.4478223,
-  "last_reported_at": 1793274898.4478223,
-  "last_changed_at": 1793259778.583906,
+  "last_modified_at": 1793366398.6455796,
+  "last_reported_at": 1793366398.6455796,
+  "last_changed_at": 1793346418.5157776,
   "state": true,
   "include_scaling": false,
   "tags": {

client_reference/kosli_get_rego-policy.md

@@ -0,0 +1,86 @@
+---
+title: "kosli get rego-policy"
+tag: "BETA"
+description: "Get a rego policy, or one version of it."
+---
+
+import CliBetaNotice from "/snippets/cli-beta-notice.mdx";
+
+<CliBetaNotice />
+
+## Synopsis
+
+```shell
+kosli get rego-policy IDENTIFIER [flags]
+```
+
+Get a rego policy, or one version of it.
+Without `--policy-version`, the policy is shown with its newest version and its current
+version. The current version is the highest-numbered valid version, which is the
+one an evaluation runs, so it can be older than the newest version.
+
+With `--policy-version`, that version is shown with its status, its digest, who
+published it and when, and the reason when it is rejected or failed. The command
+exits 0 whatever the status of the version.
+
+With `--download` and `--policy-version`, the bundle of that version is written to the
+given file as a gzipped tar, unchanged and whatever the status of the version, in place
+of printing it. An existing file is not overwritten.
+
+## Flags
+| Flag | Type | Description |
+| :--- | :--- | :--- |
+| `--download` | string | [optional] The file to write the bundle of the version given by `--policy-version` to, as a gzipped tar. An existing file is not overwritten. |
+| `-h`, `--help` | bool | help for rego-policy |
+| `-o`, `--output` | string | [defaulted] The format of the output. Valid formats are: [table, json]. (default "table") |
+| `--policy-version` | int | [optional] The version of the rego policy to get. Without it, the policy and its current version are shown. |
+
+
+## Flags inherited from parent commands
+| Flag | Type | Description |
+| :--- | :--- | :--- |
+| `-a`, `--api-token` | string | The Kosli API token. |
+| `-c`, `--config-file` | string | [optional] The Kosli config file path. Config is read from this path or the default only, never implicitly from the current directory. (default "$HOME/.kosli.yml") |
+| `--debug` | bool | [optional] Print debug logs to stdout. |
+| `-H`, `--host` | string | [defaulted] The Kosli endpoint. (default "https://app.kosli.com") |
+| `--http-proxy` | string | [optional] The HTTP proxy URL including protocol and port number. e.g. `http://proxy-server-ip:proxy-port` |
+| `-r`, `--max-api-retries` | int | [defaulted] How many times should API calls be retried when the API host is not reachable. (default 3) |
+| `--org` | string | The Kosli organization. |
+| `-q`, `--quiet` | bool | [optional] Suppress non-critical warning messages. Errors and normal output are not affected. If both `--quiet` and `--debug` are set, `--debug` wins. |
+
+
+## Examples Use Cases
+
+These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](/getting_started/install/#assigning-flags-via-environment-variables). 
+
+<AccordionGroup>
+<Accordion title="get a rego policy and its current version">
+```shell
+kosli get rego-policy pr-approved 
+
+```
+</Accordion>
+<Accordion title="get version 3 of a rego policy">
+```shell
+kosli get rego-policy pr-approved 
+	--policy-version 3 
+
+```
+</Accordion>
+<Accordion title="download the bundle of version 3 of a rego policy to ./pr-approved-v3.tgz">
+```shell
+kosli get rego-policy pr-approved 
+	--policy-version 3 
+	--download ./pr-approved-v3.tgz 
+
+```
+</Accordion>
+<Accordion title="get version 3 of a rego policy as JSON">
+```shell
+kosli get rego-policy pr-approved 
+	--policy-version 3 
+	--output json 
+```
+</Accordion>
+</AccordionGroup>
+