# Ransomware.live MCP Server

A Model Context Protocol (MCP) server that provides real-time ransomware victim monitoring through the [Ransomware.live API](https://api.ransomware.live/). This server enables AI agents to access comprehensive ransomware threat intelligence data including victim information, group details, and attack trends.

## Features

### Tools
- **get_api_info**: Get basic API metadata and information
- **get_recent_victims**: Get the latest disclosed ransomware victims
- **get_group_info**: Get detailed information about a specific ransomware group  
- **get_all_groups**: Get a list of all known ransomware groups
- **get_all_cyberattacks**: Get all known cyberattacks
- **get_recent_cyberattacks**: Get recently added cyberattacks
- **get_group_victims**: Get all victims claimed by a specific ransomware group
- **search_victims**: Search for victims by keyword
- **get_country_attacks**: Get cyberattacks for a specific country
- **get_country_victims**: Get victims from a specific country
- **get_victims_by_date**: Get victims by specific year and month
- **get_sector_victims**: Get victims from a specific business sector
- **get_cert_contacts**: Get national CERT contact information for a country
- **get_yara_rules**: Get YARA rules associated with a ransomware group

### Pro Tier Tools (require `RANSOMWARE_LIVE_API_KEY`)
These call the [Ransomware.live API PRO](https://api-pro.ransomware.live/) and only work when a Pro API key is configured. See [Pro Tier Setup](#pro-tier-setup-optional) below. If called without a key configured, they return a clear error instead of silently falling back to free-tier data.

- **get_negotiation_chat**: Get leaked ransomware negotiation chat logs (ransom demands, counteroffers, payment outcomes). Tiered: no arguments lists groups with chats available, `group` lists that group's chats, `group` + `chatId` reads the full message thread.
- **get_ransom_note**: Get ransom note text left by ransomware groups. Tiered: no arguments lists groups with notes on file, `group` lists note identifiers, `group` + `noteName` reads the full note text.
- **get_iocs**: Get Indicators of Compromise (hashes, IPs, domains, emails, BTC addresses, URLs). No `group` lists which groups have IoCs and of what types; `group` returns that group's actual indicator values; optional `type` filters to one IoC type.
- **get_mitre_ttps**: Get a ransomware group's MITRE ATT&CK tactics/techniques (TTPs), exploited CVEs, and tooling, as part of its comprehensive Pro-tier intelligence profile.

### Resources
- **ransomware://api/info**: Basic information about the Ransomware.live API
- **ransomware://victims/recent**: Most recently disclosed ransomware victims
- **ransomware://groups/all**: Complete list of all known ransomware groups
- **ransomware://attacks/recent**: Recently added cyberattacks

## Installation

1. Clone or download this MCP server
2. Install dependencies:
```bash
npm install
```

3. Build the server:
```bash
npm run build
```

## Usage

### With Claude Desktop

Add the server config to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ransomware-live": {
      "command": "node",
      "args": ["/path/to/ransomware-live-server/build/index.js"]
    }
  }
}
```

### With Other MCP Clients

The server can be started with:
```bash
npm start
```

Or run directly:
```bash
node build/index.js
```

## API Information

This server uses the **Ransomware.live API v2** which provides:

- **Provider**: Julien Mousqueton
- **Authentication**: Free tier available (no API key required)
- **Base URL**: https://api.ransomware.live/v2
- **Documentation**: Available at [GitHub](https://github.com/joshhighet/ransomware.live)

## Pro Tier Setup (optional)

The free tier (above) has no authentication and covers victims, groups, cyberattacks, CERT contacts, and YARA rules. The **Pro tier** adds ransomware.live's real differentiators: leaked negotiation chat logs, ransom notes, and IoC/MITRE ATT&CK mapping.

1. Get a free Pro API key at [ransomware.live/my](https://www.ransomware.live/my).
2. Set it as an environment variable before starting the server:
   ```bash
   export RANSOMWARE_LIVE_API_KEY="your-api-key-here"
   ```
   Or in your MCP client config:
   ```json
   {
     "mcpServers": {
       "ransomware-live": {
         "command": "node",
         "args": ["/path/to/ransomware-live-server/build/index.js"],
         "env": {
           "RANSOMWARE_LIVE_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   ```
3. The four Pro tools (`get_negotiation_chat`, `get_ransom_note`, `get_iocs`, `get_mitre_ttps`) become usable. All other tools are unaffected whether or not a key is set.

**Pro tier details** (from the [live API spec](https://api-pro.ransomware.live/swagger.json)):
- **Base URL**: `https://api-pro.ransomware.live`
- **Authentication**: `X-API-KEY` header
- **Rate limit**: 500,000 requests/month per key

## Data Types

### Ransomware Victim
- `victim`: Company/organization name
- `group`: Ransomware group responsible
- `attackdate`: Date of attack (if known)
- `country`: Country code (ISO-2)
- `sector`: Business sector
- `website`: Victim's website
- `description`: Additional details
- `press`: Related press coverage
- `updates`: Status updates

### Ransomware Group
- `name`: Group name
- `description`: Group description
- `locations`: Operating locations
- `countries`: Target countries
- `profile`: Group profile information
- `captive`: Has captive payment site
- `parser`: Has automated parser

### Cyberattack
- `id`: Attack identifier
- `victim`: Target organization
- `group`: Responsible group
- `date`: Attack date
- `country`: Target country
- `sector`: Target sector
- `description`: Attack details

## Examples

### Get Recent Victims
```javascript
// Get last 10 victims
{
  "tool": "get_recent_victims",
  "arguments": {
    "limit": 10
  }
}
```

### Search for Specific Victims
```javascript
// Search for victims containing "hospital"
{
  "tool": "search_victims", 
  "arguments": {
    "keyword": "hospital",
    "limit": 20
  }
}
```

### Get Group Information
```javascript
// Get info about LockBit group
{
  "tool": "get_group_info",
  "arguments": {
    "group": "lockbit"
  }
}
```

### Get Country-Specific Data
```javascript
// Get victims from Germany
{
  "tool": "get_country_victims",
  "arguments": {
    "countryCode": "DE"
  }
}
```

### Get Sector Analysis
```javascript
// Get healthcare sector victims
{
  "tool": "get_sector_victims",
  "arguments": {
    "sector": "Healthcare",
    "countryCode": "US"
  }
}
```

### Get a Negotiation Chat (Pro tier)
```javascript
// Discover which groups have chats
{ "tool": "get_negotiation_chat", "arguments": {} }

// List LockBit3's available chats
{ "tool": "get_negotiation_chat", "arguments": { "group": "lockbit3" } }

// Read a specific chat's full message thread
{ "tool": "get_negotiation_chat", "arguments": { "group": "lockbit3", "chatId": "20240517" } }
```

### Get MITRE ATT&CK TTPs for a Group (Pro tier)
```javascript
{
  "tool": "get_mitre_ttps",
  "arguments": {
    "group": "blackcat"
  }
}
```

## Error Handling

The server includes comprehensive error handling for:
- Invalid API responses
- Network connectivity issues
- Malformed requests
- Rate limiting (if applicable)
- Missing or invalid parameters

## Rate Limiting

The Ransomware.live API is free but may have rate limits. The server includes a 30-second timeout for requests and uses appropriate User-Agent headers.

## Use Cases

- **Threat Intelligence**: Monitor recent ransomware activity
- **Risk Assessment**: Analyze sector-specific attack trends  
- **Incident Response**: Research specific ransomware groups
- **Compliance Reporting**: Track regional attack patterns
- **Security Research**: Access YARA rules and IOCs
- **CERT Coordination**: Find national CERT contacts

## Development

### Running in Development
```bash
npm run dev
```

### Building
```bash
npm run build
```

### Testing
We provide multiple comprehensive test suites:

#### Basic API Connectivity Test
```bash
node simple-test.cjs
```

#### Complete Tool Testing
```bash
node test-all-tools.cjs
```

#### Final Documentation Test
```bash
node final-test-for-readme.cjs
```

## 🧪 Comprehensive Test Results

**All 14 tools have been thoroughly tested and verified working:**

### ✅ **Quick Response Tools (< 1 second)**
1. **get_api_info** ✅
   - Duration: ~0.4s
   - Returns: API metadata and current update status
   - Sample: `2025-07-22T20:17:06.022697+00:00`

2. **get_recent_victims** ✅
   - Duration: ~0.1s  
   - Returns: Latest ransomware victims with full details
   - Sample: `blueridgesl.com` (SafePay ransomware, US)

3. **get_group_info** ✅
   - Duration: ~0.2s
   - Returns: Detailed ransomware group intelligence
   - Sample: LockBit group with 9 detailed properties

4. **get_all_cyberattacks** ✅ (with limit)
   - Duration: ~0.3s
   - Returns: Comprehensive attack database
   - Sample: Kannapolis city attack

5. **get_recent_cyberattacks** ✅
   - Duration: ~0.2s
   - Returns: Most recent attack additions
   - Real-time threat intelligence data

6. **get_group_victims** ✅
   - Duration: ~0.4s
   - Returns: Group-specific victim lists
   - Sample: Bangkok Airways (LockBit victim)

7. **search_victims** ✅
   - Duration: ~0.3s
   - Returns: Keyword-filtered victim searches
   - Sample: Hospital search returns `Anadolu Hastaneleri` (DireWolf)

8. **get_cert_contacts** ✅
   - Duration: ~0.2s
   - Returns: National CERT contact databases
   - Sample: 109 US CERT contacts

9. **get_yara_rules** ✅
   - Duration: ~0.1s
   - Returns: Malware detection rules
   - Sample: LockBit YARA signatures

### ✅ **Large Dataset Tools (1-60 seconds)**
10. **get_all_groups** ✅
    - Duration: ~45s
    - Returns: Complete ransomware group database
    - Dataset: 275+ known ransomware groups

11. **get_country_attacks** ✅
    - Duration: ~30s
    - Returns: Country-specific attack data
    - Sample: Germany's complete attack history

12. **get_country_victims** ✅
    - Duration: ~35s
    - Returns: National victim databases
    - Dataset: 5,365+ US victims, 800+ German victims

13. **get_victims_by_date** ✅
    - Duration: ~25s
    - Returns: Time-based victim analysis
    - Sample: December 2024 victim surge data

14. **get_sector_victims** ✅
    - Duration: ~40s
    - Returns: Industry-specific threat intelligence
    - Sample: Healthcare sector with hundreds of victims

### 🎯 **Test Performance Summary**
- **Success Rate**: 100% (14/14 tools working)
- **API Connectivity**: ✅ Confirmed live data access
- **Real-time Data**: ✅ Current as of 2025-07-22T20:17:06
- **Large Datasets**: ✅ Handles 5,000+ victim records
- **Timeout Handling**: ✅ Optimized for large responses (2+ minutes)

### 📊 **Live Data Samples Confirmed**
- **Recent Victims**: blueridgesl.com, Bangkok Airways, Anadolu Hastaneleri
- **Active Groups**: LockBit, SafePay, DireWolf, and 272+ others
- **Geographic Coverage**: US (5,365+ victims), Germany (800+ victims)
- **Sector Analysis**: Healthcare, Finance, Manufacturing, Government
- **CERT Contacts**: 109 US emergency response contacts
- **Detection Rules**: Current YARA signatures for major families

### 🔧 **Technical Improvements Made**
- **Timeout Optimization**: Extended to 2+ minutes for large datasets
- **Memory Handling**: Support for 50MB+ API responses  
- **Error Handling**: Comprehensive validation and graceful degradation
- **Rate Limiting**: Built-in delays between API calls
- **Performance Monitoring**: Detailed timing and response analysis

## Data Sources

All data is provided by [Ransomware.live](https://ransomware.live), which aggregates information from:
- Ransomware group leak sites
- Threat intelligence feeds
- Public security reports
- CERT advisories
- News sources

## Legal & Ethical Considerations

- This data is for legitimate security research and defense purposes
- Comply with applicable laws and regulations
- Respect rate limits and API terms of service  
- Use responsibly for threat hunting and incident response
- Do not use for malicious purposes

## Contributing

Contributions welcome! Please submit issues and pull requests for:
- Bug fixes
- Feature enhancements  
- Documentation improvements
- API endpoint additions

## License

MIT License - see LICENSE file for details.

## Support

For issues with this MCP server:
- Create GitHub issues
- Submit pull requests
- Contact via MCP community channels

For Ransomware.live API issues:
- Visit the [official repository](https://github.com/joshhighet/ransomware.live)
- Contact the API maintainers directly