npm package: @modular-intelligence/stix-taxii
Description: MCP server for STIX 2.1 parsing and TAXII 2.1 threat intelligence sharing
Latest version: 1.0.2

# STIX/TAXII MCP Server

A comprehensive threat intelligence sharing server that implements the TAXII 2.1 protocol for accessing threat intelligence feeds and provides STIX 2.1 parsing capabilities. This MCP (Model Context Protocol) server enables Claude to query TAXII servers, extract indicators of compromise (IOCs), create threat indicators, and analyze STIX threat intelligence objects.

## Overview

This server provides complete support for modern threat intelligence sharing and analysis:

- **TAXII 2.1 Protocol** - Query threat intelligence collections from TAXII servers including MITRE ATT&CK, threat feeds, and custom installations
- **STIX 2.1 Parsing** - Parse, analyze, and search STIX object bundles for threat indicators and relationships
- **IOC Extraction** - Automatically extract indicators of compromise from text including IPv4/IPv6 addresses, domains, URLs, email addresses, file hashes, and CVE identifiers

Perfect for threat intelligence integration, incident response analysis, malware analysis, and security research workflows.

## Tools

| Tool | Description |
|------|-------------|
| `taxii_discover` | Discover TAXII 2.1 server API roots and capabilities |
| `taxii_get_collections` | List available threat intelligence collections on a TAXII server |
| `taxii_poll` | Poll a TAXII collection for STIX objects and threat indicators |
| `stix_parse_bundle` | Parse and summarize STIX 2.1 bundles including object counts and indicators |
| `stix_create_indicator` | Create valid STIX 2.1 indicator objects with proper formatting |
| `stix_search_indicators` | Search for indicators within STIX bundles by type and pattern content |
| `ioc_extract_text` | Extract IOCs from text (IPs, domains, URLs, emails, hashes, CVEs) |

### TAXII Discover

Discover TAXII 2.1 server API roots, capabilities, and metadata.

**Input Parameters:**
```typescript
{
  server_url: string  // TAXII server URL (must be HTTP or HTTPS)
}
```

**Example Request:**
```json
{
  "server_url": "https://cti-taxii.mitre.org"
}
```

**Example Output:**
```json
{
  "title": "MITRE CTI TAXII Server",
  "description": "Hosted threat intelligence data from MITRE",
  "contact": "taxii-support@mitre.org",
  "default": "stix",
  "api_roots": [
    "https://cti-taxii.mitre.org/stix",
    "https://cti-taxii.mitre.org/enterprise-attack",
    "https://cti-taxii.mitre.org/mobile-attack"
  ]
}
```

### TAXII Get Collections

List all available threat intelligence collections from a TAXII API root.

**Input Parameters:**
```typescript
{
  server_url: string  // TAXII server URL
  api_root: string    // API root path (e.g., "stix" or "enterprise-attack")
}
```

**Example Request:**
```json
{
  "server_url": "https://cti-taxii.mitre.org",
  "api_root": "stix"
}
```

**Example Output:**
```json
{
  "collections": [
    {
      "id": "enterprise-attack",
      "title": "Enterprise ATT&CK",
      "description": "ATT&CK objects describing adversary tactics and techniques targeting Enterprise systems",
      "can_read": true,
      "can_write": false,
      "media_types": ["application/stix+json;version=2.1"]
    },
    {
      "id": "mobile-attack",
      "title": "Mobile ATT&CK",
      "description": "ATT&CK objects describing adversary tactics and techniques targeting Mobile systems",
      "can_read": true,
      "can_write": false,
      "media_types": ["application/stix+json;version=2.1"]
    },
    {
      "id": "ics-attack",
      "title": "ICS ATT&CK",
      "description": "ATT&CK objects describing adversary tactics and techniques targeting ICS/OT systems",
      "can_read": true,
      "can_write": false,
      "media_types": ["application/stix+json;version=2.1"]
    }
  ]
}
```

### TAXII Poll

Poll a TAXII collection for STIX objects and threat indicators with optional filtering.

