LevelBlue USM Anywhere MCP Server

⚠️ DISCLAIMER: This is NOT an official LevelBlue or AlienVault product. See DISCLAIMER.md for full terms.

A production-ready Model Context Protocol (MCP) server that connects AI assistants to LevelBlue's USM Anywhere security platform. Execute advanced security queries, manage investigations, and analyze threats through natural language.

Version: 3.0.0 Author: Javier Ballesteros (javier.ballesteros@gmail.com) License: GNU GPL v3.0 Repository: https://github.com/javierb507/anywhere-mcp-server

---

🚀 Quick Start (3 Minutes)

# 1. Clone and install
git clone https://github.com/javierb507/anywhere-mcp-server.git
cd anywhere-mcp-server
npm install && npm run build

# 2. Configure credentials
cp env.example .env
# Edit .env with your USM Anywhere credentials

# 3. Test connection
node test-connection.js

✅ Ready to integrate with your AI assistant! See integration examples below.

---

What is MCP?

Model Context Protocol (MCP) is an open protocol that allows AI assistants to securely connect to external data sources and tools. This server implements MCP to bridge AI assistants with LevelBlue USM Anywhere, enabling:

🤖 Natural language queries → Advanced SQL/PPL security analysis
🔍 Automated threat hunting → AI-powered detection and investigation
📊 Investigation management → Create, update, and track security incidents
🌐 Threat intelligence → AlienVault OTX integration

Supported AI Platforms: Claude Desktop, Claude Code, Cline (VS Code), Cursor IDE, Zed Editor, and any MCP-compatible client.

---

Features

Core Capabilities

✅ OAuth 2.0 Authentication - Secure client credentials flow
✅ 16 MCP Tools - Complete USM Anywhere API coverage
✅ Advanced Query Engine - Execute SQL and PPL queries
✅ Investigation Management - SANS-aligned incident response workflows
✅ Threat Intelligence - AlienVault OTX API integration
✅ Type-Safe - Built with TypeScript and Zod validation
✅ Production Ready - Comprehensive error handling and rate limiting

Pre-Built Security Queries

📚 15+ SQL Queries - Threat hunting, compliance, anomaly detection
📚 12+ PPL Pipelines - Behavioral analytics and log correlation
📖 Complete Documentation - Query guides in QueryLanguage/ directory

---

Available MCP Tools

| Tool | Description | |------|-------------| | get_alarms | Retrieve security alarms with filtering | | get_events | Retrieve security events | | get_alarm_details | Get detailed alarm information | | get_event_details | Get detailed event information | | get_investigations | List investigations with advanced filters | | get_investigation_details | Get full investigation details | | create_investigation | Create new security investigation | | update_investigation | Update investigation status/priority | | add_investigation_note | Add notes to investigation | | delete_investigation | Delete investigation | | execute_advanced_query | Execute SQL/PPL queries | | validate_query_syntax | Validate query before execution | | get_query_examples | Get pre-built query examples | | search_pulses | Search OTX threat intelligence | | get_indicator | Get threat indicator info (IP/domain/hash) | | get_pulse | Get detailed pulse information |

---

Integration Examples

Claude Desktop (macOS/Windows)

Configuration File Locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "usm-anywhere": {
      "command": "node",
      "args": ["C:\\path\\to\\anywhere-mcp-server\\dist\\index.js"],
      "env": {
        "ALIENVAULT_CLIENT_ID": "your_client_id",
        "ALIENVAULT_CLIENT_SECRET": "your_client_secret",
        "ALIENVAULT_SUBDOMAIN": "your_subdomain",
        "ALIENVAULT_ACCOUNT_NAME": "Default"
      }
    }
  }
}

Restart Claude Desktop → Look for 🔌 icon to confirm MCP server is connected.

Claude Code (CLI)

Add to ~/.config/claude-code/config.json:

