Scans

A scan runs on an agent to collect data from the machine and report it back to the Athena server. Athena supports three kinds of scan: built-in inventory collection, custom PowerShell scan definitions, and Windows Update (WSUS offline) scans.

Scan types at a glance#

Scan type	What it collects	How it runs
Inventory	Built-in hardware, software, services, OS and network facts.	Automatically on the agent's inventory cycle.
PowerShell scan definition	Anything your PowerShell script returns, stored as structured rows.	By trigger mode: Inventory, Heartbeat, or On-Demand.
Windows Update (WSUS offline)	Missing/installed Windows updates, evaluated against the WSUS offline catalog.	Against the `wsusscn2.cab` catalog uploaded to the server.

Inventory scans#

Every enrolled agent runs a built-in inventory collection that gathers hardware, installed software, services, operating-system and network information and sends it to the server on its inventory cycle. This is the data behind agent detail pages and dynamic collection filters. For the full picture of what is collected and how to read it, see Inventory and Built-in Collectors.

You can also read an agent's inventory from PowerShell:

# Full inventory for one agent
Get-AthenaAgentInventory -AgentId "12345678-1234-1234-1234-123456789012"

# Focused sections
Get-AthenaAgentHardware -AgentId $id
Get-AthenaAgentSoftware -AgentId $id
Get-AthenaAgentServices -AgentId $id

PowerShell scan definitions#

A scan definition is a PowerShell script you author once and run across the fleet. The agent runs the script, wraps its output as JSON, and returns structured rows that Athena renders as a table — the column schema is discovered automatically from the data, so any script that returns objects works without predefining a schema.

A scan definition has these fields:

Field	Description
`name`	Required. Display name for the scan.
`description`	Optional free-text description of what the scan collects.
`powerShellScript`	The PowerShell script executed on the agent.
`triggerMode`	When the scan runs — see trigger modes (a flags value; modes can be combined).
`timeoutSeconds`	Maximum script run time. Defaults to `60` seconds.
`isEnabled`	Whether the scan definition is active.

Trigger modes#

triggerMode controls when a scan definition runs. It is a flags value, so a single scan can use more than one mode (for example, Inventory + On-Demand):

Mode	Runs…
`Inventory`	During the agent's inventory collection cycle; results are sent with the inventory data.
`Heartbeat`	On every heartbeat cycle; results are sent with the heartbeat message.
`OnDemand`	When you trigger it manually from the console.

Scan results feed collection filters

Fields returned by a PowerShell scan become filterable for dynamic collections using the Scan.<scanDefinitionId>.<field> path form, once the scan has returned data.

Example script#

Write natural PowerShell that emits objects — the agent handles JSON conversion. For example, a scan that lists local administrators:

Get-LocalGroupMember -Group "Administrators" |
    Select-Object Name, ObjectClass, PrincipalSource

Windows Update (WSUS offline) scans#

Athena evaluates Windows Update status against the Microsoft WSUS offline scan catalog (wsusscn2.cab). You upload the signed catalog to the server once, and agents use it to determine which updates are installed or missing — this works even in air-gapped environments because the catalog is served from Athena rather than from the internet. For the full workflow — uploading the catalog, on-demand and scheduled scans, viewing missing/installed updates, roles, the REST API and PowerShell — see Windows Update Management.

Download the latest wsusscn2.cab from the Microsoft Update Catalog (search for wsusscn2.cab). The file must be signed by Microsoft; its signature is verified on upload. Manage the catalog from PowerShell:

# Upload the WSUS offline scan catalog (Admin role)
Send-AthenaUpdateScanCab -Path "C:\Downloads\wsusscn2.cab"

# Check the stored catalog (Operator or Admin role)
Get-AthenaUpdateScanCab

# Remove the stored catalog
Remove-AthenaUpdateScanCab

Keep the catalog current

Microsoft refreshes wsusscn2.cab roughly monthly. Re-upload it periodically so update-status results reflect the latest catalog.