Spaces:
Running
Running
| # 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](https://github.com/VolkanSah/Universal-MCP-Hub/security/advisories/new) | |
| 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)](ESOL). Using this software for surveillance, unauthorized access, or harm to others automatically terminates your license. | |