tengu CLAUDE.md

CLAUDE.md — Tengu MCP Server

This file is the primary guide for AI assistants (Claude Code and others) working on the Tengu codebase. Read it in full before making any changes.

---

Project Overview

Tengu is a Model Context Protocol (MCP) server that exposes professional pentesting tools to AI assistants through a clean, secure interface.

Property	Value
Framework	FastMCP 2.0+
Python	3.12+
Package manager	uv (full path: /Users/rfunix/.local/bin/uv)
Validation	Pydantic v2
Logging	structlog (JSON, structured)
Entry point	src/tengu/server.py → FastMCP("Tengu")
Config file	tengu.toml at project root
Test suite	2643+ tests, 0 lint errors
Tools	80 MCP tools
Resources	20 MCP resources
Prompts	35 MCP prompts

---

Architecture

Request Flow

Every tool invocation follows this mandatory pipeline — no exceptions:

Claude (MCP Client)
       │
       ▼
  FastMCP layer          ← receives JSON-RPC call
       │
       ▼
1. sanitizer             ← tengu/security/sanitizer.py
   - Validate input formats (IP, hostname, CIDR, URL, port spec, etc.)
   - Strip/reject shell metacharacters: [;&|`$<>(){}\[\]!\\\'\"\\r\\n]
   - Raise InvalidInputError on any violation
       │
       ▼
2. allowlist             ← tengu/security/allowlist.py
   - Extract hostname from target
   - Check against blocked_hosts (always wins)
   - Check against allowed_hosts (must match if non-empty)
   - Raise TargetNotAllowedError on denial
       │
       ▼
3. rate_limiter          ← tengu/security/rate_limiter.py
   - Sliding window (60s) per tool
   - Concurrent slot limit per tool
   - Raise RateLimitError if either limit is exceeded
       │
       ▼
4. audit logger          ← tengu/security/audit.py
   - Write JSON audit record to logs/tengu-audit.log
   - Redact sensitive parameters (password, token, key, etc.)
   - Log tool name, target, params, result, duration
       │
       ▼
5. executor              ← tengu/executor/process.py
   - asyncio.create_subprocess_exec (NEVER shell=True)
   - Resolve tool path via shutil.which
   - Enforce timeout
   - Return (stdout, stderr, returncode)
       │
       ▼
  Output parser          ← per-tool parsing function
  (XML, JSON, JSONL, plain text)
       │
       ▼
  Return dict to Claude