Mcpwn

MCPwn Operator

MCPwn is a Linux-container-backed MCP server (Kali or Debian base — the MCP/catalog contract is the same, while installed runtime tools differ and genuinely heavy tools remain Kali-only): a non-root runtime user with sudo NOPASSWD:ALL, ~200 security tools behind a catalog, a container workspace, a CAS artifact plane (:5001), tunnels, and reverse-shell handling. Prefix root-only operations with sudo. Use the right execution path, discover tools instead of guessing, and move files with the correct mechanism; wrong choices cause timeouts, lost output, orphaned processes, and wasted turns.

Network sharing is host-OS-dependent: only a Linux host shares its network with the container (network_mode: host) — local listeners and the host's tun0 are directly reachable. On Windows/macOS (Docker Desktop) the container is NAT'd, so a listener isn't reachable from the LAN/VPN unless you bring a VPN up inside the container (tunnel_up kind=vpn → routable tun0) or publish via a relay (reach=public). Don't assume host reachability off Linux.

Choose the debugger locus before attaching. local means the process namespace where MCPwn's API runs; in the standard Docker deployment that is the container, not the Windows/macOS host. Separate hosts require an explicit debugger server/transport, while NeuroMatrix is only needed for emulation. Keep a challenge's matching binary, loader, and libc together in the selected runtime.

The Loop

1. Session first. create_analysis_session() → keep session_id + workspace. Reuse it for the whole task. Lost it after a context reset? list_sessions() / list_interactive_sessions() to rediscover, don't spawn a duplicate.
2. Discover, never guess. The infra tools are always direct — call them with no discovery: session (create_analysis_session/list_sessions/delete_session), artifacts (request_upload/request_download/list_artifacts/analyze_artifact/import_artifact_to_workspace), jobs (list_jobs/poll_job/delete_job), workspace (write_workspace_file/read_workspace_file/patch_workspace_file), storage (storage_usage/prune_*), execution (execute_command), interactive (start_interactive_shell/send_to_shell/read_shell_output/run_in_shell/stabilize_shell/close_shell/list_interactive_sessions/signal_interactive_shell). Only DOMAIN tools (network/web/pwn/…) need discovery: list_catalog() → get_tools(domain=..., query=...) → get_tool("name") (read args) → run_tool("name", {...}). Catalog names are hidden until discovered; guessing them wastes turns — but never list_catalog to "find" an infra tool.
3. Execute on the right path (see decision table below).
4. Collect results; request output_mode=auto or artifact when complete output may be large. The CAS artifact then preserves the complete streams while inline stdout/stderr remain bounded head/tail previews. /api/command defaults to inline, so read the digest, byte counts, and truncation flags instead of assuming a complete artifact exists.
5. Cleanup when done: close_shell, delete_job, delete_session. For emulation, prove jobs/endpoints/interactive clients stopped before destruction and explicitly delete only confirmed, unshared provider artifacts.

Debugging and optional emulation

MCPwn runs GDB and Frida without NeuroMatrix. It can also map its emulation domain onto a standalone, client-neutral NeuroMatrix server when emulation is required.

Load references/debugging-and-emulation.md before attaching to a host process, choosing GDB versus Frida, or composing MCPwn with NeuroMatrix.

NeuroMatrix compatibility boundary

• list_catalog.provider_identity is authoritative. Persist it with provider_ref for every session, artifact, workspace, job, interactive, and endpoint handle; IDs and refs are opaque and provider-scoped.
• Keep operation_id (the MCPwn bridge job for poll_job/delete_job) separate from neuromatrix_job_id (the native provider job for emulation_operation/recovery). Use the explicit native name when the compatibility alias is available.
• workspace_ref is a non-path logical reference: pass it unchanged to provider tools. Provider-private workspace/host paths never cross the boundary; guest/target paths returned inside operational output remain caller-visible findings. On identity mismatch, rediscover and restage instead of replaying stale handles.
• Recover lost provider jobs/artifacts with list_jobs/list_artifacts; use delete_artifact only for explicitly confirmed, unshared objects. Artifact PUT/GET sends required_headers, accepts 2xx only, and disables redirects.

Execution path — pick correctly (top time-sink)

Known-long commands are rejected synchronously on execute_command — use detach=True. Never send real scans, brute-force, cracking, or fuzzing work inline. Exact informational invocations containing only -h/--help/-V/--version remain valid inline; adding operands makes them workload commands again.

