Lab 5: Runtime Controls

Create environments, snapshot what’s running in production, and enforce compliance policies.

Prerequisites: Complete Lab 4: Release Controls before starting this lab.

Learning goals

• Understand Kosli Environments and how they track runtime state
• Create a Kosli Environment representing your deployment target
• Snapshot a Docker environment to report what’s running
• Create and configure compliance Policies
• Attach Policies to Environments for enforcement
• Integrate environment snapshotting into your CI/CD pipeline

Introduction

Kosli Environments allow you to track what’s actually running in your runtime environments (dev, staging, production). By taking regular snapshots, Kosli creates an immutable record of:

• What artifacts are running, identified by their SHA256 digest
• When they started and stopped
• Whether they comply with your policies
• The complete change history over time

Policies define compliance requirements for environments — rules like “all artifacts must have provenance”, “all artifacts must have passed unit tests”, or “all artifacts must have an SBOM”.

Together, Environments and Policies give you runtime visibility and enforcement for your software supply chain.

Environment types

Kosli supports several environment types:

Type	Tracks
docker	Docker containers on a host
k8s	Kubernetes pods in namespaces
ecs	AWS ECS tasks
lambda	AWS Lambda functions
s3	Files in S3 buckets
server	Files on a server filesystem

See Environments for more.

Exercise

1. Create an environment

   Your application deploys as a Docker container, so create a docker type environment:

   kosli create environment labs-prod \
     --type docker \
     --description "Production environment for labs application"
   
   # Verify it was created
   kosli get environment labs-prod
   

   Visit app.kosli.com → Environments and you should see labs-prod listed (with no snapshots yet).

   See kosli create environment for full flag reference.

2. Explore an existing environment

   To see a real-world example, navigate to the Cyber-Dojo AWS Beta environment.

   Here you can see a history of snapshots taken from a production AWS environment. Each snapshot shows:

   • Running artifacts: Container images currently running
   • Compliance status: Whether they meet policy requirements
   • Events: What started or stopped since the last snapshot
   • Duration: How long the application has been running

   Each snapshot is immutable. If nothing changed since the last snapshot, Kosli won’t create a new one — only real changes produce new snapshots.

3. Integrate snapshotting into CI

   In .github/workflows/full-pipeline.yaml, add this step to the Deploy job after the “Deploy to production” step:

       - name: Snapshot environment
         run: kosli snapshot docker labs-prod
   

   This captures what’s running immediately after deployment.

4. Create a compliance policy

   Create .kosli-policy.yml in the root of your repository:

   _schema: https://kosli.com/schemas/policy/environment/v1
   
   artifacts:
     provenance:
       required: true  # All artifacts must be part of a Flow
   
     attestations:
       - name: unit-tests
         type: junit
       - name: sbom
         type: "*"  # Any attestation type
   

   This policy requires:

   1. All running artifacts must have been attested to Kosli (provenance)
   2. All artifacts must have JUnit test results
   3. All artifacts must have an SBOM

   Then create the policy in Kosli:

   kosli create policy labs-prod-requirements .kosli-policy.yml
   
   # View it
   kosli get policy labs-prod-requirements
   

   See kosli create policy and Policies for more details.

5. Attach the policy to your environment

   kosli attach-policy labs-prod-requirements --environment labs-prod
   
   # Verify attachment
   kosli get environment labs-prod
   

   Attaching a policy automatically triggers a new snapshot evaluation. Kosli immediately checks if currently running artifacts meet the requirements.

   See kosli attach-policy for full flag reference.

6. Add policy management to CI

   In the Deploy job, add these steps before the “Assert compliance” step:

       - name: Update policy
         run: kosli create policy labs-prod-requirements .kosli-policy.yml
       - name: Attach policy to environment
         run: kosli attach-policy labs-prod-requirements --environment labs-prod
   
7. Push and verify

   git add .kosli-policy.yml .github/workflows/full-pipeline.yaml
   git commit -m "Add Kosli environment and policy management"
   git push origin main
   

   Watch the workflow execute. After it completes, in app.kosli.com:

   • Navigate to Environments → labs-prod → latest snapshot
   • Check the compliance status — it should be Compliant, since you’ve been attesting unit tests and SBOM since Lab 3
   • Click on the running artifact to see which attestations are present

   If your artifact is non-compliant

   • Verify the attestation names in your workflow match the names in .kosli-policy.yml exactly
   • Check that all attestation steps completed successfully in the previous workflow run
   • Confirm the artifact fingerprint matches what was attested

Optional: policy enforcement gate

You can also use policies as deployment gates, preventing non-compliant artifacts from deploying:

# Assert against specific policies before deployment
kosli assert artifact ghcr.io/${IMAGE}:latest \
  --policy labs-prod-requirements

If the artifact is non-compliant, this command exits with a non-zero status, failing the deployment step.

See kosli assert artifact for more details.

Optional: policy expressions

Policies support conditional logic for sophisticated compliance rules:

artifacts:
  attestations:
    # Only require security scans for production flow
    - if: ${{ flow.name == "production" }}
      name: security-scan
      type: snyk

    # Exceptions for specific artifacts
    - name: unit-tests
      type: junit
      exceptions:
        - if: ${{ artifact.name == "legacy-component" }}

See Policy expressions for more.

Verification checklist

• labs-prod environment of type docker created
• Explored the Cyber-Dojo environment in Kosli
• .kosli-policy.yml created with compliance requirements
• Policy created in Kosli and attached to the environment
• Workflow updated with policy update and snapshot steps
• Workflow runs successfully
• Environment snapshots visible in Kosli
• Running artifact shows as Compliant

Congratulations!

You’ve completed all five Kosli Learning Labs. You now know how to:

1. Set up Kosli and integrate it with a CI/CD pipeline
2. Create Flows and Trails to track your software delivery process
3. Attest artifacts and attach evidence (tests, SBOMs, scans)
4. Define compliance requirements and gate releases
5. Create environments, track what’s running, and enforce policies

You have full visibility and control over your software supply chain, from build to deployment.

Explore further

• Custom attestation types for your specific tools
• Kubernetes environment reporting if you use K8s
• Approvals for production deployment workflows

Further reading:

• Environments
• Policies