---
name: Kosli
description: Use when building compliance automation for software delivery, tracking artifacts through CI/CD pipelines, enforcing policies on deployments, reporting runtime environments, or creating audit trails for security and compliance reviews.
metadata:
    mintlify-proj: kosli
    version: "1.0"
---

# Kosli Skill

## Product summary

Kosli is a compliance automation platform that acts as a "flight recorder" for your software delivery lifecycle. It consolidates evidence from CI/CD pipelines, runtime environments, and business processes into immutable audit trails, then evaluates them against compliance policies. Agents use the **Kosli CLI** (installed via `kosli` command) and **REST API** to report artifacts, attestations, environment snapshots, and policies. The primary documentation is at https://docs.kosli.com. Key files: flow templates (YAML), environment policies (YAML), CLI commands for flows/trails/artifacts/attestations/environments/policies.

## When to use

Reach for Kosli when:
- **Building compliance automation**: Automating evidence collection for SOC 2, ISO 27001, NIST frameworks instead of manual spreadsheets
- **Tracking artifact provenance**: Recording where artifacts came from, what controls they passed, and where they're running
- **Gating deployments**: Blocking non-compliant artifacts from production via CI/CD assertions or Kubernetes admission controllers
- **Reporting runtime state**: Capturing what's running in Kubernetes, ECS, Lambda, S3, Docker, or Azure environments and detecting drift
- **Investigating incidents**: Tracing a production issue back to the git commit, build, and controls that produced it
- **Creating audit packages**: Downloading immutable evidence files for auditors or internal investigations

## Quick reference

### Core CLI commands

| Task | Command |
|------|---------|
| Create a flow | `kosli create flow <flow-name> --template-file template.yml` |
| Begin a trail | `kosli begin trail <trail-id> --flow <flow-name>` |
| Report an artifact | `kosli attest artifact <image> --artifact-type docker --flow <flow> --trail <trail> --name <artifact-name>` |
| Attest test results | `kosli attest junit --name <artifact>.unit-tests --flow <flow> --trail <trail> --junit-results-file results.xml` |
| Attest security scan | `kosli attest snyk --artifact-type docker <image> --name <artifact>.security-scan --flow <flow> --trail <trail> --snyk-json-file report.json` |
| Create environment | `kosli create environment <env-name> --type kubernetes` |
| Snapshot environment | `kosli snapshot k8s --environment <env-name> --kubeconfig ~/.kube/config` |
| Create policy | `kosli create policy <policy-name> policy.yaml` |
| Attach policy | `kosli attach-policy <policy-name> --environment <env-name>` |
| Assert artifact compliance | `kosli assert artifact <image> --artifact-type oci --environment production` |
| Get artifact history | `kosli get artifact <fingerprint>` |
| List trails | `kosli list trails --flow <flow-name>` |

### Environment variables

Set these to avoid repeating flags:
- `KOSLI_API_TOKEN` — API key (from service account or personal account)
- `KOSLI_ORG` — Organization name
- `KOSLI_DRY_RUN` — Set to `true` to disable all writes (useful for testing or when Kosli is down)

### Artifact types

| Type | Use for | Example |
|------|---------|---------|
| `docker` | Local Docker images | `kosli attest artifact myapp:latest --artifact-type docker` |
| `oci` | Container images in registries | `kosli attest artifact registry.io/myapp:v1.0 --artifact-type oci` |
| `file` | Single files, binaries, JARs | `kosli attest artifact app.jar --artifact-type file` |
| `dir` | Directories, source code | `kosli attest artifact ./src --artifact-type dir` |

### Environment types

| Type | Supported scoping |
|------|-------------------|
| Kubernetes | All resources, by name, by regex, exclude by name/regex |
| Docker | All containers |
| ECS | All clusters, by name, by regex, exclude by name/regex |
| Lambda | All functions, by name, by regex, exclude by name/regex |
| S3 | All buckets (no scoping) |
| Azure | All apps/functions (no scoping) |
| Paths | Server directories |

## Decision guidance

### When to use Flow Templates vs. no template

| Scenario | Use template | Use empty template |
|----------|--------------|-------------------|
| You have compliance requirements (tests, scans, approvals must pass) | ✓ | |
| You want to gate deployments on missing attestations | ✓ | |
| You're just tracking changes without compliance rules | | ✓ |
| You want to enforce specific attestation types per artifact | ✓ | |

### When to assert against environment vs. policy vs. flow template

| Assertion type | Use when | Example |
|---|---|---|
| `--environment` | Checking all policies attached to a target environment | `kosli assert artifact $IMAGE --environment production` |
| `--policy` | Checking specific policies regardless of environment | `kosli assert artifact $IMAGE --policy has-tests,has-review` |
| No scope flag | Checking against the flow template that produced the artifact | `kosli assert artifact $IMAGE --flow my-flow` |

### When to use service account vs. personal API key

| Context | Use service account | Use personal key |
|---------|-------------------|------------------|
| CI/CD pipelines, automation | ✓ | |
| Local development, testing | | ✓ |
| Production deployments | ✓ | |
| Multiple organizations | | ✓ (but risky) |

## Workflow

### Typical flow: Build → Attest → Deploy → Enforce

1. **Create a flow** (once per process)
   - Write a flow template YAML defining required attestations
   - Run `kosli create flow my-flow --template-file template.yml`