The detached contract decides what you can run at all. execute_command(cmd, detach=True) with no timeout has no deadline and stays interruptible — delete_job SIGKILLs its owned process tree and verifies the kill. It is the path for any long-running or unwrapped program. Inline is capped at 20s (clients that serialize requests stall on anything longer); MCPWN_INLINE_TIMEOUT_CAP only lowers it, to a 5s floor, and only an operator's MCPWN_ALLOW_LONG_INLINE=1 lifts it. Cleanup adds bounded time after the timeout, so detach anything near 20s or duration-uncertain. A detached catalog job reports killable=true while a local subprocess phase is active; pure-Python, remote, and between-command phases remain cooperative and may stay cancellation_pending. Its wrapper owns the deadline: inspect get_tool, poll_job, and list_jobs; use execute_command(detach=True) when arbitrary work must remain continuously hard-killable or outlive a wrapper ceiling.

Duration-uncertain catalog wrappers — especially deep decompilation or global analysis — must use detach=True, bounded poll_job intervals, and limited concurrent heavy jobs. A caller/MCP request timeout may end the wait without cancelling the backend job; inspect job and cancellation state before retrying or duplicating work. If the backend reports unhealthy/unavailable, report that state and do not restart or rebuild it without user direction. Active detached jobs expose lifecycle state, not incremental stdout/stderr; use an interactive stream or a bounded workspace progress file when early output matters. After terminal status, retrieve and persist the result or artifact before delete_job, because deletion removes the retained payload.

Interactive shells: prefer run_in_shell(id, cmd) for a discrete command. It is marker-synced — returns THAT command's output + exit_code in ONE call (autodetects posix/powershell/cmd) — so no guess-the-timing send_to_shell+read_shell_output loop and no command-echo / job-control noise bleeding into the read. Keep read_shell_output(wait_seconds=N) for streaming / TUI / a shell you must watch live; wait_seconds is server-clamped to ~20s, so loop it for longer waits rather than expecting one longer block. Full rules, sleep/backgrounding traps, and the interactive lifecycle: load references/execution-model.md.

Moving files — use the right mechanism

Decide by source/type, not size. NEVER base64 -w0 a file that exists on disk into write_workspace_file — it streams the bytes through model context (token cost ∝ file size) and one flipped char stays valid base64 = silent corruption (decoded bytes differ from source with no error; downstream PKI/binary consumers reject the result). The :5001 PUT has no minimum size and is SHA-addressed — default for any on-disk file. If you must send content_base64, pass sha256= (server refuses on mismatch).

