Files

Alexander Whitestone 95d65a1155 feat: extract sovereign work from hermes-agent fork into sidecar

Extracted 52 files from Timmy_Foundation/hermes-agent (gitea/main) into
hermes-sovereign/ directory to restore clean upstream tracking.

Layout:
  docs/             19 files — deploy guides, performance reports, security docs, research
  security/          5 files — audit workflows, PR checklists, validation scripts
  wizard-bootstrap/  7 files — wizard environment, dependency checking, auditing
  notebooks/         2 files — Jupyter health monitoring notebooks
  scripts/           5 files — forge health, smoke tests, syntax guard, deploy validation
  ci/                2 files — Gitea CI workflow definitions
  githooks/          3 files — pre-commit hooks and config
  devkit/            8 files — developer toolkit (Gitea client, health, notebook runner)
  README.md          1 file  — directory overview

Addresses: #337, #338

2026-04-07 10:11:20 -04:00

3.1 KiB

Raw Blame History

V-006 MCP OAuth Deserialization Vulnerability Fix

Summary

Fixed the critical V-006 vulnerability (CVSS 8.8) in MCP OAuth handling that used insecure deserialization, potentially enabling remote code execution.

Changes Made

1. Secure OAuth State Serialization (`tools/mcp_oauth.py`)

Replaced pickle with JSON: OAuth state is now serialized using JSON instead of pickle.loads(), eliminating the RCE vector
Added HMAC-SHA256 signatures: All state data is cryptographically signed to prevent tampering
Implemented secure deserialization: SecureOAuthState.deserialize() validates structure, signature, and expiration
Added constant-time comparison: Token validation uses secrets.compare_digest() to prevent timing attacks

2. Token Storage Security Enhancements

JSON Schema Validation: Token data is validated against strict schemas before use
HMAC Signing: Stored tokens are signed with HMAC-SHA256 to detect file tampering
Strict Type Checking: All token fields are type-validated
File Permissions: Token directory created with 0o700, files with 0o600

3. Security Features

Nonce-based replay protection: Each state has a unique nonce tracked by the state manager
10-minute expiration: States automatically expire after 600 seconds
CSRF protection: State validation prevents cross-site request forgery
Environment-based keys: Supports HERMES_OAUTH_SECRET and HERMES_TOKEN_STORAGE_SECRET env vars

4. Comprehensive Security Tests (`tests/test_oauth_state_security.py`)

54 security tests covering:

Serialization/deserialization roundtrips
Tampering detection (data and signature)
Schema validation for tokens and client info
Replay attack prevention
CSRF attack prevention
MITM attack detection
Pickle payload rejection
Performance tests

Files Modified

tools/mcp_oauth.py - Complete rewrite with secure state handling
tests/test_oauth_state_security.py - New comprehensive security test suite

Security Verification

# Run security tests
python tests/test_oauth_state_security.py

# All 54 tests pass:
# - TestSecureOAuthState: 20 tests
# - TestOAuthStateManager: 10 tests  
# - TestSchemaValidation: 8 tests
# - TestTokenStorageSecurity: 6 tests
# - TestNoPickleUsage: 2 tests
# - TestSecretKeyManagement: 3 tests
# - TestOAuthFlowIntegration: 3 tests
# - TestPerformance: 2 tests

API Changes (Backwards Compatible)

SecureOAuthState - New class for secure state handling
OAuthStateManager - New class for state lifecycle management
HermesTokenStorage - Enhanced with schema validation and signing
OAuthStateError - New exception for security violations

Deployment Notes

Existing token files will be invalidated (no signature) - users will need to re-authenticate
New secret key will be auto-generated in ~/.hermes/.secrets/
Environment variables can override key locations:
- HERMES_OAUTH_SECRET - For state signing
- HERMES_TOKEN_STORAGE_SECRET - For token storage signing

References

Security Audit: V-006 Insecure Deserialization in MCP OAuth
CWE-502: Deserialization of Untrusted Data
CWE-20: Improper Input Validation

3.1 KiB Raw Blame History