yrfy - YARAify CLI Client

A command-line tool for interacting with the YARAify API.

Part of the abuse.ch CLI toolkit - This project is part of a collection of CLI tools for interacting with abuse.ch services:

• urlhs - URLhaus (malware URL database)
• tfox - ThreatFox (IOC database)
• yrfy - YARAify (YARA scanning)
• mbzr - MalwareBazaar (malware samples)

Features

• ✅ Uses only Go standard libraries
• 📝 JSON output for easy parsing
• ⚡️ Built-in rate limiting (10 req/s)
• 🐳 Docker, Podman, and Apple container support
• 🔍 YARA and ClamAV scanning
• 📦 Optional malware unpacking

Installation

Using Homebrew

brew install andpalmier/tap/yrfy

Using Go

go install github.com/andpalmier/yrfy@latest

Using Container (Docker/Podman)

# Pull pre-built image
docker pull ghcr.io/andpalmier/yrfy:latest

# Or build locally
docker build -t yrfy .

From Source

git clone https://github.com/andpalmier/yrfy.git
cd yrfy
make build

Quick Start

1. Get your API key from abuse.ch Authentication Portal

2. Set your API key:

export ABUSECH_API_KEY="your_api_key_here"

3. Scan a file:

yrfy scan -file malware.exe

Usage

Commands

Command	Description
scan	Scan a file with YARA and ClamAV
task	Get results for a scan task
query	Query by hash, YARA rule, ClamAV, or fuzzy hash
version	Show version information

Scan Files

# Basic scan
yrfy scan -file malware.exe

# Scan with unpacking (PE files only)
yrfy scan -file packed.exe -unpack

# Private scan (don't share)
yrfy scan -file private.exe -no-share

# Skip if already known
yrfy scan -file sample.exe -skip-known

Get Task Results

# Get scan results
yrfy task -id fb2763e9-7b84-11ec-9f01-42010aa4000b

# With Malpedia token for non-public YARA rules
yrfy task -id fb2763e9-7b84-11ec-9f01-42010aa4000b -malpedia-token YOUR_TOKEN

Query Data

# By file hash
yrfy query -hash b0bb095dd0ad8b8de1c83b13c38e68dd

# By YARA rule
yrfy query -yara MALWARE_Win_Emotet -limit 50

# By ClamAV signature
yrfy query -clamav Win.Malware.Emotet

# By imphash
yrfy query -imphash 43fd39eb6df6bf3a9a3edd1f646cd16e

# By TLSH
yrfy query -tlsh T138F423C1EB53E7E1C8EF4D38920FFB6546...

Container Usage

# Run with Docker (mount file for scanning)
docker run --rm -e ABUSECH_API_KEY="your_key" -v $(pwd):/data ghcr.io/andpalmier/yrfy scan -file /data/sample.exe

# Run with Podman
podman run --rm -e ABUSECH_API_KEY="your_key" -v $(pwd):/data ghcr.io/andpalmier/yrfy scan -file /data/sample.exe

# Run with Apple container
container run --rm -e ABUSECH_API_KEY="your_key" -v $(pwd):/data ghcr.io/andpalmier/yrfy scan -file /data/sample.exe

# Query without mounting
docker run --rm -e ABUSECH_API_KEY="your_key" ghcr.io/andpalmier/yrfy query -yara MALWARE_Win_Emotet

Environment Variables

Variable	Description
ABUSECH_API_KEY	Your abuse.ch API key (required)

License

This project is licensed under the AGPLv3 License - see the LICENSE file for details.

Acknowledgments

• YARAify by abuse.ch
• abuse.ch for their work in fighting malware