**Input Parameters:**
```typescript
{
  server_url: string          // TAXII server URL
  api_root: string            // API root path
  collection_id: string       // Collection ID to poll
  added_after: string         // ISO 8601 timestamp filter (optional)
  match_type: string          // STIX object type filter (optional)
  max_results: number         // Maximum results to return (1-1000, default: 50)
}
```

**Example Request:**
```json
{
  "server_url": "https://cti-taxii.mitre.org",
  "api_root": "stix",
  "collection_id": "enterprise-attack",
  "match_type": "malware",
  "max_results": 10
}
```

**Example Output:**
```json
{
  "objects": [
    {
      "type": "malware",
      "id": "malware--6ca01203-79f0-481e-9ef0-07bc149285f7",
      "created": "2023-01-15T12:00:00.000Z",
      "modified": "2024-01-10T08:30:00.000Z",
      "spec_version": "2.1",
      "name": "Poison Ivy",
      "description": "Poison Ivy is a remote access trojan (RAT)...",
      "labels": ["remote-access-trojan"],
      "external_references": [
        {
          "source_name": "mitre-attack",
          "external_id": "S0012"
        }
      ]
    },
    {
      "type": "malware",
      "id": "malware--7d8e1fac-0b7f-4e9d-a2c3-d5f1a8b2c9e0",
      "created": "2023-02-20T10:00:00.000Z",
      "modified": "2024-01-12T14:15:00.000Z",
      "spec_version": "2.1",
      "name": "Emotet",
      "description": "Emotet is a modular banking trojan...",
      "labels": ["trojan"],
      "external_references": [
        {
          "source_name": "mitre-attack",
          "external_id": "S0367"
        }
      ]
    }
  ],
  "more": false,
  "next": null,
  "total_count": 2
}
```

### STIX Parse Bundle

Parse and analyze a STIX 2.1 bundle, extracting object counts, indicators, and relationships.

**Input Parameters:**
```typescript
{
  bundle_json: string  // STIX bundle as JSON string
}
```

**Example Request:**
```json
{
  "bundle_json": "{\"type\": \"bundle\", \"id\": \"bundle--00000000-0000-0000-0000-000000000000\", \"objects\": [{\"type\": \"indicator\", \"id\": \"indicator--01234567-89ab-cdef-0123-456789abcdef\", \"created\": \"2024-01-15T10:30:00.000Z\", \"modified\": \"2024-01-15T10:30:00.000Z\", \"pattern\": \"[ipv4-addr:value = '192.0.2.1']\", \"labels\": [\"malicious-activity\"]}]}"
}
```

**Example Output:**
```json
{
  "bundle_id": "bundle--00000000-0000-0000-0000-000000000000",
  "total_objects": 15,
  "type_counts": {
    "indicator": 8,
    "malware": 3,
    "relationship": 4
  },
  "indicator_count": 8,
  "relationship_count": 4,
  "indicators": [
    {
      "id": "indicator--01234567-89ab-cdef-0123-456789abcdef",
      "name": "Suspicious C2 Communication",
      "pattern": "[ipv4-addr:value = '192.0.2.1']",
      "labels": ["malicious-activity", "command-and-control"],
      "created": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "indicator--fedcba98-7654-3210-fedc-ba9876543210",
      "name": "Malware File Hash",
      "pattern": "[file:hashes.MD5 = 'd41d8cd98f00b204e9800998ecf8427e']",
      "labels": ["malicious-activity"],
      "created": "2024-01-14T15:20:00.000Z"
    }
  ],
  "relationships": [
    {
      "id": "relationship--11111111-2222-3333-4444-555555555555",
      "relationship_type": "indicates",
      "source_ref": "indicator--01234567-89ab-cdef-0123-456789abcdef",
      "target_ref": "malware--aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  ]
}
```

### STIX Create Indicator

Create a valid STIX 2.1 indicator object with proper UUID, timestamps, and structure.

**Input Parameters:**
```typescript
{
  pattern: string        // STIX pattern (e.g., "[ipv4-addr:value = '1.2.3.4']")
  name: string          // Indicator name/description
  description: string   // Optional detailed description
  labels: string[]      // Optional labels (default: ["malicious-activity"])
}
```

