Agents and execution history

Agents are scheduled automation jobs that run per account. The available list is loaded from the application configuration and database.

The list is filtered by the selected account’s source settings: Devo agents require a non-empty DevoDomain, while the three Sentinel agents (mssentinel-alert-download, mssentinel-user-behavior-profile-download, and mssentinel-heartbeat) require a SentinelTenantId to appear. A Sentinel agent is ready to enable or run only when the account credentials and valid operational settings are also configured. Each card or list row uses the agent definition’s description as its visible title, with the agent type and version shown below it.

Devo alert data collection

The devo-alert-download agent collects alerts from Devo’s siem.logtrust.alert.info table for the selected SIEM+ account. The account’s DevoDomain setting is sent as the Devo client filter, and the account time zone is used to divide the collection range into local calendar days.

Each normal run:

1. Starts at the latest stored alert for the account whose source is devo or begins with devo-, with a three-day recovery overlap. If no Devo alert exists yet, it starts at the configured Days to sync lookback, which defaults to 30 days.
2. Stops at the current local hour, divides the range into account-local calendar days, and processes each day as 15-minute windows. Each request queries siem.logtrust.alert.info with the configured client, limit=50, and an offset (skip) until the response contains fewer than 50 rows.
3. Filters returned rows to the configured Devo client and persists each page immediately. Transient gateway, network, and connection failures are retried up to five attempts.
4. Upserts alerts into Alerts using an account- and client-scoped source ID. The ID uses the Devo alert ID (id, alertid, or uuid) when available, with a SHA-256 hash of the raw row as a fallback. Repeated alerts update the existing record instead of creating duplicates.
5. Stores the embedded object from extraData in AlertData when available, otherwise the raw row. DataSource is taken from the alert’s source-table fields, Source is normally devo-<source>, and AlertType is built from available MITRE IDs, tactics, and techniques before falling back to the alert type fields. New alerts have status open.

If an administrator requests a past-date alert reset, the agent runs that targeted range after the normal download and clears the reset request only after both operations finish successfully. The alert-count materialized views are refreshed after the account’s alert writes complete. The checked-in schedule is every six hours, can be customized, and uses the account’s schedule time zone.

Devo user behavior profile collection

The devo-user-behavior-profile-download agent builds account-scoped user behavior profiles independently from Devo alert ingestion. It uses the auth.all table as the required authentication source and runs a seven-calendar-day window in the account time zone. Each day is staged durably before optional enrichment is applied.

The authentication query normalizes successful, failed, and undetermined login results, including common Windows result codes and source-specific success messages. It records activity hours, source IP/geography, actions, and source tables. The agent retries each day independently, resumes completed staging after an interrupted run, and aggregates only days whose required authentication and enrichment phases completed.

When available, enrichment queries firewall.paloalto.globalprotect, firewall.fortinet.event.user, cloud.office365.management, attributed records in firewall.all.traffic, box.all.win, box.all.unix, and cloud.gsuite.reports for users found in the authentication cohort. An unavailable optional table, or traffic without an attributed username, is recorded as a coverage gap instead of discarding the other completed source data. A user needs at least five qualifying authentication events before the profile is refreshed. Partial day coverage is recorded in the agent result and the baseline source.

The profile agent derives typical weekday and weekend active hours, source geography, data-source mix, action mix, authentication-failure rate, and unknown-classification rate. Existing role and department metadata are preserved. Its checked-in schedule is weekly on Saturday at 00:00 UTC and is read-only.

Sentinel alert data collection

The mssentinel-alert-download agent collects Microsoft Sentinel alert data for the selected SIEM+ account. Its purpose is to make Sentinel detections available in the account’s alert and case workflows using the common SIEM+ alert schema. The agent uses the Microsoft Graph security API; it does not download Sentinel workspace logs or authentication events.

Each run:

1. Lists incidents and alerts independently with a lastUpdateDateTime filter. The first run starts with the configured initial backfill window (7 days by default); later runs use separate incident and alert cursors. The agent follows Microsoft Graph @odata.nextLink values until all pages are read.
2. Stores incident metadata for context and correlation, then upserts the alert records into the selected account. An existing Sentinel alert with the same external alert ID is updated instead of duplicated.
3. Correlates each alert’s incidentId with the incidents returned for the same run. If its incident is not in the current incident result, the alert is retained without incident context.
4. Normalizes investigation fields such as event time, title, category, severity, status, service source, product, description, MITRE techniques, user, source and destination IP addresses, and cloud application.
5. Preserves the raw Graph alert and correlated incident metadata in AlertData, and stores heterogeneous Graph evidence in SentinelAlertEntities.

The two pulls are independent and run concurrently. A successful pull commits its batch and advances only its own cursor. An execution can therefore be partial if one Graph endpoint fails: the alert pull can still store alerts when the incident pull fails, and those alerts can be correlated when a later incident update supplies the missing incident context. The agent records the per-pull errors and final status in execution history.

