# withsecurelabs/chainsaw architecture

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

- Interactive diagram: https://gitdiagram.com/withsecurelabs/chainsaw
- Repository: https://github.com/withsecurelabs/chainsaw

## Overview

##### Project Type and Purpose
- Chainsaw is a standalone, full-stack CLI application written in Rust.
- Its purpose is rapid forensic triage of Windows artefacts (EVTX, MFT, registry hives, ESE databases) via search, Sigma-based hunting, timeline analysis (shimcache, SRUM), and raw dumps.
- It integrates third-party libraries (evtx parser, TAU engine) and supports custom and Sigma rules for detection.

##### High-Level Architectural Components
a. CLI Frontend
- Entry point in src/main.rs and src/cli.rs
- Dispatches commands: `search`, `hunt`, `analyse shimcache`, `analyse srum`, `dump`.
b. File Parsers
- Modules under src/file handle different formats:
- evtx (src/file/evtx.rs)
- MFT (src/file/mft.rs)
- ESE DB (Amcache, SRUM) under src/file/esedb
- Registry hives (HVE: Shimcache, Amcache)
- XML, JSON fallback
- Wraps external EVTX parser crate.
c. Analysis Engines
- Search engine (src/search.rs): string/regex/Tau (TAU engine wrapper in src/ext).
- Hunt engine (src/hunt.rs): loads Sigma rules (src/rule/sigma.rs), Chainsaw rules (src/rule/chainsaw.rs), applies mappings (mappings/*.yml), produces detections.
- Timeline analysis:
- Shimcache (src/analyse/shimcache.rs)
- SRUM (src/analyse/srum.rs) with SOFTWARE hive enrichment.
d. Rule Management
- src/rule module:
- chainsaw rules (rules/ directory of YAML files)
- Sigma conversion
- mappings directory holds YAML maps for field extraction for Sigma rules.
e. Output Writers
- src/write.rs and src/lib.rs: ASCII tables, CSV, JSON, JSONL.
- Writers are pluggable based on CLI flags.
f. Configuration & Packaging
- Cargo.toml, Cargo.lock: Rust build configuration.
- flake.nix/flake.lock, devShells: Nix-based development and packaging.
- .github/workflows for CI.

##### Data Flow and Interactions
- User invokes CLI → CLI Frontend parses args →
- For search/hunt: file parsers load artefacts → search or hunt engine filters/ matches → rule engine (Tau & Sigma) runs detection → output writer formats & writes results.
- For analyse shimcache: parse SYSTEM hive → apply regex patterns → optionally enrich with Amcache → output timeline.
- For analyse srum: parse SRUDB.dat & SOFTWARE hive → dynamic table extraction → JSON/CSV output.
- For dump: route to appropriate file parser → raw JSON/JSONL output.
- External services: none at runtime, all local.

##### Architectural Patterns and Principles
- Modular design: Each responsibility (parsing, rule matching, analysis, writing) is in its own module.
- Pluggable rule engine: supports two formats (Sigma, Chainsaw) via conversion and mapping layers.
- Single-binary CLI with subcommand pattern.
- Clear separation of concerns:
- src/file for I/O
- src/search, src/hunt, src/analyse for business logic
- src/rule for detection logic
- src/write for presentation.

##### Essential Elements
- Annotations for external libraries and config files (Cargo, flake).
- Modular boundaries and pluggable extension points (rules, mappings, regex patterns).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontend
    subgraph "CLI Frontend"
        CLI_Main["main.rs"]:::cli
        CLI_CLI["cli.rs"]:::cli
    end

    %% File Parsers
    subgraph "File Parsers"
        EVTX["EVTX Parser Wrapper"]:::parser
        MFT["MFT Parser"]:::parser
        XML["XML Parser (fallback)"]:::parser
        JSONP["JSON Parser (fallback/dump)"]:::parser
        subgraph "ESE DB Parsers"
            ESEDB_mod["mod.rs"]:::parser
            SRUDB_parser["srum.rs"]:::parser
        end
        subgraph "Registry Hive Parsers"
            HVE_mod["mod.rs"]:::parser
            Shimcache_parser["shimcache.rs"]:::parser
            Amcache_parser["amcache.rs"]:::parser
            HiveSRUM_parser["srum.rs"]:::parser
        end
    end

    %% Engines & Analysis
    subgraph "Engines & Analysis"
        SearchEngine["Search Engine"]:::engine
        TAU["TAU Engine Wrapper"]:::ext
        HuntEngine["Hunt Engine"]:::engine
        subgraph "Analysis Modules"
            Shim["Shimcache Analysis"]:::engine
            SRUM["SRUM Analysis"]:::engine
        end
    end

    %% Rule & Mapping
    subgraph "Rule & Mapping"
        ChainsawRule["Chainsaw Rules Loader"]:::rule
        SigmaRule["Sigma Rules Loader"]:::rule
        Mappings["Field Mappings"]:::rule
    end

    %% Output Writers
    subgraph "Output Writers"
        Writers["Writers (ASCII/CSV/JSON/JSONL)"]:::output
        LibAPI["Public API & Registration"]:::output
    end

    %% Configuration & Packaging
    subgraph "Config & Packaging"
        Cargo["Cargo.toml / Cargo.lock"]:::config
        Nix["flake.nix / flake.lock"]:::config
        CI[".github/workflows"]:::config
    end

    %% External Dependencies
    subgraph "External Dependencies"
        EVTXCrate["External EVTX Parser Crate"]:::ext
    end

    %% Connections
    CLI_CLI -->|"search"| SearchEngine
    CLI_CLI -->|"hunt"| HuntEngine
    CLI_CLI -->|"analyse shimcache"| Shim
    CLI_CLI -->|"analyse srum"| SRUM
    CLI_CLI -->|"dump"| EVTX

    %% Parsers usage
    SearchEngine -->|"reads artefacts"| EVTX
    SearchEngine --> MFT
    SearchEngine --> XML
    SearchEngine --> JSONP
    SearchEngine --> ESEDB_mod
    SearchEngine --> HVE_mod

    HuntEngine --> EVTX
    HuntEngine --> MFT
    HuntEngine --> ESEDB_mod
    HuntEngine --> HVE_mod

    Shim --> Shimcache_parser
    Shim --> Amcache_parser
    SRUM --> SRUDB_parser
    SRUM --> HiveSRUM_parser

    %% Engine internals
    SearchEngine --> TAU
    HuntEngine --> TAU
    HuntEngine --> ChainsawRule
    HuntEngine --> SigmaRule
    SigmaRule --> Mappings

    %% Outputs
    SearchEngine --> Writers
    HuntEngine --> Writers
    Shim --> Writers
    SRUM --> Writers
    EVTX --> Writers

    Writers --> LibAPI

    %% CI and Config not in runtime
    CLI_CLI --> Cargo
    CLI_CLI --> Nix
    CLI_CLI --> CI

    %% External crate usage
    EVTX --> EVTXCrate

    %% Click Events
    click CLI_Main "https://github.com/withsecurelabs/chainsaw/blob/master/src/main.rs"
    click CLI_CLI "https://github.com/withsecurelabs/chainsaw/blob/master/src/cli.rs"
    click EVTX "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/evtx.rs"
    click MFT "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/mft.rs"
    click XML "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/xml.rs"
    click JSONP "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/json.rs"
    click ESEDB_mod "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/esedb/mod.rs"
    click SRUDB_parser "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/esedb/srum.rs"
    click HVE_mod "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/hve/mod.rs"
    click Shimcache_parser "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/hve/shimcache.rs"
    click Amcache_parser "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/hve/amcache.rs"
    click HiveSRUM_parser "https://github.com/withsecurelabs/chainsaw/blob/master/src/file/hve/srum.rs"
    click SearchEngine "https://github.com/withsecurelabs/chainsaw/blob/master/src/search.rs"
    click TAU "https://github.com/withsecurelabs/chainsaw/blob/master/src/ext/tau.rs"
    click HuntEngine "https://github.com/withsecurelabs/chainsaw/blob/master/src/hunt.rs"
    click ChainsawRule "https://github.com/withsecurelabs/chainsaw/blob/master/src/rule/chainsaw.rs"
    click SigmaRule "https://github.com/withsecurelabs/chainsaw/blob/master/src/rule/sigma.rs"
    click Mappings "https://github.com/withsecurelabs/chainsaw/blob/master/mappings/sigma-event-logs-all.yml"
    click Writers "https://github.com/withsecurelabs/chainsaw/blob/master/src/write.rs"
    click LibAPI "https://github.com/withsecurelabs/chainsaw/blob/master/src/lib.rs"
    click Cargo "https://github.com/withsecurelabs/chainsaw/blob/master/Cargo.toml"
    click Nix "https://github.com/withsecurelabs/chainsaw/blob/master/flake.nix"
    click CI "https://github.com/withsecurelabs/chainsaw/blob/master/.github/workflows/v1.yml"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef parser fill:#bbf,stroke:#333,stroke-width:1px
    classDef engine fill:#bfb,stroke:#333,stroke-width:1px
    classDef rule fill:#ffb,stroke:#333,stroke-width:1px
    classDef output fill:#fbf,stroke:#333,stroke-width:1px
    classDef ext fill:#ccc,stroke:#333,stroke-width:1px
    classDef config fill:#cfc,stroke:#333,stroke-width:1px
```