**Example Request:**
```json
{
  "pattern": "[ipv4-addr:value = '203.0.113.42']",
  "name": "Suspected C2 Server",
  "description": "IP address associated with command and control infrastructure",
  "labels": ["malicious-activity", "command-and-control"]
}
```

**Example Output:**
```json
{
  "indicator": {
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6",
    "created": "2024-01-15T14:30:22.456Z",
    "modified": "2024-01-15T14:30:22.456Z",
    "name": "Suspected C2 Server",
    "description": "IP address associated with command and control infrastructure",
    "pattern": "[ipv4-addr:value = '203.0.113.42']",
    "pattern_type": "stix",
    "valid_from": "2024-01-15T14:30:22.456Z",
    "labels": ["malicious-activity", "command-and-control"]
  },
  "json": "{\n  \"type\": \"indicator\",\n  \"spec_version\": \"2.1\",\n  \"id\": \"indicator--a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6\",\n  \"created\": \"2024-01-15T14:30:22.456Z\",\n  \"modified\": \"2024-01-15T14:30:22.456Z\",\n  \"name\": \"Suspected C2 Server\",\n  \"description\": \"IP address associated with command and control infrastructure\",\n  \"pattern\": \"[ipv4-addr:value = '203.0.113.42']\",\n  \"pattern_type\": \"stix\",\n  \"valid_from\": \"2024-01-15T14:30:22.456Z\",\n  \"labels\": [\"malicious-activity\", \"command-and-control\"]\n}"
}
```

### STIX Search Indicators

Search for indicators and STIX objects within a bundle by type and pattern content.

**Input Parameters:**
```typescript
{
  bundle_json: string       // STIX bundle as JSON string
  search_type: string       // Optional STIX object type filter (e.g., "indicator", "malware")
  pattern_contains: string  // Optional text search in patterns/names/descriptions
  max_results: number       // Maximum results to return (1-1000, default: 50)
}
```

**Example Request:**
```json
{
  "bundle_json": "{\"type\": \"bundle\", \"id\": \"bundle--xyz\", \"objects\": [...]}",
  "search_type": "indicator",
  "pattern_contains": "command-and-control",
  "max_results": 5
}
```

**Example Output:**
```json
{
  "total_matches": 3,
  "returned_count": 3,
  "objects": [
    {
      "id": "indicator--01234567-89ab-cdef-0123-456789abcdef",
      "type": "indicator",
      "name": "C2 Server IP",
      "description": "Known command and control server",
      "pattern": "[ipv4-addr:value = '192.0.2.1']",
      "labels": ["malicious-activity", "command-and-control"],
      "created": "2024-01-15T10:30:00.000Z",
      "modified": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "indicator--fedcba98-7654-3210-fedc-ba9876543210",
      "type": "indicator",
      "name": "Suspicious Domain",
      "description": "Domain used for command and control",
      "pattern": "[domain-name:value = 'evil.example.com']",
      "labels": ["malicious-activity", "command-and-control"],
      "created": "2024-01-14T15:20:00.000Z",
      "modified": "2024-01-14T15:20:00.000Z"
    },
    {
      "id": "indicator--aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "type": "indicator",
      "name": "Malicious URL",
      "description": "URL used in command and control traffic",
      "pattern": "[url:value = 'http://malware.example.com/cmd']",
      "labels": ["malicious-activity", "command-and-control"],
      "created": "2024-01-13T12:15:00.000Z",
      "modified": "2024-01-13T12:15:00.000Z"
    }
  ]
}
```

### IOC Extract Text

Extract indicators of compromise from text including IP addresses, domains, URLs, emails, file hashes, and CVE identifiers.

**Input Parameters:**
```typescript
{
  text: string  // Text to extract IOCs from (maximum 50000 characters)
}
```

**Example Request:**
```json
{
  "text": "Malicious activity detected from 192.168.1.100 and 2001:db8::1. The attacker used command-and-control server at evil.example.com and malware.example.com:8080. Email address used: attacker@evil.example.com. File hash: d41d8cd98f00b204e9800998ecf8427e (MD5) and 356a192b7913b04c54574d18c28d46e6395428ab (SHA1). CVE-2021-44228 and CVE-2022-1234 were exploited."
}
```

