Pimatika Security Model¶

MVP Trust Boundary Statement¶

Where the workload runs decides what the guarantee is.

Pimatika is a judge: it returns an allow/deny verdict on a candidate outbound action, and something else has to honour it.

Inside a NaZelo sandbox, the kernel honours it. pimatika-nazelo compiles the manifest's targets into NaZelo's eBPF egress allow-list, and the kernel drops anything the manifest does not name. A process that never calls the enforcer reaches nothing it was not granted; declining to cooperate is not an option it has.

On a bare host, the host process honours it, and that is cooperative: a process that bypasses the Pimatika call-site can still make outbound connections.

That boundary is deliberate. Filtering egress at the node is a solved problem with mature implementations, and every one of them does it without a manifest. What none of them does is derive the verdict from a signed manifest and seal it as evidence. So the kernel guarantee is offered where it can be given whole: inside a NaZelo sandbox. Off that path Pimatika is a judge, and the verdict is honoured by whatever already filters your nodes.

Signing Key Resolution¶

Pimatika uses the same signing-key resolution as litatoli-core (SigningKey::load):

LITATOLI_SIGNING_KEY environment variable (64 hex chars).
File at LITATOLI_KEY_FILE, else $HOME/.config/litatoli/signing.key, if it exists (raw 32 bytes).

There is no auto-generation fallback for the BLAKE3 signing key: if neither source yields a key, load() errors. LITATOLI_SIGNING_KEY (or a key file) must be set in production — a per-host auto-minted MAC key has no rotation/distribution story. Only the optional Ed25519 secondary signer (LITATOLI_ED25519_KEY) auto-generates and persists a keypair (mode 0600) at its default path.

The signing algorithm is keyed BLAKE3 (blake3-keyed, 32-byte key).

`REQUEST_ID_MISSING` Warning¶

Every EgressRequest SHOULD carry a caller-supplied request_id for end-to-end correlation and idempotency. When missing, Pimatika generates a UUIDv7 and emits the request_id_missing_warning: true flag on the resulting EgressDecision. Absent caller-supplied IDs, downstream idempotency (Week 3 evidence write) MUST NOT assume the ID is stable across retries — Pimatika-generated IDs are fresh per call.

DNS Drift Limitation (v1)¶

Pimatika v1 performs exact string comparison of resolved targets against signed usage_contracts. It does not pin IP addresses, observe DNS TTL evolution, or detect rebinding attacks where a hostname's A/AAAA records shift between Pimatika's check and the actual connection. Operators requiring DNS pinning must combine Pimatika with whatever pins resolution at your node level.

HTTP Redirects¶

Pimatika's exact-match discipline is defeated by redirect following. Callers MUST configure their HTTP client to reject redirects (or handle them by re-submitting a fresh EgressRequest for the redirected target).

Signature Model¶

Pimatika's BIM signatures and Litatoli's evidence entry signatures use a keyed-BLAKE3 MAC (blake3-keyed). This is a symmetric authenticator: it provides integrity and authenticity within a trust domain that shares the 32-byte key, but it is NOT a public-key signature and is NOT non-repudiable.

For non-repudiation the BIM additionally supports an Ed25519 dual signature (policy_identity.ed25519_signature + ed25519_pubkey, both over the same canonical bytes as the MAC; the pubkey is covered by the signatures so it cannot be swapped without re-signing). sign-bim produces it when an Ed25519 key is provisioned (litatoli key resolution; generate with litatoli keygen); verify-bim-ed25519 verifies it without any shared secret — the third-party/auditor path. Verification is fail-closed on pinning: the expected public key must be supplied (--expected-pubkey) unless unpinned mode is explicitly allowed. The MAC remains mandatory in-domain; Ed25519 is layered on top, mirroring litatoli's evidence-entry model. stamp-bim timestamps the Ed25519 signature when present (else the MAC), keeping the auditor chain — pubkey → signature → RFC 3161 time — verifiable end-to-end without the MAC secret.

Commercial extensions¶

pimatika-core is the OSS trust boundary described in this document. pimatika-pro (premium drift heuristics) and pimatika-saas (managed BIM signing) extend this boundary — their trust models are documented in their respective private repos.