From f7f523688655d776a55cc9330a557017b5b9218a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 17:21:04 +0000 Subject: [PATCH] docs: update CLI and helm reference for v2.56.0 --- client_reference/kosli_attest_artifact.md | 20 +- client_reference/kosli_attest_in-toto.md | 193 ++++++++++++++++++ client_reference/kosli_attest_sbom.md | 45 +++- .../kosli_dismiss_product-updates.md | 69 +++++++ client_reference/kosli_evaluate_input.md | 2 +- client_reference/kosli_fingerprint.md | 2 +- client_reference/kosli_get_environment.md | 4 +- client_reference/kosli_list_audit-logs.md | 97 +++++++++ client_reference/kosli_list_environments.md | 16 +- client_reference/kosli_list_flows.md | 8 +- .../kosli_list_product-updates.md | 65 ++++++ client_reference/kosli_list_snapshots.md | 2 +- client_reference/overview.md | 2 +- config/navigation.json | 9 + 14 files changed, 512 insertions(+), 22 deletions(-) create mode 100644 client_reference/kosli_attest_in-toto.md create mode 100644 client_reference/kosli_dismiss_product-updates.md create mode 100644 client_reference/kosli_list_audit-logs.md create mode 100644 client_reference/kosli_list_product-updates.md diff --git a/client_reference/kosli_attest_artifact.md b/client_reference/kosli_attest_artifact.md index 2067816f..cbed1209 100644 --- a/client_reference/kosli_attest_artifact.md +++ b/client_reference/kosli_attest_artifact.md @@ -6,7 +6,7 @@ description: "Attest an artifact creation to a Kosli flow. " ## Synopsis ```shell -kosli attest artifact {IMAGE-NAME | FILE-PATH | DIR-PATH} [flags] +kosli attest artifact {IMAGE-NAME | FILE-PATH | DIR-PATH} [-- BUILD-COMMAND...] [flags] ``` Attest an artifact creation to a Kosli flow. @@ -51,6 +51,14 @@ To record repository information, all three of `--repo-id`, `--repo-url`, and `- These are automatically set in GitHub Actions, GitLab CI, Bitbucket Pipelines, and Azure DevOps. In other CI systems, set them explicitly to capture repository metadata. +Running a build command is experimental (beta) and may change between releases without warning. +Everything after `--` runs as a build command, and the artifact is attested only if the build succeeds. +Its fingerprint is calculated after the build. The build command and its duration are recorded in the +`build_command` and `build_duration_seconds` annotations. Masking in `build_command` only covers the API token and the +values of environment variables whose names look secret (e.g. containing TOKEN, SECRET, PASS, KEY or AUTH); a secret +typed literally in the command is recorded as is, so use `--record-build-command=false` to leave out the command. +If the build fails, nothing is attested and Kosli exits with the build's exit code. + ## Flags | Flag | Type | Description | | :--- | :--- | :--- | @@ -68,6 +76,7 @@ In other CI systems, set them explicitly to capture repository metadata. | `-f`, `--flow` | string | The Kosli flow name. | | `-h`, `--help` | bool | help for artifact | | `-n`, `--name` | string | The name of the artifact in the yml template file. | +| `--record-build-command` | bool | [defaulted] [experimental] Record the build command given after -- in the build_command annotation, with secret values masked. Subject to change. (default true) | | `--redact-commit-info` | strings | [optional] The list of commit info to be redacted before sending to Kosli. Allowed values are one or more of [author, message, branch]. | | `--registry-password` | string | [conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper. | | `--registry-provider` | string | [deprecated] The docker registry provider or url. Only required if you want to read docker image SHA256 digest from a remote docker registry. (DEPRECATED: no longer used) | @@ -146,6 +155,15 @@ kosli attest artifact ANOTHER_FILE.txt --external-url label=https://example.com/attachment --external-fingerprint label=yourExternalAttachmentFingerprint --name yourTemplateArtifactName + +``` + + +```shell +kosli attest artifact dist/app + --artifact-type file + --name yourTemplateArtifactName + -- go build -o dist/app ./cmd/app ``` diff --git a/client_reference/kosli_attest_in-toto.md b/client_reference/kosli_attest_in-toto.md new file mode 100644 index 00000000..a2afd02e --- /dev/null +++ b/client_reference/kosli_attest_in-toto.md @@ -0,0 +1,193 @@ +--- +title: "kosli attest in-toto" +tag: "BETA" +description: "Record an in-toto attestation, such as SLSA provenance or an SBOM, that a build already produced. " +--- + +import CliBetaNotice from "/snippets/cli-beta-notice.mdx"; + + + +## Synopsis + +```shell +kosli attest in-toto [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags] +``` + +Record an in-toto attestation, such as SLSA provenance or an SBOM, that a build already produced. +Build systems produce in-toto attestations as they build: `actions/attest`, `cosign attest` +and `docker buildx --provenance --sbom` among them. This command records one in Kosli, +verifying its signature first, rather than regenerating the same evidence with other +`kosli attest` commands. + +`--predicate-type` chooses what to record, one kind per command: + +- `provenance` (SLSA provenance v1 or v0.2) reports the artifact named by `--name`, as + `kosli attest artifact` does. The commit, branch, repository and build URL come from the + statement, never from the CI environment, so the build's own commit and run are recorded + even when this command runs in a different job or workflow. +- `sbom` (SPDX or CycloneDX) reports an SBOM attestation named by `--name`, as + `kosli attest sbom` does, with the attestation attached in place of the SBOM file. + +Recording provenance and an SBOM takes two commands. + +The attestation is read from the file given with `--bundle`: a Sigstore bundle +(`.sigstore.json`), a DSSE envelope, an in-toto statement, or an `.intoto.jsonl` file with +one of these per line. Attestations of other kinds are ignored. When several qualify, a +verified one is preferred, then the newest. + +The statement must list the artifact as its subject. A signed attestation is verified with +Sigstore against a signer you pin: `--certificate-identity` (or +`--certificate-identity-regexp`) with `--certificate-oidc-issuer`, or `--key`. There is no +way to accept any valid certificate. An unsigned attestation is refused unless +`--allow-unsigned` is given, and is then recorded as unverified. An attestation that fails +verification, because another signer made it or it was changed after signing, fails the +command and nothing is recorded, even when another attestation in the file would qualify. So +does a signed attestation whose signature cannot be checked, such as when no signer is +pinned, a trust root cannot be fetched or the signer flags do not fit how it was signed; the +error then says it could not be verified, not that it failed. + +Verifying a certificate-signed attestation needs the trust root of the Sigstore instance +that signed it: Sigstore's public-good instance, or GitHub's own, which signs attestations +for private repositories. It is fetched over TUF on every run that verifies one, from +`https://tuf-repo-cdn.sigstore.dev` or `https://tuf-repo.github.com` respectively, and +cached under `~/.sigstore`, so the runner needs outbound HTTPS to that host and a writable +`~/.sigstore` directory. A key-signed attestation needs neither, unless it carries a +transparency log entry or a signed timestamp, which are checked against Sigstore's +public-good trust root. An unsigned attestation needs neither. + +The record is annotated with `verified` and, for a signed attestation, `signer_identity`, +`signer_issuer`, `log_index`, `integrated_time` and `signed_timestamp` where they apply. +Provenance adds `builder_id`, `build_type` and `workflow`, and an SBOM adds `sbom_format` +and `sbom_sha256`. A transparency log entry is linked as the `attestation` external URL, +pinned by the SHA-256 of the attestation's bytes. + +For provenance, the commit's message, author and time are looked up on GitHub with +`--github-token` when the statement names a GitHub repository, or else read from the git +checkout at `--repo-root` if it holds the commit. Failing both, only the commit's SHA is +recorded, without its details or branch. A repository on GitHub Enterprise Server needs +`--repo-provider github` and `--github-base-url` to be looked up there: the token is only +sent to the server you name, never to a host taken from the statement. A build URL or +commit URL the statement does not carry can be given with `--build-url` and `--commit-url`. + +The artifact fingerprint can be provided directly with the `--fingerprint` flag, or +calculated based on `--artifact-type` flag. + +Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container +images in registries or "docker" for local docker images. + +Note: `--artifact-type=docker` reads the image's repo digest via the local Docker daemon. +The image must have been pushed to or pulled from a registry for a repo digest to exist; +a freshly built image (just `docker build`) will not have one. If the image is already in +a registry, prefer `--artifact-type=oci`, which fetches the digest directly from the +registry without needing a local Docker daemon. + +For `--artifact-type=oci` (and for `--artifact-type=docker` when `--registry-username` +is set), registry credentials are resolved as follows: + 1) If `--registry-username` (and optionally `--registry-password`) is set, it is used directly. + 2) Otherwise, credentials are discovered automatically from: + - the Docker config file (`~/.docker/config.json`, populated by `docker login`) + - the Podman/containers auth file (`~/.config/containers/auth.json`, or `$REGISTRY_AUTH_FILE`) + - any Docker credential helper configured in that config (e.g. `docker-credential-ecr-login` + for AWS ECR, `docker-credential-gcloud` for GCR/Artifact Registry, an ACR helper for Azure, + or a local keychain helper), invoked as an external binary on `$PATH` + - if none of the above yield credentials, the registry is accessed anonymously, which works + for public images + `--registry-provider` is deprecated and no longer used. + +To specify paths in a directory artifact that should always be excluded from the SHA256 calculation, you can add a `.kosli_ignore` file to the root of the artifact. +Each line should specify a relative path or path glob to be ignored. You can include comments in this file, using `#`. +The `.kosli_ignore` file is always treated as part of the artifact: its own entries cannot exclude it, so the exclusion list cannot be changed without changing the fingerprint. +Paths the list already matches stay excluded whatever is later added there, so keep its entries as narrow as possible. +Excluding the file with `--exclude` keeps it out of the fingerprint but still applies the paths it lists, which lets a writable directory change the list again. +To drop the file from the fingerprint safely, move its entries to `--exclude` and delete it. + +## Flags +| Flag | Type | Description | +| :--- | :--- | :--- | +| `--allow-unsigned` | bool | [optional] Record an unsigned attestation, marked as unverified. Without it, an unsigned attestation is refused. | +| `--annotate` | stringToString | [optional] Annotate the attestation with data using key=value. | +| `-t`, `--artifact-type` | string | The type of the artifact to calculate its SHA256 fingerprint. One of: [oci, docker, file, dir]. Only required if you want Kosli to calculate the fingerprint for you (i.e. when you don't specify '`--fingerprint`' on commands that allow it). | +| `--build-url` | string | [optional] The build URL to record when the provenance does not say. Provenance only. | +| `--bundle` | string | [conditional] The file holding the attestation, with `--source` bundle: a Sigstore bundle (.sigstore.json), a DSSE envelope, an in-toto statement, or an .intoto.jsonl file with one of these per line. | +| `--certificate-identity` | string | [conditional] The identity a signed attestation's certificate must name, such as a GitHub workflow URL. Use with `--certificate-oidc-issuer`. | +| `--certificate-identity-regexp` | string | [conditional] A regular expression the identity in a signed attestation's certificate must match. Use instead of `--certificate-identity`, with `--certificate-oidc-issuer`. | +| `--certificate-oidc-issuer` | string | [conditional] The OIDC issuer a signed attestation's certificate must name, such as https://token.actions.githubusercontent.com. | +| `--commit-url` | string | [optional] The commit URL to record when the provenance does not say. Provenance only. | +| `-D`, `--dry-run` | bool | [optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. | +| `-x`, `--exclude` | strings | [optional] The comma separated list of directories and files to exclude from fingerprinting. Can take glob patterns. Only applicable for `--artifact-type` dir. | +| `--external-fingerprint` | stringToString | [optional] A SHA256 fingerprint of an external attachment represented by `--external-url`. The format is label=fingerprint (labels cannot contain '.' or '='). This flag can be set multiple times. There must be an external url with a matching label for each external fingerprint. | +| `--external-url` | stringToString | [optional] Add labeled reference URL for an external resource. The format is label=url (labels cannot contain '.' or '='). This flag can be set multiple times. If the resource is a file or dir, you can optionally add its fingerprint via `--external-fingerprint` | +| `-F`, `--fingerprint` | string | [conditional] The SHA256 fingerprint of the artifact to attach the attestation to. Only required if the attestation is for an artifact and `--artifact-type` and artifact name/path are not used. | +| `-f`, `--flow` | string | The Kosli flow name. | +| `--github-base-url` | string | [optional] The GitHub Enterprise Server to look the commit up on, such as https://github.example.com, when the provenance names a repository there. Without it the commit is looked up on github.com, never at a host taken from the provenance. | +| `--github-token` | string | [optional] A GitHub token, to look up the commit's message, author and time when the provenance names a GitHub repository. | +| `-h`, `--help` | bool | help for in-toto | +| `--key` | string | [conditional] The path to a PEM public key, to verify an attestation signed with a key rather than a certificate. | +| `-n`, `--name` | string | The name of the record as declared in the flow or trail yaml template: the artifact's name for provenance, the attestation's name for sbom. | +| `--predicate-type` | string | The kind of attestation to record: provenance (SLSA provenance v1 or v0.2) or sbom (SPDX or CycloneDX). | +| `--registry-password` | string | [conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper. | +| `--registry-provider` | string | [deprecated] The docker registry provider or url. Only required if you want to read docker image SHA256 digest from a remote docker registry. (DEPRECATED: no longer used) | +| `--registry-username` | string | [conditional] The container registry username. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper. | +| `--repo-provider` | string | [optional] The provider of the repository the provenance names, when its host is not github.com, gitlab.com or bitbucket.org. One of: github, gitlab, bitbucket, bitbucket_cloud, bitbucket_dc, azure-devops, azure_devops_services, azure_devops_server, git, subversion. For a GitHub Enterprise host, also give `--github-base-url` to look the commit up there. | +| `--repo-root` | string | [defaulted] The git checkout to read the commit's details from when they cannot be looked up. Provenance only. (default ".") | +| `--source` | string | [defaulted] Where to read the attestation from. Only 'bundle' is supported for now: the file given with `--bundle`. (default "bundle") | +| `-T`, `--trail` | string | The Kosli trail name. | + + +## 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). + + + +```shell +kosli attest in-toto app.tar.gz + --artifact-type file + --bundle app.sigstore.json + --predicate-type provenance + --name app + --certificate-identity https://github.com/yourOrg/yourRepo/.github/workflows/build.yml@refs/heads/main + --certificate-oidc-issuer https://token.actions.githubusercontent.com + --github-token yourGithubToken + +``` + + +```shell +kosli attest in-toto app.tar.gz + --artifact-type file + --bundle app-sbom.sigstore.json + --predicate-type sbom + --name app.sbom + --certificate-identity-regexp '^https://github.com/yourOrg/yourRepo/' + --certificate-oidc-issuer https://token.actions.githubusercontent.com + +``` + + +```shell +kosli attest in-toto yourImageName + --artifact-type docker + --bundle provenance.json + --predicate-type provenance + --name app + --allow-unsigned + --build-url https://ci.example.com/builds/123 +``` + + + diff --git a/client_reference/kosli_attest_sbom.md b/client_reference/kosli_attest_sbom.md index 096d79eb..21973f86 100644 --- a/client_reference/kosli_attest_sbom.md +++ b/client_reference/kosli_attest_sbom.md @@ -19,8 +19,32 @@ not compressed, and a gzipped file is rejected, because the format and the summary below are read from it. Kosli reads the format, the creation time, the tools that produced it, the -subject it describes and how many packages it lists. Nothing is checked against -the artifact; the SBOM is recorded as reported. +subject it describes and how many packages it lists. A plain SBOM file is not +checked against the artifact; it is recorded as reported. + +The SBOM may also arrive inside an in-toto attestation, as a Sigstore bundle or +a DSSE envelope. The SPDX or CycloneDX document is then read from it, and the +bundle or envelope is what is uploaded and checksummed. When the artifact's +fingerprint is known, because it is calculated from the artifact or given with +`--fingerprint`, the attestation must list that artifact as its subject, signed +or not. When the attestation is bound by the artifact's template name and commit +instead, or to the trail alone, there is no fingerprint to check the subject +against, so it is not checked. To verify its signature, pass +`--certificate-identity` (or `--certificate-identity-regexp`) with +`--certificate-oidc-issuer`, or `--key`. Without them the signature is not +checked, and even a signed bundle is recorded with `verified` set to false. The +record is annotated with `verified` and the verification details, as +`kosli attest in-toto` annotates it. To pick the SBOM from a file holding +several attestations, or to record provenance, use `kosli attest in-toto`. + +Verifying a certificate-signed attestation needs the trust root of the Sigstore instance +that signed it: Sigstore's public-good instance, or GitHub's own, which signs attestations +for private repositories. It is fetched over TUF on every run that verifies one, from +`https://tuf-repo-cdn.sigstore.dev` or `https://tuf-repo.github.com` respectively, and +cached under `~/.sigstore`, so the runner needs outbound HTTPS to that host and a writable +`~/.sigstore` directory. A key-signed attestation needs neither, unless it carries a +transparency log entry or a signed timestamp, which are checked against Sigstore's +public-good trust root. An unsigned attestation needs neither. The SBOM file is the only attachment: this command does not accept additional attachments, because two or more would be compressed together. @@ -57,6 +81,9 @@ In other CI systems, set them explicitly to capture repository metadata. | :--- | :--- | :--- | | `--annotate` | stringToString | [optional] Annotate the attestation with data using key=value. | | `-t`, `--artifact-type` | string | The type of the artifact to calculate its SHA256 fingerprint. One of: [oci, docker, file, dir]. Only required if you want Kosli to calculate the fingerprint for you (i.e. when you don't specify '`--fingerprint`' on commands that allow it). | +| `--certificate-identity` | string | [conditional] The identity a signed attestation's certificate must name, such as a GitHub workflow URL. Use with `--certificate-oidc-issuer`. | +| `--certificate-identity-regexp` | string | [conditional] A regular expression the identity in a signed attestation's certificate must match. Use instead of `--certificate-identity`, with `--certificate-oidc-issuer`. | +| `--certificate-oidc-issuer` | string | [conditional] The OIDC issuer a signed attestation's certificate must name, such as https://token.actions.githubusercontent.com. | | `-g`, `--commit` | string | [conditional] The git commit for which the attestation is associated to. Becomes required when reporting an attestation for an artifact before reporting it to Kosli. (defaulted in some CIs: [docs](/integrations/ci_cd) ). If both `--commit` and `--repo-root` are left at their defaults and the commit cannot be read from the repository, a warning is printed and the attestation is sent without commit info. | | `--description` | string | [optional] attestation description | | `-D`, `--dry-run` | bool | [optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. | @@ -66,6 +93,7 @@ In other CI systems, set them explicitly to capture repository metadata. | `-F`, `--fingerprint` | string | [conditional] The SHA256 fingerprint of the artifact to attach the attestation to. Only required if the attestation is for an artifact and `--artifact-type` and artifact name/path are not used. | | `-f`, `--flow` | string | The Kosli flow name. | | `-h`, `--help` | bool | help for sbom | +| `--key` | string | [conditional] The path to a PEM public key, to verify an attestation signed with a key rather than a certificate. | | `-n`, `--name` | string | The name of the attestation as declared in the flow or trail yaml template. | | `-o`, `--origin-url` | string | [optional] The url pointing to where the attestation came from or is related. (defaulted to the CI url in some CIs: [docs](/integrations/ci_cd/#defaulted-kosli-command-flags-from-ci-variables) ). | | `--redact-commit-info` | strings | [optional] The list of commit info to be redacted before sending to Kosli. Allowed values are one or more of [author, message, branch]. | @@ -77,7 +105,7 @@ In other CI systems, set them explicitly to capture repository metadata. | `--repo-root` | string | [defaulted] The directory where the source git repository is available. It must be the repository's top-level directory. Only used if `--commit` is used or defaulted in CI, see [docs](/integrations/ci_cd/#defaulted-kosli-command-flags-from-ci-variables) . (default ".") | | `--repo-url` | string | [conditional] The URL of the repository. Must be a valid URL. All three of `--repo-id`, `--repo-url` and `--repository` must be set to record repository information (defaulted in some CIs: [docs](/integrations/ci_cd) ). | | `--repository` | string | [conditional] The name of the repository (e.g. owner/repo-name). All three of `--repo-id`, `--repo-url` and `--repository` must be set to record repository information (defaulted in some CIs: [docs](/integrations/ci_cd) ). | -| `--sbom-file` | string | The path to the SBOM file. CycloneDX (JSON, XML) and SPDX (JSON, tag-value) are supported. | +| `--sbom-file` | string | The path to the SBOM file. CycloneDX (JSON, XML) and SPDX (JSON, tag-value) are supported, also inside an in-toto attestation in a Sigstore bundle or DSSE envelope. | | `-T`, `--trail` | string | The Kosli trail name. | | `-u`, `--user-data` | string | [optional] The path to a JSON file containing additional data you would like to attach to the attestation. The maximum JSON payload size is 1MB. | @@ -107,6 +135,17 @@ kosli attest sbom yourDockerImageName --name yourAttestationName --sbom-file yourSbomPath +``` + + +```shell +kosli attest sbom yourDockerImageName + --artifact-type docker + --name yourAttestationName + --sbom-file yourSbom.sigstore.json + --certificate-identity https://github.com/yourOrg/yourRepo/.github/workflows/build.yml@refs/heads/main + --certificate-oidc-issuer https://token.actions.githubusercontent.com + ``` diff --git a/client_reference/kosli_dismiss_product-updates.md b/client_reference/kosli_dismiss_product-updates.md new file mode 100644 index 00000000..49043967 --- /dev/null +++ b/client_reference/kosli_dismiss_product-updates.md @@ -0,0 +1,69 @@ +--- +title: "kosli dismiss product-updates" +tag: "BETA" +description: "Dismiss Kosli product updates, marking them as seen." +--- + +import CliBetaNotice from "/snippets/cli-beta-notice.mdx"; + + + +## Synopsis + +```shell +kosli dismiss product-updates {PRODUCT-UPDATE-ID [PRODUCT-UPDATE-ID...] | --all} [flags] +``` + +Dismiss Kosli product updates, marking them as seen. +A dismissed product update is no longer unread for you. Give the ids of the updates to +dismiss, as listed by `kosli list product-updates`, or use `--all` to dismiss every unread update. +An id of an update the org cannot see is ignored. + +Product updates are tracked per user, so the API token must belong to a member of the org. + +## Flags +| Flag | Type | Description | +| :--- | :--- | :--- | +| `--all` | bool | [optional] Dismiss every unread product update, instead of giving their ids. | +| `-D`, `--dry-run` | bool | [optional] Run in dry-run mode. When enabled, no data is sent to Kosli and the CLI exits with 0 exit code regardless of any errors. | +| `-h`, `--help` | bool | help for product-updates | + + +## 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). + + + +```shell +kosli dismiss product-updates yourProductUpdateID + +``` + + +```shell +kosli dismiss product-updates yourProductUpdateID1 yourProductUpdateID2 + +``` + + +```shell +kosli dismiss product-updates + --all +``` + + + diff --git a/client_reference/kosli_evaluate_input.md b/client_reference/kosli_evaluate_input.md index 9beb7615..91865ba4 100644 --- a/client_reference/kosli_evaluate_input.md +++ b/client_reference/kosli_evaluate_input.md @@ -66,7 +66,7 @@ This accepts inline JSON or a file reference (`@file.json`). View an example of the `kosli evaluate input` command in GitHub. - In [this YAML file](https://github.com/cyber-dojo/snyk-scanning/blob/359c98460f5c3aefb136a77eef08d1be4c4ca08d/tests/test_rego_rules.sh#L392) + In [this YAML file](https://github.com/cyber-dojo/snyk-scanning/blob/7ec3715a952611112bb259ed92b6986335183ff3/tests/test_rego_rules.sh#L392) diff --git a/client_reference/kosli_fingerprint.md b/client_reference/kosli_fingerprint.md index 5485f2af..7d7bbd7c 100644 --- a/client_reference/kosli_fingerprint.md +++ b/client_reference/kosli_fingerprint.md @@ -82,7 +82,7 @@ To drop the file from the fingerprint safely, move its entries to `--exclude` an View an example of the `kosli fingerprint` command in GitHub. - In [this YAML file](https://github.com/cyber-dojo/snyk-scanning/blob/359c98460f5c3aefb136a77eef08d1be4c4ca08d/.github/workflows/artifact_snyk_test.yml#L189) + In [this YAML file](https://github.com/cyber-dojo/snyk-scanning/blob/7ec3715a952611112bb259ed92b6986335183ff3/.github/workflows/artifact_snyk_test.yml#L189) diff --git a/client_reference/kosli_get_environment.md b/client_reference/kosli_get_environment.md index 796f8bc8..b3570a47 100644 --- a/client_reference/kosli_get_environment.md +++ b/client_reference/kosli_get_environment.md @@ -50,8 +50,8 @@ kosli get environment aws-prod --output=json "name": "aws-prod", "type": "ECS", "description": "The ECS cluster for production cyber-dojo", - "last_modified_at": 1794418138.4235198, - "last_reported_at": 1794418138.4235198, + "last_modified_at": 1794503998.5373878, + "last_reported_at": 1794503998.5373878, "last_changed_at": 1794385498.3975194, "state": true, "include_scaling": false, diff --git a/client_reference/kosli_list_audit-logs.md b/client_reference/kosli_list_audit-logs.md new file mode 100644 index 00000000..a9bc21a4 --- /dev/null +++ b/client_reference/kosli_list_audit-logs.md @@ -0,0 +1,97 @@ +--- +title: "kosli list audit-logs" +description: "List audit log events for an org." +--- + +## Synopsis + +```shell +kosli list audit-logs [flags] +``` + +List audit log events for an org. +Each event records a change to an org member's role: a member being added, changing role, or being removed. +Listing the audit log requires org admin rights. +The list can be filtered by user, event type, role and source. When multiple filters are provided, only events matching all of them are returned. +The results are paginated and ordered from latest to oldest by default; use --page and --page-limit to navigate the pages. + +## Flags +| Flag | Type | Description | +| :--- | :--- | :--- | +| `--event-type` | string | [optional] Only list events of this type. Valid values are: [added, changed, removed]. | +| `-h`, `--help` | bool | help for audit-logs | +| `-o`, `--output` | string | [defaulted] The format of the output. Valid formats are: [table, json]. (default "table") | +| `--page` | int | [defaulted] The page number of a response. (default 1) | +| `-n`, `--page-limit` | int | [defaulted] The number of elements per page. (default 15) | +| `--role` | stringArray | [optional] Only list events that set this role. Can be repeated to match more than one role. | +| `--search` | string | [optional] Only list events where the affected user's or the acting user's name contains this substring (case-insensitive). | +| `--sort-by` | string | [optional] The column to sort events by. Valid values are: [when, user, role, changed_by, source]. (defaults to when) | +| `--sort-direction` | string | [optional] The direction to sort events in. Valid values are: [asc, desc]. (defaults to desc) | +| `--source` | stringArray | [optional] Only list events from this source (e.g. app, scim, invitation, script). Can be repeated to match more than one source. | + + +## 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). + + + +```shell +kosli list audit-logs + +``` + + +```shell +kosli list audit-logs + --page 2 + --page-limit 30 + +``` + + +```shell +kosli list audit-logs + --output json + +``` + + +```shell +kosli list audit-logs + --search alice + --event-type changed + +``` + + +```shell +kosli list audit-logs + --role admin + --role member + --source scim + +``` + + +```shell +kosli list audit-logs + --sort-by user + --sort-direction asc +``` + + + diff --git a/client_reference/kosli_list_environments.md b/client_reference/kosli_list_environments.md index a62967ed..80038cce 100644 --- a/client_reference/kosli_list_environments.md +++ b/client_reference/kosli_list_environments.md @@ -63,8 +63,8 @@ kosli list environments --output=json "name": "aws-beta", "type": "ECS", "description": "The ECS cluster for staging cyber-dojo", - "last_modified_at": 1794418103.8945718, - "last_reported_at": 1794418103.8945718, + "last_modified_at": 1794503970.7270164, + "last_reported_at": 1794503970.7270164, "last_changed_at": 1794385463.898712, "state": true, "include_scaling": false, @@ -86,8 +86,8 @@ kosli list environments --output=json "name": "aws-beta-terraform-drift-detection", "type": "server", "description": "Detection of drift of the Infrastructure-as-code components of aws-beta", - "last_modified_at": 1794417921.873653, - "last_reported_at": 1794417921.873653, + "last_modified_at": 1794504008.9524217, + "last_reported_at": 1794504008.9524217, "last_changed_at": 1793959508.8404896, "state": true, "include_scaling": false, @@ -104,8 +104,8 @@ kosli list environments --output=json "name": "aws-prod", "type": "ECS", "description": "The ECS cluster for production cyber-dojo", - "last_modified_at": 1794418138.4235198, - "last_reported_at": 1794418138.4235198, + "last_modified_at": 1794503998.5373878, + "last_reported_at": 1794503998.5373878, "last_changed_at": 1794385498.3975194, "state": true, "include_scaling": false, @@ -128,8 +128,8 @@ kosli list environments --output=json "name": "aws-prod-terraform-drift-detection", "type": "server", "description": "Detection of drift of the Infrastructure-as-code components of aws-prod", - "last_modified_at": 1794418112.3435712, - "last_reported_at": 1794418112.3435712, + "last_modified_at": 1794503912.3053038, + "last_reported_at": 1794503912.3053038, "last_changed_at": 1794044312.1617863, "state": true, "include_scaling": false, diff --git a/client_reference/kosli_list_flows.md b/client_reference/kosli_list_flows.md index 9143dcec..b2be3b86 100644 --- a/client_reference/kosli_list_flows.md +++ b/client_reference/kosli_list_flows.md @@ -63,7 +63,7 @@ kosli list flows --output=json "template": "version: 1\ntrail:\n attestations:\n - name: drift-detection\n type: decision\n", "repo_url": "", "tags": {}, - "latest_activity_at": 1794407471.9028635, + "latest_activity_at": 1794497037.5656662, "latest_state": "COMPLIANT" }, { @@ -75,7 +75,7 @@ kosli list flows --output=json "template": "version: 1\ntrail:\n attestations:\n - name: drift-detection\n type: decision\n", "repo_url": "", "tags": {}, - "latest_activity_at": 1794407467.1631155, + "latest_activity_at": 1794497030.4831336, "latest_state": "COMPLIANT" }, { @@ -273,8 +273,8 @@ kosli list flows --output=json "kind": "run", "repo_url": "https://github.com/cyber-dojo/secrets" }, - "latest_activity_at": 1794389759.5778072, - "latest_state": "NON-COMPLIANT" + "latest_activity_at": 1794477428.4107573, + "latest_state": "INCOMPLETE" }, { "id": "a43239d6-fa3d-4e58-b7c4-f00b7432", diff --git a/client_reference/kosli_list_product-updates.md b/client_reference/kosli_list_product-updates.md new file mode 100644 index 00000000..0bd5fe11 --- /dev/null +++ b/client_reference/kosli_list_product-updates.md @@ -0,0 +1,65 @@ +--- +title: "kosli list product-updates" +tag: "BETA" +description: "List Kosli product updates." +--- + +import CliBetaNotice from "/snippets/cli-beta-notice.mdx"; + + + +## Synopsis + +```shell +kosli list product-updates [flags] +``` + +List Kosli product updates. +Product updates are the new features and improvements published in Kosli's changelog. +Unread updates are listed first, then the newest. An update about a feature that is not +enabled for the org is left out. The first time you list them, in the CLI or in the Kosli app, +every update is marked as seen, so none is shown as unread; only updates published after that +start as unread. Dismiss those with `kosli dismiss product-updates`. +The update's summary is included in the JSON output. + +Product updates are tracked per user, so the API token must belong to a member of the org. + +## Flags +| Flag | Type | Description | +| :--- | :--- | :--- | +| `-h`, `--help` | bool | help for product-updates | +| `-o`, `--output` | string | [defaulted] The format of the output. Valid formats are: [table, json]. (default "table") | + + +## 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). + + + +```shell +kosli list product-updates + +``` + + +```shell +kosli list product-updates + --output json +``` + + + diff --git a/client_reference/kosli_list_snapshots.md b/client_reference/kosli_list_snapshots.md index 2154f583..b7a287ed 100644 --- a/client_reference/kosli_list_snapshots.md +++ b/client_reference/kosli_list_snapshots.md @@ -68,7 +68,7 @@ kosli list snapshots aws-prod --output=json "from": 1794385498.3975194, "to": 0.0, "compliant": true, - "duration": 32666.80686354637 + "duration": 118525.4910376072 }, { "index": 5587, diff --git a/client_reference/overview.md b/client_reference/overview.md index 7a7fde04..74a1cf7e 100644 --- a/client_reference/overview.md +++ b/client_reference/overview.md @@ -4,7 +4,7 @@ description: "Reference documentation for the Kosli CLI." --- - This reference was generated from Kosli CLI **v2.55.5**. + This reference was generated from Kosli CLI **v2.56.0**. The Kosli CLI allows you to interact with Kosli from your terminal and CI/CD pipelines. diff --git a/config/navigation.json b/config/navigation.json index dc5ea937..39c23d58 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -309,6 +309,7 @@ "client_reference/kosli_attest_custom", "client_reference/kosli_attest_decision", "client_reference/kosli_attest_generic", + "client_reference/kosli_attest_in-toto", "client_reference/kosli_attest_jira", "client_reference/kosli_attest_junit", "client_reference/kosli_attest_pullrequest_azure", @@ -358,6 +359,12 @@ "client_reference/kosli_enable_beta" ] }, + { + "group": "kosli dismiss", + "pages": [ + "client_reference/kosli_dismiss_product-updates" + ] + }, { "group": "kosli evaluate", "pages": [ @@ -399,10 +406,12 @@ "client_reference/kosli_list_api-keys", "client_reference/kosli_list_artifacts", "client_reference/kosli_list_attestation-types", + "client_reference/kosli_list_audit-logs", "client_reference/kosli_list_controls", "client_reference/kosli_list_environments", "client_reference/kosli_list_flows", "client_reference/kosli_list_policies", + "client_reference/kosli_list_product-updates", "client_reference/kosli_list_rego-policies", "client_reference/kosli_list_repos", "client_reference/kosli_list_service-accounts",