Using the HTTP Event Collector (HEC)

This helper provides developers with a simple solution for ingesting data into Falcon NG-SIEM. A code sample that uses this helper has been posted to the FalconPy sample library.

The HEC class was first introduced in FalconPy v1.5.1.

PLEASE NOTE: This helper only provides a solution for ingesting data, and does not address parsing requirements. For more detail regarding parser development and configuration refer to the Falcon NG-SIEM documentation within the Falcon console.

• Keyword arguments
• Properties
• Methods
• Usage examples

Keyword arguments

The HEC helper class leverages simple keywords to specify NG-SIEM ingestion and logging options. The following keywords are supported when creating an instance of the HEC helper class.

Properties

Once created, the following properties are available within an instance of the HEC helper class.

Methods

The HEC helper class provides several methods for ingesting data and testing connectivity.

send_event

Sends a single event to Falcon NG-SIEM.

Keyword arguments

send_event_file

Processes and sends a file to Falcon NG-SIEM.

Keyword arguments

send_event_list

Sends a list of events to Falcon NG-SIEM.

Keyword arguments

test_connection

Tests connectivity to the Falcon NG-SIEM endpoint.

Keyword arguments

None

Usage examples

Single event import

This example imports a single JSON formatted event.

from falconpy import HEC

payload = {
    "host": "sample-host",
    "message": "Sample message",
    "fields": {
        "#falconpy": "Sample payload"
    }
}    
hec = HEC(api_key=NGSIEM_API_KEY,
          api_url_key=NGSIEM_URL_KEY
          )
hec.send_event(payload)

This example imports a single JSON formatted event using the HEC context manager.

from falconpy import HEC

payload = {
    "host": "sample-host",
    "message": "Sample message",
    "fields": {
        "#falconpy": "Sample payload"
    }
}    
with HEC(api_key=NGSIEM_API_KEY,
         api_url_key=NGSIEM_URL_KEY
         ) as hec:
    hec.send_event(payload)

List import

This example imports a list of JSON formatted events.

from falconpy import HEC

payload = [{
    "host": "sample-host",
    "message": "Sample message",
    "fields": {
        "#falconpy": "Sample payload"
    }
},
{
    "host": "sample-host",
    "message": "Sample message",
    "fields": {
        "#falconpy": "Sample payload"
    }
}]    
hec = HEC(api_key=NGSIEM_API_KEY,
          api_url_key=NGSIEM_URL_KEY
          )
hec.send_event_list(payload)

Raw import

This example imports a raw file of JSON events.

from falconpy import HEC

hec = HEC(api_key=NGSIEM_API_KEY,
          api_url_key=NGSIEM_URL_KEY,
          raw_ingest=True
          )
hec.send_event_file("sample_import_file.json")

Contents of sample_import_file.json

{"event": {"category": ["host"], "host": "IV1IDSBP", "kind": "event", "module": "crowdstrike-falconpy-hec", "timestamp": 1747771778324434944, "type": ["info"], "timeunit": "nanoseconds", "message": "VP35ya83siwOC9bThq0U"}}
{"event": {"category": ["host"], "host": "XIHQBIOV", "kind": "event", "module": "crowdstrike-falconpy-hec", "timestamp": 1747771778324711936, "type": ["info"], "timeunit": "nanoseconds", "message": "ngZbqZroR8763eMODCWN"}}
{"event": {"category": ["host"], "host": "6MNTM8B8", "kind": "event", "module": "crowdstrike-falconpy-hec", "timestamp": 1747771778324791808, "type": ["info"], "timeunit": "nanoseconds", "message": "S4TCr7nY6u8fALOKHAQt"}}