{
  "mcpServers": {
    "usm-anywhere": {
      "command": "node",
      "args": ["/path/to/anywhere-mcp-server/dist/index.js"],
      "env": {
        "ALIENVAULT_CLIENT_ID": "your_client_id",
        "ALIENVAULT_CLIENT_SECRET": "your_client_secret",
        "ALIENVAULT_SUBDOMAIN": "your_subdomain",
        "ALIENVAULT_ACCOUNT_NAME": "Default"
      }
    }
  }
}

Cline (VS Code Extension)

Add to VS Code Settings (JSON):

{
  "cline.mcpServers": {
    "usm-anywhere": {
      "command": "node",
      "args": ["/path/to/anywhere-mcp-server/dist/index.js"],
      "env": {
        "ALIENVAULT_CLIENT_ID": "your_client_id",
        "ALIENVAULT_CLIENT_SECRET": "your_client_secret",
        "ALIENVAULT_SUBDOMAIN": "your_subdomain",
        "ALIENVAULT_ACCOUNT_NAME": "Default"
      }
    }
  }
}

Cursor IDE

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "usm-anywhere": {
      "command": "node",
      "args": ["/path/to/anywhere-mcp-server/dist/index.js"],
      "cwd": "/path/to/anywhere-mcp-server",
      "env": {
        "ALIENVAULT_CLIENT_ID": "your_client_id",
        "ALIENVAULT_CLIENT_SECRET": "your_client_secret",
        "ALIENVAULT_SUBDOMAIN": "your_subdomain",
        "ALIENVAULT_ACCOUNT_NAME": "Default"
      }
    }
  }
}

📖 For more integrations (Zed Editor, ChatGPT, Generic MCP), see INTEGRATION_GUIDE.md

---

Usage Examples

Once integrated, query your AI assistant using natural language:

Security Analysis

"Show me all critical alarms from the last 24 hours"
"Find failed login attempts from non-US countries"
"Detect potential brute force attacks in the last hour"
"Look for DNS queries longer than 40 characters (tunneling detection)"

Investigation Management

"Create a critical investigation for the SQL injection attempts in alarm abc-123"
"Show me all open investigations assigned to the security team"
"Add a note to investigation xyz-789 about remediation steps taken"
"Update investigation xyz-789 to resolved status"

Advanced Queries

"Execute SQL query to find lateral movement in network traffic"
"Create PPL pipeline to analyze user behavior anomalies"
"Run the port scanning detection query from the security guide"
"Show me off-hours data transfers larger than 10MB"

Threat Intelligence

"Search OTX for threat intelligence about domain malicious.com"
"Get indicator information for IP address 1.2.3.4"
"Show me recent pulses about ransomware"

---

Configuration

Required Environment Variables

# USM Anywhere API v2.0 (Required)
ALIENVAULT_CLIENT_ID=your_client_id
ALIENVAULT_CLIENT_SECRET=your_client_secret
ALIENVAULT_SUBDOMAIN=your_subdomain

# Account Name (Required for queries)
ALIENVAULT_ACCOUNT_NAME=Default

# Legacy OTX API (Optional)
ALIENVAULT_OTX_API_KEY=your_otx_key

Getting Your Credentials:

USM Anywhere: Log in → Admin → Settings → API Credentials
OTX API Key: Visit https://otx.alienvault.com/api

Important Notes:

ALIENVAULT_SUBDOMAIN: Just the subdomain (e.g., yourorg, not yourorg.alienvault.cloud)
ALIENVAULT_ACCOUNT_NAME: Ask your USM administrator for the correct account name
Never commit .env file to version control (already in .gitignore)

---

Documentation

Essential Docs

QUICK_START.md - 5-minute setup guide
INTEGRATION_GUIDE.md - Complete integration guide for all platforms
DISCLAIMER.md - ⚠️ Legal terms and liability (READ BEFORE USING)
CLAUDE.md - Instructions for AI assistants and developers

Query Documentation

