security-detections-mcp 1.1.0 → 1.3.0

package/README.md

@@ -1,19 +1,20 @@
 # Security Detections MCP
 
-An MCP (Model Context Protocol) server that lets LLMs query a unified database of **Sigma**, **Splunk ESCU**, and **Elastic** security detection rules.
+An MCP (Model Context Protocol) server that lets LLMs query a unified database of **Sigma**, **Splunk ESCU**, **Elastic**, and **KQL** security detection rules.
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=security-detections&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlY3VyaXR5LWRldGVjdGlvbnMtbWNwIl0sImVudiI6eyJTSUdNQV9QQVRIUyI6Ii9wYXRoL3RvL3NpZ21hL3J1bGVzLC9wYXRoL3RvL3NpZ21hL3J1bGVzLXRocmVhdC1odW50aW5nIiwiU1BMVU5LX1BBVEhTIjoiL3BhdGgvdG8vc2VjdXJpdHlfY29udGVudC9kZXRlY3Rpb25zIiwiU1RPUllfUEFUSFMiOiIvcGF0aC90by9zZWN1cml0eV9jb250ZW50L3N0b3JpZXMiLCJFTEFTVElDX1BBVEhTIjoiL3BhdGgvdG8vZGV0ZWN0aW9uLXJ1bGVzL3J1bGVzIn19)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=security-detections&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlY3VyaXR5LWRldGVjdGlvbnMtbWNwIl0sImVudiI6eyJTSUdNQV9QQVRIUyI6Ii9wYXRoL3RvL3NpZ21hL3J1bGVzLC9wYXRoL3RvL3NpZ21hL3J1bGVzLXRocmVhdC1odW50aW5nIiwiU1BMVU5LX1BBVEhTIjoiL3BhdGgvdG8vc2VjdXJpdHlfY29udGVudC9kZXRlY3Rpb25zIiwiU1RPUllfUEFUSFMiOiIvcGF0aC90by9zZWN1cml0eV9jb250ZW50L3N0b3JpZXMiLCJFTEFTVElDX1BBVEhTIjoiL3BhdGgvdG8vZGV0ZWN0aW9uLXJ1bGVzL3J1bGVzIiwiS1FMX1BBVEhTIjoiL3BhdGgvdG8va3FsLXJ1bGVzIn19)
 
 ## Features
 
-- **Unified Search** - Query Sigma, Splunk ESCU, and Elastic detections from a single interface
+- **Unified Search** - Query Sigma, Splunk ESCU, Elastic, and KQL detections from a single interface
 - **Full-Text Search** - SQLite FTS5 powered search across names, descriptions, queries, MITRE tactics, CVEs, process names, and more
 - **MITRE ATT&CK Mapping** - Filter detections by technique ID or tactic
 - **CVE Coverage** - Find detections for specific CVE vulnerabilities
 - **Process Name Search** - Find detections that reference specific processes (e.g., powershell.exe, w3wp.exe)
 - **Analytic Stories** - Query by Splunk analytic story (optional - enhances context)
+- **KQL Categories** - Filter KQL queries by category (Defender For Endpoint, Azure AD, Threat Hunting, etc.)
 - **Auto-Indexing** - Automatically indexes detections on startup from configured paths
-- **Multi-Format Support** - YAML (Sigma, Splunk), TOML (Elastic)
+- **Multi-Format Support** - YAML (Sigma, Splunk), TOML (Elastic), Markdown (KQL)
 - **Logsource Filtering** - Filter Sigma rules by category, product, or service
 - **Severity Filtering** - Filter by criticality level
 