**Example Output:**
```json
{
  "total_iocs": 10,
  "by_type": {
    "ipv4": {
      "count": 1,
      "values": ["192.168.1.100"]
    },
    "ipv6": {
      "count": 1,
      "values": ["2001:db8::1"]
    },
    "domain": {
      "count": 2,
      "values": ["evil.example.com", "malware.example.com"]
    },
    "url": {
      "count": 1,
      "values": ["http://malware.example.com:8080"]
    },
    "email": {
      "count": 1,
      "values": ["attacker@evil.example.com"]
    },
    "md5": {
      "count": 1,
      "values": ["d41d8cd98f00b204e9800998ecf8427e"]
    },
    "sha1": {
      "count": 1,
      "values": ["356a192b7913b04c54574d18c28d46e6395428ab"]
    },
    "cve": {
      "count": 2,
      "values": ["CVE-2021-44228", "CVE-2022-1234"]
    }
  },
  "all_iocs": [
    {
      "type": "ipv4",
      "value": "192.168.1.100",
      "source": "text_extraction"
    },
    {
      "type": "ipv6",
      "value": "2001:db8::1",
      "source": "text_extraction"
    },
    {
      "type": "domain",
      "value": "evil.example.com",
      "source": "text_extraction"
    },
    {
      "type": "domain",
      "value": "malware.example.com",
      "source": "text_extraction"
    },
    {
      "type": "url",
      "value": "http://malware.example.com:8080",
      "source": "text_extraction"
    },
    {
      "type": "email",
      "value": "attacker@evil.example.com",
      "source": "text_extraction"
    },
    {
      "type": "md5",
      "value": "d41d8cd98f00b204e9800998ecf8427e",
      "source": "text_extraction"
    },
    {
      "type": "sha1",
      "value": "356a192b7913b04c54574d18c28d46e6395428ab",
      "source": "text_extraction"
    },
    {
      "type": "cve",
      "value": "CVE-2021-44228",
      "source": "text_extraction"
    },
    {
      "type": "cve",
      "value": "CVE-2022-1234",
      "source": "text_extraction"
    }
  ]
}
```

## Configuration

### Environment Variables

This server supports optional authentication for TAXII servers that require credentials. Set these environment variables to enable Basic authentication:

```bash
export TAXII_URL="https://your-taxii-server.com"      # Optional: Default TAXII server
export TAXII_USER="your-username"                       # Optional: Username for Basic auth
export TAXII_PASSWORD="your-password"                   # Optional: Password for Basic auth
```

### Public TAXII Servers

Several public TAXII servers are available for testing and threat intelligence access:

**MITRE ATT&CK**
- URL: https://cti-taxii.mitre.org
- Description: Comprehensive knowledge base of adversary tactics and techniques
- Authentication: Not required
- API Roots: stix, enterprise-attack, mobile-attack, ics-attack
- Documentation: https://mitre-attack.github.io/

**Anomali Limo**
- URL: https://limo.anomali.com/api/v1/taxii2/
- Description: Threat intelligence feed with indicators and malware analysis
- Authentication: Not required
- API Roots: root
- Documentation: https://www.anomali.com/

**Public TAXII Servers Summary**

| Server | URL | Authentication | Status |
|--------|-----|-----------------|--------|
| MITRE ATT&CK | https://cti-taxii.mitre.org | Not required | Active |
| Anomali Limo | https://limo.anomali.com/api/v1/taxii2/ | Not required | Active |

## Installation

### Prerequisites

- Bun runtime (version 1.x or later)
- Node.js 18+ (alternative runtime)
- Network access to TAXII servers (HTTP/HTTPS)

### Steps

1. Clone or download this repository:
```bash
git clone <repo-url>
cd stix-taxii
```

2. Install dependencies:
```bash
bun install
```

3. Build the project:
```bash
bun run build
```

4. Set environment variables (optional):
```bash
export TAXII_USER="your-username"
export TAXII_PASSWORD="your-password"
```

5. Run the server:
```bash
bun run start
```

The server will start listening on stdio transport.

## Usage

### Running the Server

Start the server with Bun:

```bash
bun run src/index.ts
```

