MARSHAL Engine

MARSHAL is CITADEL's 5-gate cryptographic authorisation engine. Every privileged action from every platform in the opensecstack ecosystem passes through it before execution. The outcome — EXECUTE, REFUSE, or HARD_STOP — plus the gate-by-gate reasoning is unconditionally appended to the WORM audit chain at Gate 5, regardless of whether prior gates passed.

Overview

Each governance request — called a Kerkese — flows through five sequential gates. Gates 1 through 4 can short-circuit the outcome verdict, but evaluation always continues through to Gate 5. Gate 5 always runs: an unrecorded rejection is worse than an unrecorded execution because it leaves no trace of attempted abuse. The final outcome is the maximum severity observed across all gates.

MARSHAL is invoked by calling POST /api/v1/marshal/evaluate on port 8099. See the CITADEL Integration guide for how platforms register and connect. Every platform connector must include an X-Citadel-Signature HMAC-SHA256 header computed over key_id + timestamp + body_hash. Requests outside a ±300-second timestamp window are rejected before any gate runs.

Gate sequence

Kerkese → Gate 1 (AuthN) → Gate 2 (AuthZ) → Gate 3 (NDS) → Gate 4 (AUGUR) → Gate 5 (WORM)
          (session)     (RBAC)         (SoD)        (heuristics)   (audit — always runs)
                                                                           ↓
                                                                    Final decision written

Gate 1 — AuthN (Authentication)

Gate 1 asks: does actor.user_id have a valid session, and does the claimed role match what the session recorded?

Implementation: Store.SessionExists(ctx, userID) returns the session's recorded (role, roleGroup, exists, err) tuple. If the lookup returns an error, or no session exists, or the claimed role in the Kerkese does not equal the session role, Gate 1 fails.

Outcome on fail: REFUSE. Approximate latency on an in-memory store: ~0.8 µs.

Gate 2 — AuthZ (Authorisation)

Gate 2 asks: is actor.role permitted to perform action.type? The check is implemented as an in-code RBAC map (roleAllowed(role, actionType)). Typical mapping: admin can perform any action; operator can execute CONTAIN, PATCH, CREATE_INCIDENT; an verifier can execute VERIFY.

If the role/action pair is absent from the map, Gate 2 returns REFUSE with reason AUTHZ_FAIL: role "X" is not permitted to perform "Y". Approximate latency: ~0.3 µs.

Gate 3 — NDS (Separation of Duties)

Gate 3 enforces the two-key principle: the action must be backed by two distinct identities that belong to different role groups. The checks run in order:

"cm">// 1. Same-identity check — HARD_STOP
if sod.OperatorUserID == sod.VerifierUserID {
    return HARD_STOP("NDS_SAME_IDENTITY: operator and verifier are the same user")
}

"cm">// 2. Both parties must have valid sessions
opSession := store.SessionExists(operatorUserID)
vfSession  := store.SessionExists(verifierUserID)

"cm">// 3. Role-group check — HARD_STOP
if opSession.roleGroup == vfSession.roleGroup && opSession.roleGroup != "unknown" {
    return HARD_STOP("NDS_SAME_GROUP: operator and verifier are both in role group X")
}

Same-identity is a HARD_STOP, not a REFUSE, because passing the same user ID for both parties is a deliberate attempt to defeat the separation control. Downgrading it to REFUSE would invite a retry loop. A HARD_STOP escalates to IRFlow's P1 incident auto-creation and a project freeze. Approximate Gate 3 latency: ~1.2 µs.

Gate 4 — AUGUR (Behavioural Heuristics)

Gate 4 applies pre-emptive behavioural analysis. AUGUR reads from a read-only mirror database and does not modify state. Three rules are evaluated in sequence; rule_03 can override the result of rules 01 and 02.

rule_03 overrides anything set by rules 01 and 02 because data exfiltration without an incident context is the highest-risk pattern MARSHAL tracks. A WARN status from rules 01 or 02 does not block execution on its own — Gate 4's contribution is additive. The final outcome becomes REFUSE only if an earlier gate said so; HARD_STOP from rule_03 takes precedence unconditionally. Approximate Gate 4 latency: ~1.5 µs.

Gate 5 — WORM (Audit)

Gate 5 commits the full decision to the append-only WORM chain:

Store.AppendWORM(ctx, source, eventType, projectID, payload)
"cm">// payload = full JSON of the decision:
"cm">//   kerkese, outcome, all five gate results, reason strings, latencies

If the WORM append fails (e.g. the database is temporarily unreachable), Gate 5 logs a WARN result on itself but does not reverse the outcome of gates 1–4. The decision still stands; only the audit trail for that specific entry is lost. The metric citadel_worm_append_failures_total increments and an alert fires — Ops must resolve this urgently.

