ferret-den

An MCP server that exposes ProjectDiscovery reconnaissance binaries under decoupled tool names to prevent false-positive model refusals.

den:whisker runs subfinder. den:fang runs nuclei. The agent sees the job. The binary name stays out of the catalog.

Why the Names · Architecture & Safety · Jobs · Installation · Configuration · License

Why the Names

Frontier models and automated API moderation layers frequently trigger refusal reflexes on specific cybersecurity keywords (nuclei, subfinder, exploit, vulnerability scanner). When these names appear directly in an MCP server's tools/list catalog, models often refuse benign reconnaissance tasks (such as asset inventory or attack surface mapping) before evaluating the prompt context, target authorization, or input arguments.

ferret-den decouples tool definitions from binary execution:

• The Agent View: The agent inspects den:* names paired with clear functional descriptions and typed schemas (e.g., den:whisker = "Finds subdomains").

• The Process View: The local server translates valid calls into local binary invocations via argument arrays (subfinder, httpx, nuclei).

• The Safety View: Destructive or active scanning actions are protected by explicit human confirmation gates (confirm: true), replacing brittle keyword blocking with real operational oversight.

This design reflects recent empirical research on agentic safety boundaries:

• Not All Refusals Are Equal: How Safety Alignment Fails Cybersecurity at Scale (arXiv:2607.02714): Demonstrates that cybersecurity refusals often operate as blunt, over-generalized directional vectors that penalize defensive workflows without stopping dedicated adversaries.

• A New Framework for Cybersecurity Refusals in AI Agents (arXiv:2606.02644): Evaluates refusal variations across frontier models on multi-step security tasks.

• MLLMs Fail to Refuse when Using Tools Agentically (arXiv:2610.03938): Shows that structured tool usage focuses models on API compliance, significantly reducing superficial conversational refusals.

Renaming is not an exploit or a jailbreak. If a model determines that an underlying objective is harmful, it will still refuse. The renaming simply prevents surface-level lexical filters from blocking authorized, routine recon.

Related MCP server: PengStrike AI MCP

Architecture & Safety

• No Shell Interpolation: All binaries are spawned directly using argument arrays via POSIX spawn. Shells (/bin/sh, cmd.exe) are never invoked, eliminating command injection risks.

• Execution Timeouts: Kit jobs carry an enforced 120-second execution cap. den:denhome exits after 8 seconds.

• Human Confirmation Gate: den:fang, den:raid, den:keeper, den:chatter, den:shadow, and den:denhome require confirm: true before execution begins.

• External Binaries: The repository does not ship binaries. It invokes existing executables managed by pdtm in $PD_TOOLS_DIR (defaulting to $HOME/.pdtm/go/bin).

Jobs

The server exposes 22 discrete MCP tools. The primary nine jobs feature fully typed argument schemas, while utility tasks accept a target and an argument array.

Installation

Prerequisites

Install pdtm and set up the ProjectDiscovery suite:

go install github.com/projectdiscovery/pdtm/cmd/pdtm@latest
pdtm -install-all

Server Setup

git clone https://github.com/toxicwind/ferret-den.git
cd ferret-den
cp .env.example .env
sh scripts/write-env.sh
sh scripts/link-bins.sh
bun install
bun src/index.ts

scripts/link-bins.sh generates the symlinks in the bin directory. The server exclusively accepts and processes den:* identifiers.

Configuration

Add the server to your MCP client configuration (for example claude_desktop_config.json):

{
  "mcpServers": {
    "den": {
      "command": "bun",
      "args": ["/path/to/ferret-den/src/index.ts"],
      "env": {
        "PD_TOOLS_DIR": "$HOME/.pdtm/go/bin"
      }
    }
  }
}

Repository Layout

• src/index.ts: Primary MCP entrypoint; validates inputs and routes process execution.

• src/den-names.ts: Static mapping between MCP identifiers and system binaries.

• src/tools/: Type definitions and structured schemas for core tools.

• src/tools/kit.ts: Argument forwarding and timeout wrappers for utility tools.

• src/workflows/bug-bounty.ts: Pre-chained reconnaissance sequence (den:raid).

• scripts/: Environment configuration and binary symlink scripts.

License

• The den translation layer, scripts, and documentation are licensed under WTFPL v2.

• Upstream MCP core components derived from intelligent-ears/pd-tools-mcp remain under the MIT License.