AUGUR & VIGIL

This page covers the two behavioural and health-monitoring subsystems of CITADEL. AUGUR is the behavioural-heuristics layer at Gate 4 of the MARSHAL engine — it asks whether a request fits the normal pattern of how the caller behaves, catching insider abuse and credential-compromise attacks that pass cleanly through the first three gates. VIGIL is the ecosystem-wide health monitor that synthesises telemetry from every SIN platform into a single colour-coded signal (GREEN / AMBER / RED).

Overview

Gates 1–3 of MARSHAL answer an authorisation question: "is this caller allowed to do this?". AUGUR at Gate 4 asks a different question: "does this action fit the normal behavioural pattern for this caller?". A credential-compromise or insider attack may clear every permission check while still exhibiting observable anomalies — unusual timing, burst frequency, or a data export with no associated investigation. AUGUR surfaces those signals before the action reaches the WORM log.

AUGUR reads from a read-only mirror database. It does not hold locks on the main write path and cannot itself delay or block WORM appends. Its influence on MARSHAL outcomes is mediated entirely through the verdict mechanism described below.

AUGUR — Gate 4 in MARSHAL

AUGUR is the fourth gate in the five-gate MARSHAL pipeline. The gate sequence is:

Request
  → Gate 1: AuthN   (Ed25519 signature)
  → Gate 2: AuthZ   (RBAC permission check)
  → Gate 3: NDS     (actor ≠ verifier, SoD enforcement)
  → Gate 4: AUGUR   (behavioural heuristics)
  → Gate 5: WORM    (unconditional append — every request is logged)

AUGUR evaluates its rule catalogue against the incoming Kerkese (the CITADEL governance request object) and emits one of three statuses: PASS, WARN, or HARD_STOP. That status is then factored into the overall MARSHAL verdict before the WORM append at Gate 5.

Rule catalogue (v1.0.0)

Three rules ship with v1.0.0. They are intentionally conservative — an enterprise can tune thresholds through configuration, but the rule shape is stable and WORM-observable so auditors can reproduce decisions without re-running the engine. Expanding the catalogue is explicitly out of scope until v1.2, at which point a rule-as-code plugin system becomes justifiable.

rule_01 — Off-hours action

Condition: the request's ts_utc falls outside the 07:00–19:00 UTC business-hours window.

"cm">// Gate 4 — rule_01
if kerkese.TsUtc.Hour() < 7 || kerkese.TsUtc.Hour() >= 19 {
    reasons = append(reasons,
        fmt.Sprintf("AUGUR_rule_01: action initiated outside business hours(hour=%d UTC)",
            kerkese.TsUtc.Hour()))
    status = WARN
}

Rationale: most legitimate operator activity happens during business hours. An action at 03:00 UTC is worth flagging even if it passes every other gate. The rule deliberately emits a WARN rather than a block — a hard block on off-hours would cause too many false positives for 24/7 operations, but the warn surface is sufficient for after-the-fact review.

Reason string: AUGUR_rule_01: action initiated outside business hours (hour=N UTC)

Future tuning: the business-hours window will be configurable via CITADEL_AUGUR_BUSINESS_HOURS_START and CITADEL_AUGUR_BUSINESS_HOURS_END environment variables in v1.1+.

rule_02 — High frequency

Condition: the same actor.user_id has logged more than 10 Kerkese evaluations in the last 5 minutes.

"cm">// Gate 4 — rule_02
count, err := store.ActionCount(ctx, kerkese.Actor.UserID, 5*time.Minute)
if err == nil && count > 10 {
    reasons = append(reasons,
        fmt.Sprintf("AUGUR_rule_02: high frequency(%d actions in 5min)", count))
    if status < WARN {
        status = WARN
    }
}

Rationale: human operators rarely sustain more than 10 governed actions in 5 minutes. Spikes indicate either a scripted attack attempting to race past a window, or a legitimate automation that should be migrated to a service role token. The frequency counter is maintained by the WORM append path as a sliding window — no separate time-series store is required.

Reason string addition: AUGUR_rule_02: high frequency (N actions in 5min)

rule_03 — DATA_EXPORT without incident

Condition: action.type == "DATA_EXPORT" AND action.incident_id is empty.