The server implements the Model Context Protocol (MCP) and communicates via stdio transport. It can be integrated with Claude or other MCP clients.

### Claude Desktop Configuration

Add the server to your Claude Desktop configuration at `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "stix-taxii": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/stix-taxii/src/index.ts"
      ],
      "env": {
        "TAXII_USER": "your-username",
        "TAXII_PASSWORD": "your-password"
      }
    }
  }
}
```

### Claude Code MCP Settings

Configure the server in Claude Code's MCP settings (typically in `.mcp.json` or via settings UI):

```json
{
  "servers": {
    "stix-taxii": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/stix-taxii/src/index.ts"],
      "env": {
        "TAXII_USER": "your-username",
        "TAXII_PASSWORD": "your-password"
      }
    }
  }
}
```

### Example Usage in Claude

Once configured, you can use the tools directly in conversations with Claude:

**Request:**
"Discover the MITRE ATT&CK TAXII server and list its available collections"

**Claude will call:**
```json
{
  "tool": "taxii_discover",
  "input": {
    "server_url": "https://cti-taxii.mitre.org"
  }
}
```

Then:
```json
{
  "tool": "taxii_get_collections",
  "input": {
    "server_url": "https://cti-taxii.mitre.org",
    "api_root": "stix"
  }
}
```

**Request:**
"Poll the MITRE enterprise-attack collection for malware indicators and show me the top 5 results"

**Claude will call:**
```json
{
  "tool": "taxii_poll",
  "input": {
    "server_url": "https://cti-taxii.mitre.org",
    "api_root": "stix",
    "collection_id": "enterprise-attack",
    "match_type": "malware",
    "max_results": 5
  }
}
```

**Request:**
"Extract all indicators of compromise from this incident report text"

**Claude will call:**
```json
{
  "tool": "ioc_extract_text",
  "input": {
    "text": "[incident report text here with IPs, domains, hashes, CVEs, etc.]"
  }
}
```

**Request:**
"Create a STIX indicator for the malicious IP address 192.0.2.50"

**Claude will call:**
```json
{
  "tool": "stix_create_indicator",
  "input": {
    "pattern": "[ipv4-addr:value = '192.0.2.50']",
    "name": "Malicious IP Address",
    "description": "IP address observed in malicious activity",
    "labels": ["malicious-activity", "command-and-control"]
  }
}
```

## Security

This server implements comprehensive input validation and security measures to prevent injection attacks and misuse:

### Input Validation

**URL Validation**
- Only HTTP and HTTPS protocols allowed
- Proper URL format validation using Node.js URL parser
- Prevents protocol injection and malformed URLs

**TAXII Collection ID Validation**
- Alphanumeric characters, hyphens, and underscores only
- Maximum length: 100 characters
- Prevents path traversal and injection attacks

**STIX Type Validation**
- Validates against whitelist of allowed STIX object types (indicator, malware, threat-actor, attack-pattern, campaign, course-of-action, identity, infrastructure, intrusion-set, tool, vulnerability, relationship, sighting)
- Rejects undefined or custom types to prevent injection

**STIX Bundle Parsing**
- Validates bundle structure and required fields
- Ensures objects array is present and valid
- Rejects malformed or incomplete STIX data

**IOC Extraction**
- Maximum text input: 50,000 characters
- Uses well-defined regex patterns for IOC detection
- Deduplicates extracted IOCs
- Safe regex patterns that prevent ReDoS attacks

### Authentication

**Basic Authentication**
- Optional TAXII_USER and TAXII_PASSWORD environment variables
- Uses standard Base64 encoding for HTTP Basic auth
- Only sent over HTTPS connections to secure servers

### What Gets Blocked

The server rejects:
- Non-HTTP/HTTPS URLs
- Invalid TAXII collection IDs containing special characters
- Undefined STIX object types not in the allowed list
- Malformed STIX bundles
- Text inputs exceeding 50,000 characters
- Oversized or suspicious TAXII API responses

### Error Handling

- Invalid inputs return descriptive error messages
- API errors are caught and reported with status codes
- Network timeouts and connection failures are handled gracefully
- Validation failures prevent malicious data from being processed

## License

ISC