5.12.2

Author: lbr38

documentation/docs/reference/api.md

@@ -37,6 +37,16 @@ Once generated, copy the key and keep it safe. This key is used to authenticate
 
     ``<SNAPSHOT_ID>`` can be retrieved from the URL when you browse a snapshot from the repositories list or from the API when you list snapshots of a repository.
 
+  ### Global query parameters
+
+  - ``normalize`` (optional): when set on a request, all keys in the JSON response are converted to lowercase recursively.
+
+  Example:
+
+  ```bash
+  curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/?normalize"
+  ```
+
 
 ### Source repositories
 
@@ -396,8 +406,8 @@ Once generated, copy the key and keep it safe. This key is used to authenticate
     <tr>
       <td>/hosts/package/<code>&lt;PACKAGE&gt;</code>/<code>&lt;VERSION?&gt;</code><br><code>GET</code></td>
       <td><code>&lt;APIKEY&gt;</code></td>
-      <td><code>package</code> (required, in URL)<br><code>version</code> (optional, in URL)<br><code>strict</code> (optional, query parameter)<br><code>strict-name</code> (optional, query parameter)<br><code>strict-version</code> (optional, query parameter)</td>
-      <td>List hosts that have the specified package installed, optionally filtered by version. By default, package name and version matching can be non-strict. Use <code>strict</code> to enable strict matching for both package name and version, or use <code>strict-name</code> and <code>strict-version</code> independently.</td>
+      <td><code>package</code> (required, in URL)<br><code>version</code> (optional, in URL)<br><code>strict</code> (optional, query parameter)<br><code>strict-name</code> (optional, query parameter)<br><code>strict-version</code> (optional, query parameter)<br><code>absent</code> (optional, query parameter)</td>
+      <td>List hosts that have the specified package installed, optionally filtered by version. By default, package name and version matching can be non-strict. Use <code>strict</code> to enable strict matching for both package name and version, or use <code>strict-name</code> and <code>strict-version</code> independently. Set <code>absent</code> to list hosts where the package (and optional version) is not installed.</td>
       <td markdown="block">
         ```bash
         curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/package/nginx
@@ -418,28 +428,44 @@ Once generated, copy the key and keep it safe. This key is used to authenticate
         ```bash
         curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/package/nginx/1.24.0-1?strict-version"
         ```
+        Return hosts where package is absent:
+        ```bash
+        curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/package/nginx?absent"
+        ```
+        Return hosts where exact package version is absent:
+        ```bash
+        curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/package/nginx/1.24.0-1?absent&strict"
+        ```
       </td>
     </tr>
     <tr>
-      <td>/hosts/uptodate<br><code>GET</code></td>
+      <td>/hosts/uptodate<br>(alias: /hosts/compliant)<br><code>GET</code></td>
       <td><code>&lt;APIKEY&gt;</code></td>
-      <td></td>
-      <td>List all up-to-date hosts (hosts with no or few available updates based on configured threshold)</td>
+      <td><code>packages</code> (optional, query parameter)</td>
+      <td>List all up-to-date (compliant) hosts, i.e. hosts whose pending updates count is below the configured threshold and whose latest update is within the configured threshold (in days). Set the <code>packages</code> query parameter to also include the list of available updates for each host.</td>
       <td markdown="block">
         ```bash
         curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/uptodate
         ```
+        Including the list of available updates:
+        ```bash
+        curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/uptodate?packages"
+        ```
       </td>
     </tr>
     <tr>
-      <td>/hosts/outdated<br><code>GET</code></td>
+      <td>/hosts/outdated<br>(alias: /hosts/non-compliant)<br><code>GET</code></td>
       <td><code>&lt;APIKEY&gt;</code></td>
-      <td></td>
-      <td>List all outdated hosts (hosts with available updates exceeding the configured threshold)</td>
+      <td><code>packages</code> (optional, query parameter)</td>
+      <td>List all outdated (non-compliant) hosts, i.e. hosts whose pending updates count is greater than or equal to the configured threshold, or whose latest update is older than the configured threshold (in days). Set the <code>packages</code> query parameter to also include the list of available updates for each host.</td>
       <td markdown="block">
         ```bash
         curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" https://repomanager.mydomain.net/api/v2/hosts/outdated
         ```
+        Including the list of available updates:
+        ```bash
+        curl --fail-with-body -L -s -X GET -H "Authorization: Bearer <APIKEY>" "https://repomanager.mydomain.net/api/v2/hosts/outdated?packages"
+        ```
       </td>
     </tr>
   </tbody>
@@ -574,11 +600,11 @@ Mainly used by the `linupdate` agent, these endpoints allow to register a host t
     <tr>
       <td>/host/status<br><code>PUT</code></td>
       <td><code>&lt;HOST_ID&gt;</code> and <code>&lt;HOST_TOKEN&gt;</code></td>
-      <td><code>hostname</code> (optional)<br><code>os</code> (optional)<br><code>os_version</code> (optional)<br><code>os_family</code> (optional)<br><code>type</code> (=virtualization type) (optional)<br><code>kernel</code> (optional)<br><code>arch</code> (optional)<br><code>profile</code> (optional)<br><code>env</code> (optional)<br><code>agent_status</code> (optional)<br><code>linupdate_version</code> (optional)<br><code>reboot_required</code> (optional)</td>
+      <td><code>hostname</code> (optional)<br><code>os</code> (optional)<br><code>os_version</code> (optional)<br><code>os_family</code> (optional)<br><code>type</code> (=virtualization type) (optional)<br><code>kernel</code> (optional)<br><code>arch</code> (optional)<br><code>profile</code> (optional)<br><code>env</code> (optional)<br><code>agent_status</code> (optional)<br><code>agent_version</code> (optional)<br><code>reboot_required</code> (optional)</td>
       <td>Send host general information to Repomanager</td>
       <td markdown="block">
         ```bash
