Pentest MCP

Implementation Reference

• src/index.ts:515-550 (handler)

  Core implementation of the gobuster tool handler. Spawns the 'gobuster' process with sanitized options, captures stdout/stderr, parses lines for successful HTTP status codes (200,301,302) to extract discovered paths, logs results in professional mode, and returns full output along with found paths.

  async function runGobuster(target: string, rawOptions: string[] = []): Promise<{ fullOutput: string; foundPaths: string[] }> {
    console.error(`Executing Gobuster: target=${target}, raw_options=${rawOptions.join(' ')}`);
    if (!target.startsWith('http://') && !target.startsWith('https://')) {
      throw new Error("Target must be a valid URL starting with http:// or https://");
    }
    let options: string[];
    try {
      options = sanitizeOptions(rawOptions);
    } catch (error: any) {
      throw error;
    }
  
    let fullOutput = "";
    let foundPaths: string[] = [];
    try {
      const baseArgs = ['dir', '-u', target, ...options];
      fullOutput += `--- Directory Enumeration ---\nExecuting: gobuster ${baseArgs.join(' ')}\n`;
      try {
        const result = await runSpawnCommand('gobuster', baseArgs);
        fullOutput += `Exit Code: ${result.code}\nStdout:\n${result.stdout}\nStderr:\n${result.stderr}\n`;
        foundPaths = result.stdout.split('\n').filter(line => line.includes('Status:') && (line.includes('200') || line.includes('301') || line.includes('302'))).map(line => line.match(/^\s*(\/[^\s]*)/)?.[1] || line);
      } catch (error: any) {
        fullOutput += `Gobuster command failed to execute: ${error.message}\n`;
      }
      if (currentUserSession.mode === UserMode.PROFESSIONAL) {
        await logMessage(`Ran Gobuster against ${target}.\nOptions: ${options.join(' ')}\nFound: ${foundPaths.length} paths.`);
      }
      return { fullOutput, foundPaths };
    } catch (error: any) {
      console.error("Fatal error setting up Gobuster execution:", error);
      if (currentUserSession.mode === UserMode.PROFESSIONAL) {
        await logMessage(`Gobuster FAILED fatally before execution.\nTarget: ${target}\nOptions: ${options.join(' ')}\nError: ${error.message}`);
      }
      throw new Error(`Gobuster setup failed fatally: ${error.message}`);
    }
  }

• src/index.ts:1090-1107 (schema)

  Zod schema defining the input validation and descriptions for the gobuster tool parameters, including required target URL and wordlist, and various optional gobuster-specific options.

  const gobusterToolSchema = z.object({
    target: z.string().url().describe("Target URL"),
    wordlist: z.string().describe("Path to wordlist"),
    extensions: z.string().optional().describe("File extensions (comma-separated)"),
    threads: z.number().int().positive().optional().describe("Number of threads"),
    statusCodes: z.string().optional().describe("Valid status codes (comma-separated)"),
    useragent: z.string().optional().describe("User-Agent string"),
    timeout: z.string().optional().describe("Timeout for requests"),
    basicAuth: z.string().optional().describe("Basic authentication credentials (username:password)"),
    cookie: z.string().optional().describe("Cookie to include in requests"),
    excludeLength: z.array(z.number()).optional().describe("Exclude paths of specific lengths"),
    followRedirect: z.boolean().optional().describe("Follow HTTP redirects"),
    noTLSValidation: z.boolean().optional().describe("Skip TLS certificate validation"),
    rawOptions: z.array(z.string()).optional().describe("Raw gobuster options")
  }).describe(
    "Enumerate hidden directories and files on a web server. Run this after confirming the target hosts a web service. " +
    "Provide a wordlist and optional extensions. Example: `{\"target\":\"http://example.com\", \"wordlist\":\"/usr/share/wordlists/common.txt\"}`"
  );

