Purple8 Hyper Graph — Deployment Hardening Guide

Release: v0.72.0
Date: 2026-10-26
Audience: DevOps / Platform Engineers / Security Teams
Style: CIS Benchmark-inspired (Level 1 = essential, Level 2 = defence-in-depth)

---

Quick Reference

Section	Controls	Level 1	Level 2
1. Authentication & Secrets	6	6	6
2. Encryption	5	4	5
3. Container, OpenShift & OS	8	6	8
4. Network	4	3	4
5. Multi-Tenancy & Write Admission	4	4	4
6. Monitoring, Integrity Scrub & Audit	6	4	6
7. Backup & Recovery	4	3	4
Total	37	30	37

---

1. Authentication & Secrets

1.1 — JWT Secret (Level 1) ⚠️ CRITICAL

# Generate a cryptographically strong secret
export P8G_JWT_SECRET=$(openssl rand -hex 32)

Verify: Purple8 refuses to start with the default placeholder secret when P8G_ENV != development.

✅ Do	❌ Don't
Use ≥256-bit random secret	Use dev-secret-change-in-production
Rotate quarterly	Hardcode in source control
Store in Vault / AWS Secrets Manager	Pass as CLI argument (visible in ps)

1.2 — API Keys (Level 1)

• API keys are 256-bit random tokens generated server-side
• Revoke unused keys immediately (DELETE /auth/api-keys/{key_id})
• Set P8G_API_KEY_MAX_AGE_DAYS to enforce automatic expiry

1.3 — Bootstrap Token (Level 1)

• Used only during initial super_admin creation
• Rotate immediately after first use: DELETE /auth/bootstrap-token
• Never share across environments

1.4 — Password Policy (Level 1)

Purple8 enforces minimum password strength at the API layer. Verify:

• Minimum 12 characters
• Mixed case + digit + special character
• Account lockout after 5 failed attempts

1.5 — Session Cookie Security (Level 1)

LCNC console sessions use:

• HttpOnly — not accessible from JavaScript
• SameSite=Strict — no cross-origin submission
• Secure — requires HTTPS (automatic when P8G_ENV=production)

Action: Always set P8G_ENV=production in non-dev deployments.

1.6 — MCP Agent Authentication (Level 1)

• Every MCP tool call across all 125 MCP tools (16 namespaces) requires a valid JWT or scoped API key
• Agent tokens should have the minimum required role (viewer for read-only agents)
• Set short token expiry for automated agents (≤1 hour)

---

2. Encryption

2.1 — Enable KMS Encryption (Level 1) ⚠️ CRITICAL

# Minimum: local KMS (single-host)
export P8G_KMS_PROVIDER=local
export P8G_KMS_KEY_ID=primary

# Production: external KMS
export P8G_KMS_PROVIDER=vault   # or: aws, gcp, azure
export P8G_KMS_KEY_ID=<your-key-id>
export P8G_KMS_VAULT_ADDR=https://vault.internal:8200
export P8G_KMS_VAULT_TOKEN=<token>

Verify: GET /health should show "encryption": "active".

2.2 — Enable Vector Index Encryption (Level 1 for regulated sectors)

# Required for Finance / Healthcare / Government
export P8G_ENCRYPT_VECTORS=true

Or programmatically:

engine = GraphEngine(path=db, kms_codec=codec, encrypt_vectors=True)

Verify: ls vectors/ shows .p8enc files and .p8enc_manifest, no plaintext .bin or .json.

2.3 — TLS Termination (Level 1)

Purple8 does not terminate TLS itself. Configure your reverse proxy:

# nginx example
server {
    listen 443 ssl;
    ssl_certificate     /etc/ssl/purple8.crt;
    ssl_certificate_key /etc/ssl/purple8.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://127.0.0.1:8100;
    }
}

2.4 — Disable Swap or Encrypt It (Level 1)

DEKs live in process RAM. Swap can write them to disk.

# Option A: disable swap entirely
sudo swapoff -a

# Option B: encrypted swap (macOS automatic, Linux requires dm-crypt)

2.5 — Encrypted Volumes (Level 2)

Even with Purple8's envelope encryption, defence-in-depth requires encrypted storage:

Platform	Solution
AWS	EBS encryption (default for new volumes)
GCP	Persistent Disk default encryption
Azure	Azure Disk Encryption
Linux bare metal	LUKS / dm-crypt

---

3. Container & OS Hardening

3.1 — Run as Non-Root (Level 1) ✅ Default

Dockerfile.commercial creates appuser (UID 1000). Verify:

docker exec purple8 whoami  # Should print: appuser

3.2 — Drop All Capabilities (Level 1) ✅ Default

