Artifacts

In software processes, you typically generate one or more artifacts that are deployed or distributed, such as docker images, archives, binaries, etc. You can ensure traceability for the creation of these artifacts by attesting them to Kosli, thereby establishing a binary provenance for each one.

Binary provenance

Binary provenance for artifacts refers to the ability to trace and verify the origins, history, and journey of the artifacts throughout their lifecycle. This involves recording immutable attestations about the artifact creation, risk controls performed on it, deployments, and execution/usage. Artifacts are uniquely identified by their SHA256 fingerprints. When attesting an artifact to Kosli, you have the option to either provide the fingerprint manually or allow Kosli CLI to calculate it automatically for you. By leveraging the artifact’s fingerprint, Kosli can establish connections between the creation of the artifact and its runtime-related events, such as when the artifact starts or ceases execution within a specific environment. By establishing and maintaining binary provenance for artifacts, Kosli enables you to:

Track Changes: Trace how your Flow artifacts change over time.
Identify Sources: Understand where your artifacts originated from, which can help in identifying vulnerabilities or issues.
Monitor Compliance: Ensure that the artifacts adhere to your compliance requirements.
Enable Audits: Access audit packages on demand allowing audits and investigations into the software supply chain.
Enhance Trust: Build trust among users, customers, and stakeholders by providing transparent and verified information about the software’s history.

Attesting artifacts

To attest an artifact, you can run a command similar to the one below:

kosli attest artifact project-a-app.bin \
	--artifact-type file \
	--build-url https://exampleci.com \
	--commit-url https://github.com/ProjectA/ProjectAApp/commit/e67f2f2b121f9325ebf166b7b3c707f73cb48b14 \
	--commit e67f2f2b121f9325ebf166b7b3c707f73cb48b14 \
	--flow project-a \
	--trail trail-1 \
	--name backend

The --artifact-type flag is used to determine the type of artifact being attested. The following types are supported:

file: for any single file artifacts (e.g. a binary, Jar file, etc.)
dir: for directory artifacts.
docker: for docker images that are pulled on the machine. This option depends on having a running Docker daemon on the machine.
oci: for container images in docker or OCI format. The fingerprint is fetched directly from the registry.

docker requires the image to exist in a registry. Kosli reads the image’s repo digest via the local Docker daemon, and a freshly built image (just docker build) does not have one until it has been pushed to or pulled from a registry. If you attest an image that has only been built locally, you will see:

Error: repo digest unavailable for the image, has it been pushed to or pulled from a registry?

You have two options:

Push the image to a registry first, then attest it.
Use --artifact-type=oci and let Kosli fetch the digest directly from the registry.

See repo digest unavailable for more detail.

See kosli attest artifact for more details.

The `--dry-run` flag

All Kosli CLI commands which write data accept the --dry-run boolean flag. When this flag is used, a CLI command:

Does not communicate with Kosli at all
Prints the payload it would have sent
Exits with a zero status code

We recommend using the KOSLI_DRY_RUN environment variable to automatically set the --dry-run flag. This will allow you to instantly turn off all Kosli CLI commands if Kosli is down, as detailed in this tutorial. The --dry-run flag is also useful when trying commands locally. For example:

kosli attest artifact cyberdojo/differ:dde3b2a \
  --artifact-type=docker \
  --org=cyber-dojo \
  --flow=differ-ci \
  --trail=$(git rev-parse HEAD) \
  --dry-run \
  ...

 {
    "fingerprint": "0f53b5b9e7c266defe6984deafe039b116295b2df4a409ba6288c403f2451a9f",
    "filename": "cyberdojo/differ:dde3b2a",
    "git_commit": "fbb9e8000e2344323040e348a54b33ecbf67f273",
    "git_commit_info": {
        "sha1": "fbb9e8000e2344323040e348a54b33ecbf67f273",
        "message": "improve coverage report info (#2796)",
        "author": "Jon Jagger \u003cjon@jaggersoft.com\u003e",
        "timestamp": 1733724563,
        "branch": "master",
        "url": "https://github.com/kosli-dev/server/commit/fbb9e8000e2344323040e348a54b33ecbf67f273"
    },
    "build_url": "https://github.com/cyber-dojo/differ/actions/runs/11777650898",
    "commit_url": "https://github.com/cyber-dojo/differ/commit/dde3b2a7dab8e4567038e4c66ac68f0f01d0f704",
    "repo_url": "https://github.com/kosli-dev/server",
    "template_reference_name": "differ",
    "trail_name": "dde3b2a7dab8e4567038e4c66ac68f0f01d0f704"
}

$ echo $?
0

Understand Kosli

Get started

Core concepts

Learning labs

Help and troubleshooting

Binary provenance

Attesting artifacts

The `--dry-run` flag

​Binary provenance

​Attesting artifacts

​The --dry-run flag

Binary provenance

Attesting artifacts

The `--dry-run` flag