kali-mcp

Instructions

Implementation Reference

• src/docker-manager.ts:114-196 (handler)

  The implementation of executeCommand that interacts with the Docker API to run shell commands in the container.

  async executeCommand(
    command: string,
    timeout: number = 300
  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
    const container = await this.getContainer();
    if (!container) {
      throw new Error(
        "Kali container is not running. Use container_start first."
      );
    }
  
    const info = await container.inspect();
    if (!info.State.Running) {
      throw new Error(
        "Kali container is not running. Use container_start first."
      );
    }
  
    const exec = await container.exec({
      Cmd: ["/bin/bash", "-c", command],
      AttachStdout: true,
      AttachStderr: true,
    });
  
    const stream = await exec.start({ hijack: true, stdin: false });
  
    return new Promise((resolve, reject) => {
      let stdout = "";
      let stderr = "";
  
      const timer = setTimeout(() => {
        stream.destroy();
        resolve({
          stdout,
          stderr: stderr + "\n[Command timed out after " + timeout + "s]",
          exitCode: -1,
        });
      }, timeout * 1000);
  
      // Docker multiplexes stdout/stderr in the stream
      // Each frame: [type(1byte), 0, 0, size(4bytes big-endian), payload]
      let buffer = Buffer.alloc(0);
  
      stream.on("data", (chunk: Buffer) => {
        buffer = Buffer.concat([buffer, chunk]);
  
        while (buffer.length >= 8) {
          const type = buffer[0];
          const size = buffer.readUInt32BE(4);
  
          if (buffer.length < 8 + size) break;
  
          const payload = buffer.subarray(8, 8 + size).toString("utf-8");
          buffer = buffer.subarray(8 + size);
  
          if (type === 1) {
            stdout += payload;
          } else if (type === 2) {
            stderr += payload;
          }
        }
      });
  
      stream.on("end", async () => {
        clearTimeout(timer);
        try {
          const inspectResult = await exec.inspect();
          resolve({
            stdout,
            stderr,
            exitCode: inspectResult.ExitCode ?? 0,
          });
        } catch {
          resolve({ stdout, stderr, exitCode: 0 });
        }
      });
  
      stream.on("error", (err: Error) => {
        clearTimeout(timer);
        reject(err);
      });
    });
  }

• src/tools/execute.ts:9-51 (registration)

  Registration and handling of the execute_command tool.

  server.tool(
    "execute_command",
    "Execute a shell command inside the Kali Linux container. Use this to run security tools like nmap, sqlmap, hydra, nikto, gobuster, john, hashcat, dirb, enum4linux, and any other installed tool.",
    {
      command: z.string().describe("Shell command to execute inside the Kali container"),
      timeout: z
        .number()
        .optional()
        .describe("Timeout in seconds (default: 300)"),
    },
    async ({ command, timeout }) => {
      try {
        const result = await docker.executeCommand(command, timeout ?? 300);
  
        let output = "";
        if (result.stdout) {
          output += result.stdout;
        }
        if (result.stderr) {
          output += (output ? "\n--- stderr ---\n" : "") + result.stderr;
        }
        if (!output) {
          output = "(no output)";
        }
        output += `\n\n[exit code: ${result.exitCode}]`;
  
        return {
          content: [{ type: "text", text: output }],
          isError: result.exitCode !== 0,
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text",
              text: `Failed to execute command: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    }
  );