> Documentation index: https://docs.kiste.run/llms.txt, a list of every page in this documentation.

# Supply chain and updates

> How the Kiste image, the compute software and the CLI are built and delivered, and how you verify a download yourself.

You keep confidential data in a Kiste, and sooner or later you run `kiste update` or
`kiste self-update`. Neither may be able to bring in malware, a known-vulnerable package or a
component nobody reviewed. These are the rules every Kiste repository follows. Continuous
integration enforces them and fails a build that breaks one.

## How the Kiste image is built

- **Exact inputs.** Every input of the image is named by its exact bytes: base images by digest,
  Ubuntu packages from one signed archive snapshot, downloads by version and SHA-256, npm tools
  from a lockfile, source code by full commit. No floating tags, no `latest`, no `curl | sh`.
- **Inventory.** Each image release has a software bill of materials (SBOM) generated from the
  very image file a server boots, not from the build recipe.
- **Vulnerability gate.** That SBOM is scanned when the image changes and again every day. A
  Critical or High vulnerability that has an upstream fix blocks the release, unless a written
  exception with a reason, an owner and an expiry of at most 30 days covers it.
- **Review.** A new image is pinned only together with a review record, signed off by someone
  other than its author. The record lists every added, removed and changed component and the
  scan result.
- **Verified at boot.** The compute software carries the digests of the image and kernel it may
  boot and checks every byte against them before use. A changed image does not boot.

## How updates reach your Kiste

Nothing changes inside a running Kiste on its own. A new image reaches the platform only
through a staged release with a canary check on a fresh test Kiste. It reaches *your* Kiste
only when you run `kiste update`. `kiste list` shows when an update is available, and the
release notes come with it.

What you install inside your own Kiste (`apt`, `npm`, `pip`, …) is your choice and outside
these rules. The image ships with automatic updates of the bundled AI coding CLIs turned off.

> **Warning:** Known open item
>
> The current pinned image still contains packages with known, fixable vulnerabilities (mainly
> browsers, language runtimes and bundled dependencies). A refreshed image is being prepared. Until
> it ships, keep the tools you rely on up to date inside your Kiste.

## Platform code

- Rust: committed lockfiles, `--locked` builds, crates.io as the only source, a licence allow-list
  and RustSec advisory checks in CI.
- npm: committed lockfiles, `npm ci --ignore-scripts` (no install scripts run in CI or deploys),
  and `npm audit` must be clean at level high.
- GitHub Actions pinned to full commit SHAs, read-only permissions by default.
- Dependency updates arrive as automated pull requests and are merged only with green CI after a
  review of the changelog.
- The kiste.run control plane is deployed only by CI, from the locked tree, with scoped and
  expiring deploy credentials.

## Signed releases

The `kiste` CLI and the compute software are released with an Ed25519 signature (minisign
format), made in CI. The private key exists only in the release pipeline and in an offline
backup.

> **Warning:** Signatures start with CLI 0.1.1
>
> The CLI release published today, 0.1.0, carries checksums only. Its installer checks the
> archive's SHA-256 over HTTPS but verifies no signature. Signed releases start with 0.1.1, which
> is published once it has passed acceptance. Until then, the strongest check you can make is the
> checksum comparison below, over HTTPS.

The CLI's public key:

```text
RWRqNbdNDw3TcrPUP83KtqWGpM+Kldb8WHmNi2efvBWrZ0CRhuP6iPx2
```

From 0.1.1 on:

- **`install.sh`** always verifies the release signature before it installs anything, with
  OpenSSL 3 or, on a stock Mac, a built-in verifier. If it cannot verify, it refuses to install.
  It also checks that the signed comment names the version it installs, so an older release
  cannot be served to you as a newer one.
- **`kiste self-update`** installs a release only when its signature verifies against the key
  compiled into your CLI and the signed comment names that very version.
- **Windows (`install.ps1`)** checks the checksum over HTTPS but not yet the signature. After the
  first install, `kiste self-update` verifies.

The installers are currently served from the same storage as the release archives. Serving them
from the kiste.run code itself, so that a write to that storage alone could not change them, is
planned.

## Verify a CLI download yourself

1. Install [minisign](https://jedisct1.github.io/minisign/) (`brew install minisign`,
   `apt install minisign`, or a release from its project page).

2. Download the checksum list, its signature and your archive (replace the version and the archive
   name for your platform):

   ```bash
   v=0.1.1
   curl -fsSLO https://kiste.run/downloads/cli/v$v/checksums.txt
   curl -fsSLO https://kiste.run/downloads/cli/v$v/checksums.txt.minisig
   curl -fsSLO https://kiste.run/downloads/cli/v$v/kiste-aarch64-apple-darwin.tar.gz
   ```

3. For a signed release (0.1.1 and later), check the signature against the published key. minisign
   prints the trusted comment, which names the file and the version:

   ```bash
   minisign -Vm checksums.txt -P RWRqNbdNDw3TcrPUP83KtqWGpM+Kldb8WHmNi2efvBWrZ0CRhuP6iPx2
   ```

4. Check your archive against the signed list:

   ```bash
   grep kiste-aarch64-apple-darwin.tar.gz checksums.txt | shasum -a 256 -c -
   ```

   On Linux use `sha256sum -c -` instead of `shasum -a 256 -c -`.

The install guide has the same steps: [Verify a release yourself](https://docs.kiste.run/get-started/install.md#verify-a-release-yourself).

If either check fails, do not run the binary, and please
[tell us](https://docs.kiste.run/security/disclosure.md).

## Known gaps

- **No build provenance attestation** (SLSA). The signed checksum names the commit a release was
  built from, but there is no third-party attestation of the build.
- **Reproducibility.** Inputs are exact, but the image file is not bit-for-bit reproducible
  (file timestamps). Its identity is the published digest, and the SBOM is made from those bytes.
- **Trust on first use of upstream checksums.** Checksums are taken from the upstream project's
  release page when a version is first pinned. The SBOM review and the vulnerability scan are the
  second line of defence.
- **Zero-days.** Scans cover published advisories only.

## Related topics

- [Security and trust](https://docs.kiste.run/security.md)
- [Isolation](https://docs.kiste.run/security/isolation.md)
- [Network](https://docs.kiste.run/security/network.md)
- [Encryption](https://docs.kiste.run/security/encryption.md)
- [Data location](https://docs.kiste.run/security/data-location.md)
- [Subprocessors](https://docs.kiste.run/security/subprocessors.md)
- [Logging and retention](https://docs.kiste.run/security/logging-retention.md)
- [Export and deletion](https://docs.kiste.run/security/account-data.md)
- [Incidents and status](https://docs.kiste.run/security/incidents-status.md)
- [Vulnerability disclosure](https://docs.kiste.run/security/disclosure.md)
- [Compliance](https://docs.kiste.run/security/compliance.md)
- Previous: [Encryption](https://docs.kiste.run/security/encryption.md)
- Next: [Data location](https://docs.kiste.run/security/data-location.md)