@@ -52,7 +53,8 @@ Add to your MCP config (`~/.cursor/mcp.json` or `.cursor/mcp.json` in your proje
         "SIGMA_PATHS": "/path/to/sigma/rules,/path/to/sigma/rules-threat-hunting",
         "SPLUNK_PATHS": "/path/to/security_content/detections",
         "ELASTIC_PATHS": "/path/to/detection-rules/rules",
-        "STORY_PATHS": "/path/to/security_content/stories"
+        "STORY_PATHS": "/path/to/security_content/stories",
+        "KQL_PATHS": "/path/to/Hunting-Queries-Detection-Rules"
       }
     }
   }
@@ -73,7 +75,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
         "SIGMA_PATHS": "/Users/you/sigma/rules,/Users/you/sigma/rules-threat-hunting",
         "SPLUNK_PATHS": "/Users/you/security_content/detections",
         "ELASTIC_PATHS": "/Users/you/detection-rules/rules",
-        "STORY_PATHS": "/Users/you/security_content/stories"
+        "STORY_PATHS": "/Users/you/security_content/stories",
+        "KQL_PATHS": "/Users/you/Hunting-Queries-Detection-Rules"
       }
     }
   }
@@ -84,16 +87,17 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 | Variable | Description | Required |
 |----------|-------------|----------|
-| `SIGMA_PATHS` | Comma-separated paths to Sigma rule directories | Yes (at least one source) |
-| `SPLUNK_PATHS` | Comma-separated paths to Splunk ESCU detection directories | Yes (at least one source) |
-| `ELASTIC_PATHS` | Comma-separated paths to Elastic detection rule directories | Yes (at least one source) |
+| `SIGMA_PATHS` | Comma-separated paths to Sigma rule directories | At least one source required |
+| `SPLUNK_PATHS` | Comma-separated paths to Splunk ESCU detection directories | At least one source required |
+| `ELASTIC_PATHS` | Comma-separated paths to Elastic detection rule directories | At least one source required |
+| `KQL_PATHS` | Comma-separated paths to KQL hunting query directories | At least one source required |
 | `STORY_PATHS` | Comma-separated paths to Splunk analytic story directories | No (enhances context) |
 
 ## Getting Detection Content
 
 ### Quick Start: Download All Rules (Copy & Paste)
 
-Create a `detections` folder and download all three sources with sparse checkout (only downloads the rules, not full repos):
+Create a `detections` folder and download all sources with sparse checkout (only downloads the rules, not full repos):
 
 ```bash
 # Create detections directory
@@ -111,10 +115,15 @@ cd security_content && git sparse-checkout set detections stories && cd ..
 git clone --depth 1 --filter=blob:none --sparse https://github.com/elastic/detection-rules.git
 cd detection-rules && git sparse-checkout set rules && cd ..
 
+# Download KQL hunting queries (~400+ queries from 2 repos)
+git clone --depth 1 https://github.com/Bert-JanP/Hunting-Queries-Detection-Rules.git kql-bertjanp
+git clone --depth 1 https://github.com/jkerai1/KQL-Queries.git kql-jkerai1
+
 echo "Done! Configure your MCP with these paths:"
 echo "  SIGMA_PATHS: $(pwd)/sigma/rules,$(pwd)/sigma/rules-threat-hunting"
 echo "  SPLUNK_PATHS: $(pwd)/security_content/detections"
 echo "  ELASTIC_PATHS: $(pwd)/detection-rules/rules"
+echo "  KQL_PATHS: $(pwd)/kql-bertjanp,$(pwd)/kql-jkerai1"
 echo "  STORY_PATHS: $(pwd)/security_content/stories"
 ```
 
@@ -134,6 +143,11 @@ git clone https://github.com/splunk/security_content.git
 # Elastic Detection Rules
 git clone https://github.com/elastic/detection-rules.git
 # Use rules/ directory
