FIR

Freedom Incident Response: a Windows DFIR artifact collection and triage tool written in Go.

Overview

FIR is a Windows first-response triage tool: it collects forensic artifacts, parses them into CSV, and packages the run with integrity metadata. Collectors and analyzers sit behind a shared module contract, and one engine drives both an interactive terminal UI and a flag-driven CLI.

Features

• Two modes: an interactive Bubble Tea workflow, or fir collect for automation. Collectors run alone by default; --analyze adds the matching parsers.
• Native Windows acquisition: backup semantics, registry hive save APIs, and raw NTFS reads — $MFT, $UsnJrnl:$J and $Secure:$SDS from every fixed drive, not just C:. Requires Administrator, and enables the backup, restore, security and debug privileges at startup.
• Self-tuning concurrency: no worker knob. FIR surveys the drives a run reads and writes, then picks a worker count per phase — collection backs off on spinning media, analysis scales with free RAM. The numbers and the reasoning land in manifest.json.
• Caps that reach child processes: CPU and disk limits go through a Windows Job Object, so winpmem and the PowerShell-hosted analyzers are covered rather than quietly exempt. Disk throttling is opt-in.
• Partial-failure tolerant: a module fails only if it collected nothing; partial errors surface as warnings instead of hiding the artifacts that did come through.
• Structured output: manifest.json, summary.txt, collector.log, a storage estimate before the run, and an optional ZIP with a .sha256 sidecar.

Tech Stack

Language

CLI and TUI

Windows and Storage

Quick Start

Prerequisites

• Operating system: Windows 10/11 or Windows Server 2016+
• Privileges: Administrator is required — FIR exits immediately with an error if not run elevated
• Go: 1.26+ for building from source

Installation

1. Clone the repository:

git clone https://github.com/Liuchijang/FIR.git
cd FIR

2. Build the executable:

go build -trimpath -buildvcs=false -ldflags "-s -w" -o fir.exe .

Usage

Interactive Mode

Run FIR without a subcommand:

.\fir.exe

Interactive mode lets you select modules, review runtime configuration, watch live module status, and view the final collection summary.

Flag Mode

fir collect runs collector modules only by default — analyzers (*_parser, autoruns, process_explorer, etc.) are skipped even if a category or all would otherwise include them.

Collect specific artifacts:

.\fir.exe collect --artifact registry,eventlog,prefetch

Collect by category:

.\fir.exe collect --artifact ntfs,execution

Collect everything:

.\fir.exe collect --artifact all

Collect and then run the matching analyzers:

.\fir.exe collect --artifact eventlog --analyze

Use a custom output directory and timeout:

.\fir.exe collect --artifact registry,eventlog --output C:\triage --timeout 10m

Run with resource controls:

.\fir.exe collect --artifact all --output E:\evidence --cpu-limit 60 --disk-io 80MB

Disable compression:

.\fir.exe collect --artifact ntfs --no-compress

Common Flags

Flag	Description
-o, --output	Base output directory for collected artifacts
-v, --verbose	Enable verbose/debug output
-a, --artifact	Comma-separated list of artifacts or categories
--analyze	Also run the analyzer modules for the selected artifacts/categories (default: collect only)
-t, --timeout	Optional timeout per module; 0 disables timeout
--cpu-limit	CPU limit percentage, applied to FIR and every process it spawns via a Windows Job Object
--disk-io	Cap disk bandwidth for FIR and every process it spawns, for example 80MB. No cap by default
--compress	Compress run directory after collection; enabled by default
--no-compress	Disable run directory compression

Available Modules

Collectors

