Wip/update concepts

docs.kosli.com/assets/_markdown.scss

@@ -24,6 +24,15 @@
     margin-top: 1.5em;
     margin-bottom: $padding-16;
 
+    // If a heading starts with an image (e.g., an icon), size it like text
+    > img:first-child {
+      height: 1em;
+      width: auto;
+      vertical-align: -0.15em; // make baseline align nicely
+      margin-bottom: 0em;
+      box-shadow: none;
+    }
+
     a.anchor {
       opacity: 0;
       font-size: 0.75em;

docs.kosli.com/content/understand_kosli/concepts.md

@@ -8,54 +8,86 @@ summary: "This section helps you understand the concepts Kosli is built on. The
 
 This section helps you understand the concepts Kosli is built on. The figure below gives an overview of the main Kosli concepts and how they are related to each other.
 
-{{<figure src="/images/kosli_concepts.png" alt="Kosli Concepts" width="900">}}
+{{<figure src="/images/kosli-concepts.jpg" alt="Kosli Concepts" width="900">}}
 
 ## Organization
 
 A Kosli organization is an account that owns Kosli resources, such as Flows and Environments. Only members within an organization can access its resources.
 
 When signing up for Kosli, a personal organization is automatically created for you, bearing your username. This personal organization is exclusively accessible to you. Additionally, you can create `Shared` organizations and invite multiple team members to collaborate on different Flows and Environments.
 
-## Flow
+## ![icon](/images/diagram-elements/kosli-icon-round-flows.png) Flow
 
 A Kosli Flow represents a business or software process for which you want to track changes and monitor compliance.
 
-### Trail
+As an example, a flow can be created to track the controls involved with building an application in your CI system.
 
-A Kosli Trail represents a single execution instance of a process represented by a Kosli Flow.
+### ![icon](/images/diagram-elements/kosli-icon-round-trails.png) Trail
+
+A Kosli Trail represents a single execution instance of a Kosli Flow.
 Each Trail must have a unique identifier of your choice, based on your process and domain. Example identifiers include git commits or pull request numbers.
-
-#### Artifact
 
-Kosli Artifacts represent the software artifacts generated from every execution, portrayed as a Trail, of your software process depicted as a Flow. These artifacts play a crucial role in enabling **Binary Provenance**, providing a comprehensive chain of custody that records the origin, history and distribution of each artifact.
+**Examples:**
+
+* A CI run [example](https://app.kosli.com/cyber-dojo/flows/differ-ci/trails/98b393fa758558ceb90653a2cfb53ba3bd7898ee)
+* A terraform workflow [example](https://app.kosli.com/cyber-dojo/flows/terraform-base-infra-prs/trails/PR-11)
+* A cron job [in CI pipeline](https://github.com/cyber-dojo/live-snyk-scans/blob/2f0c74e65761b8d51271bb28de61db85b391d4f0/.github/workflows/snyk_scan_aws_prod.yml#L9) | [in Kosli](https://app.kosli.com/cyber-dojo/flows/aws-snyk-scan/trails/)
+
+### ![icon](/images/diagram-elements/kosli-icon-round-artifact-green.png) Artifact
+
+Kosli Artifacts represents the software artifacts generated from your CI pipeline.
+Its creation is captured in Kosli through the trail.
+
+When captured by Kosli, the Artifact is uniquely identified by its SHA256 fingerprint. Using this fingerprint, Kosli can link the creation of the Artifact with its runtime-related events, such as when the artifact starts or concludes execution within a specific Environment.
 
-Each Artifact is uniquely identified by its SHA256 fingerprint. Using this fingerprint, Kosli can link the creation of the Artifact with its runtime-related events, such as when the artifact starts or concludes execution within a specific Environment.
+These artifacts play a crucial role in enabling **Binary Provenance**, providing a comprehensive chain of custody that records the origin, history and distribution of each artifact.
 
-#### Attestation
+**Examples:**
+
+* Artifact attestation as part of the CLI flow [example](https://app.kosli.com/kosli-public/flows/cli/trails/6781399)
+
+### ![icon](/images/diagram-elements/kosli-icon-round-attestations-2.png) Attestation
 
 An Attestation is a record of compliance checks or controls that have been performed a particular Artifact or Trail. It is normally reported after performing a specific risk control or quality check (e.g. running tests). The attestation encompasses the procedure's results.
 
-Kosli provides specific built-in types of attestations (e.g., a snyk scan, sonar scan, junit tests) and allows to define your own custom types. 
+Kosli provides specific built-in types of attestations (e.g., a snyk scan, sonar scan, junit tests) and allows to define your own custom types with jq quering for compliance status, or generic ones that simply creates an attestation without evaluation.
+
+Attestations can be connected either to the trail, or to a specific artifact.
+
+**Examples:**
+
+* This build [in CI pipeline](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli+attest+artifact) | [in Kosli](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli+attest+artifact)
+* This test execution [in CI pipeline](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli+attest+junit) | [in Kosli](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli+attest+junit)
+* This security scan [in CI pipeline](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli+attest+snyk) | [in Kosli](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli+attest+snyk)
+* This deployment approved [in CI pipeline](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli+report+approval)
+* This pull request [in CI pipeline](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli+attest+pullrequest+github) | [in Kosli](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli+attest+pullrequest+github)
 
-##### Evidence Vault
+### ![icon](/images/diagram-elements/kosli-icon-round-vault.png) Evidence Vault
 
 Attestations in Kosli have the capability to contain additional evidence files attached to them. This supporting evidence is securely stored within Kosli's evidence vault and is retrievable on demand.
 
-## Audit package
+## ![icon](/images/diagram-elements/kosli-icon-round-package.png) Audit package
 
 During an audit process, Kosli enables you to download an audit package for a Trail, Artifact, or an individual Attestation. This package comprises a tar file containing metadata related to the selected resource, alongside any evidence files that have been attached. The audit package serves as a comprehensive collection of information aiding in audit-related investigations or reviews.
 
 ## Flow Template
 
-A Flow Template defines the expected attestations for Flow Trails and Artifacts to be considered compliant. While each Flow has its own Template, each Trail in a Flow can override the Flow Template with its own.
+A Flow Template defines the expected Artifacts and attestations for Trails of that given Flow to be considered compliant.
 
-## Environment
+While each Flow has its own Template, each Trail in a Flow can override the Flow Template with its own.
+
+**Examples:**
+
+* Template for our CLI flow [example](https://app.kosli.com/kosli-public/flows/cli/settings/)
+
+## ![icon](/images/diagram-elements/kosli-icon-round-environment.png) Environment
 
 Environments in Kosli monitor changes in your software runtime systems.
 
 Each physical or virtual runtime environment you want to track in Kosli should have its own Kosli Environment created. Kosli allows you to portray your environments precisely. For instance, with a Kubernetes cluster, you can treat it as one Kosli Environment or designate one or more namespaces in the cluster as separate Kosli Environments.
 
 Kosli supports various types of runtime environments:
+
 * Kubernetes cluster (K8S)
 * Amazon ECS
 * Amazon S3
@@ -64,15 +96,31 @@ Kosli supports various types of runtime environments:
 * Docker host
 * Azure Web Apps and Function Apps
 
-### Environment Snapshot
+**Examples:**
+
+* How this k8s cluster changes [example](https://app.kosli.com/cyber-dojo/environments/aws-prod/events/)
+* How this lambda changes [example](https://app.kosli.com/kosli-public/environments/bitbucket-lambda-example-env/snapshots/)
 
-An Environment Snapshot represents the reported status (running Artifacts) of your runtime environment at a specific point in time. Snapshots are immutable, append-only objects. Once a snapshot is created, it cannot be modified.
+### ![icon](/images/diagram-elements/kosli-icon-round-snapshots.png) Environment Snapshot
+
+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.
 
-Running artifacts that come from 3rd party sources, can be `allow-listed` in an Environment to make them compliant. 
+Running artifacts that come from 3rd party sources, can be `allow-listed` in an Environment to make them compliant.
+
+**Examples:**
+
+* The running artifacts in a AWS ECS namespace [example](https://app.kosli.com/cyber-dojo/environments/aws-prod/snapshots/)
+* The running pods in a k8s cluster
+* The terraform state files in an S3 bucket
+* The functions in AWS Lambda
+* The files in a directory
+
+### ![icon](/images/diagram-elements/kosli-icon-round-policy.png) Environment Policy
 
+Environment Policy enables you to define and enforce compliance requirements for artifact deployments across different environments.
 
-### Environment Policy
+**Examples:**
 
-Environment Policy enables you to define and enforce compliance requirements for artifact deployments across different environments.
+* A policy making sure that all artifacts have the required tests associated with them [example](https://app.kosli.com/kosli-public/policies/all-test-cases-present)

go.mod

@@ -110,7 +110,7 @@ require (
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
-	github.com/go-viper/mapstructure/v2 v2.3.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang-jwt/jwt/v4 v4.5.2 // indirect

go.sum

@@ -264,8 +264,8 @@ github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg78
 github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572/go.mod h1:9Pwr4B2jHnOSGXyyzV8ROjYa2ojvAY6HCGYYfMoC3Ls=
 github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
 github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
-github.com/go-viper/mapstructure/v2 v2.3.0 h1:27XbWsHIqhbdR5TIC911OfYvgSaW93HM+dX7970Q7jk=
-github.com/go-viper/mapstructure/v2 v2.3.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
+github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
 github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM=
 github.com/gobwas/pool v0.2.1/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6WezmKEw=
 github.com/gobwas/ws v1.2.1/go.mod h1:hRKAFb8wOxFROYNsT1bqfWnhX+b5MFeJM9r2ZSwg/KY=