Skip to content

Latest commit

 

History

History
57 lines (38 loc) · 5.62 KB

detections-as-code.md

File metadata and controls

57 lines (38 loc) · 5.62 KB

Detection as Code (DaC) Components in Detection-Rules Repo

The detection-rules repository contains features for Detections as Code (DaC). These components, including CLI options and workflows, provide methods to help apply DaC principles in practice. The specific DaC architecture should be carefully considered before implementation, for more conceptual ideas and details about DaC, refer to the DaC Documentation. Reference implementation is shared to facilitate experimentation and community contributions.

Note

This guidance outlines the support scope and best practices for using DaC components within the detection-rules repo. Users should take full responsibility for their usage of this repo, thoroughly test these tools in their environments, and verify functionality before using them.

Support and Scope

Supported DaC components that interact with the Elastic Security Solution:

  • kibana export-rules (link)
  • kibana import-rules (link)
  • import-rules-to-repo (link)
  • export-rules-from-repo (link)

We welcome general questions, feature requests, and bug reports through the following channels:

  • GitHub Issues: For raising general questions, bugs, and feature requests related to the detection-rules repo.
    GitHub Issues
  • Community Slack: For informal discussions or questions (note that message history is limited to 30 days).
    Elastic Security Community Slack

Support tickets related to this DaC reference implementation can be opened with Elastic, however since the logic is just a wrapper of the underlying product API's, we ask to resolve urgent DaC issues via direct interaction with the underlying Kibana APIs or Elastic Security Solution UI, as we will not be able to treat DaC related support requests as a high severity (immediate time frame).

Tip

Questions about Kibana API usage should be directed to the Kibana repository:
Kibana Issues

Feature Requests

Feature requests for the DaC components that interact with the Elastic Security Solution (kibana export-rules, kibana import-rules, import-rules-to-repo, and export-rules-from-repo) in this repository will be handled similarly to the rest of the detection-rules repo:

  • Prioritization: Feature requests will be prioritized along with other development work in the repository.
  • Schema Updates: If there are breaking schema changes in Kibana that affect importing/exporting detection rules, those changes will be prioritized.
  • Rule Engine API: Current CLI tools leverage the rules engine API, and improvements to this will be treated as part of the ongoing development.

Reference Implementation of DaC Components

DaC is not a single tool. Detection as Code (DaC) is a modern security approach that applies software development best practices to the creation, management, and deployment of security rules. Here is a short summary of several components that extend upon Elastic's rule management capabilities (e.g. query validation, schema validation, unit tests, etc.) provided to help fast track users ability to implement custom DaC implementations in their private environments. If you are new to these concepts, please refer to the DaC Documentation, which also provides a quickstart guide and example end-to-end CI/CD workflows. These components are configurable by using the custom-rules setup.

  • Kibana's Rule Versioning Mechanism (link)
  • Local rule management (e.g. autoschema generation, actions and exceptions) (link)

Best Practices for Using DaC Components

When implementing DaC in your production environment, follow these best practices:

  • Design and Test Rigorously: Since every DaC implementation will be user-specific, remember to diligently design, and thoroughly test the tools before deploying them in a production environment.
  • Version Compatibility: Before upgrading the detection-rules repo version, ensure that you test compatibility with your environment. For more information, see our Versioning Documentation.
  • Limited Backward Compatibility: We do not guarantee backward compatibility across versions for rule schemas. While we aim to make new fields optional where feasible, there may be minimum version requirements for Elastic Stack and are subject to Kibana's rule schema definitions.
  • Schema Parity: Not all fields in the schema defined in Kibana are fully supported. Some fields in the detection-rules repo are generalized (e.g., field = dict()), while others are more strictly defined. This is due to the complexity of the schemas and the prioritization of Elastic's internal use cases.