<div align="center">

# ⚔️ SigmaLineage MCP

### *Context-Aware EVTX Hunting · Lineage-First Triage · Zero Noise Tolerance*

[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![FastMCP](https://img.shields.io/badge/FastMCP-Server-FF6B6B?style=for-the-badge)](https://github.com/jlowin/fastmcp)
[![Chainsaw](https://img.shields.io/badge/Chainsaw-Powered-F7931E?style=for-the-badge)](https://github.com/WithSecureLabs/chainsaw)
[![Sigma](https://img.shields.io/badge/Sigma-Rules-00B4D8?style=for-the-badge)](https://sigmahq.io)

---

> **"A Sigma hit means nothing without its story. The process lineage chain *is* the story."**

</div>

---

## 🎯 Why SigmaLineage?

EVTX triage in modern SOCs is a **race against noise**. You have millions of events, hundreds of alerts, and seconds to decide what's real.

<table>
<tr>
<td width="50%" valign="top">

### 🔍 For the SOC Analyst

Generic alerts drown true incidents in **false positives**. You don't need more alerts — you need *signal from noise*.

SigmaLineage's **rarity baseline engine** automatically surfaces:
- 🚨 Anomalous process-to-port connections
- 👤 Suspicious user-log event signatures
- 🌐 Weird URL lookups no one else made

**Find the real threat. Fast.**

</td>
<td width="50%" valign="top">

### 🧬 For the Detection Engineer

A Sigma rule fires. But is it a sysadmin doing their job, or an attacker moving laterally?

**The process lineage chain is our core moat.**

SigmaLineage traces the full parent→child execution tree — up to 5+ generations — turning isolated alerts into a visual kill chain. You instantly see:
- Was this cmd.exe spawned by `services.exe` or `w3wp.exe`?
- Is `rundll32` being launched from `ProgramData`?
- Did `WmiPrvSE.exe` just spawn a reverse shell?

**Stop chasing ghosts. Confirm the kill chain.**

</td>
</tr>
</table>

---

> 🧠 **By combining rapid Sigma matching, automated lineage graphing, and multi-dimensional rarity baselining, SigmaLineage MCP transforms raw EVTX logs into actionable, context-rich intelligence — for AI agents and human analysts alike.**

---

## 🔧 Built On

| Component | Role |
|---|---|
| `src/sigmalineage_mcp/mappings/sigma-event-logs-all.yml` | Chainsaw field-mapping definition |
| `sigma_lineage.py` | Process lineage runner script |
| `src/sigmalineage_mcp/` | FastMCP server orchestration |

---

## Tool Overview

### 1) `run_sigma`
Runs the Chainsaw Sigma hunt command and returns a summary of rule hits.

**Inputs:**
- `evtx_path` (file or folder of logs to scan)
- `sigma_rules_path` (directory containing Sigma rules)
- `mapping_path` (Chainsaw mapping yaml, defaults to `src/sigmalineage_mcp/mappings/sigma-event-logs-all.yml`)
- `output_dir` (directory where `hunt.json` is written)

**Output Highlights:**
- `hunt_json_path`
- `hit_count`
- `top_rules`
- `top_source_files`

---

### 2) `run_sigma_lineage`
Runs the Sigma hunt (or loads existing results) and traces the parent/child process lineage for hit processes.

**Inputs:**
- All `run_sigma` inputs
- `levels` (number of ancestor levels to trace, default `5`)
- `skip_hunt` (skip running Chainsaw hunt, loading existing `hunt.json` instead, default `false`)

**Output Highlights:**
- `hunt_json_path`
- `process_lineage_json_path`
- `process_lineage_md_path`
- `sigma_hit_count`
- `indexed_evtx_files`
- `indexed_events`

**Example Lineage Highlights Output:**
![Lineage Highlights](docs/images/lineage_highlights.png)

---

### 3) `rare_events_baseline`
Computes rare tuple combinations from parsed CSV event logs with baseline comparison to highlight anomalies.

**Inputs:**
- `target_csv_path` (CSV file or folder to analyze)
- `baseline_csv_path` (optional, defaults to target scope itself)
- `max_results` (default `25`)
- `max_baseline_count` (filter threshold for baseline occurrence, default `2`)

**Tuple Families Analyzed:**
- `process_dst_port_protocol`: Maps unique combinations of process name, destination port, and protocol.
- `user_channel_event_id`: Maps unique combinations of user, log channel, and event ID.
- `url_host_process`: Maps unique combinations of accessed URL/domain, host computer, and initiating process name.

**Example Rarity Baseline Analysis Output:**
![Rarity Analysis](docs/images/rarity_analysis.png)

---

## Folder Structure

```text
sigmalineage-mcp/
  sigma_lineage.py            # Lineage tracer CLI script
  pyproject.toml              # Project configuration & dependencies
  README.md                   # This file
  src/
    sigmalineage_mcp/
      __init__.py
      __main__.py             # Standard script entrypoint
      config.py               # Paths configuration
      server.py               # FastMCP server orchestration
      mappings/
        sigma-event-logs-all.yml  # Chainsaw mapping file
      services/
        chainsaw_runner.py    # Subprocess runner for Chainsaw
        lineage_runner.py     # Subprocess runner for lineage tracer
        rarity.py             # Pure Python CSV rarity baseline engine
```

---

## Installation

### Prerequisites
1. **Chainsaw CLI**: Ensure `chainsaw` is installed and available in your `PATH` (e.g. at `~/.local/bin/chainsaw`).
2. **Python**: Python 3.10+ is required.

### Setup
From the repository root:
```bash
uv sync
```

---

## Running the Server

### Direct Execution
Start the FastMCP stdio server:
```bash
uv run sigmalineage-mcp
```

### MCP Client Configurations

To wire this MCP server into different AI clients, use the standard JSON configuration snippet below, placing it in the tool-specific configuration file location.

#### Standard JSON Snippet
```json
{
  "mcpServers": {
    "sigmalineage-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/sigmalineage_mcp",
        "sigmalineage-mcp"
      ],
      "env": {
        "SIGMALINEAGE_PROJECT_ROOT": "/absolute/path/to/sigmalineage_mcp"
      }
    }
  }
}
```

*Note: Replace `/absolute/path/to/sigmalineage_mcp` with the actual path where this repository is cloned on your system.*

#### Client Configuration File Paths

* **Cursor**: Add to the Cursor GUI settings panel (`Settings -> Features -> MCP`) or edit `~/.cursor/mcp.json` (Linux/macOS) or `%USERPROFILE%\.cursor\config\mcp.json` (Windows).
* **Antigravity**: Add to the `mcp_config.json` configuration file located at `~/.gemini/antigravity/mcp_config.json`.
* **OpenCode**: Add to `~/.config/opencode/opencode.json` (Linux/macOS) or a project-level `opencode.json` file in the root of the repository.
* **Claude Desktop**: Add to the global configuration file:
  * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  * Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  * Linux: `~/.config/Claude/claude_desktop_config.json`