diff --git a/.claude/settings.json b/.claude/settings.json index b1e6b8f..be39cef 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -3,7 +3,6 @@ "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }, "enabledPlugins": { - "mintlify@mintlify-marketplace": true, "mintlify-docs@kosli-plugins": true } } diff --git a/docs.json b/docs.json index 288fdef..f06e090 100644 --- a/docs.json +++ b/docs.json @@ -48,6 +48,10 @@ { "source": "/tutorials/get_familiar_with_kosli", "destination": "/tutorials/try_kosli_locally" + }, + { + "source": "/understand_kosli/concepts", + "destination": "/understand_kosli/how_kosli_works" } ], "navigation": { @@ -60,7 +64,10 @@ "icon": "book-open", "pages": [ "understand_kosli/what_is_kosli", - "understand_kosli/concepts" + "understand_kosli/risks", + "understand_kosli/controls", + "understand_kosli/how_kosli_works", + "understand_kosli/glossary" ] }, { diff --git a/images/Kosli-overview-docs.png b/images/Kosli-overview-docs.png new file mode 100644 index 0000000..f7ded2d Binary files /dev/null and b/images/Kosli-overview-docs.png differ diff --git a/images/how-kosli-works.png b/images/how-kosli-works.png new file mode 100644 index 0000000..cb92b18 Binary files /dev/null and b/images/how-kosli-works.png differ diff --git a/images/kosli-overview-docs.jpg b/images/kosli-overview-docs.jpg deleted file mode 100644 index dbb64d7..0000000 Binary files a/images/kosli-overview-docs.jpg and /dev/null differ diff --git a/implementation_guide/phase_1/roles_and_responsibilities/security_compliance.md b/implementation_guide/phase_1/roles_and_responsibilities/security_compliance.md index d83183f..82596a4 100644 --- a/implementation_guide/phase_1/roles_and_responsibilities/security_compliance.md +++ b/implementation_guide/phase_1/roles_and_responsibilities/security_compliance.md @@ -78,4 +78,4 @@ Learn more about [Kosli user roles and permissions](/administration/managing_use ## Where to start -- [**Concepts**](/understand_kosli/concepts): Understand how Flows, Trails, and Attestations fit together. +- [**How Kosli works**](/understand_kosli/how_kosli_works): Understand how Flows, Trails, and Attestations fit together. diff --git a/implementation_guide/phase_1/roles_and_responsibilities/sponsors.md b/implementation_guide/phase_1/roles_and_responsibilities/sponsors.md index bf42441..93fa711 100644 --- a/implementation_guide/phase_1/roles_and_responsibilities/sponsors.md +++ b/implementation_guide/phase_1/roles_and_responsibilities/sponsors.md @@ -72,5 +72,5 @@ Learn more about [Kosli user roles and permissions](/administration/managing_use ## Where to Start - [**What is Kosli?**](understand_kosli/what_is_kosli/): Understand the value and core ideas - [**Implementing Kosli**](/implementation_guide): A rollout guide aligned to business and technical outcomes -- [**Concepts**](/understand_kosli/concepts): Understand how Flows, Trails, and Attestations fit together +- [**How Kosli works**](/understand_kosli/how_kosli_works): Understand how Flows, Trails, and Attestations fit together diff --git a/understand_kosli/concepts.md b/understand_kosli/concepts.md deleted file mode 100644 index 37b1da5..0000000 --- a/understand_kosli/concepts.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: 'Concepts' -description: "Understand the main concepts behind Kosli" ---- - -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. - -Kosli Concepts - -## 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 - -A Kosli Flow represents a business or software process for which you want to track changes and monitor compliance. - -As an example, a flow can be created to track the controls involved with building an application in your CI system. - -### 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. - -**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/) - -### 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. - -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:** - -* Artifact attestation as part of the CLI flow [example](https://app.kosli.com/kosli-public/flows/cli/trails/6781399) - -### 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 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 - -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 - -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 Artifacts and attestations for Trails of that given Flow to be considered compliant. - -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/) - -## 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 -* Amazon Lambda -* Physical/virtual server -* Docker host -* Azure Web Apps and Function Apps - -**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/) - -### 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 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. - -**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 - -### Environment Policy - -Environment Policy enables you to define and enforce compliance requirements for artifact deployments across different environments. - -**Examples:** - -* 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) diff --git a/understand_kosli/controls.md b/understand_kosli/controls.md new file mode 100644 index 0000000..c61e92f --- /dev/null +++ b/understand_kosli/controls.md @@ -0,0 +1,103 @@ +--- +title: 'Controls' +description: 'Why SDLC controls exist, how they mitigate software delivery risks, and how Kosli implements them.' +--- + +The [risks page](/understand_kosli/risks) describes what can go wrong in software delivery. A control is the counterpart: a repeatable, verifiable activity that mitigates one or more of those risks. Controls are what stand between an identified risk and a security or compliance incident. + +The challenge is not defining controls (most teams already know what "good" looks like) but enforcing them consistently and proving they ran. Manual checklists drift, spreadsheets go stale, and tribal knowledge leaves with the people who hold it. Kosli automates the recording and enforcement of controls so you get continuous evidence that the right things happened. + +## The SDLC control model + +Controls are organized by the phase of the software delivery lifecycle where they apply: + + + + Securing the build chain: dependency management, secrets scanning, artifact provenance, controlled build environments, infrastructure as code. + + + Validation before deployment: code review, quality assurance, vulnerability scanning, deployment approvals. + + + Monitoring and enforcement in production: change records, deployment controls, secrets management, workload monitoring, drift detection. + + + Human and organizational factors: security training, penetration testing, service ownership. + + + + + Kosli's [SDLC Controls Framework](https://sdlc.kosli.com) contains a rich catalog of controls with risk mappings. Your organization may define additional controls or adapt these to fit your specific compliance requirements. + + +## Example controls by phase + +The following examples show representative controls from each phase, the risks they mitigate, and the Kosli concepts that implement them. + +### Build + +Build controls secure the build chain itself. The reason these controls exist at the build phase (rather than later) is that a compromised dependency, an exposed secret, or an unverifiable artifact is cheapest to catch before it enters the release pipeline. Once a tainted artifact passes the build stage, every downstream control has to work harder to detect it. + +| Control | Risk mitigated | Kosli concept | +|---------|---------------|---------------| +| Dependency management | Supply chain compromise, Vulnerable software in production | Attestation (`snyk` type) | +| Secrets scanning | Credential and secret exposure | Attestation (custom type) | +| Artifact binary provenance | Supply chain compromise | Artifact (SHA256 fingerprint) | + +### Release + +Release controls validate that software is ready for production. While build controls secure the ingredients, release controls verify the result: has the code been reviewed, do the tests pass, are there known vulnerabilities, and has someone authorized the deployment? The reason code review sits here (rather than in build) is that it is a validation of the change as a whole, not of the build toolchain. + +| Control | Risk mitigated | Kosli concept | +|---------|---------------|---------------| +| Code review | Insider threat, Unreviewed changes | Attestation (`pullrequest` type) | +| Quality assurance | Vulnerable software in production | Attestation (`junit` type) | +| Vulnerability scanning | Vulnerable software in production, Supply chain compromise | Attestation (`snyk` type) | +| Deployment approvals | Unauthorized deployment | Attestation (`approval` type) | + +### Runtime + +Runtime controls address what happens after deployment. Even if every build and release control passes, the production environment can still diverge from expectations. Configuration drift happens gradually as manual fixes accumulate. Shadow changes appear when someone bypasses the pipeline altogether. The reason runtime monitoring matters is that it closes the loop: you verify not just what you intended to deploy, but what is actually running. + +| Control | Risk mitigated | Kosli concept | +|---------|---------------|---------------| +| Runtime workload monitoring | Shadow changes, Unauthorized deployment | Environment Snapshot | +| Drift detection | Configuration drift | Environment Snapshot + notifications | +| Change records | Lack of auditability | Trail | + +### Lifecycle + +Lifecycle controls address the human and organizational factors that underpin all other controls. While build, release, and runtime controls target specific phases, lifecycle controls ensure that teams have the knowledge, accountability, and validation processes to operate a secure SDLC. Without them, the technical controls may be in place but the people and processes behind them are fragile. + +| Control | Risk mitigated | Kosli concept | +|---------|---------------|---------------| +| Security training | Insider threat | Attestation (custom type) | +| Penetration testing | Vulnerable software in production | Attestation (custom type) | +| Service ownership | Lack of auditability | Trail | + +## From controls to Kosli concepts + +The controls above are abstract: they describe *what* needs to happen. Kosli provides the building blocks that *implement* them. The reason Kosli models controls this way (rather than, say, embedding them as pipeline plugins or CI-specific integrations) is that controls span tools and environments. A single control like "code review" might originate in GitHub, get recorded in a CI pipeline, and need to be verifiable months later during an audit. Kosli's model is designed to be tool-agnostic so that evidence from any source fits into the same structure. + +Kosli organizes controls through a hierarchy. At the top is a **Flow**, which models a process that contains controls (your CI pipeline, your Terraform workflow, your onboarding procedure). Each time that process runs, it creates a **Trail**, a single execution that collects all the evidence for that run. The reason this layered approach matters is that a single attestation is meaningless without the context of which process produced it and which execution it belongs to. + +Within a Trail, **Attestations** record that specific controls were executed and capture their results. A **Flow Template** defines which attestations are required for a Trail to be compliant. If a required attestation is missing, Kosli flags the Trail as non-compliant. + +At the runtime level, **Environment Policies** enforce controls over what may run in production, and **Environment Snapshots** provide the data that makes runtime controls like drift detection possible. The reason Environments are modeled separately from Flows is that what you build and what you run are fundamentally different concerns. An artifact may pass every build and release control but still create a compliance problem if it appears in an environment where it does not belong. + +To understand each of these building blocks in detail, continue to [How Kosli works](/understand_kosli/how_kosli_works). + + + + Explore each building block and how they connect. + + + See build controls in action through a hands-on lab. + + + See release controls in action through a hands-on lab. + + + See runtime controls in action through a hands-on lab. + + diff --git a/understand_kosli/glossary.md b/understand_kosli/glossary.md new file mode 100644 index 0000000..8a8d33c --- /dev/null +++ b/understand_kosli/glossary.md @@ -0,0 +1,66 @@ +--- +title: 'Glossary' +description: 'Quick-reference definitions of Kosli terms and concepts.' +--- + +A reference list of Kosli terms. For a narrative explanation of how these concepts fit together, see [How Kosli works](/understand_kosli/how_kosli_works). + +### Artifact + +A software deliverable (binary, container image, archive) reported to Kosli and identified by its SHA256 fingerprint. Kosli uses the fingerprint to link an artifact's build-time origin to its runtime presence. + +### Attestation + +A record that a specific control or check was performed on an Artifact or Trail, along with its result. Built-in types include `snyk`, `junit`, `sonar`, `pullrequest`, and `approval`. Custom types support jq-based compliance evaluation. + +### Audit Package + +A downloadable tar file containing metadata and evidence for a Trail, Artifact, or Attestation. Used for audit investigations and compliance reviews. + +### Binary Provenance + +The chain of custody that links an artifact's fingerprint to its origin, build evidence, and runtime deployment history. + +### Control + +A repeatable, verifiable activity that mitigates one or more [risks](/understand_kosli/risks). Controls span build, release, runtime, and lifecycle phases. + +### Environment + +A Kosli representation of a runtime system you want to monitor (Kubernetes cluster, ECS service, Lambda function, S3 bucket, server directory, Docker host, Azure Web App). + +### Environment Policy + +A set of compliance requirements defining what may run in an Environment. Non-compliant artifacts are flagged. Trusted third-party artifacts can be allowlisted. + +### Environment Snapshot + +A point-in-time capture of the artifacts running in an Environment. Kosli traces each running artifact back to the Flow and Trail that produced it. + +### Evidence Vault + +Secure storage for evidence files attached to attestations (test reports, scan output, approval records). Retrievable on demand for audits. + +### Flow + +A model of a repeatable business or software process (e.g., a CI pipeline, a Terraform workflow) for which you want to track changes and monitor compliance. + +### Flow Template + +The compliance definition for a Flow. It specifies the artifacts and attestations that every Trail in the Flow must contain to be considered compliant. Each Trail can override its Flow's template. + +### Organization + +The account that owns Kosli resources (Flows, Environments, Policies). Most teams work within a shared organization that maps to their company. Members are invited with specific roles that control access. + +### Risk + +A condition or event in the software delivery lifecycle that could compromise the integrity, security, or compliance posture of your software. + +### Trail + +A single execution of a Flow (e.g., one CI build, one pull request). Each Trail has a unique identifier you choose, such as a git commit SHA or PR number. + +### Trail Evaluation + +The process by which Kosli checks a Trail against its Flow Template to determine whether all required artifacts and attestations are present and compliant. diff --git a/understand_kosli/how_kosli_works.md b/understand_kosli/how_kosli_works.md new file mode 100644 index 0000000..be91e95 --- /dev/null +++ b/understand_kosli/how_kosli_works.md @@ -0,0 +1,84 @@ +--- +title: 'How Kosli works' +description: 'How Kosli models software delivery using Flows, Trails, Artifacts, Attestations, and Environments.' +--- + +Kosli provides a set of building blocks that implement [controls](/understand_kosli/controls) across your software delivery lifecycle. This page explains what those building blocks are, why they exist, and how they fit together. + +## Modeling your process: Flows, Trails, and Templates + +Every process you want to track in Kosli starts with a **Flow**. A Flow models a repeatable process: a CI pipeline, a Terraform workflow, an onboarding procedure. It is the container for everything that happens within that process. + +Each time the process runs, Kosli creates a **Trail**. A Trail represents one execution of a Flow: one CI build, one pull request, one infrastructure change. You choose the identifier (a git commit SHA, a PR number, a ticket ID) so that trails map naturally to your domain. The reason Kosli uses user-chosen identifiers rather than auto-generated IDs is that trails should map to concepts your team already works with, not introduce an opaque abstraction. + +A **Flow Template** defines what "compliant" means for a given Flow. It lists the artifacts and attestations that every Trail must contain before Kosli considers it complete. This is how Kosli enforces [build and release controls](/understand_kosli/controls): if a required attestation is missing, the Trail is non-compliant. + +## Recording evidence: Artifacts and Attestations + +When your CI pipeline produces a binary, container image, or any other deliverable, you report it to Kosli as an **Artifact**. Kosli identifies each artifact by its SHA256 fingerprint rather than by name or tag. The reason for this design choice is that names and tags are mutable (a `latest` tag can point to different images over time), while a cryptographic fingerprint is immutable. This creates a tamper-proof reference that links the artifact's origin in a Trail to its runtime presence in an Environment. + +An **Attestation** records that a specific control was executed and captures its result. When your pipeline runs a Snyk scan, that scan result becomes an attestation on the artifact or trail. When a pull request is reviewed, that review becomes an attestation. Attestations are the evidence that your controls actually ran. + +Kosli provides built-in attestation types for common controls (Snyk, JUnit, SonarCloud, pull requests, approvals) and supports custom types with jq querying for compliance evaluation. You can also create generic attestations for controls that do not require automated evaluation. + +Attestations can carry attached evidence files (test reports, scan output, approval records). Kosli stores these files in the **Evidence Vault**, making them retrievable on demand for audits or investigations. + +## Monitoring runtime: Environments, Snapshots, and Policies + +Kosli tracks what is running in your production (and non-production) systems through **Environments**. The reason Environments are modeled separately from Flows is that what you build and what you run are fundamentally different concerns that need independent tracking. Each physical or virtual runtime you want to monitor gets its own Kosli Environment: a Kubernetes cluster, an ECS service, a Lambda function, an S3 bucket, or a server directory. + +Kosli supports periodic **Environment Snapshots** that capture the artifacts running at a point in time. For each artifact in a snapshot, Kosli traces it back to the Flow and Trail that produced it, creating a direct link between what was built and what is running. This is how Kosli implements [runtime controls](/understand_kosli/controls) like drift detection and shadow change identification. + +An **Environment Policy** defines compliance requirements for what may run in an environment. If an artifact appears in a snapshot that does not satisfy the policy, Kosli flags it as non-compliant. Third-party artifacts that you trust but did not build yourself can be allowlisted. + +## Audit readiness + +A Trail collects all the attestations and artifacts for a single execution of your process. You can download an **Audit Package** for any Trail, Artifact, or individual Attestation to get a tar file containing the metadata and attached evidence files. This is your on-demand compliance record, ready for auditors or internal investigations. + +## Organizations + +A Kosli **Organization** is the account that owns all of these resources: Flows, Environments, Policies, and the evidence they contain. Organizations provide the access control boundary that determines who can view and modify compliance data. This matters because many of the [risks](/understand_kosli/risks) Kosli addresses (insider threat, unauthorized deployment) depend on controlling who has access to what. + +Most teams work within a shared organization that maps to their company. Members are invited with specific roles that control what they can see and do. + +## How the pieces connect + +The diagram below shows how these building blocks relate to each other. + + + Diagram showing how Kosli concepts connect: a Flow executes as a Trail, which produces Artifacts and collects Attestations. Artifacts link via fingerprint to Environment Snapshots. Trails download as Audit Packages. + + +An Organization contains Flows and Environments. When a Flow runs, it creates a Trail. The Trail produces Artifacts and collects Attestations, some of which can be attached to a specific Artifact. Meanwhile, Environment Snapshots capture what is actually running and link back to the Artifact and the Trail it was produced in. This connection between build-time evidence and runtime state is what gives Kosli end-to-end traceability. + +## Get started + + + + Set up your first Flow and Trail. + + + Report artifacts and create attestations. + + + Monitor runtime environments and define policies. + + + + + + Quick-reference definitions of every Kosli term. + + + The SDLC risks these concepts are designed to address. + + + How controls map to Kosli building blocks. + + + Five hands-on labs covering the full Kosli workflow. + + diff --git a/understand_kosli/risks.md b/understand_kosli/risks.md new file mode 100644 index 0000000..0637f4e --- /dev/null +++ b/understand_kosli/risks.md @@ -0,0 +1,58 @@ +--- +title: 'Risks' +description: 'Why modern software delivery introduces risks that are hard to manage, and how to think about them.' +--- + +Software teams ship faster than ever. Code flows through automated pipelines, pulls in hundreds of open-source dependencies, and deploys to distributed infrastructure multiple times a day. That speed is a strength, but it also means that the number of places where something can go wrong has grown dramatically. A single compromised dependency, an unreviewed commit, or an unnoticed configuration change can reach production before anyone is aware of it. + +The reason these risks are hard to manage is not that teams are careless. It is that the delivery process spans so many tools, environments, and people that no single person has full visibility. Evidence of what happened (and whether it should have happened) is scattered across CI logs, chat threads, ticketing systems, and cloud consoles. Reconstructing the full picture after an incident, or during an audit, is slow and unreliable. + +## What is a risk? + +In this context, a risk is a condition or event in your software delivery lifecycle (SDLC) that could compromise the integrity, security, or compliance posture of your software. These are not hypothetical. They reflect real-world incidents that have affected organizations across industries. + +## The risk landscape + +Kosli identifies nine categories of risk across the SDLC. They fall into three broad groups depending on where in the lifecycle they originate. + +### Risks from your supply chain and build process + +Modern software is largely assembled, not written from scratch. Your application depends on libraries, base images, and build tools maintained by third parties. If any of those components are tampered with, malicious code enters your pipeline without anyone writing a single bad line. At the same time, the build process itself can introduce vulnerabilities if security scanning is skipped or secrets are accidentally embedded in artifacts. + +| Risk | Description | +|------|-------------| +| **Supply chain compromise** | Third-party dependencies or build tools are tampered with, injecting malicious code into your software. | +| **Vulnerable software in production** | Known vulnerabilities ship to production because scanning was skipped, ignored, or incomplete. | +| **Credential and secret exposure** | Developers commit API keys, tokens, or passwords to source control or embed them in artifacts. | + +### Risks from within your team + +Not all risks come from outside. Authorized users can introduce problems too, whether through honest mistakes or deliberate circumvention of process. Code that skips peer review, deployments that bypass approval gates, and changes that no one documents all create gaps that are invisible until something breaks or an auditor asks questions. + +| Risk | Description | +|------|-------------| +| **Insider threat** | Changes made using authorized credentials without proper review or approval. This includes mistakes by team members, deliberate circumvention of process, or third parties who have compromised legitimate credentials. | +| **Unauthorized deployment** | Software reaches production without passing required gates or approvals. | +| **Unreviewed changes** | Code or configuration changes bypass peer review, increasing the chance of defects or policy violations. | +| **Lack of auditability** | There is no reliable record of what changed, when, why, or by whom, making audits costly and unreliable. | + +### Risks from your runtime environments + +Once software is deployed, the runtime environment becomes its own source of risk. Configurations drift from their expected state, artifacts appear that cannot be traced back to any known build, and changes happen outside the deployment pipeline entirely. These "shadow changes" are particularly dangerous because they bypass every control you have put in place during build and release. + +| Risk | Description | +|------|-------------| +| **Configuration drift** | Production environments diverge from their expected state without anyone noticing. | +| **Shadow changes** | Changes appear in production that cannot be traced back to any known build or deployment process. | + + + Kosli's [SDLC Controls Framework](https://sdlc.kosli.com) organizes these nine risks with detailed descriptions and risk-to-control mappings. Your organization may identify additional risks or prioritize them differently depending on your industry, regulatory environment, and threat model. + + +## Risks and compliance frameworks + +These risks are not unique to Kosli. They are the same concerns addressed by compliance frameworks like SOC 2, ISO 27001, and FDA 21 CFR Part 11. Each framework codifies requirements for managing some or all of these risks through documented controls and evidence. For example, SOC 2's Change Management criteria address unauthorized deployment and unreviewed changes, while its Logical Access controls relate to insider threat and credential exposure. + +Kosli does not replace a compliance framework. The reason it is designed this way is that frameworks define *what* you must demonstrate, while Kosli automates *how* you demonstrate it. The alternative (building compliance tooling into each framework individually) would mean duplicating effort across SOC 2, ISO 27001, and every other standard your organization adopts. Kosli instead provides a single evidence layer that serves all of them. When your CI pipeline attests that a security scan passed, or Kosli detects unexpected changes in a production environment, that is compliance evidence recorded automatically. Without Kosli, producing and maintaining that evidence requires manual effort, and manual evidence has a tendency to be incomplete, inconsistent, or simply missing when you need it most. + +Now that you understand what can go wrong, the next step is understanding the [controls](/understand_kosli/controls) that prevent it and how Kosli implements them. diff --git a/understand_kosli/what_is_kosli.md b/understand_kosli/what_is_kosli.md index b12527b..aaf1174 100644 --- a/understand_kosli/what_is_kosli.md +++ b/understand_kosli/what_is_kosli.md @@ -1,56 +1,38 @@ --- title: 'What is Kosli?' -description: 'Learn about Kosli, its purpose, use cases, and how it fits into the tools landscape.' +description: 'Why compliance automation matters and how Kosli approaches it.' --- -Kosli is a change recording and compliance monitoring platform which allows you to record, track and query changes about any software or business process so you can prove compliance and maintain security without slowing down. +Proving compliance in fast-moving software delivery is hard. Evidence is scattered across tools, audits are manual, and changes happen faster than any spreadsheet or CAB meeting can track. Kosli automates this. It is a tool-agnostic platform that integrates with your existing CI systems, scanners, and runtime environments, consolidating compliance data into a single place. -Kosli connects the recorded changes to establish immutable "chains of custody" which enables you to: +## Kosli in a nutshell -1. **Track Changes**: Trace how your business or software processes change over time. -2. **Identify Sources**: Understand where changes originated from, which can help in identifying issues. -3. **Continuous Compliance**: Ensure that you continuously adhere to your compliance requirements. -4. **Enable Audits**: Access audit packages on demand allowing audits and investigations into the software supply chain. -5. **Enhance Trust**: Build trust among users, customers, and stakeholders by providing transparent and verified information about the change history. -6. **Remove Friction**: Make changes at the DevOps speed with continuous compliance. No spreadsheets, paperwork or CAB meetings required. +Think of Kosli as a flight recorder for your software delivery lifecycle (SDLC). Like a flight recorder, Kosli does not control the plane. It records what happened so that after the fact you can reconstruct the sequence of events. The reason this matters in software is that incidents and audit questions are inevitable, but the ability to answer "what was running, how did it get there, and did it pass all required checks?" should not depend on someone's memory or a manual audit trail. -# When to use Kosli? +You report events of interest (builds, test results, deployments, environment state) through the [CLI](/client_reference) or [API](/api-reference). Kosli stores each record as an immutable entry and evaluates it against the [controls](/understand_kosli/controls) defined in your policies. Change sources include build systems (CI pipelines), runtime environments (Kubernetes clusters, AWS ECS, Lambda), and business processes (onboarding, access management). -Kosli serves as a versatile solution for a variety of use cases. Two primary scenarios which customers find Kosli valuable are: + + Diagram showing how Kosli records events from CI pipelines, runtime environments, and business processes into immutable audit trails. + -- Monitoring and Ensuring Compliance in Software and Business Processes: - Regardless of your specific process requirements and tools, Kosli empowers you to streamline and automate your change management and evidence recording processes. This capability ensures that organizations are consistently prepared for audits. +## When to use Kosli - Examples of software process requirements that Kosli can assist with are: - - Verification that all artifacts running in production have undergone a specific risk control (e.g. security scanning). - - Mandatory code review in a pull request before deployment to production. +- **Compliance automation**: Traditional compliance evidence collection is manual, error-prone, and always playing catch-up with the pace of delivery. Kosli automates evidence collection for frameworks like SOC 2, ISO 27001, or NIST SP 800-53, verifying that artifacts in production have passed required controls (security scans, code review, approval workflows) so you stay audit-ready at all times. +- **Change observability**: In distributed systems, understanding what changed, when, and by whom often requires piecing together logs from half a dozen tools. Kosli provides a unified view of change across your entire delivery pipeline, even without specific compliance requirements. - Examples of business process requirements that Kosli can address include: - - Confirmation that employee onboarding/off-boarding aligns with relevant policies. - - Logging and adherence to relevant policies for accessing production servers. +## Where to go next -- Enhancing Overall Observability of Changes in Complex Systems and Environments: - Beyond compliance considerations, Kosli remains valuable as a comprehensive platform, offering a unified view to different stakeholders. It provides visibility into changes occurring across various components of complex systems, even when there are no specific compliance requirements in place. This single pane of glass enhances overall observability. - -Feel free to contact us with any additional questions or if you require further information regarding the capabilities of Kosli. Alternatively, [explore how our customers have successfully implemented and used our services](https://www.kosli.com/case-studies/). - -# Where does Kosli fit in the growing tools landscape? - -Kosli is tool-agnostic, specifically crafted to seamlessly integrate with various tools, including CI systems, code analysis tools, runtime environments, and more. Serving as a comprehensive compliance and change data hub, Kosli consolidates information from all your tools into a unified platform. It acts as your singular compliance and change management interface, providing a consolidated and streamlined view of data from diverse sources. - -# How does Kosli work? - -Kosli operates akin to a black box recorder, functioning as an append-only repository for immutable change records. Users report specific changes of interest through the command line interface (CLI) or API. Kosli, in turn, captures and stores these changes while actively monitoring compliance with designated policies. - -Notably, change sources can originate from diverse environments, including build systems (such as CI systems) and runtime environments (for instance, a Kubernetes cluster). This flexibility ensures that Kosli effectively captures and monitors changes across various stages of development and deployment. - -Kosli Overview - - - Ready to try Kosli hands-on? The [Kosli Learning Labs](/labs) walk you from account creation to runtime compliance enforcement in five progressive labs. - + + + Read [Risks](/understand_kosli/risks), [Controls](/understand_kosli/controls), and [How Kosli works](/understand_kosli/how_kosli_works) in order. Use the [Glossary](/understand_kosli/glossary) as a reference along the way. When you are ready to try it hands-on, work through the [Learning Labs](/labs). + + + Head to [Getting Started](/getting_started/install) for step-by-step setup, or see the [Implementation Guide](/implementation_guide/phase_1/roles_and_responsibilities/overview) for organizational rollout planning. + + + See the [Glossary](/understand_kosli/glossary) for quick-reference definitions of every Kosli term. + +