Automatic Lookback on Events

CYBERQUEST Data Transformation Service (DTS) scripts can search previously received events. This lets you correlate new information, such as an Indicator of Compromise (IOC), with historical activity and create an alert when matching events are found.

Create alerts

The global Alert object provides two methods for creating alerts.

Alert.create(options): void

Creates an alert from an options object:

/** @type {Record<string, unknown>} */
const eventObject = {
    EventID: 100000,
    LocalTime: moment().format("YYYY-MM-DD HH:mm:ss.SSS")
};

Alert.create({
    template: "template name",
    logs: [eventObject],
    name: "alert name",
    emails: "[email protected], [email protected]",
    description: "alert description",
    secLevel: 8,
    secScore: 80,
    metaData: "additional metadata"
});

options is required and must be a non-null object. Its properties are optional:

Strings containing email addresses are split on commas. Leading and trailing whitespace is removed from each valid address.

Returns: void.

Alert.createSimple(alert): void

Sends a serialized alert payload directly:

/** @type {Record<string, unknown>} */
const eventObject = {
    EventID: 100000,
    LocalTime: moment().format("YYYY-MM-DD HH:mm:ss.SSS")
};

Alert.createSimple(JSON.stringify({
    logs: [eventObject],
    GeneratedTime: moment().format("YYYY-MM-DD HH:mm:ss.SSS"),
    IsAlert: "1",
    AlertSecurityLevel: 9,
    AlertSecurityScore: 90,
    AlertName: "IOC found in historical events",
    TemplateName: "",
    Description: "A known IOC matched historical activity.",
    Why: "The source or destination IP matched the IOC.",
    Category: "Security",
    SubCategory: "Threat intelligence",
    Tenant: "Tenant-name",
    MitreID: "T1071"
}));

The alert parameter is required and has type string. It must contain the complete serialized alert payload expected by the receiving service. Alert.createSimple forwards the string unchanged; it does not parse or validate it. The example payload uses the following fields:

These fields illustrate the payload used by this example; the local API does not define their requiredness or default values.

Returns: void.

Use Alert.create for the standard options-based API. Use Alert.createSimple only when you already have the complete serialized alert payload required by the receiving service.

Search historical events

The global Events object provides the following lookback methods:

Events.getCount(query, days = 0); // number | false
Events.getBackLogs(query, days = 0, count = 100); // Array<object> | false

Events.getCount(query, days = 0): number | false

Returns: number containing the number of matching events, or false when days is not a finite number. Unlike getBackLogs, this method does not explicitly reject a negative days value.

Events.getBackLogs(query, days = 0, count = 100): Array<object> | false

Returns: Array<object> containing up to count matching events, ordered by LocalTime in descending order (newest first). Returns false when the query is too short, either numeric argument is not a finite number, or days is negative.

Example: correlate an IOC with historical events

In Rules > DTS Objects, add an object and create a custom script. The following example searches the previous 30 days for events involving either of two IP addresses. It creates an alert when more than two events match:

const query = "SrcIP:192.168.1.1 OR DestIP:192.168.0.1";
const numberOfEvents = Events.getCount(query, 30);

if (numberOfEvents > 2) {
    const matchingEvents = Events.getBackLogs(query, 30, 100);

    Alert.create({
        emails: "[email protected], [email protected]",
        logs: matchingEvents,
        name: "IOC found in historical events",
        description: "Known malicious IP addresses matched historical events.",
        secLevel: 5,
        secScore: 10,
        metaData: "Matched by a DTS threat-intelligence lookback."
    });
}

For instructions on configuring the DTS object, see Create a DTS alert.