Purpose
This guide explains how to collect CloudSEK XVigil alerts in Logsign USO with the CloudSEK XVigil API integration. Logsign reads the CloudSEK Alerts API over HTTPS with an API token. You do not need to install an agent or configure syslog forwarding on the CloudSEK side.
Each XVigil alert is collected as one log record. CloudSEK puts the incident details (incident number, status and assignee) inside each alert, so this information arrives in the same record. The integration does not open incidents in Logsign. Only XVigil alerts are collected. BeVigil and SVigil alerts are not returned by this API and are not part of this integration.
Prerequisites
Logsign version: a Logsign USO release that includes the CloudSEK XVigil source. If you do not see CloudSEK XVigil in the API source list, upgrade Logsign first.
Network access: the Logsign server must reach api.cloudsek.com on TCP 443 (HTTPS).
API token: an Alerts API token from your CloudSEK organization. The token is the only credential that the integration needs.
Step 1: Create the API Token in CloudSEK
- Sign in to the CloudSEK platform with a user that can manage integrations.
- Open the Integrations area and create a token for the Alerts API.
- Copy the token and keep it in a safe place, because you need it in Step 2.
Logsign only reads alerts and never changes anything in CloudSEK. Logsign uses the read-only historic alerts endpoint, so it does not mark alerts as processed. Another tool that uses the CloudSEK live alerts endpoint with the same organization does not take alerts away from Logsign.
Step 2: Add the Source in Logsign USO
In Logsign USO, go to Settings > Add Device > API and select CloudSEK XVigil. The form contains one CloudSEK specific field:
| Field | Value |
|---|---|
| API Key | The CloudSEK API token from Step 1. Required. Paste only the token, without the Bearer prefix. |
There is no Base URL field. Logsign always connects to https://api.cloudsek.com.
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, up to 30 days. You cannot change it after you save the source. Period sets how often Logsign polls CloudSEK.
How Collection Works
Logsign calls GET /v2/incidents/historic/alerts with the last_n_days, page and limit parameters. It requests 500 alerts per page, waits 3 seconds between two pages and reads up to 50 pages in one poll. CloudSEK does not document the order of the alerts in the response, so Logsign reads every page of the time window and selects the new alerts itself.
The position is the newest updated_at value that Logsign received, together with the event IDs that have this exact timestamp. Every poll asks CloudSEK for the days since the position plus one extra day, from 1 up to 30 days. Logsign sends only the alerts that are newer than the position, so an alert is not sent twice.
If CloudSEK changes an alert later and gives it a newer updated_at value, Logsign sends the alert again with the new values. It was not verified whether CloudSEK changes updated_at when only the incident status or assignee changes.
The CloudSEK API allows a limited number of requests for each token (CloudSEK reported 20 requests per minute for one customer). A normal poll uses one request when there are fewer than 500 alerts in the window. If the source stays stopped for more than about 29 days, alerts older than 30 days cannot be read, because the API window ends at 30 days.
The position moves only after all pages of the window are read. If a page fails, Logsign does not save the position and the next poll reads the same window again.
What Gets Collected
All timestamps are converted to one format before they are written to Logsign fields, because CloudSEK sends some dates with Z and others with +00:00. The matched_assets lists (for example several domains) are written as one comma separated value. The value Not Available in the matched alert rule is not written to any field.
Severity
The severity comes from the CloudSEK threat_magnitude value of the alert.
| CloudSEK threat magnitude | Severity.Name in Logsign |
|---|---|
| critical, high | critical |
| medium | warning |
| low | notice |
Event classification
The XVigil sub module of the alert (sub_module) selects the classification (Context / Type / SubType).
| XVigil sub module | Classification |
|---|---|
| Fake URLs and Phishing, Fake Mobile Apps, Fake Pages and Channels, Fake Call Centres | Security / Phishing / Info |
| Compromised Computers, Malware Logs | Security / Botnet / Detect |
| Credential Breaches, Documents and Open Buckets, Code Repositories, Debit/Credit Cards, API Platforms | Security / Vulnerability / Detect |
| Dark Web Discussions, Messaging Platforms, Social Media Discussions | Security / Threat / Info |
An alert from a sub module that is not in this list gets the Security / Threat / Info classification.
Field mappings
| CloudSEK field | Logsign field |
|---|---|
| created_at | Time.Generated |
| module_name | Event.Category |
| sub_module | Event.SubCategory |
| event_details.event_id | Event.AlertID |
| event_details.threat_magnitude | Severity.Name |
| event_details.posted_time | Time.FirstSeen |
| event_details.suspect_url | Threat.IndicatorValue |
| event_details.matched_assets.domain | TargetSubject.Info |
| event_details.incident_details.incident_id | Event.ID |
| event_details.incident_details.created_time | Time.Creation |
| event_details.incident_details.incident_status | Event.Status |
| event_details.incident_details.assignee | Event.Assignee |
| event_details.incident_details.matched_alert_rule | Rule.Name |
Fields that are not in this table (for example event_url, threat_tags and the incident priority) are not mapped to Logsign fields. The source appears in Logsign with vendor CloudSEK, product XVigil API and category Security Manager.
Troubleshooting
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 field is empty. | Edit the source and enter the CloudSEK API token. |
CloudSEK API token is invalid or expired. | CloudSEK answered with HTTP 401. Logsign stops the poll after this single request and does not retry. | Create a new token in CloudSEK and enter it in the source. |
Rate limited on page ..., retrying after ...s | CloudSEK answered with HTTP 429. Another tool may use the same token. | No action is necessary if it happens rarely. Logsign waits for the time in the Retry-After header (60 seconds if the header is missing) and requests the same page again. If it repeats, use a separate token for Logsign or set a longer Period. |
Unexpected response on page .... Status: ... | CloudSEK answered with another HTTP error, for example 403 or 5xx. | Logsign retries the page up to 3 times. If the error continues, check that the token is allowed to use the Alerts API. |
API call failed on page ... | The Logsign server cannot reach CloudSEK (DNS, firewall, proxy or TLS problem). | Check outbound HTTPS access to api.cloudsek.com. |
Stopped after 50 pages | The window has more than 25,000 alerts. | Send the poller log line to Logsign Support. |
There are no new alerts. on every poll | There are no new XVigil alerts in the window. | Check in the CloudSEK platform that XVigil produces alerts for the same organization. |