programServices.js

Go to the documentation of this file.

/**
 * @file Installed Programs Data Access Service
 * @description
 * Provides database query functions for retrieving installed software inventory from
 * remote agents. This module serves as the data access layer for the agent_programs table,
 * which stores Windows program lists collected by RMM agents via registry scanning or WMI queries.
 *
 * Key features:
 * - **Software inventory**: Retrieve complete list of installed programs per agent
 * - **Alphabetical sorting**: Programs returned in A-Z order by name
 * - **Bulk data**: Typically 50-500+ programs per Windows machine
 *
 * Typical use cases:
 * - Software asset management and license compliance
 * - Security audits for unauthorized software
 * - Patch management and version verification
 * - Software deployment validation
 * - IT inventory reporting
 *
 * Database schema:
 * - Table: `agent_programs`
 * - Key columns: agent_uuid, name, version, publisher, install_date, install_location
 * - Indexed on: agent_uuid for efficient lookups
 * - Data source: Windows Registry (HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall)
 * @module services/programServices
 * @requires ./db - PostgreSQL database pool
 * @note This file is in routes/ directory but should be in services/ directory (organizational issue)
 */
 
const pool = require('./db');
 
/**
 * Retrieves list of all installed programs/software for a specific agent.
 *
 * Returns complete software inventory collected from agent's Windows registry. Programs
 * are sorted alphabetically by name for easy browsing. Includes version numbers, publishers,
 * install dates, and installation paths when available. Typical Windows machine returns
 * 100-300 programs (applications, updates, drivers, system components).
 * @async
 * @function getInstalledPrograms
 * @param {string} agent_uuid - Unique identifier of the agent (UUID format)
 * @returns {Promise<object[]>} Array of installed program objects, empty array if no programs found
 * @property {string} agent_uuid - Agent UUID (matches input parameter)
 * @property {string} name - Program name (e.g., "Google Chrome", "Microsoft Office 365")
 * @property {string} version - Version string (e.g., "120.0.6099.71", "16.0.16827.20166")
 * @property {string} publisher - Software publisher/vendor (e.g., "Google LLC", "Microsoft Corporation")
 * @property {Date} install_date - Installation date (may be null for some programs)
 * @property {string} install_location - Installation directory path (e.g., "C:\\Program Files\\Google\\Chrome")
 * @property {string} uninstall_string - Command to uninstall program (registry UninstallString)
 * @example
 * const programs = await getInstalledPrograms('550e8400-e29b-41d4-a716-446655440000');
 * console.log(`Found ${programs.length} installed programs`);
 * programs.forEach(p => console.log(`${p.name} v${p.version} by ${p.publisher}`));
 * // Output:
 * // Found 187 installed programs
 * // 7-Zip v23.01 by Igor Pavlov
 * // Adobe Acrobat Reader DC v24.001.20604 by Adobe Inc.
 * // Google Chrome v120.0.6099.71 by Google LLC
 */
 
/**
 *
 * @param agent_uuid
 */
async function getInstalledPrograms(agent_uuid) {
  const res = await pool.query(
    `SELECT *
     FROM agent_programs
     WHERE agent_uuid = $1
     ORDER BY name ASC`,
    [agent_uuid]
  );
 
  return res.rows;
}
 
module.exports = { getInstalledPrograms };