2. **Begin a trail** (per execution, e.g., per commit)
   - Run `kosli begin trail <commit-sha> --flow my-flow` at the start of your CI job
   - Trail ID typically matches git commit, PR number, or ticket ID

3. **Report artifacts and attestations** (as they're produced)
   - Build artifact: `kosli attest artifact <image> --artifact-type docker --flow my-flow --trail <trail-id> --name backend`
   - Run tests: `kosli attest junit --name backend.unit-tests --flow my-flow --trail <trail-id> --junit-results-file results.xml`
   - Run security scan: `kosli attest snyk --artifact-type docker <image> --name backend.security-scan --flow my-flow --trail <trail-id> --snyk-json-file report.json`

4. **Assert compliance before deployment** (in CI/CD)
   - Run `kosli assert artifact <image> --artifact-type oci --environment production`
   - If non-compliant, the command exits with non-zero status and blocks the deployment

5. **Snapshot runtime environments** (periodically or on deployment)
   - Run `kosli snapshot k8s --environment prod --kubeconfig ~/.kube/config`
   - Kosli captures what's running and traces it back to the flow/trail that produced it

6. **Attach policies to environments** (once per environment)
   - Create policy YAML: `kosli create policy prod-policy policy.yaml`
   - Attach: `kosli attach-policy prod-policy --environment production`
   - Kosli evaluates snapshots against policies automatically

### Typical flow: Investigate an incident

1. Search for an artifact by commit SHA or fingerprint: `kosli search <sha>`
2. Get the artifact's full history: `kosli get artifact <fingerprint>`
3. Inspect the trail that produced it: `kosli get trail <trail-id> --flow <flow-name>`
4. Download the audit package: `kosli get trail <trail-id> --flow <flow-name> --output json | jq .audit_package_url`
5. Check environment snapshots to see where it ran: `kosli list snapshots <env-name>`
6. Diff snapshots to see what changed: `kosli diff snapshots <env-name>#10 <env-name>#11`

## Common gotchas

- **Attestation names must match template**: If your template expects `backend.unit-tests`, you must attest with `--name backend.unit-tests` (dot notation). Mismatched names cause compliance failures.
- **Fingerprints are immutable, tags are not**: Always identify artifacts by fingerprint, not by tag or name. A `latest` tag can point to different images over time; fingerprints never change.
- **Trail IDs must be unique within a flow**: Reusing the same trail ID overwrites the previous trail. Use git commit SHAs or PR numbers to ensure uniqueness.
- **Policies are immutable**: Updating a policy creates a new version. Old snapshots retain their evaluation against the old policy version.
- **Attestations are append-only**: You can report the same attestation multiple times; only the latest version is used for compliance evaluation.
- **Environment snapshots only trigger on change**: If you report the same artifacts twice, Kosli does not create a new snapshot. Only actual changes create new snapshots.
- **Dry-run mode always exits 0**: Use `--dry-run` to test commands without sending data, but remember it always succeeds even if the payload is invalid.
- **API token is not retrievable**: Once you create an API key, copy it immediately. Kosli only stores a hash; you cannot retrieve the original token later.
- **Service accounts are org-specific**: Service accounts exist only in shared organizations, not in personal accounts.
- **Attestation types must exist**: If you reference a custom attestation type in a template, it must be created first with `kosli create attestation-type`.
- **Environment type must match what you snapshot**: If you create a Kubernetes environment, you must snapshot with `kosli snapshot k8s`, not `kosli snapshot docker`.

## Verification checklist

Before submitting work with Kosli:

- [ ] Flow template YAML is valid (use `$schema` comment for editor validation)
- [ ] All attestation names in commands match the template (including dot notation for artifact-level attestations)
- [ ] Artifact fingerprints are calculated correctly (test with `--dry-run` first)
- [ ] Trail ID is unique within the flow (no overwrites)
- [ ] API token is set via `KOSLI_API_TOKEN` or `--api-token` flag
- [ ] Organization name is set via `KOSLI_ORG` or `--org` flag
- [ ] Environment type matches the snapshot command (e.g., `--type kubernetes` with `kosli snapshot k8s`)
- [ ] Policies are attached to environments before asserting compliance
- [ ] Assertions use the correct scope (`--environment`, `--policy`, or flow template)
- [ ] Test assertions with `--dry-run` before adding to CI/CD pipelines
- [ ] Audit packages can be downloaded for trails (for audit readiness)

## Resources

- **Comprehensive navigation**: https://docs.kosli.com/llms.txt — page-by-page listing of all documentation
- **Core concepts**: https://docs.kosli.com/understand_kosli/how_kosli_works — how flows, trails, artifacts, attestations, environments, and policies fit together
- **Getting started**: https://docs.kosli.com/getting_started/flows — step-by-step setup for flows, trails, artifacts, attestations, environments, and policies
- **CLI reference**: https://docs.kosli.com/client_reference — complete command reference with flags and examples
- **Flow template spec**: https://docs.kosli.com/template-reference/flow_template — YAML schema for defining compliance requirements
- **Environment policy spec**: https://docs.kosli.com/policy-reference/environment_policy — YAML schema for runtime compliance rules
- **API reference**: https://docs.kosli.com/api-reference — REST API endpoints for all operations

---

> For additional documentation and navigation, see: https://docs.kosli.com/llms.txt