# securehats/validate-detections architecture

> Architecture diagram of the GitHub repository securehats/validate-detections, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/securehats/validate-detections
- Repository: https://github.com/securehats/validate-detections

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD
    A["GitHub Workflow Trigger"]:::external
    B["GitHub Actions Runner"]:::environment
    C["GitHub Action Config"]:::config
    D["Validation Engine"]:::logic
    E["Test Module - JSON"]:::test
    F["Test Module - YAML"]:::test
    G["MITRE Data File"]:::data
    H["Reporting/Logging"]:::logging

    A -->|"triggers"| B
    B -->|"loads config"| C
    C -->|"provides inputs to"| D
    B -->|"initiates"| D
    D -->|"executes"| E
    D -->|"executes"| F
    D -->|"reads"| G
    D -->|"outputs results to"| H

    click C "https://github.com/securehats/validate-detections/blob/main/action.yml"
    click D "https://github.com/securehats/validate-detections/blob/main/action.ps1"
    click E "https://github.com/securehats/validate-detections/blob/main/analytics.tests.ps1"
    click F "https://github.com/securehats/validate-detections/blob/main/yaml-analytics.tests.ps1"
    click G "https://github.com/securehats/validate-detections/blob/main/mitre.csv"

    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef environment fill:#d6dbdf,stroke:#808080,stroke-width:2px;
    classDef config fill:#cce5ff,stroke:#3366cc,stroke-width:2px;
    classDef logic fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef test fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef data fill:#fadbd8,stroke:#922b21,stroke-width:2px;
    classDef logging fill:#fcf3cf,stroke:#b7950b,stroke-width:2px;
```