QueryLanguage/advanced-sql-security-guide.md - 15+ SQL security queries
QueryLanguage/ppl-security-workflows.md - 12+ PPL pipeline examples
QueryLanguage/basicsql.md - SQL basics and field reference
QueryLanguage/pplbasic.md - PPL basics and commands

Additional Resources

TO_FUTURE_DEVELOPERS.md - Philosophy and message across time 📜
RELEASE_NOTES.md - Version 3.0.0 changelog
LICENSE - GNU GPL v3.0 full text

---

Troubleshooting

Connection Issues

Error: Authentication Failed ```bash

Verify credentials

node test-connection.js

Check .env file format

cat .env | grep ALIENVAULT ```

Error: No Data Returned

Verify ALIENVAULT_ACCOUNT_NAME is correct
Check user permissions in USM Anywhere
Ensure account has access to data

MCP Server Issues

Error: spawn EACCES (Permission denied) ```bash

Make server executable

chmod +x dist/index.js

Verify permissions

ls -la dist/index.js

Should show: -rwxr-xr-x


**MCP Server Not Detected**
- Use **absolute paths** in MCP configuration
- Rebuild project: `npm run build`
- Check MCP client logs for errors

### Query Issues

**500 Internal Server Error**
- Ensure account name is correct
- Provide time ranges in queries (defaults to 24h)
- Validate field names match your data schema

**PPL Query Failures**
- Known issue: PPL has JSON encoding problems
- **Recommendation**: Use SQL queries for production
- PPL syntax validation works, but execution may fail

---

## Development

### Commands

Build project

npm run build

Development mode

npm run dev

Run tests

npm test

Clean build files

npm run clean

Lint/typecheck

npm run lint ```

Project Structure

anywhere-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── services/
│   │   └── alienvault.ts     # API service layer
│   ├── handlers/
│   │   └── tools.ts          # MCP tool handlers
│   └── types/
│       └── index.ts          # TypeScript types & Zod schemas
├── QueryLanguage/            # Query documentation
├── examples/                 # Configuration examples
├── dist/                     # Compiled output
└── test-connection.js        # Connection test script

---

Support & Contributing

Get Help

GitHub Issues: https://github.com/javierb507/anywhere-mcp-server/issues
Email: javier.ballesteros@gmail.com
Documentation: See /QueryLanguage and /examples directories

Contributing

Contributions are welcome! Please:

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests if applicable
Commit (git commit -m 'Add amazing feature')
Push (git push origin feature/amazing-feature)
Open Pull Request

Note: By contributing, you agree to license your contributions under GNU GPL v3.0.

---

License & Credits

License

This project is licensed under GNU General Public License v3.0 - see LICENSE file.

Key Points:

✅ Free to use, modify, and distribute
✅ Source code must remain open
✅ Changes must be documented
✅ Derivatives must use same license
❌ No warranty provided
❌ Authors not liable for damages

Author

Javier Ballesteros

📧 Email: javier.ballesteros@gmail.com
💻 GitHub: @javierb507
🔗 LinkedIn: Javier Ballesteros

Acknowledgments

LevelBlue - For providing USM Anywhere API (docs.levelblue.com)
AlienVault - For providing OTX API (otx.alienvault.com)
Anthropic - For Model Context Protocol specification
Open Source Community - For contributions and feedback

Trademarks

LevelBlue®, USM Anywhere®, AlienVault®, and OTX® are registered trademarks of their respective owners. This project is not affiliated with or endorsed by these companies.

---

Official Documentation Links

LevelBlue USM Anywhere: https://docs.levelblue.com/documentation/usm-anywhere
USM Anywhere API Reference: https://cybersecurity.att.com/documentation/api/usm-anywhere-apis.htm
AlienVault OTX Portal: https://otx.alienvault.com/
Model Context Protocol: https://modelcontextprotocol.io

---

⚠️ Important Reminder: This is NOT an official LevelBlue product. Read DISCLAIMER.md before using. Always test in non-production environments first.

LevelBlue USM Anywhere MCP Server