Purpose
This guide explains how to collect Heimdal Security events in Logsign USO with the Heimdal EDR API integration. Logsign reads the Heimdal API 2.0 over HTTPS with a Personal API Key and a Customer ID. You do not need to install an agent or configure syslog forwarding on the Heimdal side.
The integration collects these log streams: Threat-hunting and Action Center (TAC) notifications for devices and for Microsoft 365, Next-Gen Antivirus detections, Ransomware Encryption Protection detections, DNS Security (endpoint and network) and Privilege Elevation and Delegation Management (PEDM) requests. Extended Threat Protection (XTP) details, Application Control and the Heimdal audit log are not collected in this version.
Prerequisites
Logsign version: a Logsign USO release that includes the Heimdal EDR source. If you do not see Heimdal EDR in the API source list, upgrade Logsign first.
Network access: the Logsign server must reach dashboard.heimdalsecurity.com on TCP 443 (HTTPS).
Trusted IP: Heimdal accepts API calls only from the IP addresses or ranges that are marked as trusted for the Dashboard user account that owns the API key (in the Accounts section of the Heimdal Dashboard). Add the outbound (public) IP address of the Logsign server to this list. If you skip this step, Heimdal rejects the requests with the message User is not authorized to fulfill the operation.
Dedicated user: a Personal API Key has the same permissions as the Dashboard user that created it. We recommend a separate Dashboard user with read-only access, used only for Logsign. The integration only reads data and never changes anything in Heimdal.
Step 1: Get the API Key and Customer ID in Heimdal
- Sign in to the Heimdal Dashboard with the user that Logsign will use.
- Generate a Personal API Key for this user and copy it. Keep it in a safe place, because you need it in Step 2.
- Write down your Customer ID. It contains only digits. If you are a reseller and manage several customers, each customer needs its own Logsign source with its own Customer ID.
- Add the outbound IP address of the Logsign server to the trusted IP list of the same user.
Step 2: Add the Source in Logsign USO
In Logsign USO, go to Settings > Add Device > API and select Heimdal EDR. The form contains these Heimdal specific fields:
| Field | Value |
|---|---|
| Base URL | Filled with https://dashboard.heimdalsecurity.com/api/heimdalapi/2.0 by default. Keep this value unless Heimdal gave you a different Dashboard host. The value must include https:// and the /api/heimdalapi/2.0 suffix. A trailing slash is removed automatically. If the field is empty, Logsign uses the default address. |
| API Key | The Personal API Key from Step 1. Required. |
| Customer ID | The numeric Customer ID from Step 1. Required. |
| Streams | The log streams to collect. See the table below. If you leave the selection empty, Logsign collects the default streams. |
The common source fields (Log Start Date, Period, EPS, Device Name and so on) work as for the other API sources. Log Start Date sets how far back Logsign reads on the first run, from 10 minutes up to 30 days. You cannot change it after you save the source.
| Stream | Heimdal endpoint | Selected by default |
|---|---|---|
| TAC Device Notifications | /tac/getNotifications | Yes |
| TAC M365 Notifications | /tac/getUserNotifications | Yes |
| Next-Gen Antivirus | /vigilancedetections | Yes |
| Ransomware Encryption Protection | /encryptiondetection | Yes |
| DNS Security (Endpoint) | /darklayerguard (blocked requests only) | Yes |
| DNS Security (Network) | /threatPreventionNetwork (blocked, manually blocked and category blocked requests) | No |
| Privilege Elevation (PEDM) | /adminprivilege/getElevationsInLifecycle (states Init, Pending, Finalized and Failed) | No |
DNS Security (Network) and PEDM send one request per status or state, so they use more of the Heimdal rate limit. Select them only if you need these events.
How Collection Works
Each stream keeps its own position, which is the timestamp of the newest record that Logsign received. Every poll reads the time window from that position, and Logsign keeps only records that are newer than the position. The live window ends 60 seconds before the current time, because Heimdal shows records in the API a short time after their timestamp.
Heimdal allows 10 requests per minute for each endpoint. Logsign waits 6 seconds between two requests to the same endpoint, requests 1,000 records per page and reads up to 10 pages for each stream in one poll. If the first run or an outage leaves a large backlog, Logsign reads it in slices of up to one hour, one slice per stream per poll. For example, a 30 day Log Start Date with a 60 second period needs about 12 hours to reach the present time. When a slice has more records than 10 pages, Logsign makes the slice smaller and continues on the next poll, so no records are lost.
The position moves only after a window is read completely. If a request fails, Heimdal answers with HTTP 429 or the response cannot be read, the position stays where it is and the next poll reads the same window again. In that case a small number of records can arrive twice.
Each record is sent once. If Heimdal changes a record after Logsign received it (for example the resolution of a TAC notification or the state of a PEDM request), Logsign does not send the record again. A PEDM request appears in the state it had when Logsign first read it.
What Gets Collected
All timestamps are converted to UTC. Values that Heimdal sends as - (empty placeholder) are not written to any field. The categories list of TAC notifications is written as one comma separated value.
Severity
When a record has its own severity value, Logsign uses it. Otherwise the severity comes from the event classification below.
| Heimdal severity | Severity.Name in Logsign |
|---|---|
| Informational | information |
| Low | notice |
| Medium | warning |
| High | error |
| Critical | critical |
Event classification
Each stream uses one field of the record to select the classification (Context / Type / SubType):
| Stream | Selected by | Value and classification |
|---|---|---|
| TAC (device and M365) | Heimdal module (source) | Xtp, LoginAnomalyDetection: Security / Suspicious Behavior / Detect VectorN: Security / Threat / Info Antivirus: Security / Virus / Detect RansomwareEncryptionProtection, RansomwareEncryptionProtectionCloud: Security / Malware / Block Patching, WindowsUpdate: Security / Vulnerability / Info PrivilegedAccessManagement: Identity / User / Request AppControl: Security / Application Control / Info EmailSecurity: Security / Spam / Detect EmailFraudPrevention: Security / Phishing / Info EndpointOperationalIssues: System / Endpoint / NonCompliant M365EmailForwardRule: Application / Mail / Redirect M365SecurityIssues: Security / Alert / Info |
| Next-Gen Antivirus | Resolution (Threat.ActionTaken) | Quarantined: Security / Virus / Quarantine Deleted: Security / Malware / Clean DeniedAccess: Security / Virus / Block Excluded, FNotExist: Security / Virus / Info ErrorDelete, ErrorQuarantine, ErrorExcludeQuarantine, ErrorRemoveQuarantine: Security / Virus / Unclean |
| Ransomware Encryption Protection | Always the same | Security / Malware / Block |
| DNS Security (endpoint and network) | threatType, then status | Any record with a threat type: Security / Threat / Block Blocked, CategoryBlocked, ManualBlocked: Security / Content Filtering / Block Allowed, Passed: Network / DNS / Request Analyzed: Network / DNS / Info |
| PEDM | Elevation state (Event.Type) | Init: Identity / User / Request Pending: Identity / User / Grant Finalized: Identity / User / Info Failed: Identity / User / Error |
Status values are matched without regard to upper or lower case. A record with a value that is not in this list gets the Security / Alert / Info classification.
Field mappings
| Heimdal field | Logsign field | Streams |
|---|---|---|
| clientInfoId | Device.ID | Records that contain it |
| hostname | Source.HostName | Records that contain it |
| timestamp | Time.Generated | All except PEDM |
| lastUpdated | Time.LastSeen | Records that contain it |
| name | Rule.Name | TAC |
| ruleId | Rule.ID | TAC |
| details | Event.Description | TAC |
| processName | Process.Name | TAC |
| pid | Process.ID | TAC |
| categories | Event.Category | TAC |
| resolution | Event.Status | TAC |
| severity | Severity.Name | TAC |
| source | Event.Module | TAC |
| userPrincipalName | Source.UserName | TAC M365 |
| file | File.Path | Next-Gen Antivirus |
| processName | Process.Path | Next-Gen Antivirus |
| resolution | Threat.ActionTaken | Next-Gen Antivirus |
| threatCategory | Threat.Type | Next-Gen Antivirus |
| infectionName | Threat.Name | Next-Gen Antivirus |
| status | Event.Status | Next-Gen Antivirus, DNS Security |
| md5 | Object.MD5 | Next-Gen Antivirus |
| username | Source.UserName | Ransomware Encryption Protection |
| processPath | Process.Path | Ransomware Encryption Protection |
| processId | Process.ID | Ransomware Encryption Protection |
| serverTimestamp | Time.Received | Ransomware Encryption Protection |
| ip, ipAddress | Source.IP | DNS Security |
| activeUsername | Source.UserName | DNS Security |
| domain | Destination.DomainName | DNS Security |
| threatType | Threat.Type | DNS Security |
| threatToProcessCorrelation | Process.Name | DNS Security |
| threatToProcessCorrelationPath | Process.Path | DNS Security |
| resolvedDomains | Event.Detail | DNS Security |
| protocol | Protocol.Name | DNS Security |
| elevationId | Session.ID | PEDM |
| elevation state (from the request) | Event.Type | PEDM |
| elevationType | Event.Detail | PEDM |
| reason | Event.Reason | PEDM |
| requestTime | Time.Generated | PEDM |
| startTime | Time.Start | PEDM |
| endTime | Time.End | PEDM |
| fileName | File.Name | PEDM |
| filePath | File.Path | PEDM |
Fields that are not in this table (for example owner and resolvedIps) are not mapped to Logsign fields. The source appears in Logsign with vendor Heimdal Security, product Heimdal API and category Endpoint Security.
Troubleshooting
Heimdal returns an authorization error as HTTP 200 with a message in the body, so it does not appear as an HTTP 401 or 403. The messages below are written to the poller log.
| Message in the poller log | Likely cause | What to check |
|---|---|---|
Please ensure that all required config fields are set. | The API Key or the Customer ID is empty. | Edit the source and fill in both fields. |
User is not authorized to fulfill the operation. | The API key is wrong or revoked, the Customer ID does not belong to the user, or the Logsign IP address is not in the trusted IP list. | Check the key and the Customer ID. Add the outbound IP address of the Logsign server to the trusted IPs of the Dashboard user. |
Rate limit hit; remaining records will be picked up on the next poll. | Heimdal answered with HTTP 429. Another tool may use the same API key and endpoint. | No action is necessary if it happens rarely. If it repeats, use a separate API key for Logsign or select fewer streams. |
Unexpected response from server. Status code: ... | Heimdal answered with an HTTP error, for example 404 when the Base URL is wrong. | Check that the Base URL ends with /api/heimdalapi/2.0. |
API request failed for ... | The Logsign server cannot reach Heimdal (DNS, firewall, proxy or TLS problem). | Check outbound HTTPS access to dashboard.heimdalsecurity.com. |
Response has no known record list; top-level keys: ... | Heimdal answered with a response that Logsign does not recognize. | Send the poller log line to Logsign Support. |
Page cap reached ... | The stream has more than 10,000 records in one slice. | No action is necessary. Logsign makes the slice smaller and continues on the next poll. |
There are no new events. on every poll | There are no new records for the selected streams, or the related Heimdal module is not licensed or active. | Check that the module produces events in the Heimdal Dashboard for the same customer. |