npm package: @modular-intelligence/sigma-converter
Description: MCP server wrapping sigma-cli for Sigma rule conversion and management
Latest version: 1.0.2

# Sigma Converter MCP Server

MCP server wrapping `sigma-cli` for Sigma rule conversion and management. Convert Sigma detection rules to SIEM-specific query languages, manage processing pipelines, and analyze rule collections.

## Features

- **Multi-Backend Conversion**: Convert Sigma rules to 13+ SIEM/security platforms
- **Pipeline Management**: List and manage Sigma processing pipelines
- **Field Mapping**: View field name mappings between Sigma and target backends
- **Rule Testing**: Test-convert rules and validate output
- **Rule Analytics**: Analyze rule collections by severity, status, and logsource
- **Configuration Export**: Export backend configurations with field mappings

## Prerequisites

### 1. Install sigma-cli

```bash
pip install sigma-cli
```

### 2. Install pySigma Backends

Install backends for your target SIEM platforms:

```bash
# Splunk
pip install pysigma-backend-splunk

# Elasticsearch/OpenSearch
pip install pysigma-backend-elasticsearch
pip install pysigma-backend-opensearch

# QRadar
pip install pysigma-backend-qradar

# Microsoft 365 Defender
pip install pysigma-backend-microsoft365defender

# SentinelOne
pip install pysigma-backend-sentinelone

# CrowdStrike
pip install pysigma-backend-crowdstrike

# Carbon Black
pip install pysigma-backend-carbonblack

# Logpoint
pip install pysigma-backend-logpoint

# InsightIDR
pip install pysigma-backend-insightidr

# Loki
pip install pysigma-backend-loki

# Datadog
pip install pysigma-backend-datadog
```

### 3. Verify Installation

```bash
sigma --version
sigma list backends
```

## Installation

```bash
cd sigma-converter
bun install
bun run build
```

## Usage

### Start the Server

```bash
bun run start
```

### MCP Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "sigma-converter": {
      "command": "bun",
      "args": ["run", "/path/to/sigma-converter/src/index.ts"]
    }
  }
}
```

## Available Tools

### 1. sigma_batch_convert

Convert Sigma rules to SIEM-specific queries.

**Parameters:**
- `rule_path` (string, required): Path to Sigma rule file or directory
- `backend` (enum, required): Target SIEM backend
  - `splunk`, `elasticsearch`, `opensearch`, `qradar`, `microsoft365defender`, `sentinelone`, `crowdstrike`, `carbon_black`, `logpoint`, `sigma`, `insightidr`, `loki`, `datadog`
- `pipeline` (string, optional): Processing pipeline name
- `output_format` (enum, optional): Output format - `default`, `json`, `yaml` (default: `default`)
- `timeout` (number, optional): Max duration in seconds (10-120, default: 30)

**Example:**
```json
{
  "rule_path": "/path/to/rules/",
  "backend": "splunk",
  "pipeline": "sysmon",
  "output_format": "default",
  "timeout": 60
}
```

**Returns:**
```json
{
  "backend": "splunk",
  "pipeline": "sysmon",
  "converted_rules": [
    {
      "source_file": "rule1.yml",
      "converted_query": "index=windows EventCode=4688 ...",
      "errors": []
    }
  ],
  "total": 1,
  "success_count": 1,
  "error_count": 0
}
```

### 2. sigma_pipeline_list

List available Sigma processing pipelines.

**Parameters:** None

**Example:**
```json
{}
```

**Returns:**
```json
{
  "pipelines": [
    {
      "name": "sysmon",
      "description": "Sysmon pipeline for Windows event logs",
      "backends": ["splunk", "elasticsearch"]
    }
  ],
  "total_count": 1
}
```

### 3. sigma_pipeline_detail

Get detailed information about a specific pipeline.

**Parameters:**
- `pipeline` (string, required): Pipeline name to get details for

**Example:**
```json
{
  "pipeline": "sysmon"
}
```

**Returns:**
```json
{
  "name": "sysmon",
  "description": "Sysmon pipeline for Windows event logs",
  "compatible_backends": ["splunk", "elasticsearch", "qradar"],
  "field_mappings": []
}
```

### 4. sigma_field_mapping

View field name mappings between Sigma and target backend.

**Parameters:**
- `backend` (enum, required): Target SIEM backend
- `pipeline` (string, optional): Processing pipeline name

**Example:**
```json
{
  "backend": "splunk",
  "pipeline": "sysmon"
}
```

**Returns:**
```json
{
  "backend": "splunk",
  "pipeline": "sysmon",
  "mappings": [
    {
      "sigma_field": "EventID",
      "backend_field": "EventCode"
    },
    {
      "sigma_field": "ProcessName",
      "backend_field": "Image"
    }
  ],
  "total_mappings": 2
}
```

### 5. sigma_rule_test

Test-convert a Sigma rule and validate the output.

**Parameters:**
- `rule_content` (string, required): Sigma rule YAML content (max 100KB)
- `backend` (enum, required): Target SIEM backend
- `pipeline` (string, optional): Processing pipeline name
- `timeout` (number, optional): Max duration in seconds (10-120, default: 30)

**Example:**
```json
{
  "rule_content": "title: Test Rule\nlogsource:\n  product: windows\ndetection:\n  selection:\n    EventID: 4688\n  condition: selection",
  "backend": "splunk",
  "pipeline": "sysmon",
  "timeout": 30
}
```

**Returns:**
```json
{
  "valid": true,
  "converted_query": "index=windows EventCode=4688",
  "errors": [],
  "warnings": ["Field mapping applied"],
  "backend": "splunk",
  "pipeline": "sysmon"
}
```

### 6. sigma_rule_stats

Analyze Sigma rule collection statistics.

**Parameters:**
- `rule_path` (string, required): Path to Sigma rule file or directory

**Example:**
```json
{
  "rule_path": "/path/to/sigma/rules/"
}
```

**Returns:**
```json
{
  "total_rules": 150,
  "by_level": {
    "critical": 10,
    "high": 45,
    "medium": 60,
    "low": 25,
    "informational": 10
  },
  "by_status": {
    "stable": 80,
    "test": 50,
    "experimental": 20
  },
  "by_logsource": {
    "product:windows": 100,
    "product:linux": 30,
    "category:process_creation": 80
  },
  "tags_distribution": {
    "attack.t1059": 25,
    "attack.execution": 30,
    "attack.defense_evasion": 20
  }
}
```

### 7. sigma_export_config

Export Sigma backend configuration.

**Parameters:**
- `backend` (enum, required): Target SIEM backend
- `pipeline` (string, optional): Processing pipeline name
- `include_field_mappings` (boolean, optional): Include field mapping details (default: true)

**Example:**
```json
{
  "backend": "splunk",
  "pipeline": "sysmon",
  "include_field_mappings": true
}
```

**Returns:**
```json
{
  "backend": "splunk",
  "pipeline": "sysmon",
  "config": {
    "field_mappings": [
      {
        "sigma_field": "EventID",
        "backend_field": "EventCode"
      }
    ],
    "transforms": [],
    "conditions": []
  },
  "export_format_example": "index=* | search [converted query]",
  "description": "Configuration export for splunk with sysmon pipeline"
}
```

## Supported Backends

| Backend | Description | Example Use Case |
|---------|-------------|------------------|
| `splunk` | Splunk SIEM | Enterprise security monitoring |
| `elasticsearch` | Elasticsearch | Log analytics, SIEM |
| `opensearch` | OpenSearch | Open-source log analytics |
| `qradar` | IBM QRadar | Enterprise SIEM |
| `microsoft365defender` | Microsoft 365 Defender | Cloud security |
| `sentinelone` | SentinelOne | Endpoint detection |
| `crowdstrike` | CrowdStrike Falcon | EDR platform |
| `carbon_black` | VMware Carbon Black | Endpoint security |
| `logpoint` | Logpoint SIEM | Security operations |
| `sigma` | Native Sigma format | Rule development |
| `insightidr` | Rapid7 InsightIDR | Cloud SIEM |
| `loki` | Grafana Loki | Log aggregation |
| `datadog` | Datadog Security | Cloud monitoring |

## Security Features

- **Input Validation**: All inputs validated against strict schemas
- **Backend Whitelisting**: Only known backends allowed
- **Path Security**: Absolute paths required, traversal blocked
- **Content Limits**: Rule content max 100KB
- **Name Restrictions**: Alphanumeric + underscore/hyphen only
- **Timeout Protection**: Configurable timeouts prevent hung processes

## Error Handling

All tools return structured errors:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: Invalid backend name: only alphanumeric characters, underscores, and hyphens are allowed"
    }
  ],
  "isError": true
}
```

