ferret-den

An MCP server that exposes the Warren's reconnaissance kit 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, den:denhome, and den:sniff 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

One-shot: auto-installer (first-class)

scripts/install.ts installs every kit member the den:* jobs execute, so the server never fails on a missing member at call time. It reads src/den-names.ts as the source of truth and resolves members via PATH or ~/.pdtm/go/bin, fetching through the catalog manager (den:keeper) with a compile-from-source graft fallback for members the catalog dropped. The overlay is absolute: user-facing output speaks den names only — underlying tool and vendor identities are internal resolution constants. Internal composite workflows (den:raid, recon_workflow) are excluded — they are implemented in src/index.ts, not external binaries.

bun install                       # JS deps only
bun run install-bins              # install every missing kit binary
bun run check-bins                # verify only (exit 1 if anything missing)
bun run check-bins -- --quiet     # silent verify for CI / health checks

Safety note: the installer is explicit-only — the MCP server never auto-runs it. On missing binaries the server aborts loudly with the fix command; install passes run when an operator invokes them (or schedules them), never as an unscheduled side effect of startup.

Manual prerequisites (if you prefer)

The Warren's burrow URLs are internal constants — see the OVERLAY table in scripts/install.ts. A manual pass is just: install the catalog keeper from its burrow, run it with -install-all, and members land in ~/.pdtm/go/bin.

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.