Skip to content

Security: kiranscript/keman

Security

SECURITY.md

Security

Keman is a self-hosted proxy. It is not a hosted service, and it does not phone home.

Reporting

Open a private security advisory on the GitHub repository, or contact the maintainers out of band if an advisory is not available. Please include a way to reproduce the issue and the version (keman version).

Supported versions

Version Status
0.1.0-beta Current beta.

What you must protect

  • The master key. init stores it in master.key (mode 0600) next to the config and sets master_key_file, unless that field is already set. Anyone with the master key and the database can unwrap credential secrets. By default both files are in the same directory, so a copy of that directory (a backup, a shared volume) carries everything needed. For production, set master_key_file to a path outside the data directory or a secrets mount, or supply KEMAN_MASTER_KEY from a secrets manager, and keep the directory mode 0700.
  • The admin token. It is shown once by init and by admin-token rotate. The admin listener must stay on localhost or a Unix socket. The terminal UI keeps a typed token only in its own memory and never writes it to disk. KEMAN_ADMIN_TOKEN is readable by the same user through the process environment. scripts/quickstart.sh saves a token to .quickstart/admin.token for the demo only.
  • The SQLite file. It holds ciphertext, spend counters, events, and the wrapped data key.
  • The process memory. Plaintext credentials are cached so the proxy can swap them onto requests. A memory dump defeats the encryption. Run the process as a non-root user, on a read-only root filesystem where you can, and with egress only to the upstream hosts you configured.

What the proxy refuses to do

  • Forward a virtual key, Authorization, X-Api-Key, X-Forwarded-*, or Forwarded to the upstream.
  • Honor X-Forwarded-For from a peer that is not in trusted_proxies (empty by default).
  • Forward a path with . or .. segments (also ..;), backslashes, or control characters. The upstream could resolve it to an endpoint the path allowlist refuses, so it is answered with path_not_allowed.
  • Follow a redirect whose host or port is not the configured upstream.
  • Use HTTP_PROXY for upstream connections.
  • Serve the admin API or /metrics without the admin token.

Verifying a release

Every release binary has a .sha256 sum, an SPDX SBOM (.spdx.json), and a keyless cosign bundle (.bundle) signed by the release workflow. scripts/install.sh always checks the sum, and checks the signature when cosign is installed. To check one by hand:

cosign verify-blob --bundle keman_linux_amd64.bundle \
  --certificate-identity-regexp '^https://github.com/kirank55/keman/\.github/workflows/release\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  keman_linux_amd64

The container image ghcr.io/kirank55/keman is signed the same way: cosign verify with the same identity and issuer.

See docs/THREAT-MODEL.md and docs/ASSUMPTIONS.md.

Releases

The release workflow in .github/workflows/release.yml builds a static binary, an SPDX SBOM of that binary (Syft), a SHA-256 sum, and a keyless cosign signature, then publishes one GitHub Release. No signed release has been published yet; pushing a v* tag is what runs it.

There aren't any published security advisories