marcoallegretti/karapace
1
0
Fork 0
mirror of https://github.com/marcoallegretti/karapace.git synced 2026-03-26 21:43:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
karapace/docs/security-model.md
Marco Allegretti 5306963cce docs: comprehensive public documentation 
- docs/getting-started.md — install per distro, first use, common workflows
- docs/architecture.md — 9-crate dependency graph, design decisions, data flow
- docs/manifest-spec.md — manifest v1 specification
- docs/lock-spec.md — lock file v2 specification
- docs/store-spec.md — store format v2 specification
- docs/hash-contract.md — two-phase identity hashing algorithm
- docs/security-model.md — threat model, mount/device/env policy, privilege model
- docs/cli-stability.md — 23 stable commands, exit codes, stability guarantees
- docs/protocol-v1.md — remote protocol v1 draft
- docs/layer-limitations-v1.md — phase 1 layer limitations
- docs/api-reference.md — public API reference (Engine, D-Bus)
- docs/versioning-policy.md — semantic versioning, deprecation policy
- docs/verification.md — release artifact verification (SHA256, cosign, SBOM)
- docs/e2e-testing.md — E2E test guide with distro-specific prerequisites
- README.md — project overview, features, quick start, installation
- CONTRIBUTING.md — development setup, architecture principles, code standards
- CHANGELOG.md — full changelog for 0.1.0 and 2.0 hardening
2026-02-22 18:38:41 +01:00

3.2 KiB
Raw Blame History

Karapace Security Model

Core Invariants

  1. Host filesystem protected by default. No writes outside the store and overlay.
  2. No implicit /dev access. Device passthrough is explicit and opt-in.
  3. GPU passthrough requires hardware.gpu = true in the manifest.
  4. Audio passthrough requires hardware.audio = true in the manifest.
  5. Network isolation is configurable via runtime.network_isolation.
  6. No permanent root daemon required. All operations are rootless.
  7. No SUID binaries required.

Mount Policy

  • Absolute host paths are checked against a whitelist.
  • Default allowed prefixes: /home, /tmp.
  • Relative paths (e.g. ./) are always allowed.
  • Mounts outside the whitelist are rejected at build time.

Device Policy

  • Default policy denies all device access.
  • hardware.gpu = true adds /dev/dri to allowed devices.
  • hardware.audio = true adds /dev/snd to allowed devices.
  • No implicit device passthrough.

Environment Variable Control

  • A whitelist of safe environment variables is passed to the environment: TERM, LANG, HOME, USER, PATH, SHELL, XDG_RUNTIME_DIR.
  • A denylist prevents sensitive variables from leaking: SSH_AUTH_SOCK, GPG_AGENT_INFO, AWS_SECRET_ACCESS_KEY, DOCKER_HOST.
  • Only whitelisted, non-denied variables are propagated.

Resource Limits

  • CPU shares and memory limits are declared in the manifest.
  • The security policy enforces upper bounds.
  • Exceeding policy limits causes a build failure, not a silent cap.

Privilege Model

  • No privileged escalation at any point.
  • User namespaces provide isolation without root.
  • The OCI backend uses rootless runtimes (crun, runc, youki).

Threat Model

Privilege Boundary

  • Karapace operates entirely within the user's privilege level.
  • The store is owned by the user and protected by filesystem permissions.
  • No daemon runs with elevated privileges.

Attack Surface

  • Manifest parsing: strict TOML parser with deny_unknown_fields.
  • Store integrity: blake3 verification on every object read.
  • Image integrity: blake3 digest stored on download, verified on cache hit.
  • Shell injection: all paths and values in sandbox scripts use POSIX single-quote escaping (shell_quote). Environment variable keys are validated against [a-zA-Z0-9_].
  • Mount injection: prevented by whitelist enforcement.
  • Environment variable leakage: prevented by deny/allow lists.
  • Concurrent access: file locking on all mutating CLI and D-Bus operations.
  • Process safety: cannot destroy a running environment (must stop first).
  • Rebuild atomicity: new environment is built before the old one is destroyed.

Isolation Assumptions

  • The host kernel provides functioning user namespaces.
  • The filesystem permissions on the store directory are correct.
  • The OCI runtime (if used) is trusted and correctly installed.

Security Review Checklist

  • No SUID binaries.
  • No root daemon.
  • Mount whitelist enforced.
  • Device passthrough explicit.
  • Environment variables controlled.
  • Resource limits supported.
  • Store integrity verified.
  • Concurrent access safe.
  • Signal handling (SIGINT/SIGTERM) clean.