"cm">// Gate 4 — rule_03
if kerkese.Action.Type == "DATA_EXPORT" && kerkese.Action.IncidentID == "" {
    reasons = append(reasons,
        "AUGUR_rule_03: DATA_EXPORT attempted without incident_id — HARD_STOP")
    status = HARD_STOP "cm">// overrides any prior WARN
}

Rationale: data exfiltration without an active incident context is the single highest-risk pattern in the threat model. An attacker who has captured a live session will often attempt a bulk export first; an honest operator always ties exports to a specific investigation. This rule is the only AUGUR rule that forces a HARD_STOP outcome.

Status severity

How heuristics influence the verdict

AUGUR's status severity maps directly onto MARSHAL's verdict semantics, but with an important distinction: WARN is advisory — it enriches the audit record and surfaces anomalies to reviewers without blocking the operation. HARD_STOP is blocking and overrides any permissive result from earlier gates.

The WARN advisory model is deliberate. AUGUR is designed to complement the permission model, not duplicate it. Operators reviewing a week's audit log can search for AUGUR_rule_01 to identify after-hours patterns without having been paged at the time — the signal is preserved in the WORM chain and accessible later.

Interaction with IRFlow

When AUGUR emits HARD_STOP, the downstream effect in IRFlow is automatic:

1. POST /api/v1/incidents/.../actions returns 403 ErrMarshalHardStop.
2. If the CITADEL → IRFlow HARD_STOP webhook is configured, IRFlow receives a citadel.marshal.hard_stop event and creates a P1 incident automatically.
3. A project-freeze runbook fires if configured on the incident type.
4. On-call is paged via the incident's notification policy.

WARN statuses are audit-only: IRFlow logs them into the action's marshal_decision field but does not escalate. The warn is visible to anyone reviewing the action after the fact.

Observability

AUGUR exposes two Prometheus counters:

Recommended alerting rule: rate(citadel_augur_hard_stops_total[5m]) > 0 — any HARD_STOP event is per-se incident-worthy and warrants immediate review. rule_01 and rule_02 WARNs are expected background noise; alert only when they exceed 10 % of all MARSHAL decisions over a sustained window.

Tuning guidance

VIGIL — Ecosystem health monitor

VIGIL answers one question for every platform in the opensecstack ecosystem: "Is now a safe time to perform governance-relevant work?" It synthesises telemetry from CITADEL, IRFlow, ThreatFlow, NIS2 Compass, and APIGuard into a single colour-coded health signal that MARSHAL will consult at decision time.

GREEN / AMBER / RED states

Aggregation rule: RED dominates AMBER dominates GREEN. Any single RED input forces the overall status to RED. The individual input colours are exposed separately on the VIGIL endpoint so operators can see which dimension triggered the escalation.

Telemetry inputs

VIGIL is a consumer of telemetry, not a producer. Its planned inputs span five subsystems:

The planned endpoint response surface looks like this (v1.2+):

{
  "overall":    "AMBER",
  "updated_at": "2026-04-19T10:15:00Z",
  "components": [
    { "name": "worm_chain",    "status": "GREEN", "since": "2026-04-12T00:00:00Z" },
    { "name": "irflow_p1",     "status": "AMBER", "value": 2,    "threshold": "> 0",  "since": "2026-04-19T08:22:00Z" },
    { "name": "nis2_success",  "status": "GREEN", "value": 99.2 },
    { "name": "apiguard_crit", "status": "GREEN", "value": 1 },
    { "name": "threatflow",    "status": "GREEN", "since": "2026-04-12T00:00:00Z" }
  ]
}

Interaction with MARSHAL

In v2.0, VIGIL's output becomes an explicit input to MARSHAL gate evaluation. The interaction is designed to be in-band — VIGIL's state is available to MARSHAL at decision time, not just to a monitoring pager. Any VIGIL-driven MARSHAL outcome carries the colour state in the WORM entry, so auditors can reconstruct what VIGIL showed at the exact moment of any decision.

This design separates VIGIL from Prometheus alerting. Prometheus dashboards show per-service numbers; VIGIL combines them into a single cross-platform signal that influences governance decisions and is recorded in the immutable audit chain.

Implementation timeline