If you discover a security vulnerability in FaultLine, please email security@faultline.local with:

1. Description of the vulnerability
2. Affected component(s) (e.g., /ingest endpoint, re-embedder, filter)
3. Steps to reproduce (if applicable)
4. Potential impact (severity assessment)
5. Suggested fix (if you have one)

Please do not open public GitHub issues for security vulnerabilities. We will acknowledge receipt within 48 hours and work toward a fix in coordination with you.

• PostgreSQL: Use strong credentials and enable SSL/TLS for production. Restrict network access to database via firewall rules.
• Qdrant: The vector tier is retired for user memory and holds no user facts. If the service runs in your stack, still protect it with authentication and network isolation.
• Redis: Used for rate limiting and event queues. Configure password authentication and disable SAVE/BGSAVE in production if using ephemeral queues.
• Entity UUIDs: UUIDs are v5 surrogates derived from display names, not cryptographic identifiers. Do not rely on UUID uniqueness for security purposes.

• OpenWebUI Credentials: Protect API tokens and bearer credentials. Use environment variables or secrets management, never hardcode in source.
• LLM Endpoint: All LLM calls flow through a centralized _get_llm_url() function with fallback chain (env var → Docker service name → localhost). Verify endpoint configuration in production.
• Prompt Injection: LLM prompts are populated from database metadata (rel_types table descriptions, entity names). Validate and sanitize all user input before persisting to database.

• OpenWebUI Integration: FaultLine trusts OpenWebUI's user authentication. User UUIDs are passed by OpenWebUI filter layer; do not accept user_id from HTTP headers directly.
• Per-Tenant Isolation: Each user's memory lives in its own PostgreSQL schema (faultline_{user_id}), bound per request via search_path. The schema is the tenant boundary — there is no shared user_id column to filter on and forget. Ensure OpenWebUI forwards the authenticated user identity (the X-OpenWebUI-User-Id header) so requests bind to the correct schema.
• Rate Limiting: Per-user rate limit (default 100 req/min) is enforced at /query and /ingest endpoints. Configure via RATE_LIMIT_PER_MIN environment variable.

dBug-016 (OpenWebUI NoneType Crash on Missing chat_id)

• Status: Upstream issue in OpenWebUI (openwebui/open-webui#24550)
• Workaround: Coerce chat_id to empty string instead of None in OpenWebUI's socket/main.py (lines 902, 920)
• Mitigation: FaultLine works around this at the filter level; facts still ingest correctly despite upstream crash

• Entity ID Normalization: All entity IDs must be UUIDs or "user" anchor. String IDs are converted to UUID v5 surrogates at startup.
• Cascade Deletes: Fact deletion uses soft-delete (set superseded_at timestamp). Hard deletes only on explicit user retraction for identity rel_types (pref_name, also_known_as).
• Connection Pooling: All database connections use a pooled psycopg2 connection via connection manager with proper cleanup in finally blocks.

• Triple Validation: All (subject, rel_type, object) triples are validated by WGMValidationGate before commit:
  • Type constraints enforced (head_types/tail_types from rel_types table)
  • Bidirectional relationships validated (no orphaned child_of without parent_of)
  • Semantic conflicts detected (type entities cannot own or be owned)
• Lowercase Normalization: rel_type and entity display names are lowercased on write. All string comparisons use pre-lowercased values (guards against injection).

• Lock Files: Use pip freeze or poetry.lock to pin exact dependency versions in production.
• Regular Updates: Monitor security advisories for:
  • psycopg2 (PostgreSQL driver)
  • fastapi / uvicorn (web framework)
  • gliner2 / huggingface_hub (ML packages)
  • httpx (HTTP client)
• Vulnerable Packages: Check regularly via pip-audit or safety.

FaultLine implements best practices for open-source security:

• ✅ Dangerous Workflow: GitHub Actions use pinned versions (no latest tags)
• ✅ Branch Protection: Main branch protected (require PR reviews before merge)
• ✅ Dependency Pinning: All Python dependencies have version constraints in pyproject.toml
• ✅ SECURITY.md: This file provides clear vulnerability reporting guidelines
• ⏳ Signed Commits: Future: Enable commit signing for all contributors
• ⏳ Token Permissions: Actions use permissions: read-all by default; override only where write access needed

• Structured Logging: All operations logged via structlog with context (user_id, endpoint, operation)
• No Sensitive Data in Logs: Entity display names are logged, but API tokens, database passwords, and LLM endpoints are scrubbed
• Audit Trail: Fact creation timestamps, user_id, and provenance recorded in PostgreSQL for historical queries

• Data Retention: Facts are retained indefinitely unless explicitly soft-deleted. Implement user data deletion requests per GDPR/CCPA if required.
• PII Handling: Personal identifying information (names, addresses, birth dates) is stored with sensitivity metadata. /query applies sensitivity penalty to reduce PII leakage in facts returned to LLM.

• Implement commit signing for all contributors
• Add SBOM (Software Bill of Materials) generation
• OpenSSF Best Practices Badge application
• Annual security audit (planned for 2026 Q3)
• Fuzzing harness for input validation

Security: security@faultline.local
Issue Reports: GitHub Issues