If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/WithSecureLabs/chainsaw shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 6d ago
• 12 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live WithSecureLabs/chainsaw repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/WithSecureLabs/chainsaw.

What it runs against: a local clone of WithSecureLabs/chainsaw — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in WithSecureLabs/chainsaw | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of WithSecureLabs/chainsaw. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/WithSecureLabs/chainsaw.git
#   cd chainsaw
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of WithSecureLabs/chainsaw and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "WithSecureLabs/chainsaw(\\.git)?\\b" \\
  && ok "origin remote is WithSecureLabs/chainsaw" \\
  || miss "origin remote is not WithSecureLabs/chainsaw (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "mappings/sigma-event-logs-all.yml" \\
  && ok "mappings/sigma-event-logs-all.yml" \\
  || miss "missing critical file: mappings/sigma-event-logs-all.yml"
test -f "rules/evtx" \\
  && ok "rules/evtx" \\
  || miss "missing critical file: rules/evtx"
test -f "analysis/shimcache_patterns.txt" \\
  && ok "analysis/shimcache_patterns.txt" \\
  || miss "missing critical file: analysis/shimcache_patterns.txt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/WithSecureLabs/chainsaw"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Chainsaw is a Rust-based forensic analysis tool that rapidly searches and hunts threats within Windows event logs (EVTX), MFT files, and other forensic artifacts. It integrates Sigma detection rules and custom Chainsaw rules via the TAU Engine for threat detection, shimcache timeline analysis, SRUM database inspection, and supports multiple output formats (ASCII, CSV, JSON). Built for incident response analysts who need fast first-response capability when EDR telemetry is unavailable. Monolithic Rust binary structure: src/ contains the main application code, rules/evtx/ holds YAML-formatted Sigma and Chainsaw detection rules organized by attack tactic (account_tampering, antivirus, applocker, etc.), mappings/ contains sigma-event-logs-all.yml for event ID mapping, and analysis/ holds pattern definitions (shimcache_patterns.txt). The tool wraps the evtx parser library and tau-engine for rule matching, with Nix support (flake.nix) for reproducible builds alongside standard Cargo.

