Kastell

Instructions

Implementation Reference

• src/mcp/tools/serverEvidence.ts:44-104 (handler)

  The main handler function `handleServerEvidence` which executes the forensic evidence collection logic by invoking `collectEvidence` core function and returning a formatted MCP response.

  export async function handleServerEvidence(params: {
    server?: string;
    name?: string;
    lines?: number;
    no_docker?: boolean;
    no_sysinfo?: boolean;
    force?: boolean;
  }): Promise<McpResponse> {
    try {
      const servers = getServers();
      if (servers.length === 0) {
        return mcpError("No servers found");
      }
  
      const server = resolveServerForMcp(params, servers);
      if (!server) {
        if (params.server) {
          return mcpError(
            `Server not found: ${params.server}`,
            `Available servers: ${servers.map((s) => s.name).join(", ")}`,
          );
        }
        return mcpError(
          "Multiple servers found. Specify which server to collect evidence from.",
          `Available: ${servers.map((s) => s.name).join(", ")}`,
        );
      }
  
      const platform = server.platform ?? server.mode ?? "bare";
  
      const result = await collectEvidence(server.name, server.ip, platform, {
        name: params.name,
        lines: params.lines ?? 500,
        noDocker: params.no_docker ?? false,
        noSysinfo: params.no_sysinfo ?? false,
        force: params.force ?? false,
        json: false,
        quiet: true,
      });
  
      if (!result.success || !result.data) {
        return mcpError(result.error ?? "Evidence collection failed");
      }
  
      const { evidenceDir, serverName, serverIp, totalFiles, skippedFiles, collectedAt, manifestPath } =
        result.data;
  
      return mcpSuccess({
        evidenceDir,
        serverName,
        serverIp,
        platform,
        collectedAt,
        totalFiles,
        skippedFiles,
        manifestPath,
      });
    } catch (error: unknown) {
      return mcpError(getErrorMessage(error));
    }
  }

• src/mcp/tools/serverEvidence.ts:17-42 (schema)

  The Zod schema definition `serverEvidenceSchema` defining the input parameters for the tool.

  export const serverEvidenceSchema = {
    server: z
      .string()
      .optional()
      .describe("Server name or IP. Auto-selected if only one server exists."),
    name: z
      .string()
      .optional()
      .describe("Label for the evidence directory (e.g. 'pre-incident')."),
    lines: z
      .number()
      .default(500)
      .describe("Number of log lines to collect per file (default: 500)."),
    no_docker: z
      .boolean()
      .default(false)
      .describe("Skip Docker data collection."),
    no_sysinfo: z
      .boolean()
      .default(false)
      .describe("Skip system information collection."),
    force: z
      .boolean()
      .default(false)
      .describe("Overwrite existing evidence directory."),
  };

• src/mcp/server.ts:176-189 (registration)

  Registration of the `server_evidence` tool in the MCP server instance, mapping the name, schema, and handler.

  server.registerTool("server_evidence", {
    description:
      "Collect forensic evidence package from a server. Gathers firewall rules, auth.log, listening ports, system logs, and optionally Docker info. Writes to ~/.kastell/evidence/{server}/{date}/. Returns manifest with SHA256 checksums per file.",
    inputSchema: serverEvidenceSchema,
    annotations: {
      title: "Evidence Collection",
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
      openWorldHint: true,
    },
  }, async (params) => {
    return handleServerEvidence(params);
  });