PFM — Pure Funky Magic

A command-line data manipulation tool for security analysts and incident responders. Chain encoding, decoding, compression, and crypto modules to transform data locally without sending it to third-party websites.

This project originated from mari0d/PFM on GitHub and has been significantly extended here.

Getting started

Install with pipx (recommended)

pipx installs PFM into an isolated environment and puts both CLI commands on your PATH permanently. No source activate needed.

brew install pipx
pipx ensurepath          # adds ~/.local/bin to $PATH (restart your shell after)
pipx install /path/to/PFM

After that, both commands are available anywhere:

echo "SGVsbG8=" | pfm from_base64
pfm --list

pfm-server               # http://localhost:5000

To upgrade after pulling new changes:

pipx reinstall pfm

Install for development (venv)

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
source .venv/bin/activate

echo "SGVsbG8=" | pfm from_base64
pfm --list

Docker

docker build -t pfm .
docker run --rm -p 5000:5000 pfm

# CLI inside the container
echo "SGVsbG8=" | docker run --rm -i pfm pfm from_base64

# Persist the data/ directory across restarts
docker run --rm -p 5000:5000 -v "$PWD/data:/app/data" pfm

Layout

pfm.py              CLI entry point (installed as pfm)
pfm_core.py         Shared chain execution logic
modules/            One .py file per module
web/pfm_server.py   Flask web server (installed as pfm-server)
web/                JavaScript, CSS, and image assets
tests/              Test suite and fixtures
docs/               Documentation
Dockerfile          Container image (serves pfm-server on port 5000)

Documentation

• Usage and chaining — CLI flags, saved chains, slicing, data fidelity
• Module reference — all modules grouped by category
• pcap analysis — triage, file extraction, anomaly detection, worked examples
• Analyst workflows — common investigation patterns
• Web UI and JSON API — output modes, API, configuration, security notes
• Adding a module — template, conventions, testing

Quick examples

# Decode a PowerShell -EncodedCommand payload
echo "<blob>" | pfm from_base64 from_wide

# Auto-decode unknown encoding stack
echo "<blob>" | pfm do_pfm

# Triage a pcap
pfm -i suspicious.pcap do_pcap_analysis

# Extract IOCs and defang for a report
pfm -i script.ps1 do_extract_iocs do_defang

Testing

pytest tests/
pytest tests/ -k TestXOR    # single class