# docker-compose.yml
cap_drop: [ALL]
cap_add: [NET_BIND_SERVICE]

3.3 — no-new-privileges (Level 1) ✅ Default

security_opt:
  - no-new-privileges:true

3.4 — Seccomp Profile (Level 1) ✅ Default

security_opt:
  - seccomp:deploy/seccomp-profile.json

Blocks: ptrace, mount, unshare, kexec_load, bpf, io_uring, process_vm_readv/writev.

3.5 — Read-Only Filesystem (Level 2)

read_only: true
tmpfs:
  - /tmp:size=100M
volumes:
  - ./data:/data  # Only the data directory is writable

3.6 — Resource Limits (Level 2)

deploy:
  resources:
    limits:
      memory: 24G
      cpus: "8"
    reservations:
      memory: 4G

3.7 — Minimal & Certified Base Images (Level 2)

Use Dockerfile.commercial (python:3.12-slim) or Dockerfile.rhel (registry.access.redhat.com/ubi9/python-312:9.5). Avoid ubuntu:latest (large attack surface).

3.8 — Red Hat OpenShift restricted SCC Compliance (Level 1 for OpenShift) ✅ Default in Dockerfile.rhel

Purple8 is an approved Red Hat Technology Partner and ships Dockerfile.rhel built on certified Red Hat Universal Base Image 9 (ubi9/python-312:9.5):

• Runs under OpenShift's default restricted Security Context Constraint without requiring anyuid or custom SCC relaxation.
• Supports OpenShift's arbitrary-UID execution model: all writable paths (/data, /backups, /app/logs, /opt/venv, /app) belong to group 0 with chmod g=u, and default to non-root UID 1001 outside OpenShift.
• Embeds /licenses/LICENSE and required Red Hat Ecosystem Catalog labels.

---

4. Network

4.1 — Bind to Localhost (Level 1)

If running behind a reverse proxy on the same host:

export P8G_HOST=127.0.0.1  # Not 0.0.0.0

4.2 — Restrict /metrics (Level 1)

By default, /metrics strips tenant labels. For full tenant metrics, set:

export P8G_METRICS_TOKEN=$(openssl rand -hex 16)

Configure your Prometheus scrape with:

authorization:
  credentials: "<P8G_METRICS_TOKEN>"

4.3 — CORS (Level 1)

export P8G_CORS_ORIGINS=https://app.yourcompany.com
# Never use * in production

4.4 — Network Policies (Level 2, Kubernetes)

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: purple8-ingress
spec:
  podSelector:
    matchLabels:
      app: purple8
  ingress:
    - from:
        - podSelector:
            matchLabels:
              role: api-gateway
      ports:
        - port: 8100

---

5. Multi-Tenancy

5.1 — Choose Isolation Mode (Level 1)

Mode	When to use	Config
Shared (prefix isolation)	Low-risk tenants, cost-sensitive	Default
Dedicated (filesystem isolation)	Regulated, compliance-critical	P8G_TENANCY_MODE=dedicated

5.2 — Validate Tenant IDs (Level 1) ✅ Automatic

validate_tenant_id() rejects: /, \, .., NUL, whitespace, ::, and strings >128 chars.

No action needed — this is always enforced.

5.3 — Per-Tenant Rate Limits & RSS Admission Gate (Level 1)

export P8G_WRITE_ADMISSION_LANES=4            # concurrent write lanes
export P8G_WRITE_ADMISSION_RSS_LIMIT_MB=20480  # 20 GB RSS cap

5.4 — Disk High-Watermark Write Admission Gate (Level 1) ✅ Six-Sigma Control

Prevent catastrophic ENOSPC mid-commit failure by rejecting incoming writes before the underlying storage volume fills completely:

export P8G_WRITE_ADMISSION_DISK_MAX_PCT=95.0  # Default: 95.0% (set to 0 to disable)

---

6. Monitoring & Audit

6.1 — Enable Prometheus Scraping (Level 1)

export P8G_METRICS_TOKEN=<scrape-secret>

Key metrics to alert on:

• soc_notification_failures_total > 0 — SOC alerts being dropped
• write_admission_rss_rejects_total > 0 — memory pressure
• request_duration_seconds{quantile="0.99"} > 5s — latency degradation

6.2 — Ship Logs to SIEM (Level 1)

Purple8 emits structured JSON logs (structlog). Ship via:

• Fluentd / Fluent Bit sidecar
• Docker logging driver (json-file → Loki / Datadog)
• stdout → Kubernetes pod logging → Splunk/Elastic

6.3 — Enable Audit Trail (Level 1) ✅ Default

Journey Engine audit edges are always on. Verify:

