Thales CipherTrust Data Security Platform CAKM MCP Server

1# Thales CipherTrust Data Security Platform CAKM MCP Server
2 
3A Model Context Protocol (MCP) server for Database EKM/TDE operations using CipherTrust Application Key Management (CAKM).
4 
5## 🔑 Features
6 
7- **Resource-Based Management**: Tools are organized by the database objects they manage (e.g., keys, encryption, wallets), not just by actions.
8- **Operational Grouping**: Each tool exposes multiple `operations` (e.g., `create`, `list`, `rotate`) for comprehensive lifecycle management.
9- **Unified Status & Auditing**: A single tool (`status_tde_ekm`) provides health, compliance, and configuration monitoring across all supported databases.
10- **Advanced Oracle TDE Detection**: Intelligent detection of Oracle TDE configurations including:
11  - **HSM-only TDE**: Direct HSM wallet usage
12  - **HSM with Auto-login**: Forward migrated configurations (HSM primary, auto-login secondary)  
13  - **FILE wallet TDE**: Password-based software wallets
14  - **FILE with Auto-login**: Standard or reverse migrated configurations
15  - **Migration Status Recognition**: Automatically identifies forward/reverse migration states based on wallet order and types
16- **Database TDE Operations**: Encrypt, decrypt, and manage TDE on multiple database types.
17- **CipherTrust Integration**: Seamless integration with CipherTrust Manager via CAKM EKM.
18- **Multi-Database Support**: SQL Server and Oracle Database.
19- **Key Rotation**: Automated encryption key rotation with key management on Thales CipherTrust Manager.
20 
21> **🎥 [Watch Demo Video](https://www.youtube.com/watch?v=5GezP4_CEyY)** - See the MCP server in action managing database encryption
22 
23## 🚀 Quick Start
24 
25### Clone the Repository
26 
27```bash
28# Clone the repository
29git clone https://github.com/sanyambassi/thales-cdsp-cakm-mcp-server.git
30cd thales-cdsp-cakm-mcp-server
31```
32 
33### Installation
34 
35```bash
36# Install dependencies
37uv venv && source .venv/bin/activate  # Linux/Mac
38# uv venv && .venv\Scripts\activate   # Windows
39uv pip install -e .
40 
41# Configure (copy the example configuration)
42# Note: Create your own .env file with database connection details
43# See docs/PREREQUISITES.md for configuration examples
44 
45# Test connections
46uv run python -m database_tde_server --test-connections
47```
48 
49### Usage
50 
51```bash
52# Start the MCP server
53uv run python -m database_tde_server
54```
55 
56## 📦 Installing `uv`
57 
58This project uses `uv` to manage dependencies and run scripts. Please install it using one of the methods below.
59 
60**Windows (PowerShell):**
61```powershell
62powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
63```
64 
65**Linux, macOS, and other shells:**
66```bash
67curl -LsSf https://astral.sh/uv/install.sh | sh
68```
69 
70For more information, visit the [uv installation guide](https://github.com/astral-sh/uv#installation).
71 
72 
73## 🔧 Available Tools
74 
75- **Core Tools**
76    - `list_database_connections()`: Lists all configured database connections.
77- **Unified Status & Auditing**
78    - `status_tde_ekm()`: Provides a unified interface to monitor the health, configuration, and compliance of TDE across both SQL Server and Oracle.
79- **SQL Server Tools**
80    - `manage_sql_ekm_objects()`: Manages EKM providers, credentials, and their associated server logins.
81    - `manage_sql_keys()`: Manages the lifecycle of cryptographic keys (Asymmetric Master Keys and DEKs), including creation, listing, dropping, and rotation.
82    - `manage_sql_encryption()`: Encrypts or decrypts one or more SQL Server databases.
83- **Oracle Tools**
84    - `manage_oracle_tde_deployment()`: Handles high-level TDE deployment workflows like initial setup or migration to/from an HSM.
85    - `manage_oracle_configuration()`: Manages TDE-related database parameters.
86    - `manage_oracle_wallet()`: Performs all wallet-specific actions (open, close, backup, manage auto-login).
87    - `manage_oracle_keys()`: Manages the lifecycle of Master Encryption Keys (MEKs), including rotation and listing.
88    - `manage_oracle_tablespace_encryption()`: Manages the encryption and decryption of specific tablespaces.
89 
90## 🤖 AI Assistant Integration
91 
92Add to your AI assistant configuration:
93 
94### Claude Desktop
95```json
96{
97  "mcpServers": {
98    "database-tde": {
99      "command": "uv",
100      "args": ["run", "python", "-m", "database_tde_server"],
101      "cwd": "/path/to/cakm-mcp-server-sql-oracle",
102      "env": {
103        "DB_TDE_SERVER_NAME": "database-tde-mcp",
104        "DB_TDE_LOG_LEVEL": "INFO",
105        "DB_TDE_DATABASE_CONNECTIONS": "[{\"name\":\"prod_sql\",\"db_type\":\"sqlserver\",\"host\":\"sql-prod.company.com\",\"port\":1433,\"username\":\"tde_admin\",\"password\":\"secure_password\"},{\"name\":\"oracle_cdb1\",\"db_type\":\"oracle\",\"host\":\"oracle-prod.company.com\",\"port\":1521,\"username\":\"sys\",\"password\":\"oracle_password\",\"oracle_config\":{\"oracle_home\":\"/u01/app/oracle/product/21.0.0/dbhome_1\",\"oracle_sid\":\"cdb1\",\"service_name\":\"orcl\",\"mode\":\"SYSDBA\",\"wallet_root\":\"/opt/oracle/wallet\"},\"ssh_config\":{\"host\":\"oracle-prod.company.com\",\"username\":\"oracle\",\"private_key_path\":\"/path/to/private-key.pem\",\"port\":22,\"timeout\":30}}]"
106      }
107    }
108  }
109}
110```
111 
112### Cursor AI (mcp.json)
113```json
114{
115  "mcpServers": {
116    "database-tde": {
117      "command": "uv",
118      "args": ["run", "python", "-m", "database_tde_server"],
119      "cwd": "/path/to/cakm-mcp-server-sql-oracle",
120      "env": {
121        "DB_TDE_SERVER_NAME": "database-tde-mcp",
122        "DB_TDE_LOG_LEVEL": "INFO",
123        "DB_TDE_DATABASE_CONNECTIONS": "[{\"name\":\"prod_sql\",\"db_type\":\"sqlserver\",\"host\":\"sql-prod.company.com\",\"port\":1433,\"username\":\"tde_admin\",\"password\":\"secure_password\"},{\"name\":\"oracle_cdb1\",\"db_type\":\"oracle\",\"host\":\"oracle-prod.company.com\",\"port\":1521,\"username\":\"sys\",\"password\":\"oracle_password\",\"oracle_config\":{\"oracle_home\":\"/u01/app/oracle/product/21.0.0/dbhome_1\",\"oracle_sid\":\"cdb1\",\"service_name\":\"orcl\",\"mode\":\"SYSDBA\",\"wallet_root\":\"/opt/oracle/wallet\"},\"ssh_config\":{\"host\":\"oracle-prod.company.com\",\"username\":\"oracle\",\"private_key_path\":\"/path/to/private-key.pem\",\"port\":22,\"timeout\":30}}]"
124      }
125    }
126  }
127}
128```
129 
130### Gemini CLI (settings.json)
131```json
132{
133  "mcpServers": {
134    "database-tde": {
135      "command": "uv",
136      "args": ["run", "python", "-m", "database_tde_server"],
137      "cwd": "/path/to/cakm-mcp-server-sql-oracle",
138      "env": {
139        "DB_TDE_SERVER_NAME": "database-tde-mcp",
140        "DB_TDE_LOG_LEVEL": "INFO",
141        "DB_TDE_DATABASE_CONNECTIONS": "[{\"name\":\"prod_sql\",\"db_type\":\"sqlserver\",\"host\":\"sql-prod.company.com\",\"port\":1433,\"username\":\"tde_admin\",\"password\":\"secure_password\"},{\"name\":\"oracle_cdb1\",\"db_type\":\"oracle\",\"host\":\"oracle-prod.company.com\",\"port\":1521,\"username\":\"sys\",\"password\":\"oracle_password\",\"oracle_config\":{\"oracle_home\":\"/u01/app/oracle/product/21.0.0/dbhome_1\",\"oracle_sid\":\"cdb1\",\"service_name\":\"orcl\",\"mode\":\"SYSDBA\",\"wallet_root\":\"/opt/oracle/wallet\"},\"ssh_config\":{\"host\":\"oracle-prod.company.com\",\"username\":\"oracle\",\"private_key_path\":\"/path/to/private-key.pem\",\"port\":22,\"timeout\":30}}]"
142      }
143    }
144  }
145}
146```
147 
148### Architecture Overview
149```
150MCP Server ↔ Database Server ↔ CAKM Provider/Library ↔ CipherTrust Manager
151```
152 
153**Note**: This MCP server communicates only with database servers. The CAKM providers installed on database servers handle all communication with CipherTrust Manager.
154 
155### Oracle TDE Enablement Logic
156 
157The server uses Oracle-documented logic to determine TDE status based on wallet configurations and TDE parameters:
158 
159**✅ TDE is ENABLED when:**
160- Any wallet shows `OPEN` status AND Master Encryption Keys (MEKs) exist
161 
162**📊 Wallet Order Types (from Oracle V$ENCRYPTION_WALLET):**
163- **SINGLE**: Only one wallet type configured
164- **PRIMARY**: Primary wallet in a dual-wallet configuration  
165- **SECONDARY**: Secondary wallet in a dual-wallet configuration
166 
167**🔧 TDE Configuration Parameter Values:**
168- **FILE**: TDE configured to use FILE wallets only
169- **HSM**: TDE configured to use HSM wallets only
170- **HSM|FILE**: TDE configured with HSM as primary, FILE as secondary
171- **FILE|HSM**: TDE configured with FILE as primary, HSM as secondary
172 
173**📊 Supported TDE Scenarios:**
1741. **HSM-only TDE**: HSM wallet OPEN (SINGLE), TDE_CONFIGURATION=HSM
1752. **HSM with Auto-login (Migrated)**: HSM wallet OPEN (PRIMARY), auto-login wallet OPEN (SECONDARY), TDE_CONFIGURATION=HSM|FILE
1763. **HSM with Auto-login (Not Migrated)**: HSM wallet OPEN (PRIMARY), auto-login wallet OPEN_NO_MASTER_KEY (SECONDARY), TDE_CONFIGURATION=HSM|FILE
1774. **FILE wallet TDE**: PASSWORD wallet OPEN (SINGLE), TDE_CONFIGURATION=FILE
1785. **FILE with Auto-login (Reverse Migrated)**: PASSWORD wallet OPEN (PRIMARY), auto-login wallet OPEN (SECONDARY), TDE_CONFIGURATION=FILE|HSM
1796. **FILE with Auto-login**: PASSWORD wallet OPEN (PRIMARY), auto-login wallet OPEN (SECONDARY), TDE_CONFIGURATION=FILE
180 
181**🔍 Migration Detection Logic:**
182- **Forward Migration**: HSM becomes PRIMARY (HSM|FILE configuration) → Database migrated from FILE to HSM
183- **Reverse Migration**: FILE becomes PRIMARY (FILE|HSM configuration) → Database migrated from HSM back to FILE
184- **WALLET_ORDER** and **TDE_CONFIGURATION** are correlated to determine the migration state
185 
186**📋 Status Information:**
187- TDE configuration parameters validate the expected wallet hierarchy
188- Wallet order and TDE_CONFIGURATION together determine the deployment scenario
189 
190## 🔧 Oracle TDE Operations Guide
191 
192The `oracle_tde_deployment` tool provides different operations for various TDE setup scenarios:
193 
194### Operation Types & Use Cases
195 
196**1. HSM-Only TDE Setup (No Auto-login)**
197```json
198{
199  "oracle_connection": "oracle_cdb2",
200  "operation": "setup_hsm_only",
201  "ciphertrust_username": "tdeuser",
202  "ciphertrust_password": "Thales123!",
203  "ciphertrust_domain": "TDE",
204  "auto_restart": true
205}
206```
207- **Use when**: "Skip auto-login wallet creation" or "HSM only"
208- **Creates**: HSM keystore only
209- **Result**: Manual wallet opening required after restarts
210- **No software_wallet_password needed**
211 
212**2. Complete TDE Setup (HSM + Auto-login)**
213```json
214{
215  "oracle_connection": "oracle_cdb2",
216  "operation": "setup_hsm_with_autologin",
217  "ciphertrust_username": "tdeuser", 
218  "ciphertrust_password": "Thales123!",
219  "ciphertrust_domain": "TDE",
220  "software_wallet_password": "Thales123!",
221  "auto_restart": true
222}
223```
224- **Use when**: "Set up complete TDE with auto-login"
225- **Creates**: HSM + software wallet + auto-login keystore
226- **Result**: Database starts automatically without manual intervention
227- **Requires software_wallet_password**
228 
229**3. Add Auto-login to Existing TDE**
230```json
231{
232  "oracle_connection": "oracle_cdb2",
233  "operation": "add_autologin",
234  "ciphertrust_username": "tdeuser",
235  "ciphertrust_password": "Thales123!", 
236  "ciphertrust_domain": "TDE",
237  "software_wallet_password": "Thales123!",
238  "auto_restart": true
239}
240```
241- **Use when**: Database has HSM TDE, want to add auto-login
242- **Creates**: Software wallet + auto-login for existing HSM setup
243- **Requires software_wallet_password**
244 
245**4. Check TDE Status**
246```json
247{
248  "oracle_connection": "oracle_cdb2",
249  "operation": "get_tde_status"
250}
251```
252- **Use when**: Want to see current TDE configuration
253- **Returns**: Comprehensive wallet and TDE status
254- **No credentials needed**
255 
256### Quick Reference
257- **"Skip auto-login"** → Use `setup_hsm_only`
258- **"Complete TDE setup"** → Use `setup_hsm_with_autologin`  
259- **"Add auto-login to existing"** → Use `add_autologin`
260- **"Check what I have"** → Use `get_tde_status`
261 
262**📚 References:**
263- [Oracle V$ENCRYPTION_WALLET Documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/refrn/V-ENCRYPTION_WALLET.html)
264- [Oracle TDE_CONFIGURATION Parameter](https://docs.oracle.com/en/database/oracle/oracle-database/19/refrn/TDE_CONFIGURATION.html)
265 
266### Example Prompts
267```
268"Show me the TDE status of all my databases"
269"For my 'prod_sql' connection, list all the asymmetric keys using the 'manage_sql_keys' tool"
270"Rotate the master key on the 'Db05' database using the 'prod_sql' connection"
271"Encrypt the 'SalesDB' database on my 'prod_sql' server"
272"What is the wallet status for my 'oracle_cdb2' connection?"
273```
274 
275### Important Notes
276- **Automatic Database Restarts**: When specified in prompts, MCP tools can automatically restart Oracle databases as part of TDE operations
277- **SSH Authentication**: Oracle connections support both private key and password authentication
278  - Private key: Use `"private_key_path": "/path/to/key.pem"` in ssh_config
279  - Password: Use `"password": "your_ssh_password"` in ssh_config (instead of private_key_path)
280- **Supported Databases**: Microsoft SQL Server and Oracle Database are supported
281 
282## 📚 Documentation
283 
284- [Prerequisites](docs/PREREQUISITES.md) - System requirements and setup
285- [Testing Guide](docs/TESTING.md) - Comprehensive testing procedures
286- [Example Prompts](docs/EXAMPLE_PROMPTS.md) - Ready-to-use testing prompts for SQL Server and Oracle
287 
288## 🤝 Contributing
289 
2901. Fork the repository
2912. Create a feature branch
2923. Make your changes
2934. Add tests for new functionality
2945. Ensure all tests pass
2956. Submit a pull request
296 
297## 📄 License
298 
299This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
300