hermes-agent/V-006_FIX_SUMMARY.md

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

1. Existing token files will be invalidated (no signature) - users will need to re-authenticate
2. New secret key will be auto-generated in ~/.hermes/.secrets/
3. 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