Security Overview

Security Architecture at a Glance

flow8 implements defense-in-depth security across multiple layers:

┌──────────────────────────────────────────────────────────┐
│                    NETWORK & TRANSPORT                    │
│  (TLS via reverse proxy, CORS, origin validation)         │
└──────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────┐
│                  AUTHENTICATION LAYER                     │
│  Session/Cookie  │  API Keys/JWT  │  OAuth2  │  MCP      │
└──────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────┐
│              AUTHORIZATION & RBAC LAYER                   │
│  Company isolation  │  User/Group permissions  │  Entity- │
│  level access control                                     │
└──────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────┐
│                   FIELD-LEVEL ENCRYPTION                  │
│  NaCl SecretBox + Argon2/Scrypt key derivation            │
│  Encrypted: credentials, KV, OAuth tokens, URIs           │
└──────────────────────────────────────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────────┐
│                    AUDIT LOGGING LAYER                    │
│  All HTTP requests, CRUD ops, auth events, module calls   │
│  Field sanitization, retention policies, compliance ready │
└──────────────────────────────────────────────────────────┘

Security Domains

1. Authentication

Three authentication methods:

Method	Mechanism	Session Lifetime	Use Case
Session/Cookie	Username + bcrypt password	1 hour (configurable)	Browser-based UI access
API Key (JWT)	HS256 JWT with user/company/key ID	Token TTL (default: 24h)	Programmatic API access, integrations
OAuth2 (Microsoft)	Delegated auth to Azure AD, auto-user registration	OAuth2 provider session	Enterprise SSO

Security properties:

Passwords: bcrypt with cost=12 (not stored as plaintext)
Cookies: HTTP-only, Secure flag, SameSite=Strict
JWT: HS256 signed with server secret, includes company/user/key IDs, supports MCP scope
OAuth2: Auto-creates users, no plaintext credentials stored locally

2. Authorization & RBAC

Company-level isolation:

All 43+ entities include company_id
All database queries automatically filtered by authenticated company
Users can belong to multiple companies; session context determines accessible company

User permissions (8 roles):

admin: Full system access, user/company management
flow_editor: Create, edit, deploy flows
flow_executor: Execute flows, view results
audit_viewer: Read audit logs
integration_manager: Manage OAuth2 links and API credentials
analytics_viewer: Access flow metrics and reports
viewer: Read-only access to flows and results
none: No access (default for new users)

Entity-level access control (DBAccess collection):

Granular: per-flow, per-flow-group, per-integration
Assignment: to individual users or security groups
Inheritance: flows inherit from flow groups
Prevents: users from accessing flows/groups outside their assignment

3. Encryption

Field-level encryption with NaCl SecretBox:

Algorithm: XSalsa20-Poly1305
Key derivation: Argon2 (N=32768, R=8, P=1) or Scrypt
Key length: 32 bytes (256 bits)

Encrypted fields:

User passwords (stored as bcrypt hash, not encrypted)
OAuth2 access/refresh tokens (in DBLink)
API keys (component configs, integrations)
Connection URIs (DB, SMTP, etc.)
KV store sensitive values (marked with secret: prefix)
Field values exceeding ENC_FIELD_MAX_BYTES

Key management:

ENC_KEY_SECRET: 256-character hex string (primary encryption key)
ENV_KEY_SALT: 64-character hex string (salt for Argon2/Scrypt derivation)
Stored in .env (development) or Kubernetes Secrets (production)
Key rotation: requires re-encrypting all encrypted fields

4. Audit Logging

Audit log schema:

Timestamp, user, company, action, resource type, resource ID
Before/after state (for CRUD operations)
HTTP request details (method, path, status code)
Field sanitization (passwords, keys, PII masked)
Retention: configurable cadence + entry count, enforced minimums

Logged events:

HTTP requests (method, path, status, user, IP)
Authentication (login, logout, token creation)
Authorization (permission check failures)
CRUD operations (flow create/update/delete, user add/remove)
Module execution (module name, input/output summary)
Background jobs (scheduler runs, retention cleanup)
System events (config changes, integration auth)

Compliance:

GDPR-ready (retention policies respect data minimization)
HIPAA: audit logs include access trails for regulated data
SOC 2: comprehensive audit trail for certification

5. Network & Transport

Recommended deployment:

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ HTTPS/TLS 1.3
       │ (via reverse proxy)
       │
       ▼
┌──────────────────┐
│ Reverse Proxy    │ (nginx, Caddy, AWS ALB)
│ (TLS termination)│
└────────┬─────────┘
         │ HTTP (internal network)
         │
         ▼
┌──────────────────────────┐
│ flow8 Core (4454)        │
│ (no built-in TLS,        │
│  assumes reverse proxy)   │
└──────────────────────────┘
         │
         ▼
