tfox - ThreatFox CLI Client

A command-line tool for interacting with the ThreatFox 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

Installation

Using Homebrew

brew install andpalmier/tap/tfox

Using Go

go install github.com/andpalmier/tfox@latest

Using Container (Docker/Podman)

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

# Or build locally
docker build -t tfox .

From Source

git clone https://github.com/andpalmier/tfox.git
cd tfox
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. Query recent IOCs:

tfox recent -days 3

Usage

Commands

Command	Description
recent	Query recent IOCs (max 7 days)
query	Query by IOC ID, tag, malware, or label
search	Search IOCs by term or file hash
list	List malware families, types, or tags
version	Show version information

Query Recent IOCs

# IOCs from last 3 days
tfox recent -days 3

# IOCs from last 7 days
tfox recent -days 7

Query by Criteria

# By tag
tfox query -tag Emotet -limit 10

# By malware family
tfox query -malware "Cobalt Strike" -limit 10

# Identify malware label
tfox query -label warzone -platform win

Search IOCs

# Search by IOC value (wildcard)
tfox search -ioc suspicious.com

# Exact match
tfox search -ioc evil.com -exact

# Search by file hash
tfox search -hash <md5_or_sha256_hash>

List Data

tfox list -malware    # Malware families
tfox list -types      # IOC/threat types
tfox list -tags       # Known tags

Container Usage

# Run with Docker
docker run --rm -e ABUSECH_API_KEY="your_key" ghcr.io/andpalmier/tfox recent -days 3

# Run with Podman
podman run --rm -e ABUSECH_API_KEY="your_key" ghcr.io/andpalmier/tfox recent -days 3

# Run with Apple container
container run --rm -e ABUSECH_API_KEY="your_key" ghcr.io/andpalmier/tfox recent -days 3

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

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