-        curl --fail-with-body --post301 -L -s -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '{"hostname":"myfqdn.localhost","os":"ubuntu","os_version":"22.04","os_family":"Debian","type":"Bare metal","kernel":"5.15.0-89-generic","arch":"x86_64","profile":"PC","env":"prod","agent_status":"running","linupdate_version":"2.2.2","reboot_required":"false"}' https://repomanager.mydomain.net/api/v2/host/status
+        curl --fail-with-body --post301 -L -s -X PUT -H "Authorization: Host <HOST_ID>:<HOST_TOKEN>" -H "Content-Type: application/json" -d '{"hostname":"myfqdn.localhost","os":"ubuntu","os_version":"22.04","os_family":"Debian","type":"Bare metal","kernel":"5.15.0-89-generic","arch":"x86_64","profile":"PC","env":"prod","agent_status":"running","agent_version":"2.2.2","reboot_required":"false"}' https://repomanager.mydomain.net/api/v2/host/status
         ```
       </td>
     </tr>

www/controllers/Api/Api.php

@@ -177,6 +177,12 @@ private static function returnSuccess(array $results): void
         // TODO: remove 'return' key in favor of 'rc' key in future major release
         $results['return'] = $results['rc'];
         $results['note'] = "The 'return' key is deprecated and will be removed in a future major release (replaced by 'rc' key)";
+
+        // If the "normalize" query parameter is set, convert all result keys to lowercase
+        if (isset($_GET['normalize'])) {
+            $results = Serializer::normalize($results);
+        }
+
         http_response_code((int) $results['rc']);
         echo json_encode($results);
         exit;

www/controllers/Api/Host/Host.php

@@ -247,9 +247,16 @@ public function execute(): array
                     }
 
                     // If linupdate version has been specified then update it in database
-                    if (!empty($this->data['linupdate_version'])) {
+                    if (!empty($this->data['linupdate_version']) or !empty($this->data['agent_version'])) {
+                        // TODO: temporary
+                        # Use agent_version later
+                        if (!empty($this->data['linupdate_version'])) {
+                            $version = $this->data['linupdate_version'];
+                        } else {
+                            $version = $this->data['agent_version'];
+                        }
                         try {
-                            $hostUpdateController->updateLinupdateVersion($this->hostId, $this->data['linupdate_version']);
+                            $hostUpdateController->updateAgentVersion($this->hostId, $version);
                             $message[] = "Linupdate version updated successfully.";
                         } catch (Exception $e) {
                             throw new Exception('Linupdate version update has failed.');

www/controllers/Api/Hosts/Hosts.php

@@ -99,27 +99,31 @@ public function execute(): array
                     $strictVersion = true;
                 }
 
+                // If the "absent" query parameter is set, return hosts on which the package is NOT installed
+                $absent = isset($_GET['absent']);
+
                 if (empty($this->uri[5])) {
                     throw new Exception('You must specify a package');
                 }
 
-                return ['results' => $hostListingController->getByPackage($this->uri[5], $version, $strictName, $strictVersion)];
+                return ['results' => $hostListingController->getByPackage($this->uri[5], $version, $strictName, $strictVersion, $absent)];
             }
 
             /**
              *  List up-to-date hosts
              *  https://repomanager.mydomain.net/api/v2/hosts/uptodate
              */
-            if ($this->uri[4] == 'uptodate' and $this->method == 'GET') {
-                return ['results' => $hostListingController->getUpToDate()];
+            if (in_array($this->uri[4], ['uptodate', 'compliant']) and $this->method == 'GET') {
+                return ['results' => $hostListingController->getUpToDate(isset($_GET['packages']))];
             }
 
             /**
              *  List outdated hosts
              *  https://repomanager.mydomain.net/api/v2/hosts/outdated
              */
-            if ($this->uri[4] == 'outdated' and $this->method == 'GET') {
-                return ['results' => $hostListingController->getOutdated()];
+            if (in_array($this->uri[4], ['outdated', 'non-compliant']) and $this->method == 'GET') {
+                // Also get the list of available updates if the "list" query parameter is set
+                return ['results' => $hostListingController->getOutdated(isset($_GET['packages']))];
             }
         }
 

www/controllers/Api/Serializer.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Controllers\Api;
+
+class Serializer
+{
+    /**
+     *  Recursively normalize the keys of an array to lowercase
+     *  so that the API always returns a consistent key format, no matter
+     *  whether the data comes from the database (PascalCase columns) or
+     *  is built by the backend (lowercase keys).
+     */
+    public static function normalize($data)
+    {
+        // Only arrays have keys to normalize, return scalars as-is
+        if (!is_array($data)) {
+            return $data;
+        }
+
+        $result = [];
+
+        foreach ($data as $key => $value) {
+            // Recursively normalize nested arrays
+            $value = self::normalize($value);
+
+            // Numeric keys (sequential lists) are kept as-is
+            if (is_int($key)) {
+                $result[$key] = $value;
+                continue;
+            }
+
+            $result[strtolower($key)] = $value;
+        }
+
+        return $result;
+    }
+}

www/controllers/Filesystem/Directory.php

@@ -10,7 +10,7 @@ class Directory
      *  Return an array with the list of founded directories in specified directory path
      *  Directory name can be filtered with a regex
      */
-    public static function findRecursive(string $directoryPath, string $directoryNameRegex = null, bool $returnFullPath = true) : array
+    public static function findRecursive(string $directoryPath, string $directoryNameRegex = '', bool $returnFullPath = true) : array
     {
         $foundedDirs = [];
 

www/controllers/Host/Export.php

@@ -18,9 +18,7 @@ public function export(array $hosts): string
             throw new Exception('No hosts provided for export');
         }
 
-        /**
-         *  First check that hosts Id are valid and exist
-         */
+        // First check that hosts Id are valid and exist
         foreach ($hosts as $id) {
             if (!is_numeric($id)) {
                 throw new Exception('Invalid host Id: ' . $id);
@@ -31,9 +29,7 @@ public function export(array $hosts): string
             }
         }
 
-        /**
-         *  Generate the CSV header
-         */
+        // Generate the CSV header
         $csv[] = [
             'Id',
             'Hostname',
@@ -53,9 +49,7 @@ public function export(array $hosts): string
             'Reboot required',
         ];
 
-        /**
-         *  For each host, get its information and add it to the CSV array
-         */
+        // For each host, get its information and add it to the CSV array
         foreach ($hosts as $id) {
             $data = $this->get($id);
 
@@ -74,14 +68,12 @@ public function export(array $hosts): string
                 $data['Online_status'],
                 $data['Online_status_date'],
                 $data['Online_status_time'],
-                $data['Linupdate_version'],
+                $data['Agent_version'],
                 $data['Reboot_required'],
             ];
         }
 
-        /**
-         *  Encode to JSON and return the CSV data
-         */
+        // Encode to JSON and return the CSV data
         try {
             return json_encode($csv, JSON_THROW_ON_ERROR);
         } catch (JsonException $e) {

www/controllers/Host/Host.php

@@ -87,22 +87,22 @@ public function getSettings(): array
     /**
      *  Edit the display settings on the hosts page
      */
-    public function setSettings(int $packagesConsideredOutdated, int $packagesConsideredCritical): void
+    public function setSettings(int $complianceThresholdCount, int $complianceThresholdDays): void
     {
         if (!HostPermission::allowedAction('edit-settings')) {
             throw new Exception('You are not allowed to perform this action');
         }
 
-        if (!is_numeric($packagesConsideredOutdated) or !is_numeric($packagesConsideredCritical)) {
+        if (!is_numeric($complianceThresholdCount) or !is_numeric($complianceThresholdDays)) {
             throw new Exception('Parameters must be numeric');
         }
 
-        // Parameters must be greater than 0
-        if ($packagesConsideredOutdated <= 0 or $packagesConsideredCritical <= 0) {
-            throw new Exception('Parameters must be greater than 0');
+        // Value must be greater than 0
+        if ($complianceThresholdCount <= 0 or $complianceThresholdDays <= 0) {
+            throw new Exception('Value must be greater than 0');
         }
 
-        $this->model->setSettings($packagesConsideredOutdated, $packagesConsideredCritical);
+        $this->model->setSettings($complianceThresholdCount, $complianceThresholdDays);
     }
 
     /**