Name	Category	Description
browser	browser	Collects browser forensic artifacts from supported Chromium and Firefox profiles
eventlog	eventlog	Collects Windows Event Log files (.evtx)
amcache	execution	Collects Amcache.hve and transaction logs
prefetch	execution	Collects Windows Prefetch files (.pf)
ram	memory	Acquires physical memory using winpmem
mft	ntfs	Collects the $MFT via raw disk access, from every fixed drive
secure_sds	ntfs	Collects the $Secure:$SDS stream, from every fixed drive
usnjrnl	ntfs	Collects the $UsnJrnl:$J USN Change Journal, from every fixed drive
registry	registry	Collects primary registry hives and transaction logs (excludes SECURITY, which requires SYSTEM, not just Administrator)
srum	system	Collects the SRUM database (SRUDB.dat)
wmi	system	Collects WMI repository files

Analyzers

Name	Category	Description
autoruns	live	Generates live autoruns-style triage CSV
process_explorer	live	Generates live process, module, and network triage CSV
amcache_parser	execution	Parses Amcache artifacts
browser_history_parser	browser	Parses Chromium browser history artifacts
eventlog_parser	eventlog	Parses EVTX logs
mft_parser	ntfs	Parses $MFT into CSV
prefetch_parser	execution	Parses Prefetch artifacts
recentdocs_parser	registry	Parses RecentDocs entries
runmru_parser	registry	Parses RunMRU entries
secure_sds_parser	ntfs	Parses Secure SDS data
shimcache_parser	registry	Parses ShimCache
userassist_parser	registry	Parses UserAssist
usnjrnl_parser	ntfs	Parses USN records and enriches with MFT when available
wmi_parser	system	Parses WMI artifacts

Category Shortcuts

Use browser, eventlog, execution, live, memory, ntfs, registry, system, or all.

Output

A typical run creates a timestamped directory:

HOSTNAME_YYYYMMDD_HHMMSS/
  collector.log
  manifest.json
  summary.txt
  collected/
  analysis/

When compression is enabled, FIR writes:

HOSTNAME_YYYYMMDD_HHMMSS.zip
HOSTNAME_YYYYMMDD_HHMMSS.zip.sha256

A collected memory image is delivered next to the archive rather than inside it:

HOSTNAME_YYYYMMDD_HHMMSS_memory.raw

A RAM dump is high-entropy and barely compresses, while zipping it would need a second full-size copy on disk at the same time — on a 32GB host, the difference between needing ~38GB free and ~69GB. The interactive run config says so before the run starts, and manifest.json lists the file under uncompressed_files.

manifest.json is the source of truth for run configuration, storage estimates, module results, hashes, and output metadata.

RAM Acquisition

FIR does not bundle winpmem. To enable RAM acquisition, place winpmem_mini_x64.exe in one of these locations:

• Same directory as fir.exe
• Current working directory
• System PATH

If winpmem is not found, the RAM module fails gracefully and records the error in the run summary.

Project Structure

FIR/
  cmd/                 Cobra commands and runtime option parsing
  internal/
    acquisition/       Low-level Windows and raw disk acquisition helpers
    analyzers/         Parsed and enriched output modules
    artifact/          Artifact layout helpers
    collection/        Module resolution, runner, and executor
    collectors/        Artifact acquisition modules grouped by category
    console/           Console/window handling
    logging/           Session logger
    module/            Shared collector/analyzer module contracts and registry
    output/            Manifest, archive, summary, and output writer
    platform/          Host/platform helpers
    resource/          Resource config, estimates, and disk checks
    tui/               Bubble Tea interactive UI
    utils/             Windows privilege, hashing, and file helpers
  main.go              Application entry point
  go.mod               Go module definition
  go.sum               Go dependency checksums

Runtime flow:

main -> cmd -> module registry -> collection runner -> collectors/analyzers -> output/logging

Security and Legal Notice

FIR is intended for authorized forensic investigation and incident response only. Run it only on systems where you have explicit permission to collect artifacts.

Contributing

1. Fork the repository.
2. Create a feature or fix branch.
3. Keep changes focused and aligned with the module structure.
4. Update documentation when behavior changes.
5. Submit a pull request.

License

This project is licensed under the MIT License.

Support

• Issues: GitHub Issues
• Repository: Liuchijang/FIR

---

Star this repository if FIR is useful for your incident response workflow.

Made by Liuchijang