stellar-cyber-mcp-agents/README.md

Model Context Protocol (MCP) server for Stellar Cyber security operations with specialized multi-agent analysis capabilities

# 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](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)
```bash
# 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)
```bash
# 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
```bash
# 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:
```bash
cp .env.example .env
```

2. Edit `.env` with your Stellar Cyber credentials:
```env
# 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)
```bash
# 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
```bash
# 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:**
```json
{
  "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:
```bash
npm install -g stellar-cyber-mcp-agents
```

2. Add to your Claude Desktop configuration file:
```json
{
  "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](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

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

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

await orchestrator.start();
```

### Case Investigation

```typescript
// 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

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

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

### Network Analysis

```typescript
// 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

```typescript
// 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

```typescript
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

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

### Event Monitoring

```typescript
// 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

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

### Integration Testing

```bash
# 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:

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

### Error Handling

Comprehensive error handling with retry logic:

```typescript
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

```env
# 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

```typescript
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

```typescript
// 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

```typescript
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](LICENSE) file for details.

## 🆘 Support

For questions, issues, or contributions:

1. Check the [Issues](../../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