EDRF-HS-Scripts

This Python script demonstrates how to programmatically execute Historical Searches via the HX Historical Search API. It allows users to run the same TQL (Trellix Query Language) statements used in the HX Console UI directly through Python and get the results. This serves as a foundational template for integrating EDR Telemetry into 3rd-party solutions, custom automation workflows, or security orchestration scripts.

Pre-requisites

• Python 3.8+ must be installed
• HX server instance is up and running with Historical-Search plugin installed on it.
• Historical-Search plugin is already configured to connect to an OpenSearch server.
• A valid HX user API-Token to invoke the scripts.
  • Get token
    • curl -s -k GET "https://<ip>:3000/hx/api/v3/token" -H "accept: application/json" -i --user admin
  • Refer this for more details on API-Token : https://docs.trellix.com/bundle/api_1-0-0_ug/page/configuring-the-api-documentation-module/api-authorization-and-authentication/access-token.html
  • Optional - Install the HX API Documentation Module.

Project Structure

• /scripts — This folder contains the python scripts
  • /scripts/connection_test.py - This script tests the connection with OpenSearch and returns the appropriate status message.
  • /scripts/historical_search.py - This script performs a historical search and returns the search result in JSON API format.
• .env — This file contains all the environment variables used in the project.
• historical-search-swagger-doc.yaml - This is the Swagger API specification file containing the spec for all the search APIs used in this project
• requirements.txt — This file contains the list of python packages required to execute the scripts.

Setup and execute the scripts

• Checkout the project repo and navigate to the project root directory

• Setup and activate the Python virtual environment

  • For Windows

  • python -m venv hs_venv

  • hs_venv\Scripts\activate.bat

  • For MAC

  • python -m venv hs_venv

  • source hs_venv/bin/activate

  • For Linux

  • python -m venv hs_venv

  • source hs_venv/bin/activate

• Install the packages from requirements.txt file

  • pip install -r requirements.txt

• Once the installation is complete, we can execute any script present inside the /scripts folder

Script execution with CommandLine arguments

• CommandLine arguments for scripts/connection_test.py

  • hxUrl : HX Server instance url

  • apiToken : Valid user API token, this takes preference over username/password

  • username : HX login username, not required if apiToken is provided, this should be a fallback approach

  • password : HX login password, not required if apiToken is provided, this should be a fallback approach

  • logLevel : Logging level for the script. Set any one of [DEBUG, INFO, WARN]. Default is INFO.

  • Examples on how to execute this script

    • python scripts/connection_test.py --hxUrl=https://0.0.0.0:3000 --apiToken=IGis7dAPmwNV/U9WAh3qZ5V+lZjZ4T+ROVTCVhp710rTACs=
    • python scripts/connection_test.py --hxUrl=https://0.0.0.0:3000 --username=user --password=pass123 --logLevel=DEBUG

• CommandLine arguments for scripts/historical_search.py

  • hxUrl : HX Server instance url

  • apiToken : Valid user API token, this takes preference over username/password

  • username : HX login username, not required if apiToken is provided, this should be a fallback approach

  • password : HX login password, not required if apiToken is provided, this should be a fallback approach

  • searchTql : TQL for creating a search

  • relativeTime : Search relative time in minutes (last x minutes)

  • startTime : Exact search start date-time in UTC format (YYYY-MM-DDThh:mm:ssZ)

  • endTime : : Exact search end date-time in UTC format (YYYY-MM-DDThh:mm:ssZ)

  • logLevel : Logging level for the script. Set any one of [DEBUG, INFO, WARN]. Default is INFO. Set this to WARN if only search result set is needed as script output.

  • Examples on how to execute this script

    • python scripts/historical_search.py --hxUrl=https://0.0.0.0:3000 --apiToken=IGis7dAPmwNV/U9WAh3qZ5V+lZjZ4T+ROVTCVhp710rTACs= --searchTql="procFileAttrs.md5='8146139c2ad7e550b1d1f49480997446' or procFileAttrs.sha256='207df9d438f75185ab3af2ab1173d104831a6631c28ef40d38b2ab43de27b40f' or fileAttributes.sha256='207df9d438f75185ab3af2ab1173d104831a6631c28ef40d38b2ab43de27b40f' or fileAttributes.md5='8146139c2ad7e550b1d1f49480997446'" --relativeTime=150

    • python scripts/historical_search.py --hxUrl=https://0.0.0.0:3000 --username=user --password=pass123 --searchTql="procFileAttrs.md5='8146139c2ad7e550b1d1f49480997446' or procFileAttrs.sha256='207df9d438f75185ab3af2ab1173d104831a6631c28ef40d38b2ab43de27b40f' or fileAttributes.sha256='207df9d438f75185ab3af2ab1173d104831a6631c28ef40d38b2ab43de27b40f' or fileAttributes.md5='8146139c2ad7e550b1d1f49480997446'" --relativeTime=150

    • python scripts/historical_search.py --hxUrl=https://0.0.0.0:3000 --username=user --password=pass123 --searchTql="procFileAttrs.md5='8146139c2ad7e550b1d1f49480997446' or procFileAttrs.sha256='207df9d438f75185ab3af2ab1173d104831a6631c28ef40d38b2ab43de27b40f' or fileAttributes.sha256='207df9d438f75185ab3af2ab1173d104831a6631c28ef40d38b2ab43de27b40f' or fileAttributes.md5='8146139c2ad7e550b1d1f49480997446'" --startTime=2025-12-10T10:30:43Z --endTime=2025-12-11T10:30:43Z --logLevel=WARN

Few Search TQL examples

• "fileAttributes.name:/.*daily.*/"
• "fileAttributes.name:shanya_crypter.exe"
• "cmdLine:/.*GUP.exe.*/ AND cmdLine:/.*-dexmb25nic6n25sclnf44rrgynq.*/"
• "network.dstIp:'10.194.0.191'"
• "network.dstPort:'9090'"
• "network.srcIp:'10.26.21.225'"
• "network.dstIp:'10.194.0.191' network.dstPort:'9090'"
• "dns.name:/.*glcloud.*/"
• "cmdLine:/.*conhost.exe.*/ processName:con*"