hacktricks-mcp-server 1.3.1

package/.github/workflows/publish-mcp.yml

@@ -0,0 +1,49 @@
+name: Publish to MCP Registry
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for OIDC token generation
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Download mcp-publisher CLI
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz
+          chmod +x mcp-publisher
+
+      - name: Publish to MCP Registry
+        env:
+          ACTIONS_ID_TOKEN_REQUEST_TOKEN: ${{ env.ACTIONS_ID_TOKEN_REQUEST_TOKEN }}
+          ACTIONS_ID_TOKEN_REQUEST_URL: ${{ env.ACTIONS_ID_TOKEN_REQUEST_URL }}
+        run: |
+          ./mcp-publisher publish \
+            --registry-url "https://registry.modelcontextprotocol.io" \
+            --mcp-file "./server.json" \
+            --auth-method github-oidc

package/.github/workflows/test-event.json

@@ -0,0 +1,9 @@
+{
+  "ref": "refs/tags/v1.3.1",
+  "repository": {
+    "name": "hacktricks-mcp-server",
+    "owner": {
+      "name": "Xplo8E"
+    }
+  }
+}

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "hacktricks"]
+	path = hacktricks
+	url = https://github.com/carlospolop/hacktricks.git

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "hacktricks": {
+      "command": "node",
+      "args": [
+        "dist/index.js"
+      ],
+      "env": {}
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## [1.3.0] - 2025-12-26
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_hacktricks` | Search with results grouped by file, showing title, match count, and relevant sections |
+| `get_hacktricks_page` | Get full page content |
+| `get_hacktricks_outline` | Get table of contents (section headers) |
+| `get_hacktricks_section` | Extract specific section by name |
+| `get_hacktricks_cheatsheet` | Extract only code blocks/payloads |
+| `list_hacktricks_categories` | Browse categories and file structure |
+| `hacktricks_quick_lookup` | ⚡ One-shot exploitation lookup with alias support |
+
+### Features
+
+- **Grouped search results** - Results aggregated by file with title, match count, sections, and top matches
+- **Section extraction** - Read specific sections (~200 tokens) instead of full pages (~3000 tokens)
+- **Quick lookup** - One-shot "how do I exploit X" answers with alias expansion (sqli, xss, rce, etc.)
+- **Smart tool descriptions** - Guide Claude toward efficient usage patterns
+- **Category filtering** - Narrow searches to specific categories
+- **Code block extraction** - Get just the commands/payloads
+
+### Security
+
+- Command injection protection via `execFile()`
+- Path traversal prevention
+- Input validation on all parameters

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Xplo8E
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# HackTricks MCP Server
+
+MCP (Model Context Protocol) server for searching and querying [HackTricks](https://github.com/carlospolop/hacktricks) pentesting documentation directly from Claude.
+
+## Features
+
+- **Quick lookup** - One-shot exploitation info with alias support (sqli, xss, ssrf, etc.)
+- **Grouped search results** - Results aggregated by file with match count, title, and relevant sections
+- **Page outline** - Quick table of contents to identify relevant sections
+- **Section extraction** - Read specific sections instead of full pages (token-efficient)
+- **Cheatsheet mode** - Extract only code blocks/commands from pages
+- **Category browsing** - Discover available topics and file paths
+- **Fast grep search** - Uses ripgrep for instant results
+- **Security hardened** - Protection against command injection and path traversal
+
+## Setup
+
+### 1. Clone and Initialize
+
+```bash
+git clone https://github.com/Xplo8E/hacktricks-mcp-server.git
+cd hacktricks-mcp-server
+git submodule update --init --recursive
+```
+
+### 2. Install Dependencies
+
+```bash
+bun install
+```
+
+### 3. Build
+
+```bash
+bun run build
+```
+
+### 4. Configure Claude
+
+Add to your Claude settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "hacktricks": {
+      "command": "node",
+      "args": ["/path/to/hacktricks-mcp/dist/index.js"],
+      "disabled": false
+    }
+  }
+}
+```
+
+### 5. Restart Claude
+
+After adding the MCP server configuration, restart Claude for the changes to take effect.
+
+## Available Tools
+
+### `hacktricks_quick_lookup`
+
+⚡ **One-shot exploitation lookup**. Searches, finds best page, and returns exploitation sections + code blocks in one call.
+
+**Parameters:**
+- `topic` (string, required): Attack/technique to look up (e.g., 'SUID', 'sqli', 'xss', 'docker escape')
+- `category` (string, optional): Category filter for faster results
+
+**Supported aliases:** `sqli`, `xss`, `rce`, `lfi`, `rfi`, `ssrf`, `csrf`, `xxe`, `ssti`, `idor`, `jwt`, `suid`, `privesc`
+
+**Example:**
+```
+hacktricks_quick_lookup("SSRF", category="pentesting-web")
+```
+
+**Benefits:** Reduces 3+ tool calls to 1 for "how do I exploit X" questions.
+
+---
+
+### `search_hacktricks`
+
+Search through HackTricks documentation. **Returns results GROUPED BY FILE** with match count, page title, and relevant section headers.
+
+**Parameters:**
+- `query` (string, required): Search term or regex pattern
+- `category` (string, optional): Filter to specific category (e.g., 'pentesting-web')
+- `limit` (number, optional): Max grouped results (default: 20)
+
+**Example output:**
+```
+Found matches in 5 files for: "SUID"
+
+────────────────────────────────────────────────────────────
+
+📄 **Linux Privilege Escalation**
+   Path: src/linux-hardening/privilege-escalation/README.md
+   Matches: 12
+   Sections: SUID Binaries | Finding SUID | GTFOBins
+   Preview:
+     L45: Find files with SUID bit set...
+     L78: Common SUID exploitation techniques...
+
+────────────────────────────────────────────────────────────
+```
+
+---
+
+### `get_hacktricks_outline`
+
+Get the **table of contents** of a page (all section headers). Use this BEFORE reading full pages to understand structure.
+
+**Parameters:**
+- `path` (string): Relative path to markdown file
+
+**Example output:**
+```
+# Linux Privilege Escalation
+  ## Enumeration
+    ### System Information
+    ### Network
+  ## SUID Binaries
+    ### Finding SUID Files
+    ### Exploiting SUID
+  ## Capabilities
+```
+
+**Benefits:** See page structure in ~20 lines vs reading 500+ lines.
+
+---
+
+### `get_hacktricks_section`
+
+Extract a **specific section** from a page by header name. Much more efficient than reading the full page.
+
+**Parameters:**
+- `path` (string): Relative path to markdown file
+- `section` (string): Section header to extract (partial match, case-insensitive)
+
+**Example:**
+```
+get_hacktricks_section("src/linux-hardening/privilege-escalation/README.md", "SUID")
+```
+
+**Benefits:** Read just "SUID Binaries" section (~200 tokens) instead of entire page (~3000 tokens).
+
+---
+
+### `get_hacktricks_cheatsheet`
+
+Extract **only code blocks** from a page. Perfect when you just need commands, payloads, or examples.
+
+**Parameters:**
+- `path` (string): Relative path to markdown file
+
+**Example output:**
+```bash
+find / -perm -4000 2>/dev/null
+```
+
+```bash
+./vulnerable_suid -p
+```
+
+**Benefits:** Skip explanatory text when you just need "give me the command".
+
+---
+
+### `get_hacktricks_page`
+
+Get **full content** of a HackTricks page.
+
+**Parameters:**
+- `path` (string): Relative path to markdown file
+
+**Warning:** Pages can be very long (3000+ tokens). Consider using `get_hacktricks_outline` + `get_hacktricks_section` instead.
+
+---
+
+### `list_hacktricks_categories`
+
+List categories and their contents.
+
+**Parameters:**
+- `category` (string, optional): Category to expand
+
+**Without category:** Lists top-level categories
+**With category:** Shows full directory tree with file paths
+
+## Efficient Usage Pattern
+
+For optimal token usage, Claude should:
+
+1. **Search with category filter** → Get grouped results with context
+2. **Get outline of relevant page** → See structure before reading
+3. **Extract specific section** → Read only what's needed
+4. **Get cheatsheet** → Quick command reference
+
+**Before (inefficient):**
+```
+search_hacktricks("SUID")     → 50 raw lines
+get_page(file1)               → 3000 tokens
+get_page(file2)               → 2500 tokens  
+Total: ~5500 tokens, 3 calls
+```
+
+**After (efficient):**
+```
+search_hacktricks("SUID", category="linux-hardening")  → Grouped results
+get_outline(best_match)                                 → 20 lines
+get_section(best_match, "SUID")                         → 200 tokens
+Total: ~400 tokens, 3 calls
+```
+
+## Requirements
+
+- Node.js (v18 or higher)
+- ripgrep (`rg`) - usually pre-installed on macOS/Linux
+- Bun (for package management)
+
+## Development
+
+**Watch mode:**
+```bash
+bun run dev
+```
+
+**Test locally:**
+```bash
+bun run start
+```
+
+## License
+
+MIT
+
+## Credits
+
+- [HackTricks](https://github.com/carlospolop/hacktricks) by Carlos Polop
+- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)

package/TESTING.md

@@ -0,0 +1,188 @@
+# Testing the HackTricks MCP Server
+
+This document describes how to test the MCP server functionality.
+
+## Manual Testing
+
+### Prerequisites
+```bash
+cd ~/projects/hacktricks-mcp
+bun install
+bun run build
+```
+
+### Test 1: Verify Build Output
+```bash
+ls -la dist/
+# Should show index.js
+```
+
+### Test 2: Test Search Functionality (CLI)
+```bash
+# Test basic search
+rg -n -i --type md "SUID" hacktricks/ | head -10
+
+# Test regex search
+rg -n -i --type md "docker.*escape" hacktricks/ | head -5
+
+# Test no results
+rg -n -i --type md "xyznotfound12345" hacktricks/
+```
+
+### Test 3: Test File Reading
+```bash
+# Test reading a valid file
+cat hacktricks/src/linux-hardening/privilege-escalation/README.md | head -20
+
+# Test path traversal protection (should fail)
+cat hacktricks/../../../etc/passwd 2>&1
+```
+
+### Test 4: List Categories
+```bash
+ls hacktricks/src/ | grep -v "\.md$" | grep -v "^images$" | sort
+```
+
+## Integration Testing with Claude Code
+
+### 1. Add to Claude Code Settings
+
+Edit `~/.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "hacktricks": {
+      "command": "node",
+      "args": ["/Users/vinay/projects/hacktricks-mcp/dist/index.js"],
+      "disabled": false
+    }
+  }
+}
+```
+
+### 2. Restart Claude Code
+
+### 3. Test Commands
+
+Try these queries with Claude Code:
+
+**Search Test:**
+```
+"Search HackTricks for SUID privilege escalation"
+```
+
+**Category List Test:**
+```
+"What categories are available in HackTricks?"
+```
+
+**Page Retrieval Test:**
+```
+"Show me the Linux privilege escalation page from HackTricks"
+```
+
+**Edge Cases:**
+```
+"Search HackTricks for: XXE|SSRF|CSRF"  # Regex test
+"Search HackTricks for: docker.*escape"  # Regex test
+```
+
+## Expected Results
+
+### Search Results Format
+```
+Found X matches for: "query"
+
+📄 path/to/file.md:123
+Content of matching line
+
+📄 path/to/another.md:456
+Another matching line
+```
+
+### Category List Format
+```
+Available HackTricks Categories (X):
+
+- AI
+- binary-exploitation
+- crypto
+- linux-hardening
+...
+```
+
+### Page Content Format
+```
+[Full markdown content of the page]
+```
+
+## Debugging
+
+Check MCP server logs in Claude Code console:
+```
+[HackTricks MCP] Searching for: "query"
+[HackTricks MCP] Found X results (showing Y)
+[HackTricks MCP] Reading file: path/to/file.md
+[HackTricks MCP] File size: XXXX bytes
+```
+
+## Error Testing
+
+### Test Empty Query
+```
+search_hacktricks("")
+# Expected: "Search query cannot be empty"
+```
+
+### Test Invalid Path
+```
+get_hacktricks_page("../../../etc/passwd")
+# Expected: "Invalid file path: directory traversal not allowed"
+```
+
+### Test Non-existent File
+```
+get_hacktricks_page("src/nonexistent.md")
+# Expected: "File not found: src/nonexistent.md"
+```
+
+### Test Invalid Regex
+```
+search_hacktricks("[[invalid")
+# Expected: "Invalid search pattern: ..."
+```
+
+## Performance Testing
+
+### Large Query Results
+```bash
+# Search for common term
+rg -n -i --type md "privilege" hacktricks/ | wc -l
+# Should handle large result sets (limited to 50)
+```
+
+### File Size Limits
+```bash
+# Find largest markdown file
+find hacktricks/src -name "*.md" -type f -exec du -h {} + | sort -rh | head -5
+# Ensure server can handle large files
+```
+
+## Security Testing
+
+### Command Injection Prevention
+Test that special characters in queries don't execute commands:
+```
+search_hacktricks("test; ls -la")
+search_hacktricks("test && whoami")
+search_hacktricks("test $(whoami)")
+```
+All should search for the literal strings, not execute commands.
+
+### Path Traversal Prevention
+```
+get_hacktricks_page("../../../etc/passwd")
+get_hacktricks_page("/etc/passwd")
+get_hacktricks_page("src/../../..")
+```
+All should be rejected with appropriate error messages.