kosli_assert_artifact.md

title	kosli assert artifact
description	Assert the compliance status of an artifact in Kosli. There are three ways to choose what to assert against: 1. Against an environment. When `--environment` is specified, asserts against all poli...

Synopsis

kosli assert artifact [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags]

Assert the compliance status of an artifact in Kosli. There are three ways to choose what to assert against:

1. Against an environment. When --environment is specified, asserts against all policies currently attached to the given environment.
2. Against one or more policies. When --policy is specified, asserts against all the given policies.
3. Against flow templates. When neither --environment nor --policy is specified, asserts against the template files of the flows the artifact is found in.

--environment and --policy are mutually exclusive.

--flow can be combined with any of the above to narrow the lookup to a specific flow. Without --flow, all flows containing the artifact (by fingerprint) are considered.

Exits with zero code if the artifact has compliant status, non-zero code if non-compliant status.

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
-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).
-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.
--environment	string	The Kosli environment name to assert the artifact against.
-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.
-F, --fingerprint	string	[conditional] The SHA256 fingerprint of the artifact. Only required if you don't specify '--artifact-type'.
-f, --flow	string	The Kosli flow name.
-h, --help	bool	help for artifact
-o, --output	string	[defaulted] The format of the output. Valid formats are: [table, json]. (default "table")
--policy	strings	[optional] policy name (can be specified multiple times)
--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.

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.

Live Examples in different CI systems

View an example of the `kosli assert artifact` command in GitHub.

In [this YAML file](https://github.com/cyber-dojo/differ/blob/06dc33ad1a46960bd685d00be993098a74a6dca0/.github/workflows/main.yml#L274)
</Tab>
<Tab title="GitLab">
View an example of the `kosli assert artifact` command in GitLab.

In [this YAML file](https://gitlab.com/cyber-dojo/creator/-/blob/42876c4da26ee74e4bbfe14c2949cc7cb2d3345e/.gitlab/workflows/main.yml#L158)
</Tab>

Examples Use Cases

These examples all assume that the flags --api-token, --org, --host, (and --flow, --trail when required), are set/provided.

```shell kosli assert artifact --fingerprint 184c799cd551dd1d8d5c5f9a5d593b2e931f5e36122ee5c793c1d08a19839cc0 --environment prod

</Accordion>
<Accordion title="assert that an artifact meets a set of policies">
```shell
kosli assert artifact 
	--fingerprint 184c799cd551dd1d8d5c5f9a5d593b2e931f5e36122ee5c793c1d08a19839cc0 
	--policy has-approval,has-been-integration-tested 

```shell export KOSLI_FLOW=yourFlowName kosli assert artifact --fingerprint 184c799cd551dd1d8d5c5f9a5d593b2e931f5e36122ee5c793c1d08a19839cc0

</Accordion>
<Accordion title="fail if an artifact has a non-compliant status in any flow (using the artifact name and type)">
```shell
unset KOSLI_FLOW
kosli assert artifact library/nginx:1.21 
	--artifact-type docker