curl -H "Authorization: Bearer $TOKEN" https://purple8/admin/audit?limit=10

6.4 — SOC Webhook Configuration (Level 2)

export P8G_SOC_WEBHOOK_URL=https://siem.internal/api/events

Monitor soc_notification_failures_total — if this counter rises, alerts are being silently dropped.

6.5 — Backup Verification (Level 2)

Regularly test restore from backup to verify archive integrity.

6.6 — Online Non-Destructive Storage Scrub (Level 1) ✅ Six-Sigma Control

Run periodic online bit-rot and CRC32 integrity verification across BrickWAL frames and cold BrickCoreStorage slabs without taking the instance offline via POST /admin/storage/scrub.

---

7. Backup & Recovery

7.1 — Configure Automated Backups (Level 1)

export P8G_BACKUP_SCHEDULE="0 2 * * *"  # Daily at 02:00
export P8G_BACKUP_PATH=/backups/purple8/
export P8G_BACKUP_RETENTION_DAYS=30

7.2 — Streaming JSONL Backup & Archive Ceiling (Level 1) ✅ Six-Sigma Controls

Bound backup and restore memory usage on large graphs by enabling record-by-record JSONL streaming and enforcing a maximum archive size ceiling on restore:

export P8G_BACKUP_JSONL=1                 # Stream backup records line-by-line
export P8G_BACKUP_MAX_ARCHIVE_MB=2048     # Default: 2048 MB maximum archive size on restore

7.3 — WAL Checkpoint Policy (Level 1)

export P8G_WAL_CHECKPOINT_RECORDS=1000000  # Checkpoint interval in WAL records

7.4 — Disaster Recovery Testing (Level 2)

Monthly DR drill:

1. Restore from latest backup to a fresh instance
2. Verify node/edge counts match
3. Run POST /admin/storage/scrub and GET /health — ensure "status": "healthy"
4. Validate vector search returns expected results

---

Compliance Mapping

Framework	Relevant Controls
SOC 2 Type II	1.1–1.6, 2.1–2.3, 6.1–6.3
ISO 27001 Annex A	A.8 (Asset), A.9 (Access), A.10 (Crypto), A.12 (Ops), A.14 (Dev)
PCI DSS v4.0	2.1, 2.2, 2.3, 3.1–3.5 (encryption), 6.1–6.3, 8.1–8.6
HIPAA Technical Safeguards	§164.312(a)(1) Access, §164.312(e)(1) Transmission, §164.312(c)(1) Integrity
FedRAMP (Moderate)	AC-2, AC-6, AU-2, AU-6, CM-6, IA-2, SC-8, SC-13, SC-28

---

Audit Checklist (Copy & Complete)

Date: ___________  Reviewer: ___________  Environment: ___________

[ ] 1.1  P8G_JWT_SECRET is ≥256-bit random, stored in secrets manager
[ ] 1.2  Unused API keys revoked
[ ] 1.3  Bootstrap token rotated after initial setup
[ ] 1.4  Password policy enforced (12+ chars, complexity)
[ ] 1.5  P8G_ENV=production set
[ ] 1.6  Agent tokens have minimum required role, short expiry
[ ] 2.1  KMS encryption active (GET /health shows encryption: active)
[ ] 2.2  Vector encryption enabled (if regulated sector)
[ ] 2.3  TLS 1.2+ enforced at ingress
[ ] 2.4  Swap disabled or encrypted
[ ] 3.1  Container runs as non-root
[ ] 3.2  All capabilities dropped
[ ] 3.3  no-new-privileges enforced
[ ] 3.4  Seccomp profile loaded
[ ] 3.8  Red Hat OpenShift restricted SCC / UBI9 image used (if on OpenShift)
[ ] 4.1  Service bound to localhost (if behind proxy)
[ ] 4.2  P8G_METRICS_TOKEN set
[ ] 4.3  CORS restricted to known origins
[ ] 5.1  Tenancy mode appropriate for workload
[ ] 5.3  Write admission RSS limit configured
[ ] 5.4  P8G_WRITE_ADMISSION_DISK_MAX_PCT configured (default 95.0%)
[ ] 6.1  Prometheus scraping active with alerts
[ ] 6.2  Logs shipped to SIEM
[ ] 6.3  Audit trail verified (GET /admin/audit returns records)
[ ] 6.6  Online storage scrub scheduled (POST /admin/storage/scrub)
[ ] 7.1  Automated backups configured
[ ] 7.2  P8G_BACKUP_JSONL=1 and P8G_BACKUP_MAX_ARCHIVE_MB=2048 set
[ ] 7.3  WAL checkpoint policy set

---

Last updated: 2026-10-26 (v0.72.0)