Spamhaus CLI

A command-line interface to query the Spamhaus Intelligence API.

---

Authentication

All commands require --username and --password.

---

Requirements

To run spamhaus_cli.py, ensure you have the following:

Python 3

Check your version:

python3 --version

Required Python packages

Install the requests library:

pip install requests

Optional (for local timezone formatting)

If you use --date-timezone local and run on a minimal system, ensure the timezone data is installed:

sudo apt install tzdata

---

Available Commands

CIDR Check

python3 spamhaus_cli.py \
  --username YOUR_EMAIL \
  --password YOUR_PASSWORD \
  check-cidr \
  --cidrs xxx.xxx.xxx.xxx/32,xxx.xxx.xxx.xxx/24 \
  --dataset ALL \
  --mode listed \
  --type live \
  --format csv \
  --out cidr_results.csv \
  --summary \
  --human-readable-dates \
  --date-timezone local

For one IP, you don't need to add netmask (/32)

Options for check-cidr

• --cidrs: Comma-separated list of IPs or CIDRs. Example: 192.0.2.1/32,203.0.113.0/24
• --dataset: Choose the dataset: XBL, CSS, BCL, or ALL (default: XBL)
• --mode: CIDR matching mode:
  • listed: looks for listed IPs within the CIDR
  • listings: matches listings that include the CIDR (reserved for future use)
• --type:
  • live: only active listings
  • history: includes past listings too
• --limit: Max number of results to fetch (default: 100, max: 2000)
• --since / --until: UNIX timestamps to filter historical data
• --format: Output format: json or csv
• --summary: Print a summary by dataset
• --human-readable-dates: Adds _iso timestamp fields
• --date-timezone: utc (default) or local

---

Domain Check

python3 spamhaus_cli.py \
  --username YOUR_EMAIL \
  --password YOUR_PASSWORD \
  check-domain \
  --domain example.com \
  --extra all \
  --format json \
  --out-dir ./results \
  --summary \
  --human-readable-dates \
  --date-timezone utc

--extra Options for Domain Check

You can specify one or more:

• dimensions: reputation dimensions (SMTP, infra, malware...)
• contexts: observed contexts (dkim, helo, tls, etc.)
• listing: DNSBL status
• senders: sending IPs
• a: A/AAAA records with reputation
• hostnames: listed hostnames
• malware-hashes: hashes linked to the domain
• malware-urls: URLs related to malware
• all: fetch all of the above

---

Timestamp Formatting

Use:

--human-readable-dates

To convert all timestamp fields (e.g. listed, seen, ts, last-seen) into human-readable ISO-8601 format with _iso suffix.

You can control the timezone with:

--date-timezone utc     # default
--date-timezone local   # based on your system timezone

---

Output

• --format: json or csv
• --out: output file (for CIDR)
• --out-dir: output directory (for domain)
• --summary: display summary in terminal

---

Usage Examples

Check CIDR

python3 spamhaus_cli.py \
  --username [email protected] \
  --password your_password \
  check-cidr \
  --cidrs 42.42.42.0/24 \
  --dataset ALL \
  --mode listed \
  --type live \
  --format csv \
  --out result.csv \
  --summary \
  --human-readable-dates \
  --date-timezone local

---

Check Domain

python3 spamhaus_cli.py \
  --username [email protected] \
  --password your_password \
  check-domain \
  --domain example.com \
  --extra all \
  --format json \
  --out-dir ./output \
  --summary \
  --human-readable-dates \
  --date-timezone utc

---

Check Limits (Python)

python3 spamhaus_limits.py

---

Heuristic Types (CSS dataset)

When querying CIDRs (especially in the CSS dataset), Spamhaus returns a field called heuristic for each listed IP.

This field represents the type of behavior or issue detected for that IP.

Possible Heuristic Values

Heuristic	Meaning
SPAM	Spam - Detected based on spam trap hits or bulk sending patterns.
LTB	Low Trust Behavior - IPs with unusual sending behaviors not necessarily tied to spam volume.
WAB	Weak Authentication Behavior - Issues with SPF, DKIM, DMARC, open relays, or lack of authentication.
IMPERSONATE	Impersonation - IPs suspected of trying to impersonate known domains or brands.
LEGACY	Legacy listing - Older listings retained under legacy classification rules.
SPAMBOT	Spam Bot - IPs associated with botnet activity or infected machines.

Detection Field (Optional)

For certain heuristics, Spamhaus may include an additional detection field.

This is a human-readable description explaining how the listing was determined (e.g., based on multiple signals or detection methods).

Note: The detection field is only present for some listings and when the heuristic involves multiple detection sources.

---