Stellar Cyber MCP Agents

A sophisticated Model Context Protocol (MCP) multi-agent system for Stellar Cyber security operations, featuring specialized agents for investigation, correlation, network analysis, and workflow orchestration.

⚠️ Security Notice

IMPORTANT: Before using this project, please read docs/SECURITY.md for critical security setup instructions, especially regarding API token management.

🏗️ Architecture

The system implements a Hub-and-Spoke architecture with the following components:

Core Components

• Hub Agent: Central orchestration and workflow management
• Investigation Agent: Comprehensive case investigation and analysis
• Correlation Agent: Cross-case correlation and campaign detection
• Network Analysis Agent: Advanced network traffic analysis and threat detection
• Agent Registry: Service discovery and health monitoring
• Communication Channel: Inter-agent messaging with priority queues

Features

• ✅ Distributed Agent Architecture: Each agent runs independently with proper lifecycle management
• ✅ Intelligent Workflow Orchestration: Hub agent coordinates complex multi-step workflows
• ✅ Advanced Case Correlation: Find related cases using observables, temporal, and behavioral analysis
• ✅ Network Threat Detection: Comprehensive network analysis including lateral movement, C2 detection, and data exfiltration
• ✅ Robust Communication: Priority-based messaging with retry logic and timeout handling
• ✅ Health Monitoring: Real-time agent health checks and performance metrics
• ✅ Event-Driven Architecture: Asynchronous event processing and broadcasting

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• Access to Stellar Cyber API
• Claude Desktop (for MCP integration) or other MCP client

Installation

Option 1: NPX (Recommended - No Installation Required)

# Use directly with npx - always gets latest version
npx stellar-cyber-mcp-agents@latest stellar-cyber-mcp-server

# Or specify a specific server variant
npx stellar-cyber-mcp-agents@latest stellar-cyber-mcp-full
npx stellar-cyber-mcp-agents@latest stellar-cyber-mcp-minimal
npx stellar-cyber-mcp-agents@latest stellar-cyber-mcp-simple

Option 2: Global Installation (For frequent usage)

# Install globally for MCP client integration
npm install -g stellar-cyber-mcp-agents

# Then use the commands directly
stellar-cyber-mcp-server
stellar-cyber-mcp-full
stellar-cyber-mcp-minimal

Option 3: Development Installation

# Clone the repository
git clone https://github.com/tsanford01/stellar-cyber-mcp-agents.git
cd stellar-cyber-mcp-agents

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Copy the environment template:

cp .env.example .env

2. Edit .env with your Stellar Cyber credentials:

# Stellar Cyber API Configuration
STELLAR_API_URL=https://your-instance.stellarcyber.cloud
STELLAR_API_TOKEN=your_api_token_here

# Optional: Test case ID for demo
TEST_CASE_ID=your_test_case_id

# Logging Configuration
LOG_LEVEL=info

⚠️ Security Warning: Never commit the .env file to version control. It contains sensitive API credentials.

📝 Implementation Status: ✅ Fully Functional - All TypeScript compilation issues have been resolved! The project now includes a complete multi-agent architecture with multiple MCP server variants to suit different needs.

Running the System

MCP Server Usage (Recommended)

# Start the full-featured MCP server
stellar-cyber-mcp-server

# Or start the minimal server (fewer tools, faster startup)
stellar-cyber-mcp-minimal

# Or start the simple server (basic functionality)
stellar-cyber-mcp-simple

Development Mode

# Development mode (with TypeScript compilation)
npm run dev

# Run specific MCP server variants
npm run mcp:start     # Full server
npm run mcp:minimal   # Minimal server
npm run mcp:simple    # Simple server

# Demo mode with examples
npm run demo

🔌 MCP Client Integration

Claude Desktop Integration

Option 1: NPX Configuration (Recommended)

No installation required - uses the latest version directly from npm.

Configuration:

