# Audit Log with Microsoft Sentinel

# Preamble

Psono can send audit events directly to a Microsoft Sentinel-enabled Log Analytics workspace using the Azure Monitor Logs Ingestion API (opens new window). See the audit log guide for general audit logging configuration.

TIP

This feature is only available in the Enterprise Edition.

# Azure setup

  1. Create a custom table, for example PsonoAudit_CL, in the workspace used by Sentinel. Use the following incoming stream and table schema:

    Column Type
    TimeGenerated datetime
    Logger string
    Level string
    Source string
    Message string
    AuditData dynamic
  2. Create a data collection rule (DCR) with an input stream named Custom-PsonoAudit declaring those columns, and a data flow to the workspace and output stream Custom-PsonoAudit_CL. When using the same schema for the input and destination, use source as the transformation. Record the DCR's immutable ID (dcr-...) and logs ingestion endpoint. A data collection endpoint (DCE) can also be used where required by your Azure configuration.

  3. Register a Microsoft Entra application and create a client secret. Assign its service principal the Monitoring Metrics Publisher role on the DCR.

# Server (settings.yaml)

Add the following to settings.yaml and restart the server:

LOGGING_AUDIT: true
SENTINEL_ENDPOINT: 'https://<your-ingestion-endpoint>.ingest.monitor.azure.com'
SENTINEL_RULE_ID: 'dcr-<immutable-id>'
SENTINEL_STREAM_NAME: 'Custom-PsonoAudit'
SENTINEL_TENANT_ID: '<directory-tenant-id>'
SENTINEL_CLIENT_ID: '<application-client-id>'
SENTINEL_CLIENT_SECRET: '<client-secret-value>'
SENTINEL_TIMEOUT: 5

Copy the endpoint exactly from Azure, including its region/host suffix; supply only the base HTTPS endpoint, without an API path. Setting SENTINEL_ENDPOINT enables the provider; the rule ID and all three credentials are required.

# Configuration reference

Setting Default Description
SENTINEL_ENDPOINT Not enabled Base HTTPS logs ingestion endpoint of the DCR or DCE. Enables forwarding when set.
SENTINEL_RULE_ID Not set DCR immutable ID (dcr-...), required when forwarding is enabled.
SENTINEL_STREAM_NAME Custom-PsonoAudit Input stream declared in the DCR.
SENTINEL_TENANT_ID Not set Microsoft Entra directory (tenant) ID, required when forwarding is enabled.
SENTINEL_CLIENT_ID Not set Application (client) ID, required when forwarding is enabled.
SENTINEL_CLIENT_SECRET Not set Client secret value, required when forwarding is enabled. Use the value, not the secret ID.
SENTINEL_TIMEOUT 5 Positive timeout in seconds for ingestion HTTP requests and authentication connection/read operations.

The settings are also available as environment variables with the PSONO_ prefix, for example PSONO_SENTINEL_CLIENT_SECRET.

# Event structure and delivery

Events from the administration, credit, enterprise, fileserver, and REST API loggers are sent at INFO level and above. Audit events respect LOGGING_AUDIT and the existing audit event whitelist/blacklist.

The request body is a JSON array. Each event contains the stable columns listed above, with the original structured audit fields in the AuditData JSON object. Sentinel stores AuditData as a dynamic column, so fields such as event, user, user_id, and success can be queried directly. UUIDs are serialized as strings, and booleans retain their JSON type. Source identifies the configured HOST_URL, TimeGenerated is the event's UTC timestamp, and Message contains the readable audit log message. Non-dictionary log messages have an empty AuditData object.

Delivery is synchronous, one HTTPS request per event, with cached Entra access tokens and TLS certificate verification. Delivery errors use Python's logging error handling; events are not queued or retried by this handler.

# Querying events

After generating an audit event, query the table in Sentinel:

PsonoAudit_CL
| order by TimeGenerated desc

To extract audit fields:

PsonoAudit_CL
| project TimeGenerated,
          Event = tostring(AuditData.event),
          User = tostring(AuditData.user),
          Success = tobool(AuditData.success)