diff --git a/docs.kosli.com/content/getting_started/environments.md b/docs.kosli.com/content/getting_started/environments.md index 8e52fc738..6f3114b02 100644 --- a/docs.kosli.com/content/getting_started/environments.md +++ b/docs.kosli.com/content/getting_started/environments.md @@ -74,6 +74,22 @@ Depending on the type of your environment, you can scope what to snapshot from t | azure (functions and apps) | √ | | | | | +## Environment Compliance + +An environment's compliance status is determined by its attached policies. The compliance state can be: + +* **Compliant** - All artifacts in the snapshot satisfy the requirements defined in attached policies +* **Non-compliant** - One or more artifacts violate the requirements defined in attached policies +* **Unknown** - No policies are attached to the environment, compliance requirements are undefined + +When you create a new environment, it starts with an **unknown** compliance state since no policies are attached +by default. To establish compliance requirements, you need to attach at least one policy to the environment +(see [Environment Policies](/getting_started/policies)) + +**Note:** If you detach all policies from an environment, its compliance state returns to **unknown** since there are +no longer any defined requirements for artifacts running in it. + + ## Logical Environments Logical environments are a way to group your Kosli environments so you can view all changes happening in your group in the same place. For example, if what you consider to be “Production” is a combination of a Kubernetes cluster, an S3 bucket, and a configuration file, you can combine the reports sent to these Kosli environments into a “Production” logical environment. diff --git a/docs.kosli.com/content/getting_started/policies.md b/docs.kosli.com/content/getting_started/policies.md index 7a1639690..a990e2369 100644 --- a/docs.kosli.com/content/getting_started/policies.md +++ b/docs.kosli.com/content/getting_started/policies.md @@ -7,17 +7,20 @@ summary: "Environment Policies enable you to define and enforce compliance requi # Part 9: Environment Policies -Environment Policies enable you to define and enforce compliance requirements for artifact deployments across different environments. With Environment Policies, you can: +Environment Policies enable you to define and enforce compliance requirements for artifact deployments across +different environments. With Environment Policies, you can: - Define specific requirements for each environment (e.g, dev, staging, prod) - Enforce consistent compliance standards across your deployment pipeline - Prevent non-compliant artifacts from being deployed (via admission controllers) -Policies are written in YAML and are immutable (updating a policy creates a new version). They can be attached to one or more environments, and an environment can have one or more policies attached to it. +Policies are written in YAML and are immutable (updating a policy creates a new version). They can be attached to +one or more environments, and an environment can have one or more policies attached to it. ## Create a Policy -You can create a policy via CLI or via the API. Here is a basic policy that requires provenance and specific attestations: +You can create a policy via CLI or via the API. Here is a basic policy that requires provenance and specific +attestations: ```yaml {.command} # prod-policy.yaml @@ -137,7 +140,9 @@ artifacts #### Policy Expressions -Policy expressions allow you to create conditional rules using a simple and powerful syntax. Expressions are wrapped in `${{ }}` and can be used in policy rules to create dynamic conditions. An expression consists of operands and operators: +Policy expressions allow you to create conditional rules using a simple and powerful syntax. Expressions are wrapped +in `${{ }}` and can be used in policy rules to create dynamic conditions. An expression consists of operands +and operators: **Operators** @@ -169,7 +174,8 @@ Contexts are built-in objects which are accessible from an expression. Expressio **Functions** -Functions are helpers that can be used when constructing conditions. They may or may not accept arguments. Arguments can be literals or context variables. Expressions can use following functions: +Functions are helpers that can be used when constructing conditions. They may or may not accept arguments. Arguments +can be literals or context variables. Expressions can use following functions: - `exists(arg)` : checks whether the value of arg is not None/Null - `matches(input, regex)` : checks if input matches regex @@ -202,17 +208,23 @@ To detach a policy from an environment: kosli detach-policy prod-requirements --environment=aws-production ``` -Any attachment/detachment operation automatically triggers an evaluation of the latest environment snapshot and creates a new one with an updated compliance status. +Any attachment/detachment operation automatically triggers an evaluation of the latest environment snapshot and +creates a new one with an updated compliance status. {{% hint info %}} -If you detach all attached policies from an environment, the environment will have no defined requirements for artifacts running in it, and therefore, new environment snapshots will have status `unknown` +If you detach all attached policies from an environment, the environment compliance state will become **unknown** +since there are no longer any defined requirements for artifacts running in it. The environment will continue to +track snapshots, but its compliance cannot be evaluated without policies. {{% /hint %}} + ## Policy Enforcement Gates -Environment policies enable you to proactively block deploying a non-compliant artifact into an environment. This can be done as a deployment gate in your delivery pipeline or as an admission controller in your environment. +Environment policies enable you to proactively block deploying a non-compliant artifact into an environment. This +can be done as a deployment gate in your delivery pipeline or as an admission controller in your environment. -Regardless of where you place your policy enforcement gate, it will be using the `assert artifact` Kosli CLI command or its equivalent API call. +Regardless of where you place your policy enforcement gate, it will be using the `assert artifact` Kosli CLI command +or its equivalent API call. ```shell {.command} kosli assert artifact --fingerprint=$SHA256 --environment=aws-production diff --git a/docs.kosli.com/content/understand_kosli/concepts.md b/docs.kosli.com/content/understand_kosli/concepts.md index 2424940a5..4ef60b519 100644 --- a/docs.kosli.com/content/understand_kosli/concepts.md +++ b/docs.kosli.com/content/understand_kosli/concepts.md @@ -105,7 +105,10 @@ Kosli supports various types of runtime environments: An Environment Snapshot represents the reported status (running Artifacts) of your runtime environment at a specific point in time. -In each snapshot, Kosli links the running artifacts to the Flows and Trails that produced them. Snapshot compliance relies on the compliance status of each running artifact, while Environment compliance depends on its latest snapshot compliance. +In each snapshot, Kosli links the running artifacts to the Flows and Trails that produced them. Snapshot compliance +relies on the compliance status of each running artifact against the environment's attached policies. Environment +compliance depends on its latest snapshot compliance. Environments without attached policies have an **unknown** +compliance state. Running artifacts that come from 3rd party sources, can be `allow-listed` in an Environment to make them compliant.