Content
<div align="center">
# ⚔️ SigmaLineage MCP
### *Context-Aware EVTX Hunting · Lineage-First Triage · Zero Noise Tolerance*
[](https://python.org)
[](https://github.com/jlowin/fastmcp)
[](https://github.com/WithSecureLabs/chainsaw)
[](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:**
---
### 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:**
---
## 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`
