How securehats/validate-detections works
Project Type and Purpose
• This is an automation tool provided as a GitHub Action. Its primary purpose is to validate Sentinel Analytics rules using PowerShell scripts.
• The README makes it clear that the action is integrated into GitHub workflows and validates detection rules using inputs such as a file path and a log verbosity level.
• It supports testing both JSON and YAML rules and even integrates with external data (e.g., the MITRE ATT&CK CSV file).
File Structure
• Top-Level Files:
• LICENSE – standard project licensing.
• README.md – provides an overview, usage instructions, and details about limitations.
• action.yml – the GitHub Action manifest file defining the action’s inputs, outputs, and environment.
• action.ps1 – the main PowerShell script that likely implements the validation logic.
• analytics.tests.ps1 and yaml-analytics.tests.ps1 – test scripts (using Pester, as hinted) for validating JSON and YAML detection files.
• mitre.csv – an external data file that might be used for mapping or enhancing detection rule context.
• The structure indicates a simple but modular design centered on action execution and validation tests.
Main Components to Highlight
a. GitHub Workflow Trigger:
• Represents the external GitHub workflow that invokes the action.
• Illustrated as a “GitHub Workflow” block which leads into the execution pipeline on a push event.
b. GitHub Action Definition:
• The action.yml file can be represented as a configuration component that provides the metadata (inputs, environment details).
c. Execution Environment:
• A block representing the “GitHub Actions Runner” or “Execution Environment” (e.g., ubuntu-latest as specified).
• This environment houses the runtime where the PowerShell script (action.ps1) executes.
d. Validation Logic and Test Modules:
• The core validation logic is implemented in action.ps1.
• “Analytics Validation Module” that processes the Sentinel rules.
• Separate modules (or sub-components) for handling JSON rules and YAML rules can be represented (backed by analytics.tests.ps1 and yaml-analytics.tests.ps1).
e. External or Auxiliary Data:
• The mitre.csv file serves as an external data source that could be invoked by the validation scripts.
f. Reporting/Logging:
• The outputs generated by the tests (and guided by the “logLevel” parameter input) can be depicted as a logging/reporting component showing the test results.
Relationships and Data Flow
• The trigger from an external GitHub workflow initiating the runner.
• The checkout of the repository and the loading of configuration files (action.yml, action.ps1, test scripts, and mitre.csv).
• How the action runs the main validation (via action.ps1) which reads the analytics rules (from the provided files path).
• The interplay between the validation core and test modules.
• The eventual output of test results back to the GitHub workflow logs.
Architectural Patterns or Design Principles
• Separation of Concerns: The project cleanly separates configuration (action.yml), business logic (action.ps1), and testing (analytics.tests.ps1, yaml-analytics.tests.ps1).
• Modularity: Although not a multi-service architecture, the distinct division between handling JSON and YAML rules suggests modular treatment of different data types.
• Extensibility: The design allows for future extensions (e.g., adding support for hunting queries or fusion rules as mentioned in the README).
Additional Elements
• Annotations or labels that indicate the supported inputs (filesPath and logLevel).
• If desired, a section depicting potential error paths or logging flows.