get_agent_packages

Instructions

Implementation Reference

• src/tools/syscollector.ts:46-113 (handler)

  The handler function for the 'get_agent_packages' tool. Calls client.getAgentPackages(), processes the response, and returns formatted package data (name, version, architecture, description, format, vendor, install_time, size). Handles errors and returns them as error responses.

  server.tool(
    "get_agent_packages",
    "List software packages installed 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 packages to return (1-500)"),
      offset: z
        .number()
        .int()
        .min(0)
        .default(0)
        .describe("Pagination offset"),
      search: z
        .string()
        .optional()
        .describe("Filter packages by name"),
    },
    async ({ agent_id, limit, offset, search }) => {
      try {
        const params: Record<string, string | number> = { limit, offset };
        if (search) params.search = search;
  
        const response = await client.getAgentPackages(agent_id, params);
        const data = response.data;
  
        const result = {
          agent_id,
          packages: data.affected_items.map((pkg) => ({
            name: pkg.name,
            version: pkg.version,
            architecture: pkg.architecture,
            description: pkg.description,
            format: pkg.format,
            vendor: pkg.vendor,
            install_time: pkg.install_time,
            size: pkg.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:49-70 (schema)

  Input schema (Zod validations) for the 'get_agent_packages' tool: agent_id (string), limit (int 1-500, default 25), offset (int min 0, default 0), search (optional 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 packages to return (1-500)"),
    offset: z
      .number()
      .int()
      .min(0)
      .default(0)
      .describe("Pagination offset"),
    search: z
      .string()
      .optional()
      .describe("Filter packages by name"),
  },

• src/index.ts:9-12 (registration)

  Registration: The tool is registered via the registerSyscollectorTools function, called at line 45 in src/index.ts, which imports and invokes it to register all syscollector tools.

  import { registerDecoderTools } from "./tools/decoders.js";
  import { registerVersionTools } from "./tools/version.js";
  import { registerScaTools } from "./tools/sca.js";
  import { registerSyscollectorTools } from "./tools/syscollector.js";

• src/client.ts:310-315 (helper)

  Helper/client method: getAgentPackages() in the WazuhClient class. Makes an API GET request to /syscollector/{agentId}/packages with optional query params. Returns typed response with WazuhPackage data.

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

• src/types.ts:198-212 (schema)

  Type definition for WazuhPackage, used as the response shape for package data returned by the API.

  export interface WazuhPackage {
    name: string;
    version?: string;
    architecture?: string;
    description?: string;
    format?: string;
    vendor?: string;
    install_time?: string;
    location?: string;
    size?: number;
    priority?: string;
    source?: string;
    section?: string;
    multiarch?: string;
  }