┌──────────────────┐
│ MongoDB          │ (mTLS recommended if remote)
│ (authenticate    │
│  with credentials)
└──────────────────┘

CORS configuration (configurable in config.yml):

Allowed origins: whitelisted domains
allowCredentials: true (sessions are sent with requests)
Allowed methods: GET, POST, PUT, OPTIONS
Allowed headers: Content-Type, Authorization, X-API-Key

Firewall rules (recommended):

Restrict MongoDB access to flow8 instance only
Restrict channel ports (7701-7799) to internal network
Block direct access to sensitive endpoints (/admin, /audit) via WAF rules

6. Secrets Management

Development:

# .env file (gitignored)
ENCRYPTION_KEY=abc123...def456...  # 256-char hex
MONGODB_URI=mongodb://localhost:27017
OAUTH2_CLIENT_ID=...
OAUTH2_CLIENT_SECRET=...

Production:

Use Kubernetes Secrets or environment variable injection:

# Kubernetes Secret
apiVersion: v1
kind: Secret
metadata:
  name: flow8-secrets
type: Opaque
data:
  ENCRYPTION_KEY: <base64-encoded-256-char-hex>
  MONGODB_URI: <base64-encoded>
  OAUTH2_CLIENT_SECRET: <base64-encoded>

Or use external secret management:

AWS Secrets Manager: Rotate credentials automatically
HashiCorp Vault: Centralized secrets, audit trail
Google Cloud Secret Manager: Integrated secrets for GCP deployments

Threat Model

Trust Boundaries

Boundary	Trust Level	Mitigation
Client ↔ Network	Untrusted	TLS 1.3 via reverse proxy
Network ↔ flow8	Trusted	Internal network, private VPC
flow8 ↔ MongoDB	Partially Trusted	mTLS, IP whitelisting, strong auth
flow8 ↔ External APIs	Untrusted	API key encryption, TLS validation
Users ↔ Permissions	Trusted	RBAC enforced at query layer

Key Threat Scenarios

Scenario 1: Credential Theft

Attack: Attacker steals OAuth2 token from encrypted storage
Mitigation: NaCl SecretBox encryption, Argon2 key derivation, audit logging of credential access
Detection: Audit log queries for suspicious token usage

Scenario 2: Privilege Escalation

Attack: Non-admin user attempts to access flows they don’t have permission for
Mitigation: RBAC enforced at query layer, entity-level access control (DBAccess)
Detection: Authorization failure logged in audit trail

Scenario 3: Multi-Tenancy Breach

Attack: User A reads data from Company B
Mitigation: All queries filtered by company_id, session context enforced
Detection: Audit logs show unauthorized company access attempts

Scenario 4: Data Exfiltration via Logs

Attack: Sensitive data (passwords, PII) ends up in logs
Mitigation: Field sanitization in audit logger, configurable log retention
Detection: Regular audit log review, automated PII detection

Scenario 5: Timing Attack on Encryption

Attack: Attacker infers encrypted value by timing decryption
Mitigation: NaCl constant-time verification, no timing-sensitive comparisons
Detection: N/A (cryptographic protection)

Hardening Recommendations

Network

Deploy flow8 behind a WAF (AWS WAF, Cloudflare, Akamai)
Use reverse proxy with rate limiting (nginx rate_limit, Caddy)
Restrict outbound HTTPS to whitelisted external services
Monitor bandwidth for exfiltration attempts

Application

Enable audit logging and export to SIEM (Datadog, Splunk, ELK)
Set up alerting for failed logins, permission denials
Rotate API keys and encryption keys quarterly
Run regular penetration tests (focus on RBAC, multi-tenancy)

Data

Enable MongoDB encryption at rest (WiredTiger EncryptionEngine)
Use encrypted PersistentVolumes in Kubernetes
Implement field-level encryption for highest-sensitivity data
Backup to encrypted S3 bucket with versioning

Operations

Maintain least-privilege IAM for deployment
Enable audit logging for all infrastructure changes
Monitor resource usage (CPU, memory, disk) for anomalies
Keep Go and dependencies up to date (weekly security scans)

Compliance Frameworks

Framework	Status	Notes
GDPR	Supportable	Retention policies, audit trail, user data export
HIPAA	Configurable	Requires encryption at rest, audit logging, mTLS
SOC 2 Type II	Achievable	Comprehensive audit trail, access controls, encryption
PCI DSS	Partial	Not suitable for payment processing without review
ISO 27001	Supportable	Aligns with security controls, audit logging

Security Updates & Disclosure

Source: Monitor github.com/osbits/gorgany and upstream Go dependencies for vulnerabilities
Patches: Apply security updates within 1 week of release
Responsible Disclosure: Report security issues to security@flow8.io

Security Checklist

Before deploying to production: