Skip to content

Latest commit

 

History

History
59 lines (43 loc) · 4.54 KB

CONTRIBUTING.md

File metadata and controls

59 lines (43 loc) · 4.54 KB
Raw

EQL Contribution Guide

Welcome to the Event Query Language (EQL) contribution guide and thank you for expressing an interest in contributing to EQL!

As a quick refresher, the Event Query Language (EQL) was built by Endgame to express relationships between events. It is data source and platform agnostic, includes the ability to ask stateful questions, and enables sifting and stacking of data with unix-like pipes.

The EQL community consists of two main components

  • This repository, which houses the underlying language and evaluation engine
  • An Analytics Library, which contains detections and hunting strategies.

Contributions to extend core capabilities of the language are directed to eql. For new detections, hunts, data sources, or knowledge sharing, please read the guidelines below before contributing.

Table of Contents

  1. Contribution Process
  2. Ways to Contribute
  3. Resources
  4. Licenses

Contribution Process

Contributing to EQL is a simple five-step process facilitated by Git:

  1. Create an issue to track and discuss the work
  2. Create a branch
  3. Submit a pull request
  4. Update according to the code review
  5. Merge after approval.

Additional Notes

  • If you are accustomed to git, then great! If you aren't, don't fear, the command line tools are easy to use, but GitHub also has a straightforward process within your web browser to create branches and subsequent merging
  • Use the Issues and PR templates! Git Issues are a great place to collaborate, discuss, or just track a request before development begins.
  • There is plenty of literature and resources out there to help you. A great place to start is GitHub guides.

Ways to contribute

Bug Fixes

Bug fixes are a natural area to contribute. We only ask that you please use the bug report issue to track the bug. Please elaborate on how to reproduce the bug and what behavior you would have expected. Compatibility is a priority for EQL, so be sure to capture information about your operating system and version of python.

Language or Engine Changes

For any changes within the language or the evaluation engine, propose your changes in a Feature Request issue to start a discussion. For new functionality function, be mindful of handling different edge cases, acceptable input, etc. We are happy to collaborate on such topics and encourage you to share ideas.

Some types of core development include:

  • Syntax changes: This can be an entirely new construct ranging from high level constructs (e.g. sequence, join), to smaller changes (e.g. adding binary operators).
  • Pipes: pipes usually can be added without needing to make syntax changes. Some pipes may stream output while processing, and others track state and only output when all input is finished (e.g. count).
  • Functions: functions can be easily extended without needing to recommend changes to the syntax
  • API: You may also want to add new APIs, utility functions, etc. like is_stateful

Anyone is encouraged to make a PR for open issues that have a clear path forward. When making changes, be sure to

  • Link back to the issue "Resolves #100"
  • Include unit tests in the relevant tests/ folder.
  • Include end-to-end tests by updating the test data and queries. These are used as the gold standard of expected behavior, and the queries should have a list of the serial_event_id of the events, in the expected order.

CLI

Finally, the CLI is an area we are always looking to expand. This may include new input file types, new processing features, new tables, etc. Some shell functionality, like tab completions ANSI coloring, and history often varies across different operating systems. If possible, please test new functionality across a few different operating systems if you have access, and Python 2.7 and 3.6+. If you find any unusual behavior in the shell related to compatibility, please let us know in an issue.

Resources

See the resources page on ReadTheDocs for a full list of resources

Licenses

The Event Query Language is licensed under AGPL