From c01ade3c167e1a82065ca53ab34f5f35a960728e Mon Sep 17 00:00:00 2001 From: shulkwisec Date: Tue, 9 Jun 2026 15:49:35 +0300 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20add=20Agent=20Skills=20integration?= =?UTF-8?q?=20for=20AI=20agents=20Adds=20an=20Agent=20Skills=20skill=20(ag?= =?UTF-8?q?entskills.io=20standard)=20that=20teaches=20AI=20agents=20how?= =?UTF-8?q?=20to=20efficiently=20query=20the=20HackTricks=20MCP=20server.?= =?UTF-8?q?=20Includes:=20SKILL.md=20with=20when-to-use=20triggers=20and?= =?UTF-8?q?=20setup=20instructions=20Token-efficient=20usage=20patterns=20?= =?UTF-8?q?(search=20=E2=86=92=20outline=20=E2=86=92=20section)=20Quick=20?= =?UTF-8?q?lookup=20aliases=20for=20common=20vulnerabilities=20Troubleshoo?= =?UTF-8?q?ting=20guide=20and=20setup=20verification=20script=20The=20skil?= =?UTF-8?q?l=20is=20discoverable=20via:=20npx=20skills=20add=20Xplo8E/hack?= =?UTF-8?q?tricks-mcp-server=20--skill=20hacktricks-mcp?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/hacktricks-mcp/SKILL.md | 218 ++++++++++++++++++ .../references/quick-lookup-aliases.md | 28 +++ .../references/tool-reference.md | 126 ++++++++++ .../references/troubleshooting.md | 13 ++ .../references/usage-patterns.md | 81 +++++++ skills/hacktricks-mcp/scripts/verify-setup.sh | 48 ++++ 6 files changed, 514 insertions(+) create mode 100644 skills/hacktricks-mcp/SKILL.md create mode 100644 skills/hacktricks-mcp/references/quick-lookup-aliases.md create mode 100644 skills/hacktricks-mcp/references/tool-reference.md create mode 100644 skills/hacktricks-mcp/references/troubleshooting.md create mode 100644 skills/hacktricks-mcp/references/usage-patterns.md create mode 100644 skills/hacktricks-mcp/scripts/verify-setup.sh diff --git a/skills/hacktricks-mcp/SKILL.md b/skills/hacktricks-mcp/SKILL.md new file mode 100644 index 0000000..9961a17 --- /dev/null +++ b/skills/hacktricks-mcp/SKILL.md @@ -0,0 +1,218 @@ +--- +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. +license: MIT +compatibility: Node.js 18+, ripgrep (rg), hacktricks-mcp-server npm package. +metadata: + author: Xplo8E + version: "1.0" + source: https://github.com/Xplo8E/hacktricks-mcp-server + tags: [pentesting, security, exploit, payload, mcp, hacktricks, offensive-security] +--- + +# HackTricks MCP Skill + +Query the [HackTricks](https://book.hacktricks.xyz/) pentesting knowledge base directly from your agent via the Model Context Protocol (MCP). + +## When to Use + +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) + +## MCP Server Setup + +### 1. Install the Server + +```bash +npm install -g hacktricks-mcp-server +``` + +The postinstall script clones the HackTricks repo automatically (~2 min on first install). + +### 2. Configure Your Agent + +Add to your agent's MCP configuration (e.g., `~/.claude/settings.json`, `.cursor/mcp.json`, etc.): + +```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"] + } + } +} +``` + +### 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 | + +### Supported Quick-Lookup Aliases + +`sqli`, `xss`, `rce`, `lfi`, `rfi`, `ssrf`, `csrf`, `xxe`, `ssti`, `idor`, `jwt`, `suid`, `privesc` + +## Usage Patterns + +### Pattern 1: Quick Exploitation Lookup (Recommended) + +**User:** *"How do I exploit SUID binaries for privilege escalation?"* + +**Action:** Call `hacktricks_quick_lookup` with topic `"SUID"` (or `"suid"`). + +**Result:** Returns the best page's exploitation sections + code blocks in one shot. + +``` +Tool: hacktricks_quick_lookup +Args: { "topic": "SUID", "category": "linux-hardening" } +``` + +--- + +### Pattern 2: Search → Outline → Section (Token-Efficient) + +**User:** *"Show me SSRF techniques"* + +**Step 1 — Search:** +``` +Tool: search_hacktricks +Args: { "query": "SSRF", "category": "pentesting-web", "limit": 10 } +``` + +**Step 2 — Outline the best match:** +``` +Tool: get_hacktricks_outline +Args: { "path": "src/pentesting-web/ssrf-server-side-request-forgery/README.md" } +``` + +**Step 3 — Extract the relevant section:** +``` +Tool: get_hacktricks_section +Args: { + "path": "src/pentesting-web/ssrf-server-side-request-forgery/README.md", + "section": "SSRF in PDF" +} +``` + +**Token savings:** ~5500 tokens → ~400 tokens for the same info. + +--- + +### Pattern 3: Cheatsheet Mode + +**User:** *"Give me all the reverse shell one-liners from HackTricks"* + +**Action:** Find the page via search, then call `get_hacktricks_cheatsheet`. + +``` +Tool: search_hacktricks +Args: { "query": "reverse shell" } +→ identifies: src/generic-methodologies-and-resources/shells/README.md + +Tool: get_hacktricks_cheatsheet +Args: { "path": "src/generic-methodologies-and-resources/shells/README.md" } +``` + +**Result:** Only code blocks — no explanatory text. + +--- + +### Pattern 4: Category Discovery + +**User:** *"What cloud security topics does HackTricks cover?"* + +``` +Tool: list_hacktricks_categories +Args: { "category": "pentesting-cloud" } +``` + +Returns the full directory tree under that category. + +--- + +### Pattern 5: Full Page Read + +**User:** *"Read me the entire Linux privilege escalation page"* + +``` +Tool: get_hacktricks_page +Args: { "path": "src/linux-hardening/privilege-escalation/README.md" } +``` + +> ⚠️ Warning: Pages can exceed 3000 tokens. Prefer Pattern 2 for targeted questions. + +## Best Practices + +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. **Respect rate limits** — The server uses ripgrep locally; queries are fast but avoid rapid-fire parallel calls. + +## 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. | + +## Credits + +- [HackTricks](https://book.hacktricks.xyz/) by Carlos Polop +- MCP Server by [Xplo8E](https://github.com/Xplo8E/hacktricks-mcp-server) +- Built with the Model Context Protocol SDK 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! ===" From 1bd71ae130f63f5717ee6aa6e663e448109c9f53 Mon Sep 17 00:00:00 2001 From: shulkwisec Date: Tue, 9 Jun 2026 16:31:18 +0300 Subject: [PATCH 2/2] resolve the skills.sh format conflict --- hacktricks | 2 +- skills/hacktricks-mcp/SKILL.md | 146 ++++++++++++++++----------------- 2 files changed, 73 insertions(+), 75 deletions(-) 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 index 9961a17..62ceed5 100644 --- a/skills/hacktricks-mcp/SKILL.md +++ b/skills/hacktricks-mcp/SKILL.md @@ -6,20 +6,14 @@ description: > 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. -license: MIT compatibility: Node.js 18+, ripgrep (rg), hacktricks-mcp-server npm package. -metadata: - author: Xplo8E - version: "1.0" - source: https://github.com/Xplo8E/hacktricks-mcp-server - tags: [pentesting, security, exploit, payload, mcp, hacktricks, offensive-security] --- -# HackTricks MCP Skill +# 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 +## When to Use This Skill Activate this skill whenever the user asks for: @@ -37,9 +31,20 @@ Activate this skill whenever the user asks for: - Writing original exploit code from scratch (use this for *reference*, not generation) - Legal/policy questions (the skill provides technical knowledge only) -## MCP Server Setup +## What is the HackTricks MCP Server? -### 1. Install the 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 @@ -47,9 +52,9 @@ npm install -g hacktricks-mcp-server The postinstall script clones the HackTricks repo automatically (~2 min on first install). -### 2. Configure Your Agent +### Step 2: Configure Your Agent -Add to your agent's MCP configuration (e.g., `~/.claude/settings.json`, `.cursor/mcp.json`, etc.): +Add to your agent's MCP configuration (e.g., `~/.claude/settings.json`): ```json { @@ -63,15 +68,16 @@ Add to your agent's MCP configuration (e.g., `~/.claude/settings.json`, `.cursor ``` **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 +npm install && npm run build ``` Then point to the built file: + ```json { "mcpServers": { @@ -83,7 +89,7 @@ Then point to the built file: } ``` -### 3. Verify +### Step 3: Verify Restart your agent and test with: *"Search HackTricks for SQL injection"* @@ -99,107 +105,103 @@ Restart your agent and test with: *"Search HackTricks for SQL injection"* | `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 | -### Supported Quick-Lookup Aliases +### Quick-Lookup Aliases -`sqli`, `xss`, `rce`, `lfi`, `rfi`, `ssrf`, `csrf`, `xxe`, `ssti`, `idor`, `jwt`, `suid`, `privesc` +These shorthand aliases work with `hacktricks_quick_lookup`: -## Usage Patterns +| 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` | -### Pattern 1: Quick Exploitation Lookup (Recommended) +## How to Query HackTricks -**User:** *"How do I exploit SUID binaries for privilege escalation?"* +### Pattern 1: Quick Lookup (1 Call) -**Action:** Call `hacktricks_quick_lookup` with topic `"SUID"` (or `"suid"`). +**Best for:** Known vulnerability names, common techniques. -**Result:** Returns the best page's exploitation sections + code blocks in one shot. +**User:** *"How do I exploit SUID binaries for privilege escalation?"* ``` -Tool: hacktricks_quick_lookup -Args: { "topic": "SUID", "category": "linux-hardening" } +→ 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 (Token-Efficient) +### Pattern 2: Search → Outline → Section (3 Calls) -**User:** *"Show me SSRF techniques"* +**Best for:** Exploratory queries where you need to find the right page first. -**Step 1 — Search:** -``` -Tool: search_hacktricks -Args: { "query": "SSRF", "category": "pentesting-web", "limit": 10 } -``` - -**Step 2 — Outline the best match:** -``` -Tool: get_hacktricks_outline -Args: { "path": "src/pentesting-web/ssrf-server-side-request-forgery/README.md" } -``` +**User:** *"Show me SSRF techniques"* -**Step 3 — Extract the relevant section:** -``` -Tool: get_hacktricks_section -Args: { - "path": "src/pentesting-web/ssrf-server-side-request-forgery/README.md", - "section": "SSRF in PDF" -} -``` +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 for the same info. +**Token savings:** ~5500 tokens → ~400 tokens. --- -### Pattern 3: Cheatsheet Mode - -**User:** *"Give me all the reverse shell one-liners from HackTricks"* +### Pattern 3: Cheatsheet Mode (2 Calls) -**Action:** Find the page via search, then call `get_hacktricks_cheatsheet`. +**Best for:** "Give me the commands" — no prose needed. -``` -Tool: search_hacktricks -Args: { "query": "reverse shell" } -→ identifies: src/generic-methodologies-and-resources/shells/README.md +**User:** *"Give me all the reverse shell one-liners from HackTricks"* -Tool: get_hacktricks_cheatsheet -Args: { "path": "src/generic-methodologies-and-resources/shells/README.md" } -``` +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 +### Pattern 4: Category Discovery (1 Call) + +**Best for:** "What topics does HackTricks cover?" -**User:** *"What cloud security topics does HackTricks cover?"* +**User:** *"What cloud security topics are there?"* ``` -Tool: list_hacktricks_categories -Args: { "category": "pentesting-cloud" } +→ list_hacktricks_categories(category="pentesting-cloud") ``` -Returns the full directory tree under that category. +**Result:** Full directory tree under the requested category. --- -### Pattern 5: Full Page Read +### 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"* ``` -Tool: get_hacktricks_page -Args: { "path": "src/linux-hardening/privilege-escalation/README.md" } +→ get_hacktricks_page(path="src/linux-hardening/privilege-escalation/README.md") ``` -> ⚠️ Warning: Pages can exceed 3000 tokens. Prefer Pattern 2 for targeted questions. +> ⚠️ Pages can exceed 3000 tokens. Prefer Pattern 2 for targeted questions. -## Best Practices +## 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. **Respect rate limits** — The server uses ripgrep locally; queries are fast but avoid rapid-fire parallel calls. +6. **Broaden keywords if no results** — Try removing the `category` filter or using a more general search term. ## Troubleshooting @@ -210,9 +212,5 @@ Args: { "path": "src/linux-hardening/privilege-escalation/README.md" } | 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. | - -## Credits - -- [HackTricks](https://book.hacktricks.xyz/) by Carlos Polop -- MCP Server by [Xplo8E](https://github.com/Xplo8E/hacktricks-mcp-server) -- Built with the Model Context Protocol SDK +| 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. |