SIEM Connector

The Synqly SIEM provider connects your application to your customers' SIEMs. Synqly supports writing and querying events to and from SIEMs.

The Synqly SIEM provider connects your application to your customers' SIEMs. Synqly supports writing and querying events to and from SIEMs.

Providers require authentication to securely transmit data. Before creating an Integration, use the Credentials API to create a Synqly Credential object containing credentials for the target Provider. The expected credential format for each Provider is detailed in the "Authentication" sections below.

Once you have created a Credential object, use the Create Integration API to instantiate an Integration with the target Provider. Make sure to set the provider_type field to siem. After an Integration has been configured, use the v1/siem/events API to send event data in OCSF format or to querying data out of the SIEM.

Pagination

The SIEM connector implements pagination using a cursor. Responses return a field cursor which can be included in the next GET request to retrieve the next page of results. If the cursor field is not included in the request, the first page of results will be returned.

The number of results returned is controlled with the limit query parameter. The default limit is 100.

Filtering

The SIEM provider supports a standardized query language that is translated to each SIEM. The following operations are supported:

These are used as query parameters in the v1/siem/events API. For example, to query for all events with a severity of high, you would GET the following URL: https://api.synqly.com/v1/siem/events?filter=severity[eq]high

Multiple filters can be applied to a single field and in a request. If specified multiple times, filters are combined with AND semantics. For example, to query for all events with a severity of high and a created_at greater than 2023-11-15T15:04:05Z, you would use the following parameters: ?filter=severity[eq]high&filter=created_at[gt]2023-11-15T15:04:05Z.

Time-based filtering

Many SIEM providers work using time windows to control the time frame events are returned from. To make queries as simple as possible, Synqly's API does not require you to send a time intervale when making a query to a SIEM provider. Instead, a long default time range is automatically populated when the query is made to the backing provider. Exact values can differ slightly between providers, but it will generally default to a date far in the past to now.

While these default make getting up and running much easier, it can be very useful to control the query time interval. With Synqly this is controlled using our standard filters for time in conjunction with the [gte] and [lte] operators. You can specify one or both of these to control exactly what time interval is queried, and when a time bound is not specified Synqly's API will fill in the default before querying the provider.

An example of filtering for events between June 21, 2024 12pm GMT and 1pm UTC:

?filter=time[gte]2024-06-21T12:00:00Z&filter=time[lte]2024-06-21T13:00Z

Log Provider filtering

Some SIEM providers allow filtering to a specific set of logs. In fact, some provider require specifying a specific log set when searching logs. Where possible, we map the log set available from the provider to the OCSF metadata.log_provider field. When present in the response, this field can be used to filter the logs for that provider. Adding this filter is always optional. When a provider does require a log set Synqly will attempt to query over all log sets by default (as no specific filter was sent for metadata.log_provider).

Ordering

SIEM results can be ordered using Synqly's standard ordering syntax. For example, to order by created_at in ascending order, you would GET the following URL: https://api.synqly.com/v1/siem/events?order=created_at[asc]

The fields that may be ordered on depend on the SIEM implementations and whether or not there is an index on the field. If the field is not indexed, the query will fail. For example, if the field is not indexed in Elasticsearch you will receive a 400 Bad Request error with an "illegal_argument_exception".

Raw Data

If you would like the provider's raw data in addition any mapped fields, you can request it. For requests without a body (sug as GET requests), you can add include_raw_data=true to the request. Items returned from the API will then include a "raw_data" key filled with the text of the response body from the request used to populate the Synqly response data.

For endpoints that support raw data inclusion, you can also use raw data in filters. Just author your filter indexing into the raw data (?filter=raw_data.last_seen[lte]1717786216)

Meta Functions

The SIEM event query endpoint supports synqly meta functions. Using meta functions you can further decorate the response with additional meta data. Supported meta functions include:

• api/response
• stats/count

Note: When using the stats count meta function, most providers will run a statistics query instead of a search, resulting in rich meta data, but an empty event results array.

Asynchronous Querying for Supported Providers

Many SIEM providers (such as QRadar, Splunk, Rapid7, and Sumo Logic) offer asynchronous APIs for querying events. In general, Synqly will manage polling for results and return the data all within a single HTTP call from you. However, sometimes the query will take longer than polling window for an individual HTTP request. When this happens, Synqly will return a body with an empty result set, a cursor, and a status of "PENDING".

{
    "result": [],
    "cursor": "ey...",
    "status": "PENDING"
}

You can continue to poll the Synqly API for a response from the backing provider until on of the following occurs

1. you get results
2. you decide to stop waiting
3. an error is thrown

When results are available, the status is "COMPLETE". This differentiates between a query with an empty result and a query that is still processing.

Go SDK Event Query Example

    qrQuery := &engine.QuerySiemEventsRequest{
        // Author your query
    }
    var resp *engine.QuerySiemEventsResponse
    var err error
    // This will poll synqly's API up to 10 times
    for i := 0; i < 10; i++ {
        resp, err = a.Client.Siem.QueryEvents(ctx, qrQuery)
        if err != nil {
            // An error return means an actual problem, handle the error as makes sense for your application
            consoleLogger.Printf("error reading events for tenant %s: %s\n", a.TenantName, err)
            os.Exit(1)
        }
        if resp.Status == engine.QueryStatusComplete {
            // When status is COMPLETE the search is done and we will have results if any matched the query
            consoleLogger.Println("search complete")
            break
        }
        // When the status is PENDING the search is incomplete, we will update the query cursor and try again
        // to continue waiting for the result set.
        consoleLogger.Println("search still pending, polling to continue search")
        qrQuery.Cursor = &resp.Cursor
    }

Python SDK Event Query Example

    try:
        query_rsp = None
        query = dict(
            # Author your query
        )
        # This will poll synqly's API up to 10 times
        for i in range(0,10):
            q_rsp = client.siem.query_events(**query)
            if q_rsp.status == engine.QueryStatus.COMPLETE:
                # When status is COMPLETE the search is done and we will have results if any matched the query
                print("Query complete")
                query_rsp = q_rsp
                break

            # When the status is PENDING the search is incomplete, we will update the query cursor and try again
            # to continue waiting for the result set.
            print(f"query still pending after try {i}, polling to continue waiting...")
            query["cursor"] = q_rsp.cursor

        # Events now available in query_rsp.result
        print(f"Query complete, found {len(query_rsp.result)} events")
    except Exception as e:
        # An error return means an actual problem, handle the error as makes sense for your application
        print("Error querying events: " + str(e))

API Reference

For full API documentation see the SIEM API Reference.

To create an integration with the SIEM connector, use the Create Integration API endpoint, using one of the provider configs below.

Supported Providers

• CrowdStrike Falcon® Next-Gen SIEM (siem_crowdstrike)
• Elastic SIEM (siem_elasticsearch)
• Google Security Operations (Chronicle Compatibility) (siem_google_chronicle)
• Google Security Operations (siem_google_security_operations)
• IBM QRadar SIEM (siem_q_radar)
• Microsoft Sentinel (siem_sentinel)
• OpenSearch SIEM (siem_opensearch)
• Rapid7 InsightIDR (siem_rapid7_insightidr)
• Splunk Enterprise Security (siem_splunk)
• Sumo Logic Cloud SIEM (siem_sumo_logic)
• Synqly Test Provider (siem_mock_siem)

Supported Operators by Provider

APIs with Filters