Requirements

SAM basic metering and SAM total usage metrics

For SAM basic metering and SAM total usage metrics, the non-privileged servicenow user (which the agent service logs on as) must be configured with READ only access in the registry. This access allows for successful execution of the OSQuery against the UserAssist table to be successful. Go to regedit and allow the servicenow user to read UserAssist for a user account on the device (for example: HKEY_USERS\SID...\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\UserAssist for every user in HKEY_USERS).

Note:

The UserAssist key does not inherit permissions from the HKEY_USERS\SID... parent key. Therefore, you must navigate to the UserAssist key and add permission directly on the key.

To apply SAM basic metering or SAM total usage metrics, you need the following:

• SAM plugin (com.snc.samp) enabled
• System property [sn_acc_vis_content.persist_sam_usage_metrics] set to true. See System properties for more details.

For details on SAM metering setup with the Agent Client Collector, see the Knowledge Base article KB1642676.

Software edition information

To retrieve software edition information, you need the SAM plugin (com.snc.samp) enabled.

SAM basic metering

For the list of software in the payload, query the Software Discovery Model [cmdb_sam_sw_discovery_model] table to fetch the corresponding product and publisher. Once the product is fetched, check if the reclamation rule is enabled for that product to persist the last usage information in the Software Usage [samp_sw_usage] table. See the flowchart for details.

SAM total usage metrics

SAM total usage metrics allows you to measure total usage time and total usage count on any application that has a software reclamation rule enabled.

Osquery provides a daemon executable which can run as a service, called Osqueryd. Osqueryd needs to be manually deployed for SAM total usage metrics to work properly. Each Osqueryd deployment requires the osquery.conf file, optional external packs, and initialization flags (configured in osquery.flags file) provided when starting the service. In return, the daemon service runs scheduled queries on the host and logs it into a local file system.

Domain information can be collected during the data collection. This can help large organizations with multiple employee directories map software to the correct user. Currently, this is supported for Windows only. To map the software usage/assigned_to with the correct user in a domain separated environment, use the system property [sn_acc_vis_content.column_name_for_user_mapping] with a valid field name. By default, the value of this system property is empty which means it only validates the username and not the domain. You can use either of the following formats to validate username and domain: username@domain or domain\username.

Using the list of processes, you can perform SAM normalization to map the processes for the relevant installed software records. This provides flexibility since installed software names and processes are not usually the same. For the list of processes in the payload, query the Software Discovery Model [cmdb_sam_sw_discovery_model] table and Software Product [samp_sw_product] table to fetch the corresponding product and publisher. Once the product is fetched, check if the reclamation rule is enabled for that product to persist the total usage time in the Software Usage [samp_sw_usage] table. See the flowchart for details.

# Install latest osquery

$msi = "osquery-5.7.0.msi"
$url = "https://pkg.osquery.io/windows/$msi"
$dst = "$PSScriptRoot\$msi"
Invoke-WebRequest -Uri $url -OutFile $dst
# msiexec /i "$dst" /quiet /qn /norestart
Start-Process msiexec.exe -Wait "/i $dst /quiet /qn /norestart"

# Configure osqueryd service

$flags = "--logger_rotate=true
--logger_rotate_size=26214400
--logger_rotate_max_files=1
--watchdog_level=-1
--config_path=C:\Program Files\osquery\osquery-sam.conf"
Set-Content -Path 'C:\Program Files\osquery\osquery.flags.default' -Value "$flags"

$conf = @'
{
  "options": {
    "config_plugin": "filesystem",
    "logger_plugin": "filesystem",
    "utc": "true"
  },
  "schedule": {
    "sam_process_info": {
      "query": "SELECT name, pid, elapsed_time, start_time, user_time, system_time, username FROM processes p JOIN users u ON u.uid = p.uid WHERE p.elapsed_time != -1 AND u.type != 'special';",
      "snapshot" : true,
      "interval": 300
    },
    "system_info": {
      "query": "SELECT hostname, cpu_brand, physical_memory FROM system_info;",
      "interval": 3600
    }
  },
  "decorators": {
    "load": [
      "SELECT uuid AS host_uuid FROM system_info;",
      "SELECT user AS username FROM logged_in_users ORDER BY time DESC LIMIT 1;"
    ]
  },
  "packs": {
  }
}
'@
Set-Content -Path 'C:\Program Files\osquery\osquery-sam.conf' -Value "$conf"

cd 'C:\Program Files\osquery'
.\manage-osqueryd.ps1 -uninstall
.\manage-osqueryd.ps1 -install
Restart-Service osqueryd

For details on Windows and macOS see Configure Osqueryd schedule for SAM total usage metrics and Configure Osqueryd logs for SAM total usage metrics.

Collecting SAM metrics without osqueryd

Optionally, you can enhance efficiency by using non-osqueryd data collection when using push-based Discovery and Software Asset Management (SAM) together. When non-osqueryd data collection is invoked, data collection is automatically performed on all available agents, instead of invoking osqueryd on each agent individually.

Software edition information

Starting in ACC-V version 2.3.0, edition information is supported for Adobe Acrobat and MS SQL server. In future releases, additional software will be supported. With this feature, SAM admins can get clear visibility into the editions of their installed software. Osquery commands are used to fetch the edition information which then shows in the Software Installation [cmdb_sam_sw_install] table in the Edition Override column. For more details, see the support KB: https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB0721360