Security Model

This document describes Hexarch’s threat model, trust boundaries, and security assumptions. It also states what Hexarch does not protect against.

Trust Boundaries

Hexarch operates at three trust boundaries:

1. Control Plane ↔ Data Plane

The control plane (Hexarch application) manages policy and configuration. The data plane (gateway nodes) enforces policy at runtime.

Trust assumption: The control plane is authoritative. Gateway nodes trust configuration received from the control plane.

Verification mechanism: Configuration snapshots reference immutable artifacts that include a cryptographic hash.

interface ConfigArtifact {
  id: string;
  hash: string; // Content hash
}

interface ConfigSnapshot {
  id: string;
  artifactId: string; // Points to the hashed artifact
}

interface GatewayNode {
  appliedSnapshotId: string;
  desiredSnapshotId: string;
  status: 'Ready' | 'Starting' | 'Error' | 'Divergent';
}

2. Gateway ↔ Backend Services

The gateway sits in front of backend services. It enforces policy before forwarding requests.

Trust assumption: Requests that pass the gateway are authorized. Backend services can trust the gateway’s decision.

Actor context headers: The gateway forwards actor identity to backends:

X-Actor-Id: user_123
X-Actor-Type: user

Backend services should validate these headers came from the gateway (e.g., via mTLS or shared secret), not accept them from arbitrary sources.

3. Audit Chain ↔ External Verifiers

Audit records form a hash chain. External parties can verify the chain without trusting the database.

Trust assumption: If the chain verifies, records are intact. If verification fails, tampering occurred.

Limitation: The chain proves integrity, not correctness. It proves records weren’t altered, not that they were accurate when created.

Threat Model

What Hexarch Protects Against

Unauthorized access at the gateway Policies enforce default-deny. Requests without valid authorization context are rejected.

failureMode: 'Fail Closed'  // Deny on policy failure

Post-hoc audit tampering Hash-linked records make alterations visible. The verify_chain() function detects broken links.

Configuration drift Authority vs. execution tracking shows when nodes diverge from desired state. Force reconciliation restores consistency.

Entitlement sprawl Version-locked subscriptions bind consumers to specific API versions. Changes require explicit action.

Rate limit bypass Per-plan rate limiting at the gateway. Requests exceeding limits are rejected before reaching backend services.

What Hexarch Does NOT Protect Against

Compromised control plane If an attacker gains access to the Hexarch control plane, they can modify policies, create subscriptions, and alter configuration. The audit chain records their actions, but doesn’t prevent them.

Mitigation: Role-based access control, audit logging of administrative actions, justification requirements for sensitive operations.

Compromised gateway nodes If an attacker compromises a gateway node, they can bypass policy enforcement for traffic through that node.

Mitigation: Fleet governance shows divergent nodes. Cryptographic verification detects unexpected state. But a sophisticated attacker could falsify reports.

Insider threats with database access If someone has direct database access, they could theoretically truncate the audit chain, rewrite history, and rebuild hashes.

Mitigation: Database access controls, separate audit storage, periodic chain snapshots to external systems.

Application-level vulnerabilities Hexarch enforces authorization at the gateway. It doesn’t protect against SQL injection, XSS, or other vulnerabilities in backend services.

Mitigation: Hexarch is a layer, not a replacement for application security.

Denial of service Rate limiting controls traffic volume, but Hexarch itself can be targeted. Gateway nodes under extreme load may fail.

Mitigation: Standard DDoS protection, horizontal scaling, health monitoring.

Cryptographic Assumptions

Hash Function

Hexarch uses SHA-256 for content hashing and chain linking.

Assumption: SHA-256 is collision-resistant. Two different records will not produce the same hash.

If SHA-256 is broken: An attacker could create fraudulent records with matching hashes. This is a theoretical concern; SHA-256 remains secure as of this writing.

Signature Scheme

When signatures are enabled, Hexarch signs audit records with the authority’s private key.

Assumption: The private key is kept secure. Signatures prove authorship only if the key is uncompromised.

Key management: Hexarch does not prescribe a key management system. Integrate with your existing HSM, KMS, or secrets manager.

Failure Modes

Policy Execution Failures

From the FailureMode enum:

enum FailureMode {
  FAIL_OPEN = 'Fail Open',
  FAIL_CLOSED = 'Fail Closed'
}

Security-critical policies (authentication, authorization) should use FAIL_CLOSED. If the policy can’t execute, the request is denied.

Non-critical policies (caching, analytics) may use FAIL_OPEN. If the policy fails, the request proceeds without that policy’s effect.

Node Failures

When a gateway node fails:

Traffic is routed to healthy nodes (load balancer responsibility)
The failed node appears as status: 'Offline' in Fleet Governance
When recovered, it reconciles to the desired configuration

Gap: During failure, the node isn’t processing traffic. No decisions are recorded for traffic that didn’t reach it.

Chain Verification Failures

If verify_chain() returns ok: false:

The chain has been tampered with, OR
Records are missing (gaps in the sequence), OR
A storage error corrupted data

Response: Investigate. Determine if this is an attack or an operational issue. The chain doesn’t tell you which—only that something is wrong.

Security Recommendations

Use FAIL_CLOSED for security policies. Don’t default to permissive on failure.
Enable signatures. Hashes prove integrity; signatures prove authorship.
Restrict control plane access. Hexarch enforces policy, but policy editors can change what’s enforced.
Monitor fleet cohesion. Divergent nodes may indicate compromise or misconfiguration.
Export audit snapshots. Don’t rely solely on the database. Periodic exports to immutable storage provide defense in depth.
Validate actor headers in backends. Don’t trust X-Actor-Id from arbitrary sources. Verify requests came through the gateway.

Non-Goals

Hexarch is not:

A WAF (Web Application Firewall). It doesn’t inspect payloads for attacks.
An IDS/IPS. It doesn’t detect intrusion patterns.
A secrets manager. It doesn’t store credentials (except for its own operation).
A complete security solution. It’s a layer in your security architecture.