feat: add Hacktricks-mcp Skills integration for AGENT

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. |

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.

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.

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. |