Prepare the Sentinel data source

Add these least-privileged Microsoft Graph application permissions to the Entra app registration used by the agent:

Collection purpose	Endpoint	Application permission
Download incident records for alert context	GET /v1.0/security/incidents	SecurityIncident.Read.All
Download alert records and evidence	GET /v1.0/security/alerts_v2	SecurityAlert.Read.All
Run Sentinel Advanced Hunting queries for profiles and heartbeat	POST /beta/security/runHuntingQuery	ThreatHunting.Read.All

The first two permissions are required by the List incidents and List alerts APIs. The third is required by the profile and heartbeat agents because they run Sentinel threat-hunting queries. Use Microsoft Graph with Application permissions, not Delegated permissions, and grant tenant-wide admin consent to all permissions needed by the enabled agents. The selected Sentinel workspace must also expose the queried Advanced Hunting data and grant the connected application appropriate Advanced Hunting access.

The account and agent must both be configured before collection can run:

1. In the selected account’s Admin > Integrations settings, enter the target tenant’s Microsoft Sentinel tenant ID, Application (client) ID, and Client secret as valid values. Optionally enter a workspace ID to select the Advanced Hunting workspace for the profile and heartbeat agents. A blank tenant ID hides all Sentinel agents for the account and prevents them from running.
2. Select Save in Integrations. If a client secret is already configured, leave that field blank to keep it; the secret is never displayed after saving.
3. In Agents, open the Sentinel configuration and save only the operational settings. SIEM+ checks the required Graph endpoint for each enabled Sentinel agent at application startup and reports authentication or missing-permission failures. Collection failures are recorded in agent history.
4. Use Run now for an immediate collection, or keep the agent schedule. The alert agent’s checked-in default schedule is every six hours and can be customized for the account.

The initial backfill accepts 1–30 days and defaults to 7 days. The checked-in Sentinel agent context uses a page size of 3,000; Microsoft Graph list requests follow @odata.nextLink, and Advanced Hunting profile queries page their results with the configured value. Poll interval, retry count, retry backoff, and mapping profile version are also stored with the Sentinel agent configuration.

Operational settings are stored in the Sentinel agent definition context and are shared by accounts that use the same definition. Sentinel credentials are stored per account in Admin > Integrations; the API returns the application ID and only whether a client secret is configured, never the secret itself. Only account managers should change the account credentials or shared operational settings.

Sentinel user behavior profile collection

The mssentinel-user-behavior-profile-download agent builds account-scoped user behavior profiles from Sentinel’s _Im_Authentication() ASIM parser through Microsoft Graph Advanced Hunting. It runs independently from mssentinel-alert-download and stores the resulting baseline in UserBehaviorProfiles.

The profile query uses a fixed seven-day baseline window:

_Im_Authentication()
| where TimeGenerated >= datetime(<start>) and TimeGenerated < datetime(<end>)

The KQL range and Graph Timespan cover the same fixed seven-day (P7D) baseline window. The profile agent chunks the window by day, pages each result, and restricts enrichment to users found in the authentication cohort before activity is grouped into profile statistics.

The profile agent derives typical weekday and weekend active hours, source geography, data-source mix, action mix, authentication-failure rate, and unknown-classification rate. It requires at least five qualifying authentication events for a user before refreshing that user’s profile. Existing role and department metadata are preserved because they are not supplied by the Sentinel authentication data.

Each run also checks _Im_AuditEvent(), _Im_NetworkSession(), the union of _Im_ProcessCreate() and _Im_ProcessTerminate(), and _Im_WebSession() for users in the authentication cohort. These enrichment queries are reported as populated, empty, or unavailable; an unavailable optional parser produces a partial-coverage baseline without discarding the other completed sources. This agent calls /beta/security/runHuntingQuery. The Entra app must have the Microsoft Graph ThreatHunting.Read.All Application permission, tenant-wide admin consent, and appropriate Advanced Hunting access to the selected workspace. Set an optional workspace ID in Admin > Integrations, or leave it empty to use the tenant’s primary/default workspace.

The checked-in profile-agent schedule is weekly on Saturday at 00:00 UTC and is read-only. A tenant ID is required before this agent appears; the tenant ID, application (client) ID, client secret, and valid agent settings are required before it can be enabled or run for an account.

Sentinel heartbeat collection

The mssentinel-heartbeat agent uses Microsoft Graph Advanced Hunting to query Sentinel ASIM parsers and map them to the existing SIEM+ heartbeat categories. It processes the account’s configured heartbeat lookback in the account time zone and writes hourly heartbeat counts. Each parser is queried once, so multiple source aliases do not double-count the same source.

ASIM table	Heartbeat category
_Im_Authentication(), _Im_AuditEvent()	cloud_identity
_Im_NetworkSession(), _Im_WebSession()	network
_Im_ProcessEvent() (the create/terminate union), _Im_AlertEvent()	endpoint