The project_id field defaults to "citadel" when the Kerkese carries none. This lets auditors partition chain queries per tenant, service, or regulator jurisdiction without scanning the full log.

Gate 5 is the dominant performance cost. With a synchronous PostgreSQL 16 write the typical latency is 4.22 ms, dwarfing the sub-2 µs total of gates 1–4. Candidates for v1.1+ optimisation: batched appends and per-project_id sharded chains (v2.0).

Kerkese schema

A Kerkese (Albanian: request) is the canonical envelope every caller sends to POST /api/v1/marshal/evaluate. The schema is at v2.0.

At ingress, CITADEL validates: JSON parses; actor.user_id > 0; actor.role != ""; action.type != ""; ts_utc is valid RFC3339. All other checks are gate-level.

Worked example

The following Kerkese represents IRFlow asking CITADEL to authorise a containment action on incident inc_2026_0123. Operator user 42 (role: operator) initiates; verifier user 77 (a different role group) approves.

{
  "execution_id": "7e9a9a7e-2a1f-4c13-9f60-5a1f2e0d1a98",
  "project_id":   "prod",

  "actor": {
    "user_id": 42,
    "role":    "operator"
  },

  "sod": {
    "operator_user_id": 42,
    "verifier_user_id": 77
  },

  "action": {
    "type":         "CONTAIN",
    "incident_id":  "inc_2026_0123",
    "payload_hash": "sha256:abcd1234ef567890abcd1234ef567890abcd1234ef567890abcd1234ef567890"
  },

  "dry_run": false,
  "ts_utc":  "2026-04-19T10:12:03Z"
}

Verdicts and response envelope

MARSHAL returns one of three verdicts for every Kerkese evaluation:

The response envelope for the worked example above (all gates passing) looks like:

{
  "execution_id": "7e9a9a7e-2a1f-4c13-9f60-5a1f2e0d1a98",
  "outcome":      "EXECUTE",
  "dry_run":      false,
  "ts_utc":       "2026-04-19T10:12:03.412Z",
  "gates": [
    { "gate": 1, "name": "AuthN",  "status": "PASS", "latency_ms": 0.84 },
    { "gate": 2, "name": "AuthZ",  "status": "PASS", "latency_ms": 0.21 },
    { "gate": 3, "name": "NDS",    "status": "PASS", "latency_ms": 1.12 },
    { "gate": 4, "name": "AUGUR",  "status": "PASS", "latency_ms": 1.43 },
    { "gate": 5, "name": "WORM",   "status": "PASS", "latency_ms": 4.22 }
  ],
  "reasons":       [],
  "worm_entry_id": "wo_0000017234"
}

reasons is empty when outcome == EXECUTE. Otherwise it contains the concatenated reason strings from all failing gates in gate order. The worm_entry_id is present whenever Gate 5 succeeded — callers can quote this ID when later retrieving the WORM entry for forensics. The entry is present even when gates 1–4 rejected the call, because Gate 5 always runs.

A REFUSE from Gate 2 (wrong role) would look like:

{
  "execution_id": "9b3c1f2a-0011-4e78-b42a-d88e9cf10003",
  "outcome":      "REFUSE",
  "dry_run":      false,
  "ts_utc":       "2026-04-19T11:05:44.107Z",
  "gates": [
    { "gate": 1, "name": "AuthN",  "status": "PASS",   "latency_ms": 0.79 },
    { "gate": 2, "name": "AuthZ",  "status": "REFUSE",  "latency_ms": 0.18,
      "reason": "AUTHZ_FAIL: role \"viewer\" is not permitted to perform \"CONTAIN\"" },
    { "gate": 3, "name": "NDS",    "status": "SKIP",   "latency_ms": 0.00 },
    { "gate": 4, "name": "AUGUR",  "status": "SKIP",   "latency_ms": 0.00 },
    { "gate": 5, "name": "WORM",   "status": "PASS",   "latency_ms": 4.19 }
  ],
  "reasons":       ["AUTHZ_FAIL: role \"viewer\" is not permitted to perform \"CONTAIN\""],
  "worm_entry_id": "wo_0000017235"
}

Outcome resolution

The final outcome is the maximum severity observed across gates 1–4:

EXECUTE  <  REFUSE  <  HARD_STOP

If any gate escalated to HARD_STOP, the outcome is HARD_STOP — even if a later gate would have returned REFUSE or EXECUTE. Reason strings from every failing gate are concatenated into decision.reasons[] for debugging and forensic review.

Dry-run mode

Setting dry_run: true in the Kerkese instructs MARSHAL to produce a full Decision without calling the Gate 5 WORM append. Use cases:

• Caller-side integration tests.
• Policy validation before rollout ("what would happen if…?").
• Reproducing an audit finding locally without polluting the live chain.

Performance

Measured on Go 1.24.4, Intel Core i7-7600U, in-memory mock store unless noted.