diff --git a/hacktricks b/hacktricks index 3748718..6fde4d2 160000 --- a/hacktricks +++ b/hacktricks @@ -1 +1 @@ -Subproject commit 3748718df63c4e7cd6f34bfd26c70a5ce6a0488e +Subproject commit 6fde4d240bc4ec757b55592175cf5e5380fa7386 diff --git a/skills/hacktricks-mcp/SKILL.md b/skills/hacktricks-mcp/SKILL.md new file mode 100644 index 0000000..62ceed5 --- /dev/null +++ b/skills/hacktricks-mcp/SKILL.md @@ -0,0 +1,216 @@ +--- +name: hacktricks-mcp +description: > + Query the HackTricks pentesting knowledge base via MCP server. + Use when the user asks for exploitation techniques, privilege escalation, + payloads, cheatsheets, web/cloud/AD pentesting, or "how do I exploit X?" + Do NOT use for general programming, writing original exploits from scratch, + or legal/policy questions. +compatibility: Node.js 18+, ripgrep (rg), hacktricks-mcp-server npm package. +--- + +# HackTricks MCP + +Query the [HackTricks](https://book.hacktricks.xyz/) pentesting knowledge base directly from your agent via the Model Context Protocol (MCP). + +## When to Use This Skill + +Activate this skill whenever the user asks for: + +- **Exploitation techniques** — SQL injection, XSS, SSRF, XXE, SSTI, IDOR, RCE, LFI/RFI, etc. +- **Privilege escalation** — Linux/Windows SUID, capabilities, kernel exploits, misconfigurations +- **Payloads & cheatsheets** — Reverse shells, one-liners, encoding tricks, bypass techniques +- **Web pentesting** — Authentication bypass, JWT attacks, file upload, deserialization +- **Cloud & container security** — AWS/GCP/Azure misconfigurations, Docker escapes, Kubernetes +- **Active Directory / network** — BloodHound, Kerberoasting, relay attacks, lateral movement +- **Specific tool usage** — How to use a tool mentioned in HackTricks (e.g., `linpeas`, `pspy`, `gobuster`) +- **"How do I exploit X?"** — Any vulnerability class or technique name + +**Do NOT use** for: +- General programming questions unrelated to security +- Writing original exploit code from scratch (use this for *reference*, not generation) +- Legal/policy questions (the skill provides technical knowledge only) + +## What is the HackTricks MCP Server? + +The HackTricks MCP Server is a Model Context Protocol server that provides 7 specialized tools for searching and querying the HackTricks pentesting documentation. It uses ripgrep for instant local search across the entire HackTricks knowledge base (~2GB of content). + +**Key capabilities:** +- One-shot exploitation lookup with alias support (`sqli`, `xss`, `ssrf`, etc.) +- Full-text search with results grouped by file +- Token-efficient section extraction — read only what you need +- Cheatsheet mode — extract only code blocks/commands +- Category browsing — discover what topics exist + +## Setting Up the MCP Server + +### Step 1: Install the Server + +```bash +npm install -g hacktricks-mcp-server +``` + +The postinstall script clones the HackTricks repo automatically (~2 min on first install). + +### Step 2: Configure Your Agent + +Add to your agent's MCP configuration (e.g., `~/.claude/settings.json`): + +```json +{ + "mcpServers": { + "hacktricks": { + "command": "npx", + "args": ["hacktricks-mcp-server"] + } + } +} +``` + +**Source install alternative:** + +```bash +git clone https://github.com/Xplo8E/hacktricks-mcp-server.git +cd hacktricks-mcp-server +git submodule update --init --recursive +npm install && npm run build +``` + +Then point to the built file: + +```json +{ + "mcpServers": { + "hacktricks": { + "command": "node", + "args": ["/absolute/path/to/hacktricks-mcp-server/dist/index.js"] + } + } +} +``` + +### Step 3: Verify + +Restart your agent and test with: *"Search HackTricks for SQL injection"* + +## Available MCP Tools + +| Tool | Purpose | When to Use | +|------|---------|-------------| +| `hacktricks_quick_lookup` | One-shot lookup by topic/alias | User asks "how do I exploit X?" — reduces 3+ calls to 1 | +| `search_hacktricks` | Full-text search with grouped results | User gives a keyword but isn't sure which page | +| `get_hacktricks_outline` | Table of contents of a page | Before reading a full page to find the right section | +| `get_hacktricks_section` | Extract a specific section | User wants only the "SUID Binaries" part of a long page | +| `get_hacktricks_cheatsheet` | Extract only code blocks/commands | User wants copy-paste commands, no prose | +| `get_hacktricks_page` | Full page content | User explicitly asks for the complete page | +| `list_hacktricks_categories` | Browse categories / directory tree | User wants to discover what topics exist | + +### Quick-Lookup Aliases + +These shorthand aliases work with `hacktricks_quick_lookup`: + +| Alias | Full Topic | Typical Category | +|-------|-----------|------------------| +| `sqli` | SQL Injection | `pentesting-web` | +| `xss` | Cross-Site Scripting | `pentesting-web` | +| `rce` | Remote Code Execution | `pentesting-web` | +| `lfi` | Local File Inclusion | `pentesting-web` | +| `rfi` | Remote File Inclusion | `pentesting-web` | +| `ssrf` | Server-Side Request Forgery | `pentesting-web` | +| `csrf` | Cross-Site Request Forgery | `pentesting-web` | +| `xxe` | XML External Entity | `pentesting-web` | +| `ssti` | Server-Side Template Injection | `pentesting-web` | +| `idor` | Insecure Direct Object Reference | `pentesting-web` | +| `jwt` | JSON Web Token attacks | `pentesting-web` | +| `suid` | SUID privilege escalation | `linux-hardening` | +| `privesc` | Privilege escalation (general) | `linux-hardening` / `windows-hardening` | + +## How to Query HackTricks + +### Pattern 1: Quick Lookup (1 Call) + +**Best for:** Known vulnerability names, common techniques. + +**User:** *"How do I exploit SUID binaries for privilege escalation?"* + +``` +→ hacktricks_quick_lookup(topic="SUID", category="linux-hardening") +``` + +**Result:** Returns the best page's exploitation sections + code blocks in one shot. + +--- + +### Pattern 2: Search → Outline → Section (3 Calls) + +**Best for:** Exploratory queries where you need to find the right page first. + +**User:** *"Show me SSRF techniques"* + +1. `search_hacktricks(query="SSRF", category="pentesting-web", limit=10)` +2. `get_hacktricks_outline(path="src/pentesting-web/ssrf-server-side-request-forgery/README.md")` +3. `get_hacktricks_section(path="src/pentesting-web/ssrf-server-side-request-forgery/README.md", section="SSRF in PDF")` + +**Token savings:** ~5500 tokens → ~400 tokens. + +--- + +### Pattern 3: Cheatsheet Mode (2 Calls) + +**Best for:** "Give me the commands" — no prose needed. + +**User:** *"Give me all the reverse shell one-liners from HackTricks"* + +1. `search_hacktricks(query="reverse shell")` → identifies the page path +2. `get_hacktricks_cheatsheet(path="src/generic-methodologies-and-resources/shells/README.md")` + +**Result:** Only code blocks — no explanatory text. + +--- + +### Pattern 4: Category Discovery (1 Call) + +**Best for:** "What topics does HackTricks cover?" + +**User:** *"What cloud security topics are there?"* + +``` +→ list_hacktricks_categories(category="pentesting-cloud") +``` + +**Result:** Full directory tree under the requested category. + +--- + +### Pattern 5: Full Page Read (1 Call) + +**Best for:** User explicitly asks for the complete page. + +**User:** *"Read me the entire Linux privilege escalation page"* + +``` +→ get_hacktricks_page(path="src/linux-hardening/privilege-escalation/README.md") +``` + +> ⚠️ Pages can exceed 3000 tokens. Prefer Pattern 2 for targeted questions. + +## Tips for Effective Queries + +1. **Prefer `quick_lookup` for known topics** — It bundles search + section extraction + cheatsheet into one call. +2. **Always filter by category** when possible (`pentesting-web`, `linux-hardening`, `pentesting-cloud`, etc.) for faster, more relevant results. +3. **Use `outline` before `page`** — Avoid loading 3000+ tokens when you only need one section. +4. **Use `cheatsheet` for commands** — Skip prose when the user just wants copy-paste payloads. +5. **Chain tools intelligently** — Search → Outline → Section is the most token-efficient path for exploratory queries. +6. **Broaden keywords if no results** — Try removing the `category` filter or using a more general search term. + +## Troubleshooting + +| Issue | Fix | +|-------|-----| +| "MCP server not found" | Verify `npx hacktricks-mcp-server` runs in your terminal. Check Node.js ≥ 18. | +| "ripgrep not found" | Install `rg` (`brew install ripgrep` / `apt install ripgrep`). | +| Empty search results | Try broader keywords or remove the `category` filter. | +| Section not found | Use `get_hacktricks_outline` first to confirm the exact header spelling. | +| Outdated content | Run `git submodule update --init --recursive` in the server directory to refresh the HackTricks repo. | +| Slow first query | First install clones ~2GB of HackTricks content. Subsequent queries are instant via ripgrep. | +| Permission denied | Ensure the path in your MCP config points to the correct `dist/index.js` for source installs. | diff --git a/skills/hacktricks-mcp/references/quick-lookup-aliases.md b/skills/hacktricks-mcp/references/quick-lookup-aliases.md new file mode 100644 index 0000000..98eb98e --- /dev/null +++ b/skills/hacktricks-mcp/references/quick-lookup-aliases.md @@ -0,0 +1,28 @@ +# Quick Lookup Aliases + +The `hacktricks_quick_lookup` tool supports these shorthand aliases for common attack vectors. +Pass the alias as the `topic` parameter. + +| Alias | Full Topic | Typical Category | +|-------|-----------|------------------| +| `sqli` | SQL Injection | `pentesting-web` | +| `xss` | Cross-Site Scripting | `pentesting-web` | +| `rce` | Remote Code Execution | `pentesting-web` | +| `lfi` | Local File Inclusion | `pentesting-web` | +| `rfi` | Remote File Inclusion | `pentesting-web` | +| `ssrf` | Server-Side Request Forgery | `pentesting-web` | +| `csrf` | Cross-Site Request Forgery | `pentesting-web` | +| `xxe` | XML External Entity | `pentesting-web` | +| `ssti` | Server-Side Template Injection | `pentesting-web` | +| `idor` | Insecure Direct Object Reference | `pentesting-web` | +| `jwt` | JSON Web Token attacks | `pentesting-web` | +| `suid` | SUID privilege escalation | `linux-hardening` | +| `privesc` | Privilege escalation (general) | `linux-hardening` / `windows-hardening` | + +## Usage + +```json +{ "topic": "ssrf", "category": "pentesting-web" } +``` + +The `category` filter is optional but recommended for faster, more relevant results. diff --git a/skills/hacktricks-mcp/references/tool-reference.md b/skills/hacktricks-mcp/references/tool-reference.md new file mode 100644 index 0000000..3a6400f --- /dev/null +++ b/skills/hacktricks-mcp/references/tool-reference.md @@ -0,0 +1,126 @@ +# MCP Tool Reference + +Complete parameter reference for all 7 tools exposed by the HackTricks MCP server. + +## `hacktricks_quick_lookup` + +⚡ One-shot exploitation lookup. Searches, finds the best page, and returns exploitation sections + code blocks in a single call. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `topic` | string | **Yes** | Attack/technique to look up (e.g., `"SUID"`, `"sqli"`, `"docker escape"`) | +| `category` | string | No | Category filter for faster results (e.g., `pentesting-web`, `linux-hardening`) | + +**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. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `query` | string | **Yes** | Search term or regex pattern | +| `category` | string | No | Filter to specific category (e.g., `pentesting-web`) | +| `limit` | number | No | 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. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `path` | string | **Yes** | 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. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `path` | string | **Yes** | Relative path to markdown file | +| `section` | string | **Yes** | Section header to extract (partial match, case-insensitive) | + +**Example:** +```json +{ "path": "src/linux-hardening/privilege-escalation/README.md", "section": "SUID" } +``` + +**Benefits:** Read just the "SUID Binaries" section (~200 tokens) instead of the entire page (~3000 tokens). + +--- + +## `get_hacktricks_cheatsheet` + +Extract **only code blocks** from a page. Perfect when you just need commands, payloads, or examples. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `path` | string | **Yes** | 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. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `path` | string | **Yes** | 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. + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `category` | string | No | Category to expand | + +**Without category:** Lists top-level categories. +**With category:** Shows full directory tree with file paths. diff --git a/skills/hacktricks-mcp/references/troubleshooting.md b/skills/hacktricks-mcp/references/troubleshooting.md new file mode 100644 index 0000000..b273188 --- /dev/null +++ b/skills/hacktricks-mcp/references/troubleshooting.md @@ -0,0 +1,13 @@ +# Troubleshooting + +Common issues and their fixes when using the HackTricks MCP server. + +| Issue | Cause | Fix | +|-------|-------|-----| +| "MCP server not found" | Server binary not in PATH or Node.js < 18 | Verify `npx hacktricks-mcp-server` runs in your terminal. Upgrade Node.js to ≥ 18. | +| "ripgrep not found" | `rg` binary missing | Install ripgrep: `brew install ripgrep` (macOS) or `apt install ripgrep` (Debian/Ubuntu). | +| Empty search results | Query too narrow or wrong category | Try broader keywords or remove the `category` filter. | +| Section not found | Header name mismatch | Use `get_hacktricks_outline` first to confirm the exact header spelling. | +| Outdated content | HackTricks repo stale | Run `git submodule update --init --recursive` in the server directory to refresh. | +| Slow first query | Initial repo clone | First install clones ~2GB of HackTricks content. Subsequent queries are instant via ripgrep. | +| Permission denied | MCP config path issue | Ensure the path in your MCP config points to the correct `dist/index.js` for source installs. | diff --git a/skills/hacktricks-mcp/references/usage-patterns.md b/skills/hacktricks-mcp/references/usage-patterns.md new file mode 100644 index 0000000..4fc485d --- /dev/null +++ b/skills/hacktricks-mcp/references/usage-patterns.md @@ -0,0 +1,81 @@ +# Usage Patterns + +Token-efficient workflows for querying HackTricks via MCP. + +## Pattern A: Quick Lookup (1 Call) + +**Best for:** Known vulnerability names, common techniques. + +``` +User: "How do I exploit SUID binaries?" + +→ hacktricks_quick_lookup(topic="SUID", category="linux-hardening") +``` + +**Result:** Exploitation sections + code blocks from the best-matching page. + +--- + +## Pattern B: Search → Outline → Section (3 Calls) + +**Best for:** Exploratory queries where you need to find the right page first. + +``` +User: "Show me SSRF techniques" + +Step 1: search_hacktricks(query="SSRF", category="pentesting-web", limit=10) +Step 2: get_hacktricks_outline(path="src/pentesting-web/ssrf-server-side-request-forgery/README.md") +Step 3: get_hacktricks_section( + path="src/pentesting-web/ssrf-server-side-request-forgery/README.md", + section="SSRF in PDF" + ) +``` + +**Token savings:** ~5500 tokens → ~400 tokens. + +--- + +## Pattern C: Cheatsheet Mode (2 Calls) + +**Best for:** "Give me the commands" — no prose needed. + +``` +User: "Give me reverse shell one-liners" + +Step 1: search_hacktricks(query="reverse shell") + → identifies: src/generic-methodologies-and-resources/shells/README.md + +Step 2: get_hacktricks_cheatsheet( + path="src/generic-methodologies-and-resources/shells/README.md" + ) +``` + +**Result:** Only code blocks — no explanatory text. + +--- + +## Pattern D: Category Discovery (1 Call) + +**Best for:** "What topics does HackTricks cover?" + +``` +User: "What cloud security topics are there?" + +→ list_hacktricks_categories(category="pentesting-cloud") +``` + +**Result:** Full directory tree under the requested category. + +--- + +## Pattern E: Full Page Read (1 Call) + +**Best for:** User explicitly asks for the complete page. + +``` +User: "Read me the entire Linux privilege escalation page" + +→ get_hacktricks_page(path="src/linux-hardening/privilege-escalation/README.md") +``` + +> ⚠️ Pages can exceed 3000 tokens. Prefer Pattern B for targeted questions. diff --git a/skills/hacktricks-mcp/scripts/verify-setup.sh b/skills/hacktricks-mcp/scripts/verify-setup.sh new file mode 100644 index 0000000..2d6bfe7 --- /dev/null +++ b/skills/hacktricks-mcp/scripts/verify-setup.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +# Verify HackTricks MCP server setup + +set -e + +echo "=== HackTricks MCP Setup Verification ===" + +# Check Node.js version +node_version=$(node --version 2>/dev/null || echo "not found") +if [[ "$node_version" == "not found" ]]; then + echo "❌ Node.js not found. Install Node.js ≥ 18." + exit 1 +elif [[ "${node_version#v}" < "18" ]]; then + echo "❌ Node.js $node_version is too old. Upgrade to ≥ 18." + exit 1 +else + echo "✅ Node.js $node_version" +fi + +# Check ripgrep +if command -v rg &> /dev/null; then + echo "✅ ripgrep $(rg --version | head -n1)" +else + echo "❌ ripgrep (rg) not found. Install it:" + echo " macOS: brew install ripgrep" + echo " Ubuntu/Debian: sudo apt install ripgrep" + exit 1 +fi + +# Check hacktricks-mcp-server +if command -v hacktricks-mcp-server &> /dev/null || npx hacktricks-mcp-server --version &> /dev/null 2>&1; then + echo "✅ hacktricks-mcp-server is available" +else + echo "❌ hacktricks-mcp-server not found. Install it:" + echo " npm install -g hacktricks-mcp-server" + exit 1 +fi + +# Check HackTricks repo clone +hacktricks_dir="$(npm root -g)/hacktricks-mcp-server/hacktricks" 2>/dev/null || true +if [[ -d "$hacktricks_dir" ]]; then + echo "✅ HackTricks repo cloned at $hacktricks_dir" +else + echo "⚠️ HackTricks repo not found. It will be cloned on first use (~2 min)." +fi + +echo "" +echo "=== All checks passed! ==="