SECURITY.md

Security Policy

Reporting a Vulnerability

If you find a security issue, please do not open a public GitHub issue.

Report privately via: GitHub Security Advisories

Include: what you found, how to reproduce it, and what impact you think it has. You'll get a response within 72 hours. If the issue is confirmed, a fix will be prioritized before any public disclosure.

---

Security Architecture

The Guardian Pattern

main.py is the only process that ever touches secrets. It reads .env / HF Space Secrets, initializes fundaments/* conditionally, and passes the results into app/* as a validated dict. After that handoff, app/* has no path back to the raw environment.

.env / HF Secrets
      │
      ▼
main.py (Guardian) — only entry point
      │
      │  initializes fundaments/* conditionally
      │  injects as: fundaments = {"config": ..., "db": ..., "encryption": ..., ...}
      │
      ▼
app/app.py — unpacks fundaments ONCE at startup, never stores globally
      │
      └── app/* modules — read only from app/.pyfun, never from os.environ

This is enforced structurally. app/* has no import of fundaments/, no os.environ calls, no .env access. It's not a coding convention — it's an import boundary.

---

Secret Handling

• API keys live exclusively in HF Space Secrets or .env — never in app/.pyfun, never in source code
• app/.pyfun references only ENV variable names (e.g. env_key = "ANTHROPIC_API_KEY") — never values
• list_active_tools returns key names only — the actual key values are never exposed through any MCP tool
• fundaments/ modules are initialized only if their required ENV vars are present — missing config = service skipped, not crashed

---

Encryption (fundaments/encryption.py)

When MASTER_ENCRYPTION_KEY and PERSISTENT_ENCRYPTION_SALT are set:

• Key derivation: PBKDF2-HMAC-SHA256, 480,000 iterations, 256-bit output
• Encryption: AES-256-GCM — authenticated encryption, provides both confidentiality and integrity
• Each encryption operation uses a fresh random 96-bit nonce
• Authentication tag (128-bit) is stored alongside ciphertext — decryption fails loudly if data was tampered
• File encryption uses streaming with 8 KB chunks — nonce prepended, tag appended to file
• If encryption keys are not set, the service is skipped cleanly — the app runs without it

---

Authentication (fundaments/user_handler.py)

• Passwords hashed with PBKDF2-SHA256 via passlib
• Sessions stored in SQLite with IP address + User-Agent binding — validate_session() checks both
• Session IDs are regenerated on login (session fixation prevention)
• Failed login attempts tracked per user — account locks after 5 consecutive failures
• Session table uses ON DELETE CASCADE — deleting a user removes all their sessions automatically

---

Access Control (fundaments/access_control.py)

• Role-based permission system backed by PostgreSQL (cloud DB, Guardian-only)
• Schema: users → user_role_assignments → user_roles → role_permissions → user_permissions
• All queries use parameterized statements via asyncpg — no string interpolation
• has_permission() checks the full role→permission chain per request
• AccessControl only initializes if a DB connection is available — degrades gracefully otherwise

---

Database Security (fundaments/postgresql.py)

Cloud DB (asyncpg pool):

• SSL enforced at minimum sslmode=require — upgraded automatically if not set
• Neon.tech quirks handled: statement_timeout stripped from DSN (unsupported, causes silent failures), keepalives set
• Credentials masked in all log output — full DSN only in DEBUG level logs
• SSL runtime check via pg_stat_ssl on every new connection (cloud providers: warning only if unavailable)
• Automatic pool restart on Neon connection termination (sqlstate 08006)
• Pool: min 1 / max 10 connections, connect timeout 5s, command timeout 30s

Internal SQLite (app/db_sync.py + fundaments/user_handler.py):

• Same SQLite file, separate tables — zero overlap enforced by code
• users + sessions → owned by user_handler.py (Guardian layer)
• hub_state + tool_cache → owned by db_sync.py (app/* layer)
• db_query MCP tool exposes SELECT-only access to hub_state and tool_cache — cannot reach users or sessions
• SELECT enforcement: non-SELECT queries raise ValueError before execution
• On HuggingFace Spaces: SQLite auto-relocated to /tmp/ (HF filesystem is read-only outside /tmp/)

---

MCP Transport Security

• All MCP traffic routes through Quart /mcp endpoint before reaching FastMCP
• This is the natural interception point for auth checks, rate limiting, and payload logging — none are optional add-ons
• /crypto endpoint exists but returns 501 until the app-layer encryption wrapper is implemented — not bypassed, not silently ignored
• health_check and list_active_tools are always available — they expose no secrets, only status and key names

---

Sandboxing Rules

These rules are enforced by code structure, not just documentation:

Rule	Enforced by
app/* never reads os.environ	No os.environ calls in any app/ file
app/* never imports fundaments/	No cross-imports between layers
fundaments/ services injected, not constructed in app/*	start_application(fundaments) signature
Direct execution of app/app.py blocked	__main__ guard with null-fundaments warning
db_query tool is SELECT-only	ValueError raised before any non-SELECT execution
API keys never in .pyfun	.pyfun parser only reads key names, never resolves them

---

What This Project Does Not Claim

• It is not a penetration-tested security product
• The encrypted /crypto endpoint is not yet implemented
• Search provider implementations (Brave, Tavily) are pending — the tool registers as placeholder
• This is a personal/community project — use in production at your own assessment

PyFundaments is not perfect. But it's more secure than most of what runs in production today.

---

Supported Versions

Version	Supported
latest (main)	✅
older forks	❌ — fork at your own risk

---

License Note

This project is dual-licensed under Apache 2.0 and the Ethical Security Operations License v1.1 (ESOL). Using this software for surveillance, unauthorized access, or harm to others automatically terminates your license.