+
+# KQL Hunting Queries (multiple sources supported)
+git clone https://github.com/Bert-JanP/Hunting-Queries-Detection-Rules.git
+git clone https://github.com/jkerai1/KQL-Queries.git
+# Use entire repos, combine paths with comma
 ```
 
 ## MCP Tools
@@ -145,8 +159,8 @@ git clone https://github.com/elastic/detection-rules.git
 | `search(query, limit)` | Full-text search across all detection fields (names, descriptions, queries, CVEs, process names, etc.) |
 | `get_by_id(id)` | Get a single detection by its ID |
 | `list_all(limit, offset)` | Paginated list of all detections |
-| `list_by_source(source_type)` | Filter by `sigma`, `splunk_escu`, or `elastic` |
-| `get_raw_yaml(id)` | Get the original YAML/TOML content |
+| `list_by_source(source_type)` | Filter by `sigma`, `splunk_escu`, `elastic`, or `kql` |
+| `get_raw_yaml(id)` | Get the original YAML/TOML/Markdown content |
 | `get_stats()` | Get index statistics |
 | `rebuild_index()` | Force re-index from configured paths |
 
@@ -174,6 +188,14 @@ git clone https://github.com/elastic/detection-rules.git
 | `list_by_detection_type(type)` | Filter by type (TTP, Anomaly, Hunting, Correlation) |
 | `list_by_analytic_story(story)` | Filter by Splunk analytic story |
 
+### KQL-Specific Filters
+
+| Tool | Description |
+|------|-------------|
+| `list_by_kql_category(category)` | Filter KQL by category (e.g., "Defender For Endpoint", "Azure Active Directory", "Threat Hunting") |
+| `list_by_kql_tag(tag)` | Filter KQL by tag (e.g., "ransomware", "hunting", "ti-feed", "dfir") |
+| `list_by_kql_datasource(data_source)` | Filter KQL by Microsoft data source (e.g., "DeviceProcessEvents", "SigninLogs") |
+
 ### Story Tools (Optional)
 
 | Tool | Description |
@@ -183,6 +205,45 @@ git clone https://github.com/elastic/detection-rules.git
 | `list_stories(limit, offset)` | List all analytic stories |
 | `list_stories_by_category(category)` | Filter stories by category (Malware, Adversary Tactics, etc.) |
 
+### Efficient Analysis Tools (Token-Optimized)
+
+These tools do heavy processing server-side and return minimal, actionable data:
+
+| Tool | Description | Output Size |
+|------|-------------|-------------|
+| `analyze_coverage(source_type?)` | Get coverage stats by tactic, top techniques, weak spots | ~2KB |
+| `identify_gaps(threat_profile, source_type?)` | Find gaps for ransomware, apt, persistence, etc. | ~500B |
+| `suggest_detections(technique_id, source_type?)` | Get detection ideas for a technique | ~2KB |
+| `get_technique_ids(source_type?, tactic?, severity?)` | Get only technique IDs (no full objects) | ~200B |
+| `generate_navigator_layer(name, source_type?, tactic?)` | Generate ATT&CK Navigator layer JSON | ~3KB |
+
+**Why use these?** Traditional tools return full detection objects (~50KB+ per query). These return only what you need, saving 25x+ tokens.
+
+## Claude Code Skills
+
+This repo includes [Claude Code Skills](https://code.claude.com/docs/en/skills) in `.claude/skills/` that teach Claude efficient workflows:
+
+| Skill | Purpose |
+|-------|---------|
+| `coverage-analysis` | Efficient coverage analysis using the token-optimized tools |
+
+**Why skills?** Instead of figuring out methodology each time (wasting tokens), skills teach Claude once.
+
+You can also install personal skills to `~/.claude/skills/` for cross-project use.
+
+### Example: Efficient Coverage Analysis
+
+```
+You: "What's my Elastic coverage against ransomware?"
+
+AI uses skills + efficient tools:
+1. analyze_coverage(source_type="elastic")     → Stats by tactic
+2. identify_gaps(threat_profile="ransomware")  → Prioritized gaps
+3. suggest_detections(technique_id="T1486")    → Fix top gap
+
+Total: ~5KB of data vs ~500KB with traditional tools
+```
+
 ## Example Workflows
 
 ### Find PowerShell Detections
@@ -204,7 +265,7 @@ Tool: list_by_cve(cve_id="CVE-2024-27198")
 ```
 LLM: "What detections do we have for credential dumping?"
 Tool: search(query="credential dumping", limit=10)
