Security Model¶

Verity implements a defence-in-depth security architecture spanning authentication, authorisation, network isolation, secrets management, data encryption, and continuous security scanning.

Authentication¶

Azure AD / Microsoft Entra ID — OAuth 2.0 (OIDC)¶

All API requests are authenticated via JSON Web Tokens (JWT) issued by Microsoft Entra ID (formerly Azure AD). The API Gateway validates every incoming token before routing to downstream services.

sequenceDiagram
    autonumber
    participant User as User / Client
    participant Entra as Microsoft Entra ID
    participant API as API Gateway
    participant SVC as Downstream Service

    User->>Entra: Authenticate (OAuth 2.0 / OIDC)
    Entra-->>User: Access Token (JWT)
    User->>API: Request + Bearer Token
    API->>API: Validate JWT signature (JWKS)
    API->>API: Verify issuer, audience, expiry
    API->>API: Extract roles from token claims
    API->>SVC: Forward request + security context
    SVC-->>API: Response
    API-->>User: Response

Token Validation¶

Configuration¶

Development Mode¶

When API_AUTH_DISABLED=true:

• All requests are treated as authenticated.
• A synthetic admin identity is injected into the security context.
• RBAC checks are bypassed.
• An audit event with action=auth.dev_bypass is logged on every request.

Authorisation — Role-Based Access Control (RBAC)¶

Verity enforces RBAC using four roles defined as Entra ID App Roles. Roles are carried in the JWT roles claim and evaluated by the API Gateway middleware.

Role Definitions¶

Role-to-Endpoint Mapping¶

RBAC Middleware¶

flowchart TD
    A[Incoming Request] --> B{JWT Present?}
    B -->|No| C[401 Unauthorized]
    B -->|Yes| D{JWT Valid?}
    D -->|No| C
    D -->|Yes| E[Extract roles claim]
    E --> F{Role authorized<br/>for endpoint?}
    F -->|No| G[403 Forbidden]
    F -->|Yes| H[Forward to handler]
    H --> I[Emit audit event]

Network Policies¶

Verity deploys 21 Kubernetes NetworkPolicies that enforce a zero-trust network model within the cluster. All traffic is denied by default; only explicitly permitted flows are allowed.

Policy Summary¶

Network Architecture Diagram¶

flowchart TB
    subgraph EXTERNAL["External"]
        ING[Ingress Controller]
        SRC[Source Systems<br/>Entra ID / Snowflake / etc.]
    end

    subgraph VERITY["namespace: verity"]
        API[api-gateway :8000]
        DUI[dashboard-ui :3000]
        CON[connectors]
        IW[ingest-worker]
        NE[normalise-engine]
        DE[decay-engine]
        RG[review-generator]
        WE[workflow-engine]
        RE[remediation-executor]
        AW[audit-writer]
    end

    subgraph INFRA["namespace: verity-infra"]
        PG[(PostgreSQL :5432)]
        CH[(ClickHouse :8123)]
        KF[[Kafka :9092]]
        RD[(Redis :6379)]
        TM[Temporal :7233]
    end

    ING -->|443→8000| API
    ING -->|443→3000| DUI
    CON -->|443| SRC
    RE -->|443| SRC

    API --> PG
    API --> RD
    CON --> KF
    IW --> KF
    NE --> KF
    NE --> PG
    DE --> KF
    DE --> PG
    RG --> KF
    RG --> PG
    WE --> TM
    WE --> KF
    RE --> KF
    AW --> KF
    AW --> CH

Secrets Management¶

Kubernetes Secrets¶

All sensitive configuration is stored in Kubernetes Secret objects and mounted as environment variables. No secrets are committed to source control.

Helm Integration¶

All Helm charts support an existingSecret pattern to reference pre-created secrets rather than generating them:

# values.yaml
postgresql:
  auth:
    existingSecret: verity-db-credentials
    secretKeys:
      userPasswordKey: POSTGRES_PASSWORD

redis:
  auth:
    existingSecret: verity-redis-credentials
    secretKeys:
      passwordKey: REDIS_PASSWORD

Data Encryption¶

Encryption in Transit¶

Encryption at Rest¶

Security Scanning¶

Verity integrates three layers of security scanning into the CI/CD pipeline.

Scanning Tools¶

CI Pipeline Integration¶

flowchart LR
    A[Git Push] --> B[Lint & Format]
    B --> C[Bandit SAST]
    B --> D[Semgrep Scan]
    C --> E{Security<br/>Gate}
    D --> E
    E -->|Pass| F[Unit Tests]
    E -->|Fail| G[❌ Block Merge]
    F --> H[Build Docker Images]
    H --> I[Trivy Scan]
    I --> J{Vulnerability<br/>Gate}
    J -->|Pass| K[Push to Registry]
    J -->|CRITICAL/HIGH| G
    K --> L[Deploy to Staging]

Scanning Policies¶

Audit Trail¶

ClickHouse Audit Log¶

Every significant action in the platform is recorded in the verity_audit table in ClickHouse. The audit log is append-only and immutable — no UPDATE or DELETE operations are permitted on the audit table.

See Database Schema — ClickHouse for the complete schema definition.

What Is Audited¶

Audit Retention¶

Compliance Considerations¶

Security Checklist¶

• API_AUTH_DISABLED is set to false (or unset).
• All Kubernetes Secrets are created and referenced via existingSecret.
• TLS certificates are provisioned for all external endpoints.
• sslmode=require is set on all PostgreSQL connection strings.
• Kafka is configured with SASL_SSL and SCRAM-SHA-512.
• All 21 NetworkPolicies are applied to the verity and verity-infra namespaces.
• Trivy scanning is enabled in CI with CRITICAL,HIGH blocking.
• Bandit and Semgrep are running on every pull request.
• Nightly security scans are scheduled on main.
• ClickHouse audit table has no UPDATE or DELETE grants for any user.
• etcd encryption is enabled for Kubernetes Secrets.
• Ingress controller enforces TLS 1.2+ with strong cipher suites.