• src/index.ts:1108-1139 (registration)

  MCP tool registration using server.tool('gobuster'), which constructs gobuster command-line options from input parameters, calls the runGobuster handler, formats response differently for student/professional modes, and handles errors.

  server.tool("gobuster", gobusterToolSchema.shape, async (args /*: z.infer<typeof gobusterToolSchema> */ /*, extra */) => {
    const { target, wordlist, extensions, threads, statusCodes, useragent, timeout, basicAuth, cookie, excludeLength, followRedirect, noTLSValidation, rawOptions } = args;
    console.error(`Received gobuster request:`, args);
    try {
      const constructedOptions: string[] = [];
      constructedOptions.push('-w', wordlist);
      if (extensions) constructedOptions.push('-x', extensions);
      if (threads) constructedOptions.push('-t', threads.toString());
      if (statusCodes) constructedOptions.push('-s', statusCodes);
      if (useragent) constructedOptions.push('-a', useragent);
      if (timeout) constructedOptions.push('--timeout', timeout);
      if (basicAuth) { const [u,p] = basicAuth.split(':'); constructedOptions.push('-U', u, '-P', p); }
      if (cookie) constructedOptions.push('-c', cookie);
      if (excludeLength) constructedOptions.push('-l', excludeLength.join(','));
      if (followRedirect) constructedOptions.push('-r');
      if (noTLSValidation) constructedOptions.push('-k');
      if (rawOptions) constructedOptions.push(...rawOptions);
  
      const { fullOutput, foundPaths } = await runGobuster(target, constructedOptions);
      const responseContent: any[] = [];
      if (currentUserSession.mode === UserMode.STUDENT) {
        responseContent.push({ type: "text", text: `Found ${foundPaths.length} paths/files at ${target}:\n\n${foundPaths.join('\n')}` });
        if (foundPaths.length > 0) responseContent.push({ type: "text", text: "\n**Next Steps:** ..." });
        else responseContent.push({ type: "text", text: "\n**No paths found...**" });
      } else {
        responseContent.push({ type: "text", text: `Found ${foundPaths.length} paths at ${target}` });
        if (foundPaths.length > 0) responseContent.push({ type: "text", text: "\n**Paths:**\n" + foundPaths.join('\n') });
        responseContent.push({ type: "text", text: "\n**Full Output:**\n" + fullOutput });
      }
      return { content: responseContent };
    } catch (error: any) { return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true }; }
  });

• src/index.ts:273-291 (helper)

  Helper function to spawn external commands (like gobuster) using child_process.spawn, capture stdout/stderr, handle errors, and return results. Used by gobuster, nikto, john, hashcat handlers.

  async function runSpawnCommand(command: string, args: string[]): Promise<{ stdout: string; stderr: string; code: number | null }> {
      return new Promise((resolve, reject) => {
          console.error(`Attempting to spawn: ${command} ${args.join(' ')}`); // Added for debugging
          const process = spawn(command, args);
          let stdout = '';
          let stderr = '';
          process.stdout.on('data', (data) => { stdout += data.toString(); });
          process.stderr.on('data', (data) => { stderr += data.toString(); });
          process.on('error', (error) => {
              // Explicitly catch spawn errors (e.g., command not found)
              console.error(`Spawn error for command "${command}": ${error.message}`);
              reject(new Error(`Failed to start command "${command}": ${error.message}`));
          });
          process.on('close', (code) => {
              console.error(`Command "${command}" exited with code ${code}`); // Added for debugging
              resolve({ stdout, stderr, code });
          });
      });
  }

• src/index.ts:258-270 (helper)

  Helper function to sanitize and validate command-line options passed to tools like gobuster, preventing injection of unsafe arguments via regex matching safe patterns.

  const SAFE_OPTION_REGEX = /^(?:-[a-zA-Z0-9]+|--[a-zA-Z0-9\-]+(?:=[^;&|`$\s\(\)\<\>\\]+)?|[^;&|`$\s\(\)\<\>\\]+)$/;
  
  function sanitizeOptions(options: string[]): string[] {
    const sanitized: string[] = [];
    for (const opt of options) {
      if (SAFE_OPTION_REGEX.test(opt)) {
        sanitized.push(opt);
      } else {
        throw new Error(`Invalid or potentially unsafe option detected: "${opt}". Only standard flags and simple arguments are allowed.`);
      }
    }
    return sanitized;
  }