Show HN: RedHands – MCP for multi-stage offensive security tools

Developer Yasin D. C. released RedHands, an open-source Model Context Protocol (MCP) server written in Go with zero external dependencies that chains multi-stage offensive security tools for authorized security assessments. RedHands supports stdio, SSE and WebSocket transports and ships install profiles — minimal (nmap, subfinder, httpx, nuclei), web, network, ad, k8s, uefi, telecom, aegis, sbom, recon and all — plus structured parsing, report generation, a plugin system, rate limiting, caching and audit logging. The release verifies install archives against published SHA256SUMS and is configured as an MCP server in Claude Code, Cursor and VS Code.

MCP server for authorized security assessments Built in Go with zero external dependencies. Multi-transport stdio/SSE/WebSocket , tool chaining, structured parsing, report generation, plugin system, rate limiting, caching, and audit logging. go install github.com/yasindce1998/redhands/cmd/redhands@latest curl -fsSL https://raw.githubusercontent.com/yasindce1998/redhands/main/scripts/install.sh | bash This verifies a release archive against its published SHA256SUMS and prints MCP configuration instructions. Older releases without checksums must be built from source. To install security tools, use a reviewed checkout containing the dependency lock: git clone https://github.com/yasindce1998/redhands.git && cd redhands sudo ./scripts/install-tools.sh --profile web git clone https://github.com/yasindce1998/redhands.git && cd redhands make build sudo make install Install security tool dependencies pick a profile sudo make install-tools PROFILE=minimal nmap, nuclei, httpx, subfinder sudo make install-tools PROFILE=web web assessment tools sudo make install-tools PROFILE=network network/infrastructure tools sudo make install-tools PROFILE=ad Active Directory tools sudo make install-tools PROFILE=k8s Kubernetes offensive tools sudo make install-tools PROFILE=uefi UEFI bootkit simulation sudo make install-tools PROFILE=telecom StaticZero telecom research Linux only sudo make install-tools PROFILE=aegis Aegis-Shadow eBPF research Linux only sudo make install-tools PROFILE=sbom SBOM + vulnerability scanning syft, grype sudo make install-tools PROFILE=recon deep reconnaissance tools sudo make install-tools PROFILE=all everything Check what's installed make check-deps git clone https://github.com/yasindce1998/redhands.git; cd redhands go build -o bin\redhands.exe .\cmd\redhands Install tool dependencies .\scripts\install-tools.ps1 -Profile web .\scripts\install-tools.ps1 -Check show what's installed/missing Add to your MCP client config: Claude Code ~/.claude/claude desktop config.json , Cursor .cursor/mcp.json , VS Code .vscode/mcp.json : { "mcpServers": { "redhands": { "command": "redhands" } } } stdio default, for MCP clients redhands SSE transport local CLI or remote use with TLS/auth REDHANDS TRANSPORT=sse redhands loopback only; see secure remote setup below WebSocket transport REDHANDS TRANSPORT=ws redhands loopback only Docker selected tools pre-installed docker compose run --rm -i redhands | Profile | Tools Included | Use Case | |---|---|---| | minimal | nmap, subfinder, httpx, nuclei | Quick recon and scanning | | web | nmap, recon set subfinder, amass, dig, waybackurls, gau, arjun , web set httpx, katana, nikto, whatweb, testssl.sh , ffuf, gobuster, feroxbuster, masscan, rustscan, nuclei, sqlmap | Web application testing | | network | nmap, masscan, rustscan, tshark, chisel, ligolo | Network/infrastructure | | ad | nmap, impacket, certipy, crackmapexec, hashcat, john | Active Directory attacks | | k8s | nmap, kubedagger-client, kubedagger-operator, kubedagger-server | Kubernetes offensive eBPF | | uefi | barzakh-adversary, barzakh-scanner, barzakh-server | UEFI bootkit adversary simulation | | telecom | staticzero-defense, staticzero-offense, modem-firmware, sdr-bridge | Telecom security research eBPF, Linux only | | aegis | aegis-shadow-defense, aegis-shadow-offense, aegis-c2 | Linux eBPF security research Aegis-Shadow | | sbom | syft, grype | SBOM generation and vulnerability scanning | | recon | recon set subfinder, amass, dig, waybackurls, gau, arjun + web set httpx, katana, nikto, whatweb, testssl.sh | Deep reconnaissance | | all | Everything | Full offensive toolkit | Profiles describe desired dependencies, not a guarantee every dependency is available on every OS. RustScan, testssl.sh, and CrackMapExec currently need manual installation; KubeDagger client is Linux-only. Installers report missing tools rather than downloading unverified replacements. See dependency maintenance https://github.com/yasindce1998/RedHands/blob/main/docs/dependencies.md . make build produces redhands , redhands-cli , and redhands-creds in bin/ . The CLI uses the same authenticated SSE transport as MCP clients: Terminal 1 REDHANDS TRANSPORT=sse ./bin/redhands Terminal 2 ./bin/redhands-cli tools ./bin/redhands-cli targets add 192.0.2.1 lab-host ./bin/redhands-cli status For HTTPS, set REDHANDS URL=https://your-server:8443 , REDHANDS API KEY , and REDHANDS CLIENT CA=/path/to/ca.pem . For mTLS, also set REDHANDS CLIENT CERT and REDHANDS CLIENT KEY . The CLI rejects untrusted certificates, redirects, and non-loopback plain HTTP. REDHANDS CLIENT TIMEOUT sets its total deadline default 6m . Tool failures return a nonzero exit status; calls are never retried automatically. - Go 1.26.11+ for building from source; if using Go 1.27, use 1.27.4+ - Security tools on PATH installed via scripts above, Docker, or manually 294 tools are registered across 36 toolsets. A default startup serves 287 of them: the two credstore tools additionally require REDHANDS CREDSTORE KEY , and the five GoPhish phishing tools additionally require REDHANDS GOPHISH environment variables. | Tool | Description | |---|---| | nmap port scan | TCP/UDP port scanning SYN, connect, UDP | | nmap service detect | Service and version detection -sV | | nmap os detect | OS fingerprinting -O | | nmap vuln scan | NSE vulnerability scripts | | Tool | Description | |---|---| | subfinder enum | Subdomain enumeration from passive sources | | amass enum | Network mapping and ASN discovery OWASP Amass | | dns lookup | DNS record queries via dig A, AAAA, MX, NS, TXT, etc. | | waybackurls | Fetch archived URLs from the Wayback Machine | | gau urls | Fetch URLs from AlienVault OTX, Wayback, CommonCrawl, URLScan | | arjun discover | HTTP parameter discovery hidden GET/POST params | | Tool | Description | |---|---| | httpx probe | HTTP service probing with tech detection | | katana crawl | Next-gen web crawler JS crawling, headless | | nikto scan | Web server vulnerability scanner | | whatweb fingerprint | Web technology fingerprinting | | testssl scan | TLS/SSL encryption testing | | Tool | Description | |---|---| | ffuf fuzz | Web fuzzing dirs, params, vhosts | | gobuster dir | Directory/file brute-forcing | | feroxbuster scan | Recursive content discovery forced browsing | | Tool | Description | |---|---| | masscan scan | Internet-scale port scanning 10M pps | | rustscan scan | Modern fast port scanner all 65535 ports in seconds | | Tool | Description | |---|---| | sqlmap scan | Automatic SQL injection detection and exploitation | | Tool | Description | |---|---| | nuclei scan | Template-based vulnerability scanning | Kerberos interaction toolkit — for Windows engagement hosts running RedHands with an operator-compiled Rubeus.exe allowlisted as rubeus GhostPack ships no compiled releases by design; Linux execution is not possible — the tool P/Invokes Windows LSA APIs . | Tool | Description | |---|---| | rubeus kerberoast | | | rubeus asktgt | | | rubeus asreproast | | | rubeus harvest | | | rubeus dump | | | rubeus describe | Decode and describe a base64 ticket | | Tool | Description | |---|---| | impacket secretsdump | Dump SAM/LSA/NTDS.dit secrets | | impacket psexec | PsExec-style remote execution | | impacket wmiexec | WMI-based remote execution | | impacket smbclient | SMB client operations | | impacket dcomexec | DCOM remote execution | | impacket get tgt | Request Kerberos TGT | | impacket get st | Request service ticket Kerberoast/delegation | | impacket ntlmrelay | NTLM relay attack | | Tool | Description | |---|---| | sliver generate | Generate implant mTLS, HTTP/S, DNS, WireGuard | | sliver listeners | Manage C2 listeners | | sliver sessions | List/interact with sessions | | sliver beacons | List/interact with beacons | | sliver execute | Execute commands on implant | | sliver upload | Upload files to implant | | sliver download | Download files from implant | | sliver pivot | Pivot setup and management | | sliver portfwd | Port forwarding through implant | | Tool | Description | |---|---| | chisel server | Start Chisel reverse tunnel endpoint | | chisel client | Chisel client forward/reverse/SOCKS | | ligolo start | Start Ligolo-ng proxy server | | ligolo route | Add routes through Ligolo tunnel | | ligolo listener | Manage Ligolo listeners on agent | | Tool | Description | |---|---| | hashcat crack | Crack hashes dictionary, rules, masks | | hashcat benchmark | Benchmark hash types | | hashcat show | Show cracked from potfile | | john crack | Crack passwords with John the Ripper | | john show | Show cracked passwords | | john formats | List supported hash formats graceful degradation on core john builds | | hydra attack | | | Tool | Description | |---|---| | cme smb | SMB enumeration/exec/pass-the-hash | | cme winrm | WinRM execution | | cme ldap | LDAP enumeration | | cme mssql | MSSQL queries/execution | | cme ssh | SSH credential spray/exec | | Tool | Description | |---|---| | certipy find | Find AD CS templates and CAs | | certipy req | Request certificates | | certipy auth | Authenticate via PKINIT | | certipy shadow | Shadow credentials attack | | certipy forge | Golden certificate forgery | | certipy relay | NTLM relay to AD CS | | Tool | Description | |---|---| | tshark capture | Capture packets interface, filter, duration | | tshark read | Read pcap with display filter | | tshark stats | Protocol statistics | | tshark extract | Extract fields from captures | | tshark follow | Follow TCP/UDP/HTTP streams | | Tool | Description | |---|---| | 69 tools | eBPF-powered Kubernetes offensive toolkit, including managed C2-server lifecycle kubedagger server — see tools/kubedagger/ | | Tool | Description | |---|---| | barzakh list | List available UEFI bootkit payload types 134 payloads | | barzakh generate | Generate a UEFI bootkit payload for adversary simulation x86-64, aarch64, riscv64, power64, armv7 | | barzakh corpus | Generate full test corpus of malicious/clean firmware pairs | | barzakh scan | Scan firmware images with 138 specialized bootkit detectors exit 1 = detection, reported as a finding | | barzakh validate | Validate detector coverage TPR/FPR against a corpus | | barzakh scenario | List/show/run multi-stage ATT&CK-mapped attack chains 6 bundled | | barzakh robustness | Mutation-based detector evasion benchmark | | barzakh detectors | List/describe the 138 detectors | | barzakh baseline | Create/show firmware baselines | | barzakh intel | Query IOC feeds, MISP, ATT&CK, STIX intel | | barzakh server start | Start the Barzakh REST scanner server as a managed background daemon X-API-Key auth, SQLite history | | barzakh server stop | Stop a managed Barzakh server | | barzakh server status | Status of managed Barzakh servers | | barzakh inject | | | barzakh esp build | | | barzakh qemu | Boot firmware in an emulated QEMU/OVMF environment run config / memory dump | | barzakh range | Boot QEMU/OVMF/swTPM cyber-range suites with assert-on-detection exit 1 = failed assertions, surfaced as a result | | barzakh fuzz | Protocol-aware firmware fuzzing dhcpv6/bmp/capsule/httpboot/tcg/hii | | barzakh history | Query the SQLite scan history list/show/diff/trends | | barzakh kb | Manage the firmware knowledge base add/list/search/export/import | | barzakh ml | Train/evaluate the ML anomaly models | | barzakh manifest validate | Validate detectors against a labeled corpus manifest with train/validation/test splits | | barzakh info | Scanner build/version, detector, architecture, and format metadata | | barzakh report | Generate report files json/html/markdown/sarif/csv/ecs/cef/leef from scan results | Wraps StaticZero, an eBPF telecom security research framework 2G–5G, satellite, baseband firmware . Authorized lab use only. Warning telecom offense start launches the telecom interception research loader features F89–F172: IMSI targeting, GTP/SS7/Diameter interception, RF and satellite domains . Intercepting telecommunications is illegal without authorization in most jurisdictions — including in labs in some . Use only in an isolated lab environment with equipment you own, and only where you hold explicit permission. The tool is approval-gated and requires root. | Tool | Description | |---|---| | telecom doctor | Read-only StaticZero defense engine preflight platform/kernel/BPF checks | | telecom firmware analyze | Static vulnerability analysis of modem/baseband firmware images | | telecom firmware extract | Extract firmware components with manifest | | telecom firmware diff | Diff two firmware images | | telecom firmware nv dump | Extract NV items carrier/band/security config | | telecom firmware patch | | | telecom firmware monitor | Monitor a modem device protocol stream diag/at/qmi/mbim; bounded by the execution timeout | | telecom sdr scan | Receive-only LTE cell scan via SDR | | telecom sdr capture | Receive-only IQ capture via SDR | | telecom sdr inject | | | telecom sdr relay | | | telecom sdr selftest | | | telecom threats | Correlated threats from a running defense engine | | telecom alerts | Raw alerts from a running defense engine | | telecom stats | Engine runtime statistics | | telecom defense start | Start the StaticZero defense engine as a managed background daemon JSON alerts stream to a file | | telecom defense stop | Stop a managed defense engine daemon | | telecom defense status | Status of managed defense engine daemons | | telecom offense start | | | telecom offense stop | Stop a managed offense loader daemon | | telecom offense status | Status of managed offense loader daemons | | telecom correlator start | Start the protocol correlator as a managed daemon JSON-lines event ingest on loopback | | telecom correlator stop | Stop a managed correlator daemon | | telecom correlator status | Status of managed correlator daemons | StaticZero binaries ship as checksum-verified release assets v0.5.0, Linux only, eBPF embedded and install via the telecom profile: sudo make install-tools PROFILE=telecom . Wraps Aegis-Shadow, a Linux eBPF security research platform educational, VM-only . The analysis tools never execute binaries; aegis offense plan renders the manual lab command with risk notes without executing it. The defense engine and the offense rootkit loader can each be started as a managed background daemon approval-gated . DANGER aegis offense start launches the eBPF rootkit loader — process hiding, credential harvesting, log tampering, anti-forensics, and covert C2, running at kernel level with root. Two capabilities are destructive by design : deadman switch scorched-earth wipe triggered on tamper or timeout — the VM may become unrecoverable and wipe bytecode erases the loaded eBPF bytecode from memory, defeating live forensics . Both are opt-in, emit loud warnings in every result, and expect a disposable, snapshotted lab VM . Data loss from these flags is expected behavior, not a bug. | Tool | Description | |---|---| | aegis alerts parse | Parse/filter NDJSON alert files from the defense engine | | aegis alerts tail | Tail the last N alerts from an alert file | | aegis modules list | Reference catalog of defense modules and offense features | | aegis defense config read | Read/validate a defense engine hot-reload config | | aegis defense config write | Write a defense engine config threshold, window | | aegis offense plan | Dry-run planner: validate offense feature flags and render the exact manual command line with risk notes | | aegis defense start | Start the Aegis-Shadow defense engine as a managed background daemon NDJSON alerts stream to a file; requires root | | aegis defense stop | Stop a managed defense engine daemon | | aegis defense status | Status of managed defense engine daemons | | aegis offense start | ☠️ Launch the Aegis-Shadow eBPF rootkit loader as a managed daemon destructive deadman switch / wipe bytecode are opt-in with warnings; disposable VM only | | aegis offense stop | Stop a managed offense loader daemon | | aegis offense status | Status of managed offense loader daemons | | aegis c2 send | ☠️ Send a command to a running rootkit over its encrypted C2 channel hide/unhide pid, obfuscate file, exfil, kill-switch; fire-and-forget; requires the aegis-c2 CLI from Aegis-Shadow ≥ v0.2.0 | ExploitDB search and CVE enrichment — the connective tissue from scanner findings to Metasploit: nuclei finding → CVE → public exploits → msf module run . Requires the searchsploit binary + on-disk database distro exploitdb package — manual install, not checksum-pinnable . | Tool | Description | |---|---| | searchsploit search | Search ExploitDB by keyword JSON results | | searchsploit cve | Map a CVE ID to public exploits EDB-IDs, paths | | searchsploit edb | Look up an EDB-ID exploit file path + copy hint | | cve enrich | Extract CVEs from scanner output text, map to exploits, and suggest Metasploit modules EDB .rb paths → msf module run candidates | Generic embedded firmware analysis with binwalk v2 — completes the firmware story alongside UEFI Barzakh and baseband modem-firmware . Requires binwalk v2, Python — distro/pip manual install; do not use the v3 Rust rewrite, different CLI . | Tool | Description | |---|---| | firmware scan | Signature scan with a structured JSON summary signatures → record rules | | firmware extract | | | firmware entropy | Entropy analysis encrypted/compressed region detection | SBOM generation and vulnerability scanning with Anchore syft + grype — checksum-pinned releases, installed by the sbom profile. | Tool | Description | |---|---| | sbom generate | Generate an SBOM syft-json, CycloneDX, SPDX from an image, directory, or file | | vuln scan image | Vulnerability-scan an image or SBOM with grype exit-2-on-findings surfaced as a result with a severity summary | | vuln scan sbom | Scan an existing SBOM file with grype | Wraps Metasploit Framework msfvenom + msfconsole . Console tools generate validated .rc resource files from structured parameters — never msfconsole -x — so console-command injection is structurally impossible. Metasploit is not checksum-pinnable no stable release binaries ; install it manually apt install metasploit-framework on Kali/Parrot and the allowlist discovers msfconsole / msfvenom on PATH. msfconsole startup takes 10–60s; runs are bounded by REDHANDS TIMEOUT . | Tool | Description | |---|---| | msf payload generate | | | msf payload list | List payloads, encoders, formats, platforms, or architectures | | msf module info | Show module documentation exploit/auxiliary/post/payload/encoder/nop | | msf module run | | | msf resource run | .rc resource file arbitrary console commands; approval-gated | | Tool | Description | |---|---| | redhands health | Server health check and binary dependency status | RedHands supports four transport modes: | Transport | Use Case | Config | |---|---|---| | stdio default | Local use with Claude Code, Cursor, VS Code | REDHANDS TRANSPORT=stdio | | HTTP Streamable | Modern MCP 2026-07-28 clients: stateless single-endpoint JSON-RPC | REDHANDS TRANSPORT=http REDHANDS HTTP ADDR , default 127.0.0.1:8082 ; REDHANDS HTTP PATH , default /mcp | | SSE | Legacy HTTP clients deprecated-era transport | REDHANDS TRANSPORT=sse loopback by default | | WebSocket | Real-time bidirectional custom transport | REDHANDS TRANSPORT=ws loopback by default | The HTTP transport implements the modern spec: POST-only /mcp endpoint, required MCP-Protocol-Version / Mcp-Method and Mcp-Name for tools/call headers validated against the body, 405 for GET/DELETE, 404 + -32601 for unknown methods, 202 for notifications, and per-request meta protocol version validation -32022 with the supported list . Legacy clients that open with initialize are served by the dual-era handshake on every transport. Non-loopback listeners require authentication and TLS . | Mode | Config | Description | |---|---|---| | none default | REDHANDS AUTH=none | No authentication | | API key | REDHANDS AUTH=apikey + REDHANDS API KEY=<secret | X-API-Key header validation | | mTLS | REDHANDS AUTH=mtls + cert/key/CA env vars | Client certificate verification | Chain tools sequentially with variable substitution: { "method": "workflow/run", "params": { "steps": {"tool": "nmap port scan", "params": {"target": "10.0.0.1"}}, {"tool": "nuclei scan", "params": {"target": "http://10.0.0.1"}} } } Variables: $prev.text previous step output , $step N .text Nth step output . Substitutions contain the full formatted text, not extracted targets; only pass them to parameters that accept that format. All steps honor dry-run, rate limits and scope. Campaigns extend workflows with conditions , parallel fan-out , failure recovery goto: , checkpointing , resume , cancellation , and playbook templates . Every step executes through the same middleware chain as a direct tools/call audit, auth, rate limits, scope, dry-run, approval, concurrency limits . { "method": "campaign/run", "params": { "id": "web-engage-1", "name": "Web assessment", "steps": {"id": "portscan", "tool": "nmap port scan", "params": {"target": "10.0.0.1"}}, {"id": "webscan", "tool": "nuclei scan", "params": {"target": "http://10.0.0.1"}}, {"parallel": {"id": "nikto", "tool": "nikto scan", "params": {"target": "http://10.0.0.1"}}, {"id": "tls", "tool": "testssl scan", "params": {"target": "10.0.0.1:443"}} , "on fail": "continue"}, {"id": "report", "tool": "loot add", "params": {"description": "done"}} } } | Field | Description | |---|---| | id | Unique step identifier used by conditions and ${id...} references | | tool / params | Tool name and JSON params exactly like tools/call | | parallel | Array of sub-steps executed concurrently ≤16, no nesting | | condition | Skip the step unless the condition holds | | on fail | stop default , continue , or goto:<step id recovery jump | {"condition": {"step": "portscan", "op": "json gt", "path": "hosts.0.ports.0", "value": "0"}} Operators: success , failure , contains , not contains , equals , not equals , plus JSON-aware json exists , json not exists , json equals , json not equals , json contains , json gt , json lt evaluated against a previous step's structured output step may be a step ID, "$prev" , or a zero-based index . Placeholders can extract fields from prior results, not just whole text. Tools emitting JSON raw or in a markdown json fence are queryable by dot-path with numeric array indices: $prev.text full text of the previous step $prev.json.findings.0.severity field extraction $step 2 .json.hosts whole array from step 2 native type preserved ${portscan.json.hosts.0.ip} reference by step ID A placeholder that makes up an entire string value is substituted natively numbers stay numbers, arrays stay arrays ; placeholders embedded in a larger string are substituted as text. Unresolvable placeholders pass through untouched. record rules map JSON arrays in a step's output to target database entries, so campaigns build the host/service/credential/finding picture automatically: { "id": "discover", "tool": "kubedagger k8s discover", "params": {"namespace": "default"}, "mitre": "T1613" , "record": {"type": "host", "path": "nodes", "fields": {"ip": "ip", "hostname": "name", "os": "os"}}, {"type": "host", "path": "pods", "fields": {"ip": "pod ip", "hostname": "name"}} } Entry types: host , service , credential , finding . Recorded entries are tagged campaign:<workflow id and become queryable via the targetdb tools and the attack graph. Recording failures warn in the step result without failing the campaign. Steps accept mitre: "T1613", "T1552.001" technique tags. Campaign results aggregate the unique techniques of executed steps as mitre techniques , which can be passed to kubedagger detection action: "generate" , techniques as a comma-separated list to produce matching Falco/Sigma/audit detection rules. The shipped k8s-recon-chain playbook demonstrates recording and tagging end to end, including a final detection-rule generation step. | Method | Params | Description | |---|---|---| | campaign/run | steps or template + vars | Execute a campaign synchronously; checkpoints every step | | campaign/start | same as campaign/run | Async : with the Tasks extension declared, returns a CreateTaskResult taskId, ttlMs, pollIntervalMs and runs detached from the request; without it, identical to campaign/run . Idempotent: re-starting a running ID returns the live task | | campaign/status | workflow id | Load persisted state | | campaign/list | — | List all saved campaigns | | campaign/resume | workflow id | Continue a paused/cancelled campaign | | campaign/cancel | workflow id | Cancel a running campaign works cross-replica: the engine re-reads persisted state at each checkpoint | | campaign/templates | — | List playbook templates | | campaign/template/get | name | Fetch one template | | campaign/template/save | template JSON | Validate and persist a playbook | | tasks/get | taskId | Poll a task: working / input required / completed / failed / cancelled ; terminal states carry the result or error | | tasks/cancel | taskId | Cooperatively cancel a task acks immediately | | tasks/update | taskId , inputResponses | Submit approval responses for a paused task approval for a sequential gate, approval-<sub step id per gated sub-step inside a parallel group; unknown keys are acked and ignored | Campaigns interrupted mid-step cancellation or timeout checkpoint as paused and re-run the interrupted step on resume. Every campaign is single-writer an advisory flock per workflow ID : a duplicate start of a running campaign returns its live task instead of corrupting the checkpoint. Tools that require operator approval high-impact tools not listed in REDHANDS APPROVED TOOLS no longer need to block. When the request declares the Tasks extension, an approval-gated tools/call answers with resultType: "input required" and an elicitation/create approval request; the client re-issues the same call with inputResponses: {"approval": {"approved": true}} and the single call executes audited as an approval bypass . Inside a task-tracked campaign, an approval-gated step pauses the task input required via tasks/get , the response arrives through tasks/update , and campaign/resume re-runs the step. Requests without the capability fail closed with the classic message. Responses never ride in tool arguments — only in the dedicated inputResponses field. Parallel groups use the same machinery per sub-step instead of failing the gated sub-step outright: when one or more sub-steps of a group trip approval gates, the campaign pauses ONCE and tasks/get shows one inputRequest per gated sub-step, keyed approval-<sub step id . Answer each individually tasks/update with inputResponses: {"approval-<sub step id ": {"approved": true}} ; unknown or stale keys are acked and ignored . On campaign/resume the group replays partially: sub-steps that already completed are not re-executed, sub-steps that failed for other reasons keep their recorded failure, approved sub-steps re-run once with their own one-call bypass, denied sub-steps fail with approval denied and flow through the group's on fail stop/continue/goto , and unanswered gates re-trip with fresh request ids. A goto that re-enters a group is a fresh execution — the per-run completion set resets and every sub-step re-runs. Capability-less requests keep the classic fail-closed behavior for group sub-steps too. Playbooks are reusable, versioned campaign templates stored as JSON in REDHANDS WORKFLOW TEMPLATES DIR default ./playbooks/ . Shipped examples: recon-to-vuln , web-assessment , k8s-recon-chain , ad-kerberoast-chain , firmware-bootkit-assessment , telecom-defense-monitoring , firmware-purple-team . Point-and-shoot a playbook: { "method": "campaign/run", "params": { "template": "recon-to-vuln", "vars": {"domain": "target.example", "severity": "critical,high"} } } Campaigns can bind to an engagement with the engagement parameter. The named engagement must exist and be the active engagement — the campaign fails fast instead of silently running against the wrong scope, and every step's targets are checked against that engagement's scope by the middleware: { "method": "campaign/run", "params": { "engagement": "lab-1", "template": "web-assessment", "vars": {"target": "https://target.example"} } } Bindings are persisted with the campaign state and re-validated on resume, so switching engagements between runs rejects a stale binding. Limits: 128 steps per campaign, 16 steps per parallel group, 64 goto recovery jumps, 16 MiB cumulative output — mirroring workflow hard caps. Built-in parsers for common tool output formats: - Nmap XML — parses -oX output into structured hosts/ports/services - Nuclei JSON — parses JSONL findings into severity-grouped results - Masscan JSON — parses -oJ output into host/port pairs Generate reports from workflow results: { "method": "report/generate", "params": { "format": "markdown", "title": "Assessment report", "sections": {"title": "Summary", "tool": "nmap port scan", "content": "Reviewed scan results"} } } Formats: markdown .md and html self-contained with inline CSS . Define custom tools via JSON without writing Go: { "name": "custom quick scan", "description": "Quick nmap top-100 scan", "binary": "nmap", "args template": "-sS", "--top-ports", "100", "{{.target}}" , "input schema": { "type": "object", "properties": { "target": {"type": "string", "description": "Target IP or hostname"} }, "required": "target" } } Drop JSON files in REDHANDS PLUGINS DIR default ./plugins/ and they appear in tools/list automatically. All settings via environment variables: | Variable | Default | Description | |---|---|---| | REDHANDS TOOLSETS | all | Comma-separated toolsets to register approval still applies | | REDHANDS TIMEOUT | 5m | Execution timeout per tool call | | REDHANDS MAX OUTPUT | 10485760 | Max output bytes per execution 10MB | | REDHANDS RATE LIMIT | 10 | Token bucket refill rate requests/sec | | REDHANDS RATE BURST | 20 | Token bucket burst capacity | | REDHANDS CACHE TTL | 5m | Result cache TTL | | REDHANDS CACHE SIZE | 100 | Max pure-function results oldest-expiry eviction | | REDHANDS AUDIT FILE | audit.jsonl | Audit log file path | | REDHANDS TRANSPORT | stdio | Transport mode: stdio , sse , or ws | | REDHANDS SSE ADDR | 127.0.0.1:8080 | SSE HTTP listen address | | REDHANDS WS ADDR | 127.0.0.1:8081 | WebSocket listen address | | REDHANDS AUTH | none | Auth mode: none , apikey , or mtls | | REDHANDS API KEY | — | API key required when auth=apikey | | REDHANDS TLS CERT | — | TLS certificate path | | REDHANDS TLS KEY | — | TLS private key path | | REDHANDS TLS CA | — | CA certificate for mTLS client verification | | REDHANDS PLUGINS DIR | ./plugins | Directory for JSON plugin definitions | | REDHANDS PLUGIN POLL INTERVAL | 5s | Plugin directory polling interval | | REDHANDS CREDSTORE KEY | — | Strong encryption key required for credential persistence | | REDHANDS CREDSTORE FILE | credstore.enc | Encrypted credential store file | | REDHANDS TARGETDB FILE | targetdb.json | Target database file | | REDHANDS TARGETDB AUTOSAVE | true | Persist target database changes immediately | | REDHANDS ENGAGEMENT DIR | engagements | Engagement metadata directory | | REDHANDS DRY RUN | false | Preview executions without running tools | | REDHANDS OPSEC PROFILE | — | OPSEC profile name parsed; proxy routing not yet wired | | REDHANDS IOC FILE | — | Indicator-of-compromise list file parsed; matching not yet wired | | REDHANDS TCP ADDR | — | TCP transport listen address; mTLS only API-key headers are not supported over TCP | | REDHANDS DASHBOARD ADDR | — | Dashboard HTTP listen address parsed; dashboard not yet wired | | REDHANDS GOPHISH URL | — | GoPhish API base URL enables the phishing toolset | | REDHANDS GOPHISH API KEY | — | GoPhish API key | | REDHANDS MAX CONCURRENT | 4 | Maximum active tool calls across clients and workflows | | REDHANDS MAX QUEUED | 16 | Maximum queued calls; further requests fail without executing | | REDHANDS APPROVED TOOLS | — | Exact comma-separated names approved by the operator for high-impact/unclassified tools | | REDHANDS WORKFLOW TIMEOUT | 30m | Total deadline for a sequential workflow or campaign | | REDHANDS WORKFLOW STATE DIR | workflow state | Campaign checkpoint directory | | REDHANDS WORKFLOW TEMPLATES DIR | playbooks | Playbook template directory | | REDHANDS WORKFLOW MAX PARALLEL | 4 | Max concurrent steps inside a campaign parallel group ≤32 | | REDHANDS EVIDENCE DIR | evidence | Artifact directory with persistent metadata index | | REDHANDS LOOT DIR | loot | Directory containing the atomic loot.json store | Non-loopback listeners require authentication and TLS . API keys are accepted only in the X-API-Key header. stdio uses local OS access controls, not API-key authentication. Caching is limited to pure MITRE/risk-score lookups, never scans or state-changing tools. High-impact, mixed-mode, and unclassified tools including plugins require explicit operator approval via REDHANDS APPROVED TOOLS . Dry-run previews do not require this approval and never execute tools. tools/list publishes policy metadata and MCP safety hints. See security and deployment notes https://github.com/yasindce1998/RedHands/blob/main/docs/security-hardening.md for HTTPS/mTLS setup, scope limitations, credential migration, and remaining release work. Evidence metadata persists in REDHANDS EVIDENCE DIR/index.json . Artifacts use random IDs rather than host/tool text in filenames, and are checked against recorded size and SHA-256 values when the store opens. Old files with no index remain untouched and are not automatically listed. Corrupt metadata or missing/changed indexed artifacts stop startup instead of silently losing their history. Loot writes are atomic, and malformed loot.json files fail startup. Both stores are single-process stores: do not point multiple servers at the same directories. Artifacts and loot are private files, not encrypted storage ; protect their directories and backups. evidence screenshot requires operator approval and cutycapt installed on PATH at startup. It uses the shared executor, private staging, HTTP S -only URLs, and PNG validation. CutyCapt may require a display/headless environment; it is not bundled in the current Docker image. Browser redirects and subresources still need network isolation. See evidence and loot recovery https://github.com/yasindce1998/RedHands/blob/main/docs/evidence-storage.md before moving stores, repairing corrupt files, or handling legacy/unindexed artifacts. Enable only specific toolsets: AD/internal assessment export REDHANDS TOOLSETS=nmap,impacket,crackmapexec,certipy,sliver,crack External web assessment export REDHANDS TOOLSETS=nmap,recon,web,fuzz,scan,vuln Network analysis export REDHANDS TOOLSETS=nmap,scan,tshark,tunnel Firmware + telecom research export REDHANDS TOOLSETS=barzakh,telecom,aegis All tools default when unset export REDHANDS TOOLSETS= - Binary allowlist — only known security tools can be executed - Argument validation — shell metacharacter rejection for external-tool arguments - Target validation and scope — explicit network targets checked against active engagement scope; not a complete network sandbox - Destructive-capability posture — tools that can destroy data or destroy a machine aegis offense start with deadman switch or wipe bytecode are opt-in, approval-gated, and emit loud warnings in every result; read the warnings in the Aegis-Shadow aegis-shadow-toolset-aegis and Telecom telecom-toolset-telecom sections before using the offense tools - Output size cap — 10MB per execution - Execution timeout — configurable per tool call - Rate limiting — token bucket prevents abuse - Authentication — API key or mTLS for remote transports - Audit logging — direct calls and workflow steps logged as JSONL; logging failures reported to stderr make build Build binary to bin/ make test Run tests with race detector make lint Run golangci-lint make docker Build Docker image make install Install binary to /usr/local/bin make install-tools Install security tools PROFILE=minimal|web|network|ad|k8s|uefi|telecom|aegis|sbom|recon|all make check-deps Check which tools are available Additional regression checks: go vet ./... python3 -m unittest discover -s scripts -p 'test .py' go run golang.org/x/vuln/cmd/govulncheck@v1.9.0 ./... The wrapper unit tests build argv strings but verify them only against a MockExecutor . When an upstream binary changes its CLI, nothing catches it — the tools/livecheck suite does. It runs the real binaries and asserts that the flags, subcommands and enum values the wrappers emit are still accepted help-text assertions plus safe dry-parses terminated by --help / --echo ; nothing scans a target or mutates state . make test-live equivalent: go test -tags=livebin ./tools/livecheck/... -run TestLiveFlagSurface Notes: - The suite is gated behind the livebin build tag, so go test ./... and the normal CI jobs are unaffected. - Binaries are discovered via PATH ; a binary that is not installed is reported as SKIP ... binary not on PATH , never as a failure. The suite is safe to run on any machine. - A check can also skip with a KNOWN CLI DRIFT / SKIPPED distro quirk message when the pinned or distro binary genuinely rejects the wrapper's argv e.g. Ubuntu ships core john without the jumbo-only --list , and a broken whatweb package . Those skips are deliberate, printed in every run, and must lead to a wrapper fix or a dependency bump — never to deleting the check. - In the Docker image which ships ~25 pinned binaries but no Go toolchain , compile the suite on the host and run it inside the container, where the binaries live: CGO ENABLED=0 go test -tags=livebin -c -o livecheck.test ./tools/livecheck/ docker run --rm --network none -v "$PWD/livecheck.test:/usr/local/bin/livecheck.test:ro" \ --entrypoint /usr/local/bin/livecheck.test redhands The live-binaries CI job instead installs a minimal binary set on ubuntu-latest apt plus the checksum-verified pinned releases via scripts/dependencies.py and runs go test -tags=livebin directly. - When you change a wrapper's argv, update the matching entry in tools/livecheck/table.go so drift detection stays meaningful. Tier 1 tools/livecheck proves binaries still accept the wrappers' argv. Tier 2 testdata/ golden fixtures proves output shapes . The tools/e2e suite Tier 3 proves real execution : it drives JSON-RPC tools/call and campaign/run requests into a fully wired in-process server — the same BinaryExecutor allowlist from binaries.Discover , the same middleware chain audit to a temp file, rate limits, engagement scope, approval gates, concurrency limiter , the same registry with builtin tool policies, and the same campaign recorder as cmd/redhands — and asserts on what the real binaries actually did. make test-e2e equivalent: go test -tags=livee2e ./tools/e2e/... Scenarios all skip cleanly when their binary is missing : - Barzakh purple-team loop offline, deterministic — barzakh corpus generates a corpus into a temp dir, barzakh scan scans one malicious sample scanner exit 1 = bootkit detected must surface as a result with the severity summary rendered , barzakh validate validates the corpus. - Campaign with real execution and record rules — a campaign/run whose steps execute the real corpus+scan tools through the middleware chain; the scan step's finding record rule persists the scanner's real findings array into the target database, asserted via the store. - nmap against a test-owned listener — the suite opens a 127.0.0.1:0 listener and runs nmap port scan connect scan; SYN needs root and nmap service detect against that exact port. - nuclei with a test-authored template — a minimal http -protocol template static word matcher on a body the local test server always serves, severity info is written to a temp file and passed via the templates parameter; nothing is downloaded. - telecom doctor — staticzero-defense --doctor --json : asserts the DoctorReport renders with a checks array and the ebpf object check passes the release binary embeds the eBPF object ; privilege failures are expected and fine. - telecom firmware analyze — a synthetic modem image documented fixture generator with a fixed seed for the padding analyzed with modem-firmware analyze ; asserts the vulnerability report, its findings strcpy, weak ciphers, debug interfaces , and the written report file. - kubedagger k8s discover against no cluster — only asserts the call returns a well-formed response without hanging the wrapper's empty-stdout handling is intentionally not pinned . HOME is redirected so the client cannot pick up a developer's real kubeconfig. Safety rules enforced by the suite: - The only network targets are 127.0.0.1 /localhost listeners the test itself owns; there is no network egress beyond the local binaries' own startup. - Everything deterministic: :0 listeners, fixed seeds for synthetic inputs, temp dirs, bounded polling no sleeps for the async audit log. - Gated behind the livee2e build tag, so go test ./... and the normal CI jobs are unaffected. - Executing tools are pre-approved in the harness config exactly like a reviewed REDHANDS APPROVED TOOLS setup, so the approval middleware itself is exercised not bypassed . The live-e2e CI job installs the scenario binaries nmap via apt; nuclei via the pinned go install ; barzakh, StaticZero, and KubeDagger binaries via the checksum-verified pinned releases in scripts/dependencies.json and runs go test -tags=livee2e ./tools/e2e/... . When you add a scenario that needs a new binary, add it to that job's install steps. Build and run docker build -t redhands . docker run -i redhands With Docker Compose local stdio mode; no published ports docker compose run --rm -i redhands With authentication Requires tls/server.crt, tls/server.key, and a strong REDHANDS API KEY docker compose --profile secure up redhands-secure The Docker image includes a subset of supported security tools check dependencies before use; some tools require additional installation or privileges : - apt/source : nmap, masscan, tshark, hashcat, john, nikto, whatweb - pip : impacket, certipy-ad - Go tools : subfinder, httpx, nuclei, ffuf, katana, gobuster, gau, waybackurls - Releases : chisel, ligolo-ng, kubedagger client, operator, server v0.5.0 , barzakh adversary, scanner, server v0.7.1 , staticzero defense, modem-firmware, sdr-bridge v0.5.0 , aegis-shadow-defense v0.2.0 MIT RedHands is provided for authorized security testing, education, and research purposes only. You are solely responsible for ensuring you have explicit, written permission before using this tool against any system, network, or application. Unauthorized access to computer systems is illegal and punishable under applicable law including the Computer Fraud and Abuse Act CFAA , Computer Misuse Act, and equivalent legislation worldwide. The authors and contributors of RedHands accept no liability for misuse or damage caused by this software. Use responsibly and ethically.