EQL (Event Query Language) Python Library

Common errors

• ply.lex.LexError: Illegal character '"' ('\"') at index X

  cause The EQL query string contains a character that is not recognized by the EQL lexer, often due to an unescaped or misplaced quote, or other syntax error.
  fix Review the EQL query string for correct syntax, paying close attention to string literals, escaping special characters, and overall EQL grammar. Ensure all strings are properly quoted and keywords are spelled correctly.

• AttributeError: 'Query' object has no attribute 'execute'

  cause Attempting to directly 'execute' a parsed EQL `Query` object as if it were an event processing function. The `eql` library only parses the query into an AST.
  fix The `eql.Query` object is an Abstract Syntax Tree representation. You need to implement or use an external EQL execution engine that accepts this AST and applies it to your event data. The `eql` library provides the query structure, not the execution mechanism.

• ModuleNotFoundError: No module named 'eql'

  cause The `eql` package is not installed in the current Python environment, or the environment where it was installed is not active.
  fix Install the package using `pip install eql`. Verify you are running your script in the correct virtual environment if you are using one.

• TypeError: 'str' object is not callable (when trying to process parsed_query)

  cause This usually occurs when attempting to treat the `str()` or `repr()` representation of the `parsed_query` object as a callable function or object with methods, rather than using the `parsed_query` object itself.
  fix Ensure you are interacting directly with the `eql.Query` object returned by `eql.parse()`, using its methods like `to_json()` or passing the object itself to subsequent processing steps, instead of its string representation.

Warnings

• gotcha The `eql` Python library is primarily an EQL *parser* and AST generator. It does NOT include an event processing or execution engine to run queries against live event streams or data lakes. You will need to implement or integrate with a separate system to evaluate the parsed queries.
  Fix: Understand that `eql.parse()` returns an AST. Integrate this AST with an external EQL evaluation engine or implement your own event processing logic.
• gotcha EQL syntax is strict and unforgiving. Even minor typos, incorrect casing for keywords (e.g., `where` vs `WHERE`), or unsupported constructs will lead to parsing errors.
  Fix: Always refer to the official EQL specification or documentation for correct syntax. Use a linter or formatter if available. Common errors include missing quotes around strings or incorrect logical operators.
• gotcha The library relies on the `ply` (Python Lex-Yacc) package for parsing. While generally robust, conflicts can arise if other dependencies in your project require a significantly different version of `ply`, or if there are environment-specific issues during `ply`'s installation or operation.
  Fix: Ensure `ply` is installed correctly. If conflicts arise, consider using a dedicated virtual environment or checking for version compatibility issues with other libraries.
• gotcha EQL queries are highly dependent on the schema of the events they are intended to query. Queries referencing non-existent fields or fields with incorrect data types will lead to logical errors or runtime failures in the *execution engine*, not necessarily during parsing.
  Fix: Rigorously validate your EQL queries against the actual schema of your event data. Implement schema validation in your EQL execution pipeline.

Install

• pip install eql Install stable version

Imports

• eql.parse

  import eql
  parsed_query = eql.parse("your query")

• eql.Query
  wrong:

  from eql import Query # while possible, less common than using eql.parse()

  correct:

  import eql
  query_obj = eql.parse("...") # eql.Query object is returned

  The `eql.Query` object is typically instantiated indirectly via `eql.parse()`.

Quickstart

This quickstart demonstrates how to parse a basic EQL query string using the `eql.parse()` function. The function returns an `eql.Query` object, which represents the Abstract Syntax Tree (AST) of the query. This object can then be inspected or used as input for an EQL execution engine (which is not part of this library).

import eql

# Define a simple EQL query string
eql_query_string = "process where eventid == 1 and process_name == 'powershell.exe'"

# Parse the EQL query string into an EQL Query object (AST)
parsed_query = eql.parse(eql_query_string)

print(f"Original EQL: {eql_query_string}")
print(f"Parsed Query Type: {type(parsed_query)}")
print(f"Parsed Query (JSON representation): {parsed_query.to_json(indent=2)}")

# The parsed_query object can then be transformed or evaluated by an external engine.