# BeyondTrust EPM MCP Server

A Model Context Protocol (MCP) server for managing BeyondTrust Endpoint Privilege Management (EPM) through Claude Desktop and other MCP clients.

## Features

- 🔐 **Policy Management**: Create, read, and manage EPM policies and applications
- 📋 **Computer Management**: List, authorize, and organize managed endpoints
- 👥 **User & Group Management**: Manage EPM users, roles, and computer groups
- 🔍 **File Inspection**: Safely extract file metadata for policy creation (Windows PE files)
- 📊 **Audit & Monitoring**: Access activity audits, events, and authorization requests
- ✅ **Admin Access Requests**: Create, approve, and deny admin access requests

## 🚀 Quick Start

### Prerequisites

- Python 3.14 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- [Claude Desktop](https://claude.ai/download) (or another MCP client)
- BeyondTrust EPM instance with API credentials

### Installation

#### 1. Clone the Repository

```bash
git clone https://github.com/wesharris222/btepmmcp.git
cd btepmmcp
```

#### 2. Install Dependencies

```bash
uv sync
```

This installs:
- `httpx` - HTTP client for EPM API
- `mcp` - Model Context Protocol SDK  
- `pefile` - PE file parser for file inspection

#### 3. Get Your EPM API Credentials

From your BeyondTrust EPM console:

1. Navigate to **Configuration** → **API Registration**
2. Create a new API client
3. Copy the following values:
   - **Base URL**: `https://[your-subdomain]-services.pm.beyondtrustcloud.com`
   - **Client ID**: Your API client ID (GUID)
   - **Client Secret**: Your API client secret

#### 4. Configure Claude Desktop

**Windows:** Edit `%APPDATA%\Claude\claude_desktop_config.json`

**macOS:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`

**Linux:** Edit `~/.config/Claude/claude_desktop_config.json`

Add this configuration:

```json
{
  "mcpServers": {
    "beyondtrust-epm": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/path/to/btepmmcp",
        "run",
        "bt_epm_mcpv1.py"
      ],
      "env": {
        "BT_EPM_BASE_URL": "https://YOUR-SUBDOMAIN-services.pm.beyondtrustcloud.com",
        "BT_EPM_CLIENT_ID": "your-client-id-here",
        "BT_EPM_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}
```

**Important:** Replace the following:
- `C:/path/to/btepmmcp` → Actual path where you cloned the repo
- `YOUR-SUBDOMAIN` → Your EPM subdomain
- `your-client-id-here` → Your API client ID
- `your-client-secret-here` → Your API client secret

#### 5. Restart Claude Desktop

Close and reopen Claude Desktop to load the MCP server.

#### 6. Verify Installation

In Claude Desktop, try:
```
List all EPM policies
```

If configured correctly, Claude will use the MCP server to retrieve your policies!

---

## 📖 Usage Examples

### Policy Management

```
List all policies
```

```
Show me the details for policy ID 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a
```

```
List applications in policy 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a
```

### File Inspection (Safe - No Execution)

```
Inspect the file at C:\Program Files\7-Zip\7zFM.exe
```

Returns file properties like:
- File name, size, hashes (SHA256, SHA1)
- Publisher, product name, version
- All metadata without executing the file

### Create Policy Application

```
Create a policy application:
- Policy ID: 063caa3a-a1fe-4f41-a1d3-994ad5cb0d7a
- Application Group ID: 5c28a0a9-c133-4f19-9378-0b12f5fe7b77
- Type: exe
- Description: 7-Zip File Manager
- Publisher: Igor Pavlov
- Product Name: 7-Zip
```

### Computer Management

```
List all computers
```

```
Show unauthorized computers
```

```
Authorize computer IDs [id1, id2] and assign to group [group-id]
```

### User Management

```
List all EPM users
```

```
Create a user with email john.doe@company.com and role ID [role-id]
```

### Admin Access Requests

```
Create an admin access request for computer [computer-id]
```

```
Approve admin access request [request-id] by user john.doe@company.com
```

---

## 🛠️ Available Tools

The MCP server provides these tools (used automatically by Claude):

### Policy Management
- `list_policies` - List all policies
- `get_policy_details` - Get detailed policy information
- `list_policy_application_groups` - List applications in a policy
- `create_policy_application` - Add applications to policies

### File Inspection
- `inspect_file_for_policy` - Extract file metadata safely

### Computer Management  
- `list_computers` - List managed computers
- `get_computer_details` - Get computer details
- `authorize_computers` - Authorize computers
- `assign_computers_to_group` - Assign computers to groups

### Group Management
- `list_groups` - List computer groups
- `create_group` - Create new groups

### User Management
- `list_users` - List EPM users
- `create_user` - Create new users

### Monitoring & Auditing
- `get_activity_audits` - Get audit logs
- `search_events` - Search EPM events
- `list_authorization_requests` - List authorization requests
- `get_authorization_request_details` - Get request details

### Admin Access Requests
- `list_admin_access_requests` - List admin access requests
- `get_admin_access_request_details` - Get request details
- `create_admin_access_request` - Create new requests
- `approve_admin_access_request` - Approve requests
- `deny_admin_access_request` - Deny requests

---

## 🔒 Security & Safety

### File Inspection Safety

The `inspect_file_for_policy` tool is **100% safe**:

✅ **Never executes files** - Only reads metadata  
✅ **Read-only operations** - No file modifications  
✅ **Static analysis only** - Parses PE structures without running code  
✅ **Industry-standard library** - Uses trusted `pefile` library  
✅ **Cross-platform** - Works on Windows, Linux, macOS  

See [FILE_INSPECTION_README.md](FILE_INSPECTION_README.md) for details.

### API Security

- Uses OAuth 2.0 client credentials flow
- Credentials stored in Claude Desktop config (local only)
- HTTPS communication with BeyondTrust EPM API
- Token auto-refresh with expiration handling

---

## 📁 File Structure

```
btepmmcp/
├── bt_epm_mcpv1.py              # Main MCP server
├── pyproject.toml               # Python dependencies
├── README.md                    # This file
├── FILE_INSPECTION_README.md    # File inspection guide
├── IMPLEMENTATION_SUMMARY.md    # Technical details
├── QUICK_START.md              # Quick reference
├── test_file_inspection.py     # Safety tests
└── mcp_output/                 # Query results (auto-created)
```

---

## 🧪 Testing

### Test File Inspection

```bash
uv run python test_file_inspection.py
```

This verifies:
- Files are not executed
- Metadata is extracted correctly
- Hashes are calculated
- PE parsing works

### Manual Testing

```bash
# Test file inspection
uv run python -c "from bt_epm_mcpv1 import inspect_file_properties; import json; print(json.dumps(inspect_file_properties('C:\\Windows\\System32\\notepad.exe'), indent=2))"
```

---

## 🌐 Cross-Platform Support

### Windows
- Full functionality
- PE file metadata extraction
- Native path support

### Linux
- Full API functionality
- Can inspect Windows PE files (.exe, .dll)
- Use Linux paths: `/usr/bin/app`

### macOS
- Full API functionality  
- Can inspect Windows PE files
- Use macOS paths: `/Applications/App.app/Contents/MacOS/app`

---

## 📊 Output Files

All query results are saved to `mcp_output/`:

- `latest.json` - Last query result (always overwritten)
- `<tool>_<timestamp>.json` - Archived results for each query

Example:
```
mcp_output/
├── latest.json
├── list_policies_2025-11-13T10-30-45-123456.json
├── inspect_file_for_policy_2025-11-13T10-35-22-789012.json
└── create_policy_application_2025-11-13T10-40-15-345678.json
```

---

## ⚙️ Configuration Options

### Environment Variables

Required (set in Claude Desktop config):
- `BT_EPM_BASE_URL` - Your EPM instance URL
- `BT_EPM_CLIENT_ID` - API client ID
- `BT_EPM_CLIENT_SECRET` - API client secret

### Customization

Edit `bt_epm_mcpv1.py` to customize:

- `OUTPUT_DIR` (line 17) - Change output directory
- `timeout=30.0` (line 146) - Adjust HTTP timeout
- Tool descriptions and parameters

---

## 🐛 Troubleshooting

### "Missing required environment variables"

**Problem:** Server can't find API credentials

**Solution:** Check your `claude_desktop_config.json`:
1. Verify the path is correct
2. Ensure all three env vars are set
3. No typos in variable names
4. Restart Claude Desktop after changes

### "Import pefile could not be resolved"

**Problem:** Dependencies not installed

**Solution:**
```bash
cd /path/to/btepmmcp
uv sync
```

### "File not found" when inspecting files

**Problem:** Relative paths or incorrect path format

**Solution:** Use absolute paths:
- Windows: `C:\\Program Files\\App\\app.exe` (double backslashes)
- Linux/Mac: `/usr/bin/app`

### "HTTP Error 401 Unauthorized"

**Problem:** Invalid API credentials

**Solution:**
1. Verify credentials in EPM console
2. Check Base URL format (must include `https://`)
3. Ensure client has proper permissions

### "HTTP Error 405 Method Not Allowed"

**Problem:** Incorrect API endpoint (fixed in v1)

**Solution:** Update to latest version:
```bash
git pull origin main
```

### MCP Server Not Loading

**Problem:** Claude Desktop can't find the server

**Solution:**
1. Check absolute path in config is correct
2. Verify `uv` is in your PATH
3. Check Claude Desktop logs:
   - Windows: `%APPDATA%\Claude\logs\`
   - macOS: `~/Library/Logs/Claude/`
   - Linux: `~/.config/Claude/logs/`

---

## 📚 Additional Resources

- [BeyondTrust EPM API Documentation](https://www.beyondtrust.com/docs/privilege-management/endpoint/api/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/docs)

---

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Test your changes
4. Submit a pull request

---

## 📝 License

[Add your license here]

---

## 💡 Tips & Best Practices

### Policy Creation

1. **Inspect files first**: Use `inspect_file_for_policy` to get accurate metadata
2. **Use publisher matching**: More flexible than hash matching for updates
3. **Test with small groups**: Verify policies before wide deployment

### File Inspection

1. **Always use absolute paths**: Avoid path resolution issues
2. **Review extracted properties**: Not all files have all metadata
3. **Combine criteria**: Use publisher + product name for best results

### Security

1. **Protect API credentials**: Never commit config files with real credentials
2. **Use least privilege**: Create API clients with minimum required permissions
3. **Review audit logs**: Monitor MCP server actions in EPM audit logs

---

## 🆘 Support

For issues or questions:

1. Check the [Troubleshooting](#-troubleshooting) section
2. Review the documentation files in this repo
3. Check BeyondTrust EPM API documentation
4. Open an issue on GitHub

---

## ✨ What's New

### v1.0 (Current)
- ✅ Fixed 405 error in `create_policy_application`
- ✅ Added cross-platform file inspection
- ✅ PE metadata extraction (publisher, version, hashes)
- ✅ Comprehensive documentation
- ✅ Safety testing suite

---

## 🎯 Roadmap

Future enhancements:
- [ ] Batch file inspection
- [ ] Directory scanning
- [ ] Certificate validation
- [ ] Policy templates
- [ ] Version comparison tools
- [ ] Web UI for configuration

---

**Ready to automate your EPM management? Get started now!** 🚀