How withsecurelabs/chainsaw works
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).