/mks

name: mks
description: MKS (Metasploit-Kali Server) tool preference guide. Mount in Phase 0/1 alongside the primary skill. Provides URL resolution, REST endpoint patterns, response parsing, error handling, and fallback rules for all MKS-backed Kali tools.

MKS — Kali Tool Server Preference

Step 0: Resolve MKS URL

Run once at phase start and store as `MKS_URL`:

MKS_URL=$(cat .pentest-mks.json 2>/dev/null | jq -r '.url // empty')

• **Non-empty**: MKS is active — use the REST endpoints below instead of local Bash tool invocations.
• **Empty**: MKS not configured — skip all MKS calls and use local Bash commands as documented in the agent workflow.

Step 0.5: Capability probe (do this once before the first tool call)

Some server builds have a defect where the structured `/api/tools/*` endpoints (and `/health`) crash when the command is constructed as an argv **list** — every structured tool call returns an error like `CommandExecutor expects a string, but got list`, and the tools appear unusable even though they are installed. The generic `POST /api/command` endpoint (raw command string) is unaffected.

Probe once and set `MKS_TOOLS_MODE`:

PROBE=$(curl -s -m 20 -X POST "$MKS_URL/api/tools/nmap" \
  -H "Content-Type: application/json" \
  -d "{\"target\":\"127.0.0.1\",\"scan_type\":\"-sn\",\"additional_args\":\"-Pn\"}")
if echo "$PROBE" | grep -qiE 'got list|expects a string|TypeError|Internal Server Error|got a list'; then
  MKS_TOOLS_MODE="command"   # structured endpoints are broken on this server → route via /api/command
else
  MKS_TOOLS_MODE="structured" # structured endpoints work → use /api/tools/* as documented
fi

• `MKS_TOOLS_MODE="structured"` → use the `/api/tools/{tool}` endpoints in the Endpoints section.
• `MKS_TOOLS_MODE="command"` → use the **/api/command fallback** (see that section) for every tool.

Log the result: `{"action":"mks-capability-probe","tools_mode":"<structured|command>"}`.

> **Security note for `command` mode:** `/api/command` runs the string in a shell (`shell=True`-style), > so it is injection-prone if any target/argument is attacker-controlled. In a pentest the target and > args are operator-controlled against the operator's own Kali host, so this is an acceptable bridge — > but never interpolate untrusted scan *output* back into an `/api/command` string. The structured > endpoints are the safer design; prefer them whenever the probe says they work.

Response Contract

Every MKS tool endpoint returns JSON:

{ "output": "<raw tool stdout>", "error": "<stderr or empty string>" }

**Parsing pattern** (apply after every MKS curl call):

RESPONSE=$(curl -s -m TIMEOUT -X POST "$MKS_URL/api/tools/TOOL" \
  -H "Content-Type: application/json" \
  -d 'PAYLOAD')
RESULT=$(echo "$RESPONSE" | jq -r '.output // empty')
ERR=$(echo "$RESPONSE" | jq -r '.error // empty')

Replace `TIMEOUT`, `TOOL`, and `PAYLOAD` with values from the endpoint sections below.

Error Handling — layered fallback

If a structured `/api/tools/{tool}` call fails — `RESULT` empty, OR the response contains `got list` / `expects a string` / `TypeError` / `Internal Server Error` (the list-vs-string defect):

1. **First fall back to `/api/command`** (the raw-string endpoint — see the next section), not straight to local Bash. This recovers the tool when only the structured endpoint is broken. Log:

   {"timestamp":"...","agent":"<agent-name>","action":"mks-fallback","tool":"<tool-name>","from":"structured","to":"command","reason":"<empty-response|type-error>"}

2. **Only if `/api/command` also fails** (or `MKS_URL` is empty), fall back to the local Bash equivalent documented in the agent workflow. Log `"to":"local-bash"`. 3. Continue the engagement — a failed MKS call is non-fatal.

If Step 0.5 already set `MKS_TOOLS_MODE="command"`, skip the structured call entirely and go straight to `/api/command` for every tool.

/api/command fallback (raw-string endpoint)

The generic endpoint takes a full command string and is unaffected by the list-vs-string defect.

**Request / response shape** (different from `/api/tools/*`):

RESPONSE=$(curl -s -m TIMEOUT -X POST "$MKS_URL/api/command" \
  -H "Content-Type: application/json" \
  -d "{\"command\":\"<full command string>\"}")
RESULT=$(echo "$RESPONSE" | jq -r '.stdout // empty')
RC=$(echo "$RESPONSE" | jq -r '.return_code // empty')   # 0 = success; .success is also returned

**Equivalent command string per tool** (build the same invocation the structured endpoint would run):

| Tool | `/api/command` string | |------|-----------------------| | nmap | `nmap <scan_type> <ports?> <additional_args> <target>` (e.g. `nmap -sS -p- --min-rate 10000 -T4 -Pn $TARGET`) | | gobuster | `gobuster dir -u $TARGET -w /usr/share/wordlists/dirb/common.txt -b 404` | | dirb | `dirb $TARGET /usr/share/wordlists/dirb/common.txt` | | nikto | `nikto -h $TARGET` | | sqlmap | `sqlmap -u "$TARGET_URL" --batch --level=3 --risk=2` (add `--data="$POST_DATA"` for POST) | | hydra | `hydra -L <user_file> -P /usr/share/wordlists/rockyou.txt $TARGET $SERVICE` | | john | `john --wordlist=/usr/share/wordlists/rockyou.txt --format=$HASH_FORMAT $HASH_FILE` | | metasploit | `msfconsole -q -x "use $MODULE_PATH; set RHOSTS $TARGET; set RPORT $PORT; run; exit"` |

Quote `$TARGET_URL` and any value containing shell metacharacters. Re-read the Step 0.5 security note before interpolating anything into these strings.

**Verifying a tool is installed** (use this instead of trusting `/health`):

WHICH=$(curl -s -m 10 -X POST "$MKS_URL/api/command" -H "Content-Type: application/json" \
  -d "{\"command\":\"which <tool>\"}")
echo "$WHICH" | jq -r '.stdout // empty'   # non-empty path = installed

Endpoints

nmap

**Used by:** domain-assessment, cve-tester

SYN scan (full port, fast):

curl -s -m 120 -X POST "$MKS_URL/api/tools/nmap" \
  -H "Content-Type: application/json" \
  -d