The heartbeat agent uses /beta/security/runHuntingQuery and requires the Microsoft Graph ThreatHunting.Read.All Application permission, tenant-wide admin consent, and Advanced Hunting access to the selected workspace. Configure the optional workspace ID in Admin > Integrations when the default workspace should not be used.

Its checked-in schedule is hourly (0 * * * *) and read-only. The tenant ID is required for the agent to appear; the tenant ID, application ID, client secret, and valid agent settings are required before it can be enabled or run.

Agent management

On Agents, review the type, version, status, last execution, next execution, and definition update time. Dates and schedules are shown in the selected account’s time zone. Depending on the agent, you can:

• enable or disable it;
• customize its schedule and time zone;
• save a schedule; and
• choose Run now for an enabled job.

The page provides alphabetical A → Z / Z → A sorting and Tiles / List view switching. Administrators can enable Show system jobs when they need to inspect system-level jobs. Notification agents include report, score report, case summary, and audit report jobs. System and internal jobs do not create account activity notifications.

System jobs and read-only schedules may be visible but cannot be edited. Avoid disabling ingestion or housekeeping jobs without understanding the effect on your account.

Understand the agent card

Each agent card or list row identifies the agent name, type, definition version, status, schedule, last execution, next execution, and definition update time. The status means:

• Healthy — the agent is enabled and has completed at least one execution.
• Awaiting first run — the agent is enabled but has not completed an execution yet.
• Running — an execution is currently running or queued.
• Disabled — the agent will not run on its schedule and cannot be started manually.

The page refreshes automatically every 15 seconds. Use the refresh button when you need an immediate update.

Configure an agent schedule

Only agents marked as having a customizable schedule can be edited. The schedule editor accepts a five-field cron schedule and provides time, day, and month controls. A six-field schedule received from the server is displayed without its leading seconds field. SIEM+ synchronizes saved schedules with the scheduler and uses the selected Schedule timezone when calculating the next execution.

Select a valid Schedule timezone, adjust the schedule, and select Save. Saving also stores the current enabled or disabled state. Read-only or system schedules cannot be changed.

Enable or disable an agent

Use the switch on an agent card to change its account-level enabled state. The switch is unavailable while the agent is running or for system jobs. Disabling an agent stops future scheduled executions, but it does not delete previous execution history. Re-enable the agent before using Run now.

Agent job management

Use agent job management when you need to operate a job immediately, inspect its current execution, or stop work that has not started yet:

1. Select the correct account in the application header. Jobs and execution history are scoped to that account.
2. Open Agents and choose Tiles or List view. Use A → Z or Z → A to locate the job; administrators can enable Show system jobs when required.
3. Check that the job is enabled, its schedule and time zone are correct, and it is not already marked Running.
4. Select Run now. SIEM+ queues one execution for the selected account and displays a confirmation. A disabled agent cannot be run manually, and a second run is rejected while the same job is queued or running.
5. Open History from the agent row or the page header. Filter by agent, status, and start-time range, then select Search.
6. For a queued execution, select Cancel and confirm. Only queued jobs can be cancelled; a running job must finish or fail normally.
7. Review the result or error. JSON results are displayed as readable fields; select the file icon to inspect the raw JSON.

Manual runs are still subject to account job-concurrency limits. If a job remains queued unusually long, refresh History and check for a Cancelled, Failed, or Running status before trying again.

The scheduler monitors overdue executions and can recover an overdue job automatically. If the same job appears to be running twice, wait for the status to refresh before starting another manual run.

Review execution history

Open History to see the latest execution results for configured account agents. Filter by Agent, Status, From, and To, then select Search. Administrators can include system jobs. Available status filters include Running, Succeeded, Failed, Cancelled, and Skipped; queued jobs also expose Cancel. Clear filters returns to the default list. The history shows start, completion, duration, status, and result or error. JSON results are flattened for quick reading and can be opened as raw JSON. It automatically refreshes every 15 seconds, and timestamps use the selected account’s time zone.

Step-by-step: manage an agent job

1. Open Agents and confirm the account shown in the header.
2. If you are an administrator and need system-level jobs, enable Show system jobs.
3. Switch between Tiles and List view if needed, then sort by A → Z or Z → A.
4. Review the agent status, version, last execution, next execution, and definition update time.
5. For an enabled, editable agent, adjust the schedule and Schedule timezone, then choose Save. Read-only schedules cannot be changed.
6. Choose Run now to queue the enabled job immediately. Disabled, running, or system jobs may not allow a manual run.
7. Open History, select an agent if needed, choose a status or time range, and select Search.
8. If the row is Queued, select Cancel only when the job should not start, then confirm.
9. Check the start time, completion time, duration, status, and result or error. Expand JSON results or open raw JSON for technical details.

The manual run appears in history after it starts. Refresh the history page while a job is running.