Meta-Forensics

Meta-Forensics is a Linux-native forensic triage and evidence analysis tool for Debian-based systems. It collects file metadata, hashes, strings, indicators, timeline events, live Linux artifacts, and structured reports for defensive investigations.

Features

• File hashing: MD5, SHA1, SHA256, SHA512
• File signature and entropy analysis
• IOC extraction for URLs, domains, IPs, paths, emails, hashes, and wallet strings
• PE, PDF, Office, LNK, registry-export, Prefetch, Amcache, ShimCache, and SRUM evidence parsing
• Linux live artifact checks using /proc, /proc/net, cron, systemd, XDG autostart, shell startup files, SSH keys, and USB sysfs paths
• Optional YARA, Sigma-style, ssdeep, TLSH, osslsigncode, and Graphviz support
• Reports in TXT, JSON, CSV, Markdown, HTML, DOT, STIX JSON, and manifest formats

Requirements

Minimum:

sudo apt update
sudo apt install -y g++ coreutils

Optional tools:

sudo apt install -y cmake yara ssdeep tlsh-tools osslsigncode graphviz

Build

Using the build script:

chmod +x build_debian.sh
./build_debian.sh

Using CMake:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j1

Usage

./meta-forensics --help
./meta-forensics analyze /path/to/evidence.bin --out reports
./meta-forensics analyze /path/to/directory --recursive --out reports
./meta-forensics memory --out reports
./meta-forensics cases list
./meta-forensics cases view default-case

Useful options:

--case CASE_ID
--evidence EVIDENCE_ID
--investigator NAME
--hostname HOSTNAME
--out REPORT_DIR
--recursive
--no-memory
--no-yara
--no-sigma
--no-pe
--no-artifacts
--no-live-artifacts
--no-stix-export
--export-overlay

Quick Test

./build_debian.sh
./meta-forensics --help
printf 'Meta-Forensics smoke test\n' > sample.txt
./meta-forensics analyze sample.txt --out test_reports --no-memory --no-live-artifacts --no-yara --no-sigma --no-pe --no-artifacts --no-stix-export
find test_reports -type f -size +0

Repository Layout

include/meta_forensics/   modular implementation headers
src/main.cpp              command-line entry point
docs/                     usage and output documentation
yara_rules/               optional YARA rules
sigma_rules/              optional Sigma-style rules
threat_db/                local IOC and signer lists
scripts/                  packaging helpers
.github/workflows/        CI build checks

Module Layout

common.hpp                shared includes, utility functions, file mapping
process.hpp               process execution and PATH lookup helpers
hash.hpp                  file and buffer hashing helpers
model.hpp                 result models, graph, timeline, threat database, context
signature.hpp             PE signature inspection and base64 helpers
core_ioc.hpp              core file analysis and IOC extraction
rules.hpp                 YARA and Sigma-style rule support
pe.hpp                    PE parser and executable analysis
documents_artifacts.hpp   document and artifact parsers
runtime.hpp               script decoding, similarity, process, memory, network checks
reports_cases.hpp         scoring, report export, case storage, analysis orchestration

Safe Use

Analyze unknown evidence read-only. Do not execute suspicious files. Store reports separately from original evidence.

License

MIT License. See LICENSE.