-→ Returns results from Sigma, Splunk, AND Elastic
+→ Returns results from Sigma, Splunk, Elastic, AND KQL
 ```
 
 ### Find Web Server Attack Detections
@@ -222,24 +283,39 @@ Tool: search_stories(query="ransomware")
 Tool: list_by_analytic_story(story="Ransomware")
 ```
 
+### Find KQL Hunting Queries for Defender
+
+```
+LLM: "What KQL queries do we have for Defender For Endpoint?"
+Tool: list_by_kql_category(category="Defender For Endpoint")
+```
+
+### Search for BloodHound Detections
+
+```
+LLM: "Find detections for BloodHound usage"
+Tool: search(query="bloodhound", limit=10)
+→ Returns KQL hunting queries and other source detections
+```
+
 ## Unified Schema
 
-All detection sources (Sigma, Splunk, Elastic) are normalized to a common schema:
+All detection sources (Sigma, Splunk, Elastic, KQL) are normalized to a common schema:
 
 ### Core Fields
 
 | Field | Description |
 |-------|-------------|
-| `id` | Unique identifier (UUID for Sigma, ID field for Splunk, rule_id for Elastic) |
+| `id` | Unique identifier |
 | `name` | Detection name/title |
 | `description` | What the detection looks for |
-| `query` | Detection logic (Sigma YAML, Splunk SPL, or Elastic EQL/KQL) |
-| `source_type` | `sigma`, `splunk_escu`, or `elastic` |
+| `query` | Detection logic (Sigma YAML, Splunk SPL, Elastic EQL, or KQL) |
+| `source_type` | `sigma`, `splunk_escu`, `elastic`, or `kql` |
 | `severity` | Detection severity level |
 | `status` | Rule status (stable, test, experimental, production, etc.) |
 | `author` | Rule author |
 | `file_path` | Original file path |
-| `raw_yaml` | Original YAML/TOML content |
+| `raw_yaml` | Original YAML/TOML/Markdown content |
 
 ### Enhanced Fields (for Semantic Search)
 
@@ -252,11 +328,20 @@ All detection sources (Sigma, Splunk, Elastic) are normalized to a common schema
 | `process_names` | Process names referenced in detection |
 | `file_paths` | Interesting file paths referenced |
 | `registry_paths` | Registry paths referenced |
-| `data_sources` | Required data sources |
+| `data_sources` | Required data sources (Sysmon, DeviceProcessEvents, etc.) |
 | `detection_type` | TTP, Anomaly, Hunting, or Correlation |
 | `asset_type` | Endpoint, Web Server, Cloud, Network |
 | `security_domain` | endpoint, network, cloud, access |
 
+### KQL-Specific Fields
+
+| Field | Description |
+|-------|-------------|
+| `kql_category` | Category derived from folder path (e.g., "Defender For Endpoint") |
+| `kql_tags` | Extracted tags (e.g., "ransomware", "hunting", "ti-feed") |
+| `kql_keywords` | Security keywords extracted for search |
+| `platforms` | Platforms (windows, azure-ad, office-365, etc.) |
+
 ## Database
 
 The index is stored at `~/.cache/security-detections-mcp/detections.sqlite`.
