DEV Community

Shakhzhakhan Maxudbek
Shakhzhakhan Maxudbek

Posted on • Originally published at args.tech

Hypoxia: Dependency-Free Python CLI for DFIR & Recovery

#forensic #dfir #cli #python

Introduction

When responding to a security incident or recovering data from a failing drive, speed and precision are critical. Manually sifting through terabytes of data or writing complex shell one-liners on the fly often leads to wasted time and missed artifacts. Hypoxia is a lightweight, dependency-free, cross-platform command-line tool designed for targeted file extraction and backup. Written entirely in standard Python (3.11+), it recursively searches directories and collects files based on a granular set of criteria-including extensions, modification dates, and size boundaries.

Built for efficiency and portability, Hypoxia serves as an essential utility for digital forensics specialists, incident responders, and system administrators who need to rapidly gather digital evidence or recover data from mounted, unbootable filesystems.

What's New in 1.3.0?

The latest release evolves Hypoxia from a standard file recovery script into a robust Digital Forensics and Incident Response (DFIR) utility. The 1.3.0 update introduces several core features designed specifically for evidence integrity and reliable data extraction:

  • Forensic Manifest & Hashing: Automatically generates a JSON manifest for every collection task. This manifest includes the SHA-256 hash, original path, destination path, file size, timestamps, and an overall manifest checksum for strict integrity verification.
  • Chain of Custody Log: Maintains an append-only forensic log with timestamped entries for every action performed during execution. By logging files copied, skipped, and any errors encountered, it establishes a verifiable chain of custody.
  • Checkpoint/Resume: Provides resilience against interrupted collections caused by system crashes, power loss, or dying physical media. By utilizing the --resume flag with a previous forensic log, the extraction continues exactly from where it stopped-verified by path and hash-preventing wasted time and duplicate files.
  • Archive Output & Directory Exclusion: Introduces the --zip flag to seamlessly compress the entire collection into a single archive upon completion. Additionally, the --exclude parameter allows for skipping unwanted directories (such as system folders or .git), significantly speeding up the scanning process.

Installation & Quick Start

Hypoxia can be deployed either as a compiled binary or run directly from the source code. To get started quickly without installing any dependencies, download the standalone executable from the latest release and set the executable flag.

chmod +x hypoxia
Enter fullscreen mode Exit fullscreen mode

Verify the installation and review the available command-line arguments by accessing the help menu.

./hypoxia --help
Enter fullscreen mode Exit fullscreen mode

Alternatively, Hypoxia can be executed directly as a Python script. First, clone the repository to the local machine.

git clone https://github.com/xinitd/hypoxia.git
Enter fullscreen mode Exit fullscreen mode

Navigate into the cloned directory.

cd hypoxia
Enter fullscreen mode Exit fullscreen mode

Make the main Python script executable.

chmod +x hypoxia.py
Enter fullscreen mode Exit fullscreen mode

Advanced Use Cases

Case 1: Incident Response & Web Shell Triage

When a server is compromised, isolating modified files within a specific timeframe is the immediate priority. Hypoxia automates this process by filtering files based on the exact incident window. Extracting modified web server logs while explicitly excluding irrelevant or heavy archive directories accelerates the triage phase.

./hypoxia -v info -s "/var/log" -e "log,txt" --date-from "2026-03-20" --date-to "2026-03-23" --exclude "archives,old" -m yes
Enter fullscreen mode Exit fullscreen mode

Threat actors frequently drop web shells disguised as standard scripts. Locating potentially malicious files created or modified after the initial breach date in the web application root ensures critical artifacts are isolated with their original metadata intact.

./hypoxia -v info -s "/var/www/html" -e "php,sh,py" --date-from "2026-03-20" -m yes
Enter fullscreen mode Exit fullscreen mode

Case 2: Digital Forensics Evidence Gathering

Maintaining the integrity of digital evidence is mandatory in forensic investigations. Hypoxia ensures this by calculating cryptographic hashes and documenting every action. Creating a comprehensive forensic snapshot of document files, generating SHA-256 hashes for the manifest, and automatically packing the collected evidence into a single ZIP archive provides a secure artifact container.

./hypoxia -v info -s "/home/user/Documents" -e "pdf,docx,xlsx" --hash "sha256" --zip
Enter fullscreen mode Exit fullscreen mode

During investigations involving persistence mechanisms, extracting specific system configuration files linked to a suspected breach is necessary. Running the extraction with hashing enabled ensures the operation generates a complete JSON manifest and appends the actions to the verifiable chain of custody log.

./hypoxia -v info -s "/etc" -e "conf,xml" --hash "sha256" -m yes
Enter fullscreen mode Exit fullscreen mode

Case 3: Interrupted Data Recovery from Dying Media

When recovering data from a failing hard drive, the hardware connection might drop unexpectedly. Instead of restarting the entire extraction from the beginning and recopying gigabytes of data, Hypoxia can utilize a previous forensic log to resume the process.

./hypoxia -v info -s "/mnt/failing_drive/user" -e "jpg,mp4,docx" --resume "/path/to/hypoxia_forensic_log.jsonl"
Enter fullscreen mode Exit fullscreen mode

To avoid stressing the dying media with unnecessary read operations, it is crucial to exclude large or corrupted files from the recovery attempt. Setting a strict upper size limit ensures only viable documents and images are extracted from the mounted drive.

./hypoxia -v info -s "/mnt/failing_drive/user" -e "pdf,docx,jpg" --size-max "50mb"
Enter fullscreen mode Exit fullscreen mode

Case 4: Targeted Malware Artifact Extraction

Security researchers often need to extract potential malware samples without pulling in benign system files. Setting minimum and maximum size boundaries helps isolate suspicious executables that fit a specific profile.

./hypoxia -v info -s "/tmp" -e "elf,sh,bin" --size-min "10kb" --size-max "5mb" --hash "sha256"
Enter fullscreen mode Exit fullscreen mode

Isolating dropped payloads from hidden or temporary directories requires precision. Filtering by exact creation dates while skipping standard application folders accelerates the artifact extraction process.

./hypoxia -v info -s "/var/tmp" -e "py,pl,sh" --date-from "2026-03-22" --exclude "systemd,snap" --hash "sha256"
Enter fullscreen mode Exit fullscreen mode

Case 5: Smart Sysadmin Backups

System administrators require lightweight, focused backups of configuration files rather than complete directory dumps. Archiving deployment manifests and environment variables while explicitly preserving critical metadata ensures secure and precise backups.

./hypoxia -v info -s "/opt/docker_apps" -e "yml,env,conf" -m yes --zip
Enter fullscreen mode Exit fullscreen mode

Blindly backing up an entire configuration directory can accidentally include massive database dumps or rotated logs. Enforcing a strict size limit guarantees the resulting configuration backup remains lightweight and relevant.

./hypoxia -v info -s "/etc" -e "conf,yaml,ini" --size-max "10mb" --exclude "alternatives,ssl"
Enter fullscreen mode Exit fullscreen mode

Conclusion

Targeted file collection is a practical necessity for digital forensics, incident response, and routine system administration. Traditional tools often require chaining multiple commands to achieve granular filtering and verification. Hypoxia simplifies this workflow by providing a single, dependency-free utility capable of cryptographic hashing, checkpoint resuming, and advanced attribute filtering. Whether isolating evidence after a security breach, recovering critical documents from a failing drive, or extracting lightweight configuration backups, it offers a precise and portable solution.

For the latest releases, full documentation, and source code, visit the official GitHub repository.

Top comments (0)