A self-contained skill package that allows any AI agent (ZCode/Claude Code/Codex/OpenCode/MCP client) to “dispatch” commands to your own Kali machine for execution and retrieve the output. Windows handles orchestration only; the attack tools always stay on Kali. The first run includes a built-in health-check script that tells you exactly which repair commands to run for anything that’s missing.
Three pain points anyone using AI for penetration testing runs into
1. The dilemma of “where should the tool run?” Let Claude/Codex run scans directly on your work machine—and the antivirus starts complaining, company compliance rules may prohibit it, and nmap/Python attack libraries have all kinds of compatibility issues on Windows. Everyone knows the answer should be “run it in Kali,” but every time you have to: switch to a Kali terminal → type the command manually → copy the output back to the AI → manually organize the evidence. The AI is just a chat box; you’re still doing the hands-on work.
2. Agents writing their own SSH commands run into more pitfalls than you’d think I ran this workflow through an agent dozens of times and recorded the actual failures: zsh’s glob characters caused every for loop written by the agent to fail with no matches found; PowerShell passing commands to SSH stripped quotes twice, resulting in parse error near ')'; long-running commands exceeded two minutes, the paramiko channel timed out, and the results were lost—the run was for nothing. All these pitfalls are documented in the package’s pitfalls.md, which the agent reads the first time it triggers the skill—that’s the difference between this and hand-crafting an SSH command yourself.
3. Distributing it to a team when everyone has a different IP Ten people, ten Kali machines. This package’s solution is three-tier configuration: command-line arguments > environment variables (KALI_HOST/KALI_USER/KALI_PASSWORD) > configuration file. The zip contains no personal configuration, so you can use it immediately after extracting it; when switching machines, you only need to change the environment variables.
How it works
You (to any agent): “Run a top-100 port scan against 192.168.x.x on Kali”
↓ skill triggered; first-run health check is mandatory (doctor.py: Python → paramiko → configuration → TCP → SSH authentication)
↓ agent constructs the command and dispatches it to your Kali machine via kali_exec.py (paramiko)
↓ stdout/stderr, elapsed time, and exit code are collected in structured form (--json-out can save evidence to disk)
A few particularly well-thought-out design points:
- The doctor health check is mandatory on the first call; tasks cannot run when the status is NOT READY, and the repair commands can be copied directly—saving the support burden of “it still isn’t set up after half a day” once you’ve sent it to a colleague
- Long-running task mode: full-port scans use
nohupto write to a remote file and retrieve the results by polling, so results aren’t lost due to an SSH timeout - File transfers use a base64 command-line channel, without relying on an SFTP wrapper
- Cross-agent support: ZCode/Claude Code trigger it automatically through SKILL.md; with Codex/OpenCode, paste a section into AGENTS.md; clients without a skill mechanism can use the 30-line MCP server included in the package to wrap it as a tool
https://github.com/ffdba/kali-remote-exec