## Common Use Cases

### 1. Convert Single Rule

```json
{
  "tool": "sigma_batch_convert",
  "params": {
    "rule_path": "/path/to/rule.yml",
    "backend": "splunk"
  }
}
```

### 2. Batch Convert Directory

```json
{
  "tool": "sigma_batch_convert",
  "params": {
    "rule_path": "/path/to/rules/",
    "backend": "elasticsearch",
    "pipeline": "ecs",
    "timeout": 120
  }
}
```

### 3. Test Rule Before Deployment

```json
{
  "tool": "sigma_rule_test",
  "params": {
    "rule_content": "...",
    "backend": "qradar"
  }
}
```

### 4. Analyze Rule Repository

```json
{
  "tool": "sigma_rule_stats",
  "params": {
    "rule_path": "/path/to/sigma-rules/"
  }
}
```

### 5. Export Backend Configuration

```json
{
  "tool": "sigma_export_config",
  "params": {
    "backend": "splunk",
    "pipeline": "windows",
    "include_field_mappings": true
  }
}
```

## Development

### Build

```bash
bun run build
```

### Run

```bash
bun run start
```

### Project Structure

```
sigma-converter/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts                    # Main MCP server
│   ├── schemas.ts                  # Zod schemas
│   ├── security.ts                 # Validation functions
│   ├── cli-executor.ts             # sigma-cli wrapper
│   └── tools/
│       ├── sigma-batch-convert.ts  # Batch rule conversion
│       ├── sigma-pipeline-list.ts  # List pipelines
│       ├── sigma-pipeline-detail.ts # Pipeline details
│       ├── sigma-field-mapping.ts  # Field mappings
│       ├── sigma-rule-test.ts      # Test conversion
│       ├── sigma-rule-stats.ts     # Rule analytics
│       └── sigma-export-config.ts  # Export configuration
└── dist/                           # Compiled output
```

## Troubleshooting

### sigma-cli not found

```bash
which sigma
pip install sigma-cli
```

### Backend not available

```bash
sigma list backends
pip install pysigma-backend-[backend-name]
```

### Conversion errors

- Check rule syntax with `sigma_rule_test`
- Verify backend/pipeline compatibility
- Review field mappings with `sigma_field_mapping`

### Timeout issues

- Increase timeout parameter for large rule sets
- Process rules in smaller batches
- Check sigma-cli performance

## License

MIT

## Resources

- [Sigma HQ](https://github.com/SigmaHQ/sigma)
- [pySigma](https://github.com/SigmaHQ/pySigma)
- [Sigma Specification](https://github.com/SigmaHQ/sigma-specification)
- [MCP Documentation](https://modelcontextprotocol.io)