HTTP Event Collector

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.

Argument	Data type	Default	Description
api_key	string	None	Falcon NG-SIEM API key.
api_url_key	string	None	Falcon NG-SIEM URL key. Used to craft the target URL.
debug	boolean	False	Enable debugging.
ingest_format	string	json	Ingest data format. Allowed Values json yaml xml csv
ingest_region	string	us1	NG-SIEM ingest region. Allowed Values us1 us2 eu1 usgov1 usgov2
ingest_timeout	string	5	Ingest submission request timeout (in seconds).
raw_ingest	boolean	False	Use the NG-SIEM raw ingestion endpoint.
retry_count	integer	3	Number of request retries before erroring on a thread.
sanitize_log	boolean	True	Sanitize bearer tokens from debug logs.
thread_count	integer	CPU count times 2, or 50 (whichever is smaller)	Number of threads to use for asynchronous processing.

Properties

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

Property	Data type	Mutable	Category	Description
file_log	integer	Yes	Logging	Integer used to indicate if log data is being written to a file.
hec_headers	dictionary	No	Ingest Config	The authorization headers provided as part of a ingestion HTTP request. Calculated from the ingest_key and ingest_format.
ingest_base_url	string	Yes	Ingest Config	Base URL used during NG-SIEM endpoint creation.
ingest_config	IngestConfig	Yes	Ingest Config	The object used for storing ingestion configuration settings.
ingest_format	string	Yes	Ingest Config	Format for ingested data.
ingest_format_name	string	No	Ingest Config	The string used to identify the ingestion data format type.
ingest_key	string	Yes	Ingest Config	NG-SIEM API key.
ingest_timeout	integer	Yes	Ingest Config	URL request timeout.
ingest_timeunit	string	Yes	Ingest Config	Timeunits used for data ingested.
ingest_url	string	No	Ingest Config	The destination URL used for data import, calculated from the ingest_url_key and ingest_base_url.
ingest_url_key	string	Yes	Ingest Config	NG-SIEM URL key.
last_message	string	Yes	Collector	The last received HTTP status message.
last_status	integer	Yes	Collector	The last received HTTP status code.
log	Logger	No	Logging	Log object provided by the log facility.
log_facility	LogFacility	Yes	Logging	Logging facility used for API debug output.
raw_ingest	boolean	Yes	Ingest Config	Flag indicating if the raw ingestion endpoint should be used.
raw_ingest_url	string	No	Ingest Config	The destination URL used for raw data import, calculated from the ingest_url.
retry_count	integer	Yes	Session Management	HTTP request retry count.
sanitize_log	boolean	Yes	Logging	Flag indicating if log sanitization is enabled.
session_manager	SessionManager	Yes	Session Management	Manager object used to handle sessions during asynchronous processing.
sessions	list of Session	Yes	Session Management	Returns the list of sessions currently in use.
thread_count	integer	Yes	Session Management	Threads used in asynchronous session management.

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

Argument	Data type	Description
evt	dictionary or string	Event data to be consumed.

send_event_file

Processes and sends a file to Falcon NG-SIEM.

Keyword arguments

Argument	Data type	Description
event_file	string	File location containing the event data to be consumed.

send_event_list

Sends a list of events to Falcon NG-SIEM.

Keyword arguments

Argument	Data type	Description
event_list	list of dictionaries or a list of IngestPayload	List of data events to be consumed.
show_progress	boolean	Flag indicating if a progress indicator should be shown.

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"}}