Security Reference

A single printable reference for security auditors, compliance teams, and IT leads -- with deep links into the guides where each control is configured.

ℹ️

This page is for auditors and compliance teams
Security configuration is split across guides where it is most contextually useful. This page provides a one-stop overview and links to the detailed configuration steps. If you are implementing security for the first time, follow the guides in order: Install Guide -> Security, then Setup Guide, then Admin Guide -> Security.

Security Overview

FlowSquad uses a dual-database architecture. Understanding this separation is the foundation of the security model:

Database	Default Name	What It Stores	How to Protect
Config DB	`flowsquad_engine.db`	Admin credentials, LDAP bind passwords, LLM API keys, license keys, auth configuration	OS file permissions + field-level encryption for sensitive values. -> Install Guide
Product DB	PostgreSQL / MySQL	All product data: requirements, designs, test cases, artifacts	Dedicated DB user, SSL connections, DB-level audit logging. -> Admin Guide

Security Features Always Active (No Configuration Required)

Feature	Details
Password hashing	All local user passwords hashed with bcrypt (cost factor 12)
LDAP credential encryption	LDAP bind passwords encrypted with Fernet before storage
LLM API key encryption	All AI provider API keys encrypted at rest in the config database
CSRF protection	All state-changing endpoints protected against Cross-Site Request Forgery
Input validation	All API endpoints validate and sanitise inputs to prevent injection attacks
Session security	Secure session cookies with HttpOnly and SameSite attributes. Session signing key is unique per installation — derived from a randomly-generated `installation_id` created on first start and stored encrypted in `flowsquad_engine.db`.

Quick Reference Cheat Sheet

Three Security Layers at a Glance

Layer	Key Action	Where Configured	Priority
1. File Permissions	Linux: `chmod 600 flowsquad_engine.db` Windows: `icacls` to remove Everyone access	Install Guide -- Security	Required -- every deployment
2. Field-Level Encryption	Enabled automatically -- all sensitive values (API keys, passwords, tokens) encrypted before storage	Install Guide -- Security	Active by default -- no configuration required
3. HTTPS / TLS	Nginx + Let's Encrypt (Model A) or direct TLS in Setup Wizard (Model B)	Install Guide -- Security * Deployment Models	Required -- all production

Configuration Database Security

All sensitive values (API keys, passwords, SAML keys, tokens) are encrypted at the field level before storage using Fernet AES-128-CBC. No whole-file database encryption is available. For at-rest protection of the entire database file, use LUKS/dm-crypt (Linux), BitLocker (Windows), or place the Docker named volume on an encrypted filesystem.

Password Storage Rules

Store Here [OK]	Never Here [FAIL]
Password manager (1Password, Bitwarden, LastPass)	Hardcoded in any file
Enterprise vault (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault)	Committed to a Git repository
Secure credentials register (documented, access-controlled)	Plain text file
OS-level secrets store (Secret Service, Windows Credential Manager)	Sent via email or chat

TLS / HTTPS Configuration

All production deployments must use HTTPS. Three options are available:

Option	Use Case	Configuration Location
Nginx reverse proxy + Let's Encrypt (recommended)	Public domain, internet-accessible Linux/Docker deployment	Install Guide -- Deployment Models (Model A)
Nginx reverse proxy + Commercial CA	Internal or air-gapped deployments with corporate CA	Install Guide -- Deployment Models (Model A)
Direct TLS in FlowSquad	Standalone Windows or environments without a reverse proxy	Install Guide -- Deployment Models (Model B)

TLS cipher suites configured in the Nginx template in the Install Guide achieve an A+ rating on SSL Labs. Protocols: TLSv1.2 and TLSv1.3. SSLv3, TLSv1.0, and TLSv1.1 are not permitted.

Database Encryption

What to Encrypt	Method	Where Configured
Configuration database (`flowsquad_engine.db`)	Field-level Fernet AES-128-CBC encryption for all sensitive values (API keys, passwords, tokens). No whole-file database encryption. For full at-rest encryption use filesystem-level encryption (LUKS, BitLocker, encrypted Docker volume).	Install Guide -- Security
Product database in transit (PostgreSQL/MySQL)	SSL/TLS: use `sslmode=require` (PostgreSQL) or `ssl_ca=...` (MySQL) in Setup Wizard connection string	Setup Guide -- Step 1
Product database at rest	Use your database platform's native capabilities: `pgcrypto` extension or filesystem encryption (PostgreSQL); InnoDB tablespace encryption (MySQL)	Managed outside FlowSquad -- configure in your database server

Session Secret Key

FlowSquad signs all browser session cookies with a cryptographic secret key. A weak or shared key allows an attacker to forge valid session cookies and impersonate any user.

How It Works

Concept	Detail
`installation_id`	A 256-bit random value generated once on first start and stored encrypted in `flowsquad_engine.db`. It never changes unless the database is wiped. It is not the machine ID — it is scoped purely to this installation.
Default session secret	Derived automatically as `SHA-256("flask-secret:" + installation_id)`. Unique per installation, requires no admin action, and survives app restarts, license upgrades, and server migrations (as long as the config database is carried over).
Admin override	Available in Setup Wizard → Step 9 → Session Secret Key. Stores a flag (`flask_secret_key_override=true`) so the override is not silently replaced on the next restart. Use only when required by policy — for example, a value pinned in HashiCorp Vault or AWS Secrets Manager.
Session invalidation	Any change to the secret key — whether via the admin UI or by wiping the database — immediately invalidates all active user sessions. Every logged-in user will be signed out. Plan key rotations outside active usage hours.

