Skip to content
z4j docs

Threat model

Actors

Section titled “Actors”
ActorCapabilityTrust
External attackerInternet traffic onlyUntrusted
Agent host (your app)Holds an agent token; can emit any eventsPartially trusted
Dashboard userHas a role on one or more projectsRole-scoped trust
Brain operatorFull DB + env accessFully trusted
Postgres adminDirect SQLFully trusted (breaks audit-log semantics)

Assumptions

Section titled “Assumptions”
  • TLS terminates in front of z4j. No plaintext HTTP in production.
  • Env vars are secret. Leaking Z4J_SECRET (the master HMAC key, used for both frame signing and the audit-log row chain) compromises sessions and audit integrity. Leaking Z4J_SESSION_SECRET compromises user sessions.
  • Postgres is on a private network. Direct access is the operator’s responsibility.
  • Time is monotonic enough. Audit log ordering is by ID (sequence), not wall time.

In-scope threats

Section titled “In-scope threats”
  1. Credential stuffing / brute force - defended by argon2id + rate limits + dummy-hash timing.
  2. Session theft - HttpOnly + Secure + SameSite=Lax cookies; session invalidation on password change.
  3. Prompt injection via events - event payloads are data, never instructions. z4j never evals or templates untrusted text into action pipelines.
  4. Token enumeration - tokens are HMAC-hashed; wrong-token login takes the same time as right-token-wrong-password (dummy hash).
  5. Agent impersonation - tokens are per-agent; revocation immediate. (project_id, name) uniqueness prevents duplicate-register races.
  6. Replay attacks - WebSocket frames have monotonic seq; duplicates deduped on persist.
  7. SSRF via public_url - Z4J_PUBLIC_URL is validated (no whitespace, no user:pass, http/https only).
  8. Audit tampering - HMAC chain detects it. Not prevented at the DB level - see “out of scope” below.

Out of scope

Section titled “Out of scope”
  • Physical access to brain host / Postgres - anyone with DB access can rewrite audit. The chain makes it detectable, not impossible.
  • MFA, SSO, OAuth2 - not currently shipped. Out-of-band MFA (e.g. forwarding auth through an SSO proxy in front of the brain) is the recommended interim path.
  • Compliance certifications (SOC 2 / HIPAA / ISO 27001) - z4j is not certified. The audit log export plus Postgres backups provide raw evidence; operators own policies, controls, and external audit.
  • Browser fingerprinting / anti-automation - we’re not that kind of product.

Disclosed audits

Section titled “Disclosed audits”
  • Pre-release internal audits documented in docs/SECURITY_AUDIT_PRERELEASE.md in the repo.

Reporting issues

Section titled “Reporting issues”

security@z4j.com. Do not file a public issue for undisclosed vulnerabilities. See disclosure.