{
  "mcpServers": {
    "stellar-cyber": {
      "command": "npx",
      "args": ["stellar-cyber-mcp-agents@latest", "stellar-cyber-mcp-server"],
      "env": {
        "STELLAR_API_URL": "https://your-instance.stellarcyber.cloud",
        "STELLAR_API_TOKEN": "your-api-token-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Option 2: Global Installation Configuration

1. Install the package globally:

npm install -g stellar-cyber-mcp-agents

2. Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "stellar-cyber": {
      "command": "stellar-cyber-mcp-server",
      "args": [],
      "env": {
        "STELLAR_API_URL": "https://your-instance.stellarcyber.cloud",
        "STELLAR_API_TOKEN": "your-api-token-here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Configuration File Locations:

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

Restart Claude Desktop after making configuration changes to load the MCP server.

Server Variants

Choose the right server variant for your needs:

• stellar-cyber-mcp-server (Working): Core Stellar Cyber integration with essential tools (recommended for most users)
• stellar-cyber-mcp-minimal (Minimal): Streamlined version with essential tools only, faster startup
• stellar-cyber-mcp-simple (Simple): Basic case investigation features for lightweight usage
• Full Multi-Agent System: Available in codebase with complete orchestration capabilities

See docs/claude_desktop_config_variants.json for complete configuration examples.

Available MCP Tools

Core Stellar Cyber Tools (Available in Working Server)

• get_case_details - Retrieve detailed information about a specific case
• search_cases - Search for cases using various criteria and filters
• get_system_status - Check Stellar Cyber API connection and system health

Advanced Multi-Agent Tools (Available in Full Architecture)

The complete multi-agent system includes all the advanced capabilities:

• Investigation Agent: Case investigation, timeline analysis, observable analysis
• Correlation Agent: Case correlation, campaign detection, similarity analysis
• Network Analysis Agent: Network activity analysis, threat detection, lateral movement detection
• Hub Agent: Workflow orchestration, agent coordination, distributed request handling
• Malware Analysis Agent: Malware behavior analysis, artifact examination
• Credential Analysis Agent: Credential security analysis, breach detection
• Campaign Detection Agent: Advanced threat campaign identification

All agents are fully functional and compile successfully with complete TypeScript support.

📊 System Components

1. Hub Agent (src/agents/hub-agent.ts)

The central orchestration agent that coordinates workflows across multiple agents.

Capabilities:

• orchestrate_workflow: Execute complex multi-step workflows
• find_agents: Discover agents by capability and criteria
• distribute_request: Load-balance requests across agents
• get_system_status: Retrieve system health and metrics

Features:

• Workflow definition and execution
• Load balancing (round-robin, least-busy, random)
• Agent discovery and selection
• Retry logic with exponential backoff
• Performance monitoring

2. Investigation Agent (src/agents/investigation-agent.ts)

Comprehensive case investigation and analysis agent.

Capabilities:

• investigate_case: Perform full case investigation
• get_case_details: Retrieve case information
• analyze_case_observables: Analyze IOCs and observables
• get_case_timeline: Build case timeline
• search_cases: Search for cases by criteria

Features:

• Multi-source data aggregation
• Threat intelligence integration
• Workflow suggestions
• Risk assessment
• Artifact analysis

3. Correlation Agent (src/agents/correlation-agent.ts)

Advanced case correlation and campaign detection agent.

Capabilities:

• correlate_cases: Find related cases using multiple methods
• find_related_cases: Discover case relationships
• detect_campaigns: Identify threat campaigns
• analyze_case_similarity: Compare case similarities

Features:

• Observable-based correlation
• Temporal proximity analysis
• Behavioral pattern matching
• Campaign detection algorithms
• Configurable correlation rules

4. Network Analysis Agent (src/agents/network-agent.ts)

Comprehensive network traffic analysis and threat detection agent.

Capabilities:

• analyze_network_activity: Full network activity analysis
• detect_lateral_movement: Identify lateral movement patterns
• analyze_data_exfiltration: Detect data exfiltration attempts
• detect_c2_communication: Find C2 communication patterns
• get_network_topology: Build network topology maps

Features:

• Traffic pattern analysis
• Threat hunting capabilities
• Protocol anomaly detection
• Endpoint behavior analysis
• Network visualization

🔧 API Usage

Starting the System

import { MultiAgentOrchestrator, createDefaultConfig } from './orchestrator.js';

const config = createDefaultConfig();
const orchestrator = new MultiAgentOrchestrator(config);

await orchestrator.start();

Case Investigation

// Investigate a specific case
const investigation = await orchestrator.investigateCase('case-123', {
  includeObservables: true,
  includeTimeline: true,
  generateRecommendations: true
});

console.log('Investigation Results:', {
  caseId: investigation.caseId,
  findings: investigation.findings.length,
  recommendations: investigation.recommendations.length,
  riskScore: investigation.summary.riskScore
});

Case Correlation

// Find related cases
const correlation = await orchestrator.correlateCase('case-123', 'observables');

console.log('Related Cases:', correlation.length);

Network Analysis

// Analyze network activity
const networkAnalysis = await orchestrator.analyzeNetwork('case-123', {
  start: '2024-01-01T00:00:00Z',
  end: '2024-01-02T00:00:00Z'
});

console.log('Network Analysis:', {
  totalConnections: networkAnalysis.summary.totalConnections,
  suspiciousConnections: networkAnalysis.summary.suspiciousConnections,
  riskLevel: networkAnalysis.summary.riskLevel
});

Workflow Execution

// Execute a predefined workflow
const executionId = await orchestrator.executeWorkflow('case-investigation', {
  caseId: 'case-123',
  includeCorrelation: true,
  includeNetworkAnalysis: true
});

console.log('Workflow started:', executionId);

📈 Monitoring and Metrics

System Status

const status = await orchestrator.getStatus();
console.log('System Status:', {
  status: status.status,
  uptime: status.uptime,
  totalAgents: status.agents.total,
  healthyAgents: status.agents.healthy,
  totalRequests: status.performance.totalRequests
});

Agent Metrics

const metrics = await orchestrator.getAgentMetrics();
console.log('Agent Metrics:', {
  registryStats: metrics.registry,
  channelStats: metrics.channel,
  systemMetrics: metrics.system
});

Event Monitoring

// Monitor agent events
orchestrator.on('agent_event', (event) => {
  console.log('Agent Event:', event.type, 'from', event.sourceAgentId.type);
});

// Monitor critical agent states
orchestrator.on('agent_critical', (status) => {
  console.error('Agent Critical:', status.id.type);
});

// Monitor metrics collection
orchestrator.on('metrics_collected', (metrics) => {
  console.log('Metrics Update:', metrics.registry.totalRequests);
});

🧪 Testing

Unit Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Integration Testing

# Test with actual Stellar Cyber API
export STELLAR_API_URL=https://poc.stellarcyber.cloud
export STELLAR_API_TOKEN=your_token
export TEST_CASE_ID=actual_case_id

npm run demo

🔒 Security

Authentication

The system uses JWT-based authentication with automatic token refresh:

// Token refresh is handled automatically
const response = await agent.makeRequest('GET', '/api/v1/cases');

Error Handling

Comprehensive error handling with retry logic:

try {
  const result = await agent.executeWithRetry(request, {
    maxRetries: 3,
    backoffMultiplier: 2,
    initialDelay: 1000
  });
} catch (error) {
  logger.error('Request failed after retries', { error });
}

📝 Configuration

Environment Variables

# Required
STELLAR_API_URL=https://poc.stellarcyber.cloud
STELLAR_API_TOKEN=your_api_token

# Optional
LOG_LEVEL=info
TEST_CASE_ID=test_case_id

Agent Configuration

const config = {
  stellar: {
    apiUrl: 'https://poc.stellarcyber.cloud',
    apiToken: 'your_token'
  },
  agents: {
    hub: {
      enabled: true,
      config: {
        maxConcurrentRequests: 100,
        loadBalancing: 'least-busy'
      }
    },
    investigation: {
      enabled: true,
      config: {
        requestTimeout: 60000,
        maxRetries: 3
      }
    },
    correlation: {
      enabled: true,
      config: {
        correlationThreshold: 0.7,
        enableCampaignDetection: true
      }
    },
    network: {
      enabled: true,
      config: {
        analysisTimeout: 300000,
        enableDeepPacketAnalysis: true
      }
    }
  }
};

🛠️ Development

Project Structure

src/
├── agents/           # Agent implementations
│   ├── hub-agent.ts
│   ├── investigation-agent.ts
│   ├── correlation-agent.ts
│   └── network-agent.ts
├── core/            # Core framework
│   ├── base-agent.ts
│   ├── agent-registry.ts
│   └── communication-channel.ts
├── types/           # Type definitions
│   └── agent.ts
├── utils/           # Utilities
│   └── logger.ts
├── orchestrator.ts  # Main orchestrator
└── index.ts        # Entry point

scripts/             # Demo and test scripts
docs/               # Documentation
├── SECURITY.md     # Security guidelines
├── SYSTEM_OVERVIEW.md
└── APT-Killchain-5WH-Analysis-Report.md

Adding New Agents

1. Create agent class extending BaseAgent
2. Implement required abstract methods
3. Define agent capabilities and metadata
4. Register in orchestrator
5. Add to configuration

Extending Capabilities

// Add new capability to existing agent
const newCapability: AgentCapability = {
  name: 'new_capability',
  description: 'Description of new capability',
  inputSchema: { /* schema */ },
  outputSchema: { /* schema */ }
};

// Handle in agent's handleRequest method
protected async handleRequest(request: AgentRequest): Promise<any> {
  switch (request.capability) {
    case 'new_capability':
      return await this.handleNewCapability(request.payload);
    // ... other cases
  }
}

📖 Documentation

Agent Lifecycle

1. Initialize: Set up agent resources and connections
2. Start: Begin accepting requests and start monitoring
3. Running: Process requests and maintain health
4. Stop: Gracefully shut down and clean up resources
5. Destroy: Final cleanup and resource deallocation

Workflow Definition

const workflow: WorkflowDefinition = {
  id: 'custom-workflow',
  name: 'Custom Analysis Workflow',
  steps: [
    {
      id: 'step1',
      agentType: 'investigation',
      capability: 'investigate_case',
      input: { caseId: '${input.caseId}' }
    },
    {
      id: 'step2',
      agentType: 'correlation',
      capability: 'find_related_cases',
      input: { caseId: '${input.caseId}' },
      condition: '${step1.findings.length} > 0'
    }
  ]
};

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For questions, issues, or contributions:

1. Check the Issues page
2. Create a new issue with detailed description
3. Include relevant logs and configuration
4. Provide steps to reproduce any problems

🚀 Current Capabilities & Future Enhancements

✅ Implemented Features

• [x] Malware Analysis Agent - Fully implemented with behavior analysis
• [x] Credential Analysis Agent - Complete with breach detection and password analysis
• [x] Campaign Detection Agent - Advanced threat campaign identification
• [x] Multi-Agent Architecture - Hub-and-spoke orchestration system
• [x] Workflow Orchestration - Complex multi-step automated workflows
• [x] Network Analysis - Comprehensive network threat detection
• [x] Case Correlation - Advanced case relationship detection
• [x] MCP Integration - Multiple server variants for different use cases
• [x] TypeScript Support - Complete type safety and compilation

🔮 Future Enhancements

• [ ] Machine Learning Integration
• [ ] Distributed Deployment Support
• [ ] REST API Interface
• [ ] Web UI Dashboard
• [ ] Advanced Visualization
• [ ] Enhanced Threat Intelligence Integration
• [ ] Custom Rule Engine
• [ ] Real-time Event Streaming
• [ ] Advanced Reporting and Analytics