Automating Malicious IP and Domain Blocklist Downloads

What You Will Achieve

By the end of this playbook you will have:

• A no-auth call to GET /blocklist/stats to monitor counts and lastUpdated
• Authenticated downloads of blocklist-*.txt files via GET /blocklist/download/{filename}
• A shell pattern that diffs the new file against the previous run before pushing to your edge
• Clarity on plan behavior (full list vs sample) from response headers

This complements generic firewall automation by focusing on the official REST endpoints documented in OpenAPI.

---

Prerequisites

| Requirement | Details | | ---------------- | --------------------------------------------------------------------------------------------------------------------- | | API key + secret | Required for download (not for /blocklist/stats); X-API-KEY = Base64(apiKey:apiSecret) | | Plan | Full blocklists are plan-gated; lower tiers may receive a lite sample—check X-Blocklist-Version on the response | | Egress | Allow https://api.ismalicious.com from the sync host |

Product context: Blocklist data and API docs.

---

Step 1: Discover available files and freshness

GET https://api.ismalicious.com/blocklist/stats returns entry counts and timestamps per filename—no authentication.

curl -sS "https://api.ismalicious.com/blocklist/stats" | jq .

Use this in monitoring to alert when lastUpdated stalls or counts drop unexpectedly.

---

Step 2: Download a specific list

Path parameter filename must be one of the documented blocklist names, for example:

• blocklist-ips-critical.txt
• blocklist-ips-all.txt
• blocklist-domains-phishing.txt
• blocklist-domains-malware.txt

export B64=$(printf '%s' "${API_KEY}:${API_SECRET}" | base64)
OUT="blocklist-domains-phishing.txt"

curl -sS -D headers.txt -o "$OUT" \
  "https://api.ismalicious.com/blocklist/download/${OUT}" \
  -H "X-API-KEY: ${B64}"

Inspect headers for provisioning hints:

grep -i '^x-blocklist' headers.txt

• X-Blocklist-Version: full vs lite
• X-Blocklist-Plan: echoes plan context

Handle 401/403 by verifying credentials and subscription.

---

Step 3: Idempotent sync with diff

Only reload your firewall when content changes:

#!/usr/bin/env bash
set -euo pipefail
KEY="${ISMALICIOUS_API_KEY:?}"
SEC="${ISMALICIOUS_API_SECRET:?}"
B64=$(printf '%s' "${KEY}:${SEC}" | base64)
FILE="blocklist-ips-critical.txt"
NEW="/var/lib/ismalicious/${FILE}.new"
OLD="/var/lib/ismalicious/${FILE}.prev"
mkdir -p /var/lib/ismalicious

curl -sS -f -o "$NEW" \
  "https://api.ismalicious.com/blocklist/download/${FILE}" \
  -H "X-API-KEY: ${B64}"

if [[ -f "$OLD" ]] && cmp -s "$OLD" "$NEW"; then
  echo "No change; skip push."
  exit 0
fi

# TODO: push $NEW into your WAF/DNS appliance API or config repo
cp "$NEW" "$OLD"
echo "Updated blocklist applied."

Schedule with cron or systemd timer (for example every 6 hours), aligned with how often lists refresh.

---

Step 4: Pair with stats in the same job

curl -sS "https://api.ismalicious.com/blocklist/stats" \
  | jq -r --arg f "$FILE" '.[$f] | "count=\(.count) updated=\(.lastUpdated)"'

Log the line next to your download result for audit trails.

---

Related playbooks

• Firewall blocklist automation — broader edge and cloud patterns.
• SIEM enrichment — correlate alerts with reputation instead of only blocking.