Migration Behaviour

The session secret travels with flowsquad_engine.db, not with the hardware. Migrating to a new server:

Config DB carried over → installation_id is the same → session secret is unchanged → no session disruption.
Fresh install (DB wiped) → new installation_id generated → new session secret → all users re-login (expected for a fresh install).

This is intentionally decoupled from the license machine ID. A license re-issue for a new machine has no effect on session continuity.

Hardening Recommendations

Protect flowsquad_engine.db with chmod 600 (Linux) / icacls (Windows) — anyone who can read the file can extract the installation_id if they also have the source code. → Install Guide
Do not rotate the session secret routinely — it invalidates all sessions with no security benefit unless a breach is suspected.
If a breach of the config database is suspected: rotate via Setup Wizard → Step 9 → Session Secret Key → Generate a new random key, then rotate all other stored credentials (API keys, LDAP bind password, OAuth2 secrets).
For load-balanced / multi-node deployments: all nodes must share the same flowsquad_engine.db (or use the custom key option to pin an identical value from a shared secrets manager).

Role-Based Access Control (RBAC)

Role	Scope	Recommended Count
Global Administrator	Full unrestricted system access -- database, auth, LLMs, all products, license, audit logs	2-3 trusted IT staff only
Product Administrator	Scoped to assigned products -- team management, LLM config, artifact deletion. No system-wide access.	1-2 per product (team lead or project owner)
Regular User	Read/write on assigned products -- all 10 workflow tabs, generate and save artifacts	All other team members

Full RBAC configuration guide: Admin Guide -- Administrator Roles and Admin Guide -- Security Best Practices.

LDAP / SAML Group-Based Role Assignment

Roles can be assigned automatically based on group membership -- no manual per-user assignment needed:

LDAP/AD: Setup Wizard Step 4 → LDAP → Group Mappings. → Admin Guide — LDAP
SAML/Keycloak: Setup Wizard Step 4 → SAML → Group Mappings. → Reference Guide — Keycloak SAML

Audit Logs & Compliance

FlowSquad logs all security-relevant and data-mutating events automatically. Full audit log documentation: Admin Guide -- Audit Logs.

Event Categories Logged

Authentication: All logins (success/failure), logouts, MFA setup/reset, brute-force detection
User Management: User created/updated/deleted, role assignments changed
Product Actions: Product created/deleted, requirement/design/test case created, edited, or deleted
System Actions: License uploaded, LLM provider added/removed, database/auth settings changed
Security Events: Privilege escalation, API key creation/deletion, configuration exports

Export Formats

CSV -- for compliance audits and Excel analysis
JSON -- for SIEM integration (Splunk, Elastic, Datadog)
PDF -- formatted report for management review

Compliance Framework Coverage

Framework	FlowSquad Controls That Apply	Retention Requirement
SOC 2	Audit logs, MFA for admins, database encryption, RBAC	12 months (configure in Admin Panel -> Settings)
HIPAA	HTTPS, database encryption at rest and in transit, access logs, RBAC	6 years minimum
GDPR	User data export, user deletion (right to be forgotten), audit log of data access, configurable retention	Retain only as long as necessary; test user deletion capability

Security Hardening Checklist

Minimum -- Required for All Deployments

File permissions set on flowsquad_engine.db: chmod 600 (Linux) / icacls (Windows). -> Install Guide
HTTPS enabled -- never run on plain HTTP in production. -> Install Guide
MFA (TOTP) enabled for all Global Admin accounts. -> Admin Guide
All passwords and API keys stored as environment variables -- never hardcoded
Audit logs reviewed regularly for suspicious activity. -> Admin Guide
Session secret key is installation-unique by default (auto-generated installation_id) -- no manual action required. -> Session Secret Key

Enhanced -- Recommended for Production

Sensitive credentials verified in Settings (API keys, passwords encrypted at field level by default)
PostgreSQL or MySQL used (not SQLite) for the product database in multi-user environments. -> Setup Guide
Let's Encrypt or commercial CA-signed SSL certificate (not self-signed). -> Install Guide
LDAP or SAML SSO configured to avoid managing local passwords for enterprise users. -> Admin Guide
Automated encrypted backups of both config database and product database scheduled. -> Admin Guide
Global Admin accounts limited to 2-3 trusted people; Product Admin used for day-to-day management. -> Admin Guide
LLM API keys rotated quarterly. -> Admin Guide

Enterprise -- High-Security Environments

Encryption password managed via HashiCorp Vault, AWS Secrets Manager, or Azure Key Vault
Network firewall restricts database port access to FlowSquad server IP only
FlowSquad runs as a dedicated low-privilege OS user (non-root, no sudo). -> Install Guide -- Linux
Audit log JSON export integrated with SIEM (Splunk, Elastic, Datadog). -> Admin Guide
Quarterly access reviews: remove inactive users, verify Global Admin list
DB-level audit logging enabled on PostgreSQL/MySQL independently of FlowSquad
Run the built-in Security Scan tab on your codebase to identify vulnerabilities in your own products. -> User Guide

Incident Response

If you suspect the configuration database has been compromised:

Rotate the session secret key: Setup Wizard → Step 9 → Session Secret Key → Generate a new random key. This invalidates all active sessions immediately. → Session Secret Key
Immediately rotate all stored credentials: admin passwords, LDAP bind password, all LLM API keys, Jira/Confluence API tokens
Rotate API keys and integration passwords through the Setup Wizard when a credential is compromised
Review audit logs for the suspected time period: Admin Panel → Audit Logs → filter by date
Notify affected users to change their passwords