Scan Definitions

A scan definition is a custom PowerShell script you author once in Athena and run across your Windows fleet to collect data that the built-in inventory does not. The agent runs the script, converts its output to JSON, and returns structured rows the server stores and renders as a table — the columns are discovered automatically from the data, so any script that emits objects works without you predefining a schema. This page covers the whole admin workflow: creating and editing definitions, choosing when they run, running one on demand, and reading the results.

What a scan definition is#

Every scan definition carries the following fields. Names are shown in the JSON form used by the REST response, so the same shape works whether you author in the console or read a definition over the API.

Creating and editing a scan definition#

Open Settings → Agents → Scans. The Scans tab lists every definition with its name, trigger mode, timeout and enabled state, plus an enable/disable toggle and edit/delete actions. Managing scan definitions is part of the settings console, so it requires the Settings management permission (an administrator-level grant).

1. Click New scan to open the editor (or the edit action on an existing row).
2. Enter a name and an optional description.
3. Write your PowerShell in the built-in script editor. It is the same syntax-highlighting editor used elsewhere in Athena; see Script Editor for its keyboard and appearance options.
4. Tick one or more trigger modes — Inventory, Heartbeat and/or On-Demand.
5. Set the timeout in seconds (5–600; default 60).
6. When editing an existing definition you can toggle Enabled. Save.

Saving an enabled definition pushes it to every connected agent, so new or changed scripts take effect without touching the endpoints. Disabling a definition stops it being pushed. Deleting a definition also removes its stored results.

Trigger modes#

triggerMode controls when a scan runs. It is a combinable value, so one definition can use several modes at once (for example, Inventory + On-Demand):

Writing the script#

Write natural PowerShell that emits objects — the agent wraps your script and converts its output to JSON, so you do not call ConvertTo-Json yourself. Emit one object per row and the console builds the table columns from the property names. On Windows the agent runs your script with PowerShell 7 when it is installed, falling back to Windows PowerShell 5.1 otherwise — avoid features exclusive to one edition if your fleet is mixed.

# Return the local administrators as structured rows
Get-LocalGroupMember -Group "Administrators" |
    Select-Object Name, ObjectClass, PrincipalSource

A scan is treated as successful when the script exits with code 0 and writes nothing to the error stream. If it exits non-zero or writes an error, the result is recorded as a failure with the error text and exit code so you can troubleshoot it. Keep scripts within the configured timeout — when a scan exceeds its timeoutSeconds, the agent stops it and its process tree and records a timeout.

Running a scan on demand#

Open an agent's detail page and go to the PowerShell Scans section. Pick a definition from the selector and click Run Now. The button is available only when the agent is online and the selected definition is enabled; a run request is delivered to that agent over its live connection. When the agent finishes, its result appears in the same section (the view updates as the new result arrives).

How results are stored and displayed#

Athena keeps the latest result per agent per definition — a new result replaces the previous one for that pair, so the console always shows the most recent data. Each result records whether it succeeded, the exit code, an error message when it failed, the execution duration in milliseconds, and the time the data was collected.

In the agent's PowerShell Scans section:

• Successful results render as a table. Columns are discovered from the returned JSON: an array of objects becomes one row per object, a single object becomes a one-row table, and a bare value is shown as a single cell. The header shows the collected-at time and the duration.
• Failed results show the error message, exit code and collected-at time so you can diagnose the script.
• If a definition has never returned data on that agent, the section shows a no data yet note.
• Large tables display the first 100 rows with a Show all control to expand the full set.

Feeding collections and reports#

Scan output is not just for viewing — the fields your script returns become filterable across the fleet. Reference them in dynamic collection rules using the path form:

Scan.<scanDefinitionId>.<fieldName>

where <scanDefinitionId> is the definition's ID and <fieldName> is a property name your script emits. Fields appear once the scan has returned data; because the schema is drawn from what agents actually reported across the fleet, add a field to your script and it becomes filterable after the next results come in. See the Filter Field Reference for how scan fields sit alongside built-in inventory fields, and Reports for surfacing scan-backed data in reports.

Reading definitions over the API#

Scan results flow into the same inventory and collection surfaces you already query. You can read an agent's inventory — and, through collections, the scan fields derived from it — from PowerShell:

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

# Collections can filter on Scan.<scanDefinitionId>.<field> paths
Get-AthenaCollection

For the console API surface in general, see the API Reference and the PowerShell Module.