@@ -294,6 +379,21 @@ From [Elastic Detection Rules](https://github.com/elastic/detection-rules):
 - Optional: `rule.description`, `rule.query`, `rule.severity`, `rule.tags`, `rule.threat` (MITRE mappings)
 - Supports EQL, KQL, Lucene, and ESQL query languages
 
+### KQL Hunting Queries (Markdown & Raw .kql)
+
+Supports multiple KQL repositories:
+
+**[Bert-JanP/Hunting-Queries-Detection-Rules](https://github.com/Bert-JanP/Hunting-Queries-Detection-Rules)** (~290 queries)
+- Microsoft Defender XDR and Azure Sentinel hunting queries in Markdown format
+- Extracts title from markdown heading, KQL from fenced code blocks
+- Extracts MITRE technique IDs from tables
+- Categories: Defender For Endpoint, Azure AD, Threat Hunting, DFIR, etc.
+
+**[jkerai1/KQL-Queries](https://github.com/jkerai1/KQL-Queries)** (~130 queries)
+- Raw `.kql` files for Defender, Entra, Azure, Office 365
+- Title derived from filename
+- Lightweight queries for kqlsearch.com
+
 ## Development
 
 ```bash
@@ -307,6 +407,7 @@ npm run build
 SIGMA_PATHS="./detections/sigma/rules" \
 SPLUNK_PATHS="./detections/splunk/detections" \
 ELASTIC_PATHS="./detections/elastic/rules" \
+KQL_PATHS="./detections/kql" \
 STORY_PATHS="./detections/splunk/stories" \
 npm start
 ```
@@ -320,8 +421,71 @@ When fully indexed with all sources:
 | Sigma Rules | ~3,000+ |
 | Splunk ESCU | ~2,000+ |
 | Elastic Rules | ~1,500+ |
+| KQL Queries | ~420+ |
 | Analytic Stories | ~330 |
-| **Total** | **~6,500+** |
+| **Total** | **~7,200+** |
+
+## 🔗 Using with MITRE ATT&CK MCP
+
+**This MCP pairs perfectly with [mitre-attack-mcp](https://github.com/MHaggis/mitre-attack-mcp)** for complete threat coverage analysis:
+
+| MCP | Purpose |
+|-----|---------|
+| **security-detections-mcp** | Query 7,200+ detection rules (Sigma, Splunk ESCU, Elastic, KQL) |
+| **mitre-attack-mcp** | Analyze coverage against ATT&CK framework, generate Navigator layers |
+
+### Combined Workflow (Efficient)
+
+```
+You: "What's my coverage against APT29?"
+
+LLM workflow (3 calls, ~10KB total):
+1. mitre-attack-mcp → get_group_techniques("G0016")     # APT29's TTPs
+2. detections-mcp → analyze_coverage(source_type="elastic")  # Your coverage
+3. mitre-attack-mcp → find_group_gaps("G0016", your_coverage) # The gaps
+
+Result: Prioritized gap list, not 500KB of raw data
+```
+
+### Generate Navigator Layer (1 call)
+
+```
+You: "Generate a Navigator layer for my initial access coverage"
+
+LLM: generate_navigator_layer(
+  name="Initial Access Coverage",
+  source_type="elastic",
+  tactic="initial-access"
+)
+
+→ Returns ready-to-import Navigator JSON
+```
+
+### Install Both Together
+
+```json
+{
+  "mcpServers": {
+    "security-detections": {
+      "command": "npx",
+      "args": ["-y", "security-detections-mcp"],
+      "env": {
+        "SIGMA_PATHS": "/path/to/sigma/rules",
+        "SPLUNK_PATHS": "/path/to/security_content/detections",
+        "ELASTIC_PATHS": "/path/to/detection-rules/rules",
+        "KQL_PATHS": "/path/to/kql-hunting-queries"
+      }
+    },
+    "mitre-attack": {
+      "command": "npx",
+      "args": ["-y", "mitre-attack-mcp"],
+      "env": {
+        "ATTACK_DOMAIN": "enterprise-attack"
+      }
+    }
+  }
+}
+```
 
 ## License
 

package/dist/db.d.ts

@@ -8,7 +8,7 @@ export declare function insertDetection(detection: Detection): void;
 export declare function searchDetections(query: string, limit?: number): Detection[];
 export declare function getDetectionById(id: string): Detection | null;
 export declare function listDetections(limit?: number, offset?: number): Detection[];
-export declare function listBySource(sourceType: 'sigma' | 'splunk_escu' | 'elastic', limit?: number, offset?: number): Detection[];
+export declare function listBySource(sourceType: 'sigma' | 'splunk_escu' | 'elastic' | 'kql', limit?: number, offset?: number): Detection[];
 export declare function listByMitre(techniqueId: string, limit?: number, offset?: number): Detection[];
 export declare function listByLogsource(category?: string, product?: string, service?: string, limit?: number, offset?: number): Detection[];
 export declare function listBySeverity(level: string, limit?: number, offset?: number): Detection[];
@@ -17,6 +17,9 @@ export declare function listByAnalyticStory(story: string, limit?: number, offse
 export declare function listByProcessName(processName: string, limit?: number, offset?: number): Detection[];
 export declare function listByDetectionType(detectionType: string, limit?: number, offset?: number): Detection[];
 export declare function listByDataSource(dataSource: string, limit?: number, offset?: number): Detection[];
+export declare function listByKqlCategory(category: string, limit?: number, offset?: number): Detection[];
+export declare function listByKqlTag(tag: string, limit?: number, offset?: number): Detection[];
+export declare function listByKqlDatasource(dataSource: string, limit?: number, offset?: number): Detection[];
 export declare function listByMitreTactic(tactic: string, limit?: number, offset?: number): Detection[];
 export declare function getStats(): IndexStats;
 export declare function getRawYaml(id: string): string | null;
@@ -29,3 +32,60 @@ export declare function searchStories(query: string, limit?: number): AnalyticSt
 export declare function listStories(limit?: number, offset?: number): AnalyticStory[];
 export declare function listStoriesByCategory(category: string, limit?: number, offset?: number): AnalyticStory[];
 export declare function getStoryCount(): number;
+export interface TechniqueIdFilters {
+    source_type?: 'sigma' | 'splunk_escu' | 'elastic';
+    tactic?: string;
+    severity?: string;
+}
+export declare function getTechniqueIds(filters?: TechniqueIdFilters): string[];
+export interface CoverageReport {
+    summary: {
+        total_techniques: number;
+        total_detections: number;
+        coverage_by_tactic: Record<string, {
+            covered: number;
+            total: number;
+            percent: number;
+        }>;
+    };
+    top_covered: Array<{
+        technique: string;
+        detection_count: number;
+    }>;
+    weak_coverage: Array<{
+        technique: string;
+        detection_count: number;
+    }>;
+}
+export declare function analyzeCoverage(sourceType?: 'sigma' | 'splunk_escu' | 'elastic'): CoverageReport;
+export interface GapAnalysis {
+    threat_profile: string;
+    total_gaps: number;
+    critical_gaps: Array<{
+        technique: string;
+        priority: string;
+        reason: string;
+    }>;
+    covered: string[];
+    recommendations: string[];
+}
+export declare function identifyGaps(threatProfile: string, sourceType?: 'sigma' | 'splunk_escu' | 'elastic'): GapAnalysis;
+export interface DetectionSuggestion {
+    technique_id: string;
+    existing_detections: Array<{
+        id: string;
+        name: string;
+        source: string;
+    }>;
+    data_sources_needed: string[];
+    detection_ideas: string[];
+}
+export declare function suggestDetections(techniqueId: string, sourceType?: 'sigma' | 'splunk_escu' | 'elastic'): DetectionSuggestion;
+export interface NavigatorLayerOptions {
+    name: string;
+    description?: string;
+    source_type?: 'sigma' | 'splunk_escu' | 'elastic';
+    tactic?: string;
+    severity?: string;
+}
+export declare function generateNavigatorLayer(options: NavigatorLayerOptions): object;