Details, the pre-staged /opt/*-payloads depots, and the sub-agent CAS-handoff rule: references/files-and-artifacts.md.

Connectivity & reverse shells (bring reachability up FIRST)

A missing route fakes an all-filtered scan — establish and verify the path before enumerating.

• Route/pivot/VPN/LHOST → get_tools(domain="network") then tunnel_up (kind = vpn/expose/proxy/forward) and tunnel_revshell (cross-OS LHOST:LPORT + ready payloads).
• VPN by artifact: run_tool("tunnel_up", {"kind":"vpn","config_ref":"mcp://artifacts/<sha>"}) → iface=tun0 + IP.
• Catch shells with penelope (default), not raw nc: auto PTY upgrade + on-disk transcript. penelope/pwncat are pty-only — launch them via start_interactive_shell (pexpect gives them a TTY); fired through execute_command they're now guarded (you get guard: pty_only_listener + an nc fallback_command, not a crash — treat it as a signal to relaunch interactively). After catching, stabilize_shell (shell-aware — auto-skips the Linux PTY upgrade on a Windows shell); run discrete commands with run_in_shell (returns scoped output + exit_code — no fragmented reads). Never SIGINT the listener to stop a remote job (it drops the shell).
• Windows / AD / Kerberos: a raw Windows callback has no Unix PTY — drive it with run_in_shell (cmd/powershell autodetected), then pivot to evil-winrm for a clean PTY (creds / -H <nthash> PtH / -r <REALM> Kerberos). Kerberos needs the DC FQDN and REALM in /etc/hosts + no clock skew (krb_time_probe → faketime, impacket-getTGT → KRB5CCNAME). Full flow: references/tunnels-and-shells.md.

Tunnel kinds, cross-OS reach logic, Windows/AD shell pivots, and raw-channel survival patterns: references/tunnels-and-shells.md.

Catalog domains

16 domains for get_tools(domain=...): network, web, pwn, crypto, forensics, pcap, mobile, cloud, web3, ics, osint, llm, ml, runtime, sessions, emulation. Search is tag/alias-aware — query by intent (rdp, smb, jwt, rop, pivot, disk image, factordb, neuromatrix) not exact tool names.

Strict rules

• One session per task; discover before running; read get_tool args before first use of any wrapper.
• Long/known-slow work → detach=True + poll_job, or an interactive shell. Never inline.
• Caller-visible results and command metadata intentionally preserve operational findings such as recovered credentials, private keys, submitted commands, and guest/target paths. Only diagnostic logs and provider-private metadata are redacted best-effort; treat the MCP/chat transcript as sensitive.
• If a pre-existing secret must not appear in that transcript, do not embed it in an execute_command string. Reference a mode-0600 file, use an stdin-capable interactive session, or use a credential-aware wrapper.
• Cancellation proves MCPwn's owned local process tree stopped, not that descendants launched through SSH or another remote transport stopped. Bound remote monitors target-side with timeout -k 2s 90s <command>, then verify the remote PID is gone.
• Don't hand-read large outputs. Auto-CAS only triggers at ~64 KB, so bulky sub-64 KB dumps (a few hundred lines) still print inline and silently burn context when you loop them — the classic tax on iterative analysis of a big read-only artifact (mmap-carving a memory dump, sifting a PCAP/disk image via heredoc scripts). Fix: write results to a workspace file and grep/head only the slice you need, or force a handoff with execute_command(..., output_mode="artifact", output_filename="..."). Extract the few lines that matter; never reprint the whole set each turn. For a long carving/sift loop, quarantine it in a sub-agent that returns a digest.
• Recursive analysis is always detached. firmware_analyze and auto_malware_hunt scan only by default; binwalk_analyze requires a session when extracting and unblob_analyze always requires one. Preserve their unique output directories and explicit depth/file/entry/aggregate-byte controls; do not smuggle output/depth/process overrides through free-form arguments. Treat files as extractor output and analysis_logs as bounded helper diagnostics.
• execute_command is sh -c (dash on a Debian base, bash on Kali) — wrap bashisms in bash -c '...' so they don't silently degrade. start_interactive_shell has no shell — use cwd= (no cd &&) or bash -lc.
• /etc/hosts is a bind mount — append with sudo tee -a, not sed -i.
• Sub-agents don't inherit the MCP client — hand off state as mcp://artifacts/<sha>.
• Server readiness and profile ports: use http://127.0.0.1:5000/mcp for a local client, not localhost or ::1; Docker Desktop publishes the control plane on IPv4 loopback and an IPv6-first localhost can refuse or delay every call. Proxy profiles expose MCP /health on their published MCP port (normally :5000; Debian/macOS defaults to :5002) and artifact /health on the published artifact port (normally :5001). The Kali/macOS dev profile publishes FastMCP directly on host :5000 -> container :8080, so it has no proxy /health; validate it with an MCP initialize or create_analysis_session, and probe artifact health separately. :8081/mcp is an optional direct FastMCP diagnostic endpoint on the proxy profiles and must be tested with MCP initialize, not GET /health.
• Cleanup: close shells, delete finished jobs, delete the session.

Resources

references/

• references/execution-model.md — load when a command times out, output is lost/fragmented, a process orphans, or you need the sleep/backgrounding/interactive-shell rules and the short-vs-async-vs-interactive decision in full.
• references/files-and-artifacts.md — load for any non-trivial file movement: the :5001 upload/download handoff, workspace vs CAS vs import, the /opt payload depots, upload_to_target (incl. pass-the-hash), and the sub-agent handoff pattern.
• references/tunnels-and-shells.md — load when establishing connectivity or catching a shell: tunnel_up kinds and params, tunnel_revshell cross-OS reach, penelope/stabilize_shell/run_in_shell, and raw nc/socat survival tradecraft.
• references/debugging-and-emulation.md — load for GDB/Frida sessions, container-versus-host reachability, debugger-server transports, Frida loader-crash triage, or the optional MCPwn-to-NeuroMatrix emulation bridge.