get_agent_processes

Instructions

Implementation Reference

• src/tools/syscollector.ts:115-182 (registration)

  Registration of the get_agent_processes tool on the MCP server, including its name, description, schema (Zod), and handler function.

  server.tool(
    "get_agent_processes",
    "List running processes on a Wazuh agent",
    {
      agent_id: z
        .string()
        .describe("Agent identifier (e.g., '001')"),
      limit: z
        .number()
        .int()
        .min(1)
        .max(500)
        .default(25)
        .describe("Maximum number of processes to return (1-500)"),
      offset: z
        .number()
        .int()
        .min(0)
        .default(0)
        .describe("Pagination offset"),
      search: z
        .string()
        .optional()
        .describe("Filter processes by name or command"),
    },
    async ({ agent_id, limit, offset, search }) => {
      try {
        const params: Record<string, string | number> = { limit, offset };
        if (search) params.search = search;
  
        const response = await client.getAgentProcesses(agent_id, params);
        const data = response.data;
  
        const result = {
          agent_id,
          processes: data.affected_items.map((proc) => ({
            pid: proc.pid,
            name: proc.name,
            state: proc.state,
            ppid: proc.ppid,
            cmd: proc.cmd,
            argvs: proc.argvs,
            euser: proc.euser,
            vm_size: proc.vm_size,
          })),
          total: data.total_affected_items,
          limit,
          offset,
        };
  
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                error: error instanceof Error ? error.message : String(error),
              }),
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/tools/syscollector.ts:140-182 (handler)

  Handler function for get_agent_processes: calls client.getAgentProcesses(), maps affected_items to a simplified process list, and returns formatted JSON response.

    async ({ agent_id, limit, offset, search }) => {
      try {
        const params: Record<string, string | number> = { limit, offset };
        if (search) params.search = search;
  
        const response = await client.getAgentProcesses(agent_id, params);
        const data = response.data;
  
        const result = {
          agent_id,
          processes: data.affected_items.map((proc) => ({
            pid: proc.pid,
            name: proc.name,
            state: proc.state,
            ppid: proc.ppid,
            cmd: proc.cmd,
            argvs: proc.argvs,
            euser: proc.euser,
            vm_size: proc.vm_size,
          })),
          total: data.total_affected_items,
          limit,
          offset,
        };
  
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                error: error instanceof Error ? error.message : String(error),
              }),
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/tools/syscollector.ts:118-139 (schema)

  Input schema for get_agent_processes: agent_id (string, required), limit (int 1-500, default 25), offset (int, default 0), and optional search (string).

  {
    agent_id: z
      .string()
      .describe("Agent identifier (e.g., '001')"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(500)
      .default(25)
      .describe("Maximum number of processes to return (1-500)"),
    offset: z
      .number()
      .int()
      .min(0)
      .default(0)
      .describe("Pagination offset"),
    search: z
      .string()
      .optional()
      .describe("Filter processes by name or command"),
  },

• src/client.ts:317-322 (helper)

  Client helper method getAgentProcesses that makes an HTTP GET request to /syscollector/{agentId}/processes on the Wazuh API.

  async getAgentProcesses(
    agentId: string,
    params: Record<string, string | number> = {}
  ): Promise<WazuhApiResponse<WazuhPaginatedData<WazuhProcess>>> {
    return this.get(`/syscollector/${agentId}/processes`, params);
  }

• src/types.ts:214-243 (schema)

  TypeScript interface WazuhProcess defining the full shape of a process object returned by the Wazuh API.

  export interface WazuhProcess {
    pid?: number;
    name?: string;
    state?: string;
    ppid?: number;
    utime?: number;
    stime?: number;
    cmd?: string;
    argvs?: string[];
    euser?: string;
    ruser?: string;
    suser?: string;
    egroup?: string;
    rgroup?: string;
    sgroup?: string;
    fgroup?: string;
    priority?: number;
    nice?: number;
    size?: number;
    vm_size?: number;
    resident?: number;
    share?: number;
    start_time?: number;
    pgrp?: number;
    session?: number;
    nlwp?: number;
    tgid?: number;
    tty?: number;
    processor?: number;
  }