{"id":9725,"library":"eql","title":"EQL (Event Query Language) Python Library","description":"EQL (Event Query Language) is a high-level query language from Microsoft for expressing relationships between events, primarily used in security analytics and threat hunting contexts. The Python library provides tools to parse, validate, and transform EQL queries into an Abstract Syntax Tree (AST). The current stable version is 1.0.0, with releases typically tied to feature enhancements or bug fixes, maintaining a stable API.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/microsoft/eql","tags":["security","threat-hunting","query-language","parser","ast","microsoft"],"install":[{"cmd":"pip install eql","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for parsing EQL syntax into an AST.","package":"ply","optional":false}],"imports":[{"symbol":"eql.parse","correct":"import eql\nparsed_query = eql.parse(\"your query\")"},{"note":"The `eql.Query` object is typically instantiated indirectly via `eql.parse()`.","wrong":"from eql import Query # while possible, less common than using eql.parse()","symbol":"eql.Query","correct":"import eql\nquery_obj = eql.parse(\"...\") # eql.Query object is returned"}],"quickstart":{"code":"import eql\n\n# Define a simple EQL query string\neql_query_string = \"process where eventid == 1 and process_name == 'powershell.exe'\"\n\n# Parse the EQL query string into an EQL Query object (AST)\nparsed_query = eql.parse(eql_query_string)\n\nprint(f\"Original EQL: {eql_query_string}\")\nprint(f\"Parsed Query Type: {type(parsed_query)}\")\nprint(f\"Parsed Query (JSON representation): {parsed_query.to_json(indent=2)}\")\n\n# The parsed_query object can then be transformed or evaluated by an external engine.","lang":"python","description":"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)."},"warnings":[{"fix":"Understand that `eql.parse()` returns an AST. Integrate this AST with an external EQL evaluation engine or implement your own event processing logic.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `ply` is installed correctly. If conflicts arise, consider using a dedicated virtual environment or checking for version compatibility issues with other libraries.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rigorously validate your EQL queries against the actual schema of your event data. Implement schema validation in your EQL execution pipeline.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"ply.lex.LexError: Illegal character '\"' ('\\\"') at index X"},{"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.","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.","error":"AttributeError: 'Query' object has no attribute 'execute'"},{"fix":"Install the package using `pip install eql`. Verify you are running your script in the correct virtual environment if you are using one.","cause":"The `eql` package is not installed in the current Python environment, or the environment where it was installed is not active.","error":"ModuleNotFoundError: No module named 'eql'"},{"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.","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.","error":"TypeError: 'str' object is not callable (when trying to process parsed_query)"}]}