Incident response analysts, forensic investigators, and threat hunters at enterprises (particularly WithSecure's managed detection and response clients) who need to rapidly triage Windows endpoints post-compromise without relying on deployed EDR agents. Also used by security researchers building detection logic.

Production-ready and actively maintained: v2.15.0 released with two CI workflows (.github/workflows/v1.yml and v2.yml), GPL3 licensed, and authored by James Dorgan and Alex Kornitzer from WithSecure Labs. The project demonstrates maturity through comprehensive rule libraries (rules/evtx/ contains hundreds of detection rules organized by tactics) and stable Rust dependencies. However, the edition = '2024' in Cargo.toml appears unusual and warrants verification—this may indicate recent Rust 2024 migration or be a configuration error.

Moderate dependency complexity with 20+ direct dependencies (tau-engine 1.0, evtx 0.11, libesedb 0.2.4, mft 0.6) and two patched crates pointing to forks (mft and notatin via alexkornitzer's GitHub), suggesting upstream abandonment or customization needs. The reliance on external forks for core parsing (MFT, NTFS) creates maintenance risk if those forks diverge. No visible test suite in the file structure hints at limited automated test coverage, though this is common in forensic tools.

Active development at v2.15.0 with two separate GitHub Actions workflows (v1.yml and v2.yml) indicating parallel release or testing pipelines. The comprehensive rule library in rules/evtx/ is regularly expanded—rules cover MITRE ATT&CK tactics from credential_access to lateral_movement with specific event ID detections (e.g., eid_8002_applocker, T1021.004 for SSH lateral movement). Nix flake support (flake.lock, flake.nix) suggests recent efforts toward reproducible builds and developer environment consistency.

Clone and build with Cargo: git clone https://github.com/WithSecureLabs/chainsaw.git && cd chainsaw && cargo build --release. The binary will be at target/release/chainsaw. Alternatively, build with Nix: nix flake update && nix build. Run ./target/release/chainsaw --help to see CLI options for search, hunt, and analysis subcommands.

Daily commands: cargo build --release compiles to target/release/chainsaw. Run subcommands: chainsaw search --evtx <path> --keyword <string> for keyword search, chainsaw hunt --evtx <path> --rules rules/evtx/ --mapping mappings/sigma-event-logs-all.yml for Sigma detection, chainsaw analyse shimcache --path <shimcache_file> for timeline analysis. Output formats controlled via --output json|csv|ascii flags.

• Cargo.toml — Defines all dependencies (evtx, mft, libesedb, chrono) and project metadata; essential to understand build requirements and external forensic parsing libraries.
• README.md — Describes Chainsaw's core mission: hunting Windows forensic artifacts via Sigma rules and custom detection rules; read first to understand the project scope.
• mappings/sigma-event-logs-all.yml — Central mapping configuration that bridges Windows Event Log event IDs to Sigma rule fields; critical for rule evaluation engine.
• rules/evtx — Root directory containing all detection rules organized by threat category (account_tampering, lateral_movement, persistence, etc.); defines the threat models Chainsaw hunts.
• analysis/shimcache_patterns.txt — Pattern definitions for timeline analysis of Shimcache artifacts; enables execution timeline reconstruction from Windows forensic data.
• .github/workflows/v1.yml — CI/CD pipeline definition; shows how Chainsaw is built, tested, and released as a Rust binary.
• Cargo.lock — Locks all transitive dependencies to ensure reproducible builds of this forensic analysis tool across environments.

Add a New Detection Rule

1. Create a new YAML file in the appropriate threat category directory under rules/evtx/ (e.g., rules/evtx/persistence/ for a persistence rule). (rules/evtx/{category}/{rule_name}.yml)
2. Define the rule using Sigma or Chainsaw detection syntax with event ID filters, field matchers, and condition logic. (rules/evtx/{category}/{rule_name}.yml)
3. Verify the rule's event log field mappings exist in mappings/sigma-event-logs-all.yml; add missing field mappings if needed. (mappings/sigma-event-logs-all.yml)

Add Forensic Artifact Pattern Analysis

1. Add regex or pattern definitions to analysis/shimcache_patterns.txt for parsing new forensic artifact types (e.g., Amcache, SRUM database fields). (analysis/shimcache_patterns.txt)
2. Update Cargo.toml if new parsing libraries (like mft, libesedb alternatives) are needed for artifact extraction. (Cargo.toml)

Add Support for a New Event Log Type

1. Create a new category directory under rules/evtx/ (e.g., rules/evtx/new_log_type/) for rules targeting that log source. (rules/evtx/{new_log_type})
2. Map the new event log's event IDs and field names in mappings/sigma-event-logs-all.yml to enable Sigma rule evaluation. (mappings/sigma-event-logs-all.yml)
3. Add sample detection rules in the new category directory (one per .yml file) covering key threat indicators. (rules/evtx/{new_log_type}/{threat_indicator}.yml)

Update Dependencies or Add New Forensic Parsers

1. Update dependency versions in Cargo.toml (e.g., evtx, mft, libesedb for new artifact types). (Cargo.toml)
2. Run cargo update to regenerate Cargo.lock with new transitive dependencies. (Cargo.lock)
3. Verify CI/CD workflow tests pass in .github/workflows/v1.yml or v2.yml after dependency changes. (.github/workflows/v1.yml)

• Rust + evtx, mft, libesedb crates — Memory-safe, high-performance parsing of binary forensic artifacts (EVTX event logs, MFT file records, ESE databases); prevents buffer overflows and enables rapid scanning of large forensic datasets.
• Sigma Detection Rules (YAML format) — Standardized, community-maintained threat detection rules that map to Windows Event Log event IDs; enables code reuse across multiple forensic tools and easier rule sharing.
• Custom Chainsaw Detection Rules — Chainsaw-specific rule format for hunters who need flexibility beyond Sigma schema; supports complex field matching, regex, and timeline correlation impossible in generic Sigma rules.
• chrono + chrono-tz — Accurate timestamp parsing and timezone handling for forensic event correlation; critical for reconstructing attack timelines across systems with different locale settings.
• GitHub Actions CI/CD (v1.yml, v2.yml) — Automated testing and cross-platform binary releases (Windows, Linux, macOS) for forensic investigators; ensures reproducible builds of this safety-critical forensic tool.

• YAML-based rule definitions over embedded DSL

  • Why: Enables non-developers (threat hunters, SOC analysts) to write detection rules without modifying Rust code; lowers barrier to rule contribution.
  • Consequence: Requires a rule parser in the Rust codebase and YAML validation; rules cannot use arbitrary Rust logic, limiting expressiveness for very complex detections.

• Support both Sigma and custom Chainsaw rule formats

  • Why: Sigma rules provide community consensus; custom rules enable Chainsaw-specific optimizations for forensic timelines (Shimcache + Amcache correlation).
  • Consequence: Dual rule engine increases code complexity; maintains two rule schemas and mappers (sigma-event-logs-all.yml vs custom rule syntax).

• Linear event scanning with rule evaluation (vs. indexed database)

  • Why: Works offline on forensic image; no preprocessing or indexing step required; simple deployment for first-responders with read-only forensic artifacts.
  • Consequence: O(n) runtime per rule; slower on very large event logs (millions of events); cannot support complex cross-log correlations requiring indexed joins.

• Shimcache/Amcache timeline enrichment via file patterns (vs. full database parsing)

  • Why: Lightweight pattern matching (analysis/shimcache_patterns.txt) avoids heavyweight ESE database parsing overhead; faster timeline generation.
  • Consequence: Pattern-based extraction may miss edge cases or new artifact formats; less accurate than full binary parser but acceptable for hunting workflows.

• Does not perform real-time monitoring; operates only on forensic artifacts (event logs, MFT, databases) for post-incident analysis.
• Does not handle authentication, access control, or role-based rule filtering; designed for single-user forensic investigator workflows.
• Does not include a GUI; command-line only interface for reproducible, scriptable forensic investigations.
• Does not normalize or transform rules across different forensic tool formats; focuses on Windows EVTX and Sigma rule ecosystem.
• Does not perform remediation or incident response actions; strictly a detection and data extraction tool.

The edition = '2024' in Cargo.toml is non-standard (Rust stable editions are 2015/2018/2021); verify this is intentional or correct to the appropriate edition. Two dependencies are patched via Git forks (mft and notatin from alexkornitzer), so building may fail if those forks are unavailable or diverge from crate versions—test offline builds. The tool expects Windows forensic artifacts (EVTX, MFT, shimcache) as input; testing on Linux/macOS requires sample artifacts. No visible test directory or test files in the file listing suggests minimal automated test coverage—manual integration testing with real artifacts is likely necessary. The TAU Engine library may have its own rule syntax nuances not fully documented here; check tau-engine documentation (https://github.com/WithSecureLabs/tau-engine) for rule evaluation behavior.

• Sigma Detection Rules — Chainsaw's core hunting capability relies on Sigma YAML rules (in rules/evtx/) that define threat patterns; understanding Sigma's field naming, condition logic, and event ID filtering is essential for creating or modifying detections.
• Windows Event Logs (EVTX) Structure — Chainsaw parses EVTX binary files via the evtx crate and maps Sigma fields to Windows Event Log fields (mappings/sigma-event-logs-all.yml); understanding EVTX event structure, event IDs, and field naming is critical for rule authoring and debugging.
• Master File Table (MFT) Parsing — Chainsaw includes MFT dump and search functionality (dependency: mft crate); MFT contains NTFS file records with timestamps and file metadata essential for timeline analysis in forensic investigations.
• Shimcache (Application Compatibility Cache) — Chainsaw's analyse shimcache subcommand extracts execution timelines from Windows shimcache artefacts (analysis/shimcache_patterns.txt) enriched with Amcache; shimcache records program execution history predating Event Logs for initial compromise assessment.
• SRUM Database (System Resource Usage Monitor) — Chainsaw provides SRUM database analysis (via libesedb dependency for ESE database parsing); SRUM contains network and application resource usage metrics useful for tracking malware C2 communications and lateral movement.
• Parallel Processing with Rayon — Chainsaw uses rayon (1.5) for parallel EVTX parsing across multiple cores (especially important for large-scale incident response with gigabytes of event logs); understanding data parallelism patterns is relevant for performance optimization.
• MITRE ATT&CK Framework — Chainsaw's rule library is organized by MITRE ATT&CK tactics (rules/evtx/account_tampering, lateral_movement, defense_evasion, etc.); familiarity with ATT&CK technique IDs (e.g., T1021.004) is essential for threat hunting and rule categorization.

• SigmaHQ/sigma — Chainsaw ingests and evaluates Sigma detection rules; this is the upstream rule repository that provides the generic rule format and collection that mappings/sigma-event-logs-all.yml adapts for Windows.
• WithSecureLabs/tau-engine — Core dependency (tau-engine 1.0 in Cargo.toml) that powers Chainsaw's Sigma rule evaluation and tagging—understanding TAU Engine's API is essential for extending Chainsaw's detection logic.
• omerbenamram/evtx — The EVTX parser library (evtx = '0.11' dependency) that Chainsaw wraps for Windows Event Log parsing—understanding evtx's event structure and API is necessary for parsing enhancements.
• alexkornitzer/mft — Patched fork of the mft crate (via [patch.crates-io]) used for MFT file parsing in Chainsaw's dump and search functionality—custom fork indicates WithSecure-specific enhancements.
• libyal/libevtx — Low-level C library for EVTX parsing that inspired the Rust evtx crate; relevant for understanding EVTX binary format and forensic event log structure underlying Chainsaw.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Sigma rule detection against sample EVTX files

The repo contains extensive Sigma detection rules across rules/evtx/ (account_tampering, antivirus, applocker, credential_access, etc.) but there are no visible integration tests validating these rules work correctly. New contributors could create a test suite that parses sample EVTX files and verifies the Sigma rules produce expected detections, ensuring rule quality and preventing regressions.

• [ ] Create tests/ directory with integration test structure
• [ ] Add sample EVTX files or fixtures in tests/fixtures/evtx/ for common event types
• [ ] Write integration tests in tests/sigma_rule_detection.rs that load rules from rules/evtx/ and validate detection output
• [ ] Integrate tests into .github/workflows/ (v1.yml or v2.yml) to run on every PR

Add comprehensive unit tests for timeline generation from Shimcache and Amcache parsing

The README highlights timeline creation by analyzing Shimcache and enriching with Amcache data (analysis/shimcache_patterns.txt exists), but there's no visible test coverage for the Shimcache/Amcache parsing logic. This is a forensically critical feature where incorrect parsing could hide evidence. New contributors could add unit tests validating correct extraction and timeline enrichment.

• [ ] Locate shimcache and amcache parsing code in src/ (likely src/main.rs or dedicated modules)
• [ ] Create tests/shimcache_amcache_tests.rs with unit tests for timestamp parsing, entry extraction, and enrichment logic
• [ ] Add test fixtures with real Shimcache/Amcache binary samples in tests/fixtures/
• [ ] Document expected behavior in test comments and add assertion coverage for edge cases (corrupted entries, timezone handling)

Create GitHub Actions workflow for cross-platform Rust compatibility testing (Windows/Linux/macOS)

The repo targets Windows forensic artifacts but only has v1.yml and v2.yml workflows (content not shown). A Rust project should test compilation and basic functionality across platforms. New contributors could add a matrix-based workflow ensuring the binary compiles and core functionality works on all major platforms, improving portability and catching platform-specific bugs early.

• [ ] Review existing .github/workflows/v1.yml and v2.yml to understand current CI structure
• [ ] Create .github/workflows/cross-platform-test.yml with matrix testing for ubuntu-latest, windows-latest, and macos-latest
• [ ] Add cargo build, cargo test, and cargo clippy checks for each platform
• [ ] Ensure proper handling of platform-specific dependencies (e.g., Windows-only evtx parsing) with feature flags if needed

• Add integration tests for rules/evtx/ detection rules: the repo lacks visible test/ directory or test cases validating that Sigma rules in rules/evtx/antivirus/windows_defender.yml and rules/evtx/account_tampering/ correctly match expected event structures. Create test fixtures with mock EVTX events and assert rule hits.: Ensures rule correctness and prevents regressions as rules are added/modified; improves maintainability.
• Document the mappings/sigma-event-logs-all.yml schema and extend coverage: the file bridges Sigma and Windows Event Logs but lacks inline documentation explaining the mapping format. Add comments to the YAML file and create docs/ guide showing how to add mappings for new event IDs.: Onboarding new contributors and power users who want to add custom event mappings for organization-specific event logs.
• Expand shimcache timeline analysis: analysis/shimcache_patterns.txt exists but no clear documentation of pattern syntax or examples. Create docs/SHIMCACHE_ANALYSIS.md with pattern examples, regex syntax, and example output; add 3-5 new pattern definitions for modern Windows 10/11 shimcache artifacts.: Shimcache timeline analysis is a unique Chainsaw feature; better documentation and patterns increase its forensic utility.

The Chainsaw project demonstrates generally good security practices with well-maintained dependencies and clear licensing (GPL3). However, there are several areas for improvement: (1) the reliance on patched upstream dependencies that appear abandoned should be monitored and documented, (2) a critical build configuration error exists with an invalid Rust edition that will prevent compilation, and (3) security infrastructure like vulnerability disclosure policies and SBOMs are absent. The project would benefit from enhanced supply chain security documentation and resolution of the build configuration issue before release. Overall security posture is reasonable for a forensic analysis tool, but operational security processes should be formalized.

• Medium · Dependency on Patched Upstream Projects — Cargo.toml - [patch.crates-io] section. The project uses patched versions of 'mft' and 'notatin' from forked GitHub repositories instead of the official crates.io versions. While this is documented in [patch.crates-io], it indicates the upstream projects may be abandoned or unmaintained. This could lead to unpatched security vulnerabilities in these dependencies. Fix: Regularly audit the patched dependencies for security vulnerabilities. Consider contributing patches back to upstream projects or transitioning to actively maintained alternatives. Document the reasons for patching and establish a schedule for reviewing security updates.
• Low · Invalid Rust Edition in Cargo.toml — Cargo.toml - edition field. The Cargo.toml specifies edition = '2024', which is not a valid Rust edition. Valid editions are 2015, 2018, and 2021. This will cause compilation failures and indicates potential misconfiguration or typo in the build configuration. Fix: Correct the edition to a valid value (recommended: '2021' for modern Rust projects). Verify the build configuration and ensure CI/CD pipelines catch such errors.
• Low · Use of Lazy Initialization with lazy_static — Cargo.toml - lazy_static dependency. The project uses 'lazy_static' (version 1.4.0) which is deprecated in favor of 'once_cell'. While 'once_cell' is already included as a dependency, 'lazy_static' may introduce unnecessary code and potential issues. Fix: Migrate from lazy_static to once_cell, which is already a dependency. This reduces the attack surface and uses more modern Rust patterns.
• Low · Missing Security.txt and Vulnerability Disclosure Policy — Repository root. The repository does not appear to have a security.txt file or clear vulnerability disclosure policy based on the provided file structure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file or .well-known/security.txt with clear instructions for reporting security vulnerabilities. Include contact information and expected response times.
• Low · Rand Crate Used Without Cryptographic Verification Context — Cargo.toml - rand dependency. The project includes 'rand' (version 0.10) as a dependency. While rand is a general-purpose random number generator, if used for security-sensitive operations, it should be verified that crypto-grade randomness (rand::rngs::OsRng or getrandom) is used, not thread_rng(). Fix: Audit the codebase to ensure that security-sensitive operations (UUID generation shown in dependencies) use cryptographically secure random sources. Document the usage of rand in the codebase.
• Low · No SBOM (Software Bill of Materials) Provided — Repository root. The repository does not appear to include a software bill of materials (SBOM) or supply chain security documentation, making it difficult for users to assess supply chain risks. Fix: Generate and publish an SBOM using tools like cargo-sbom or syft. Include it in release artifacts and update it regularly with dependency changes.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.