Developer Guide

How to consume the Zedmos CTI feed API from your firewall, SIEM, or EDR. Every endpoint is HTTPS + bearer token; every response carries audit headers.

1. Authentication

Every /v1/feeds/* and /v1/lookup/* endpoint requires a bearer token. Tokens are tenant-scoped and have one or more "kinds" (ti, security, waf) attached at issue time.

curl -H "Authorization: Bearer $TOKEN" \
  https://cti.zedmos.net/v1/feeds/security/phishing/domains.txt | head

A few notes:

• The token must be at least 16 characters and sent as Authorization: Bearer <token>.
• Tokens are tenant-scoped — pulls from anywhere with the same token are billed/audited as one tenant.
• Rotation: receive a new token, switch your firewall config, then disable the old one.

1A. Self-service portal

Anyone can request a Zedmos CTI account through the public portal. There is no email-verification step right now — every new account is queued for admin review and contacted manually once approved.

1. Sign up at /register with email + password (≥12 chars, mixed case, digit). Response: 202 pending_approval.
2. Wait for admin approval. An operator flips enabled=true via PATCH /admin/v1/users/:id. You will be notified out-of-band.
3. Sign in at /login → receive a 7-day session JWT (stored in localStorage).
4. Issue API tokens at /dashboard. Each token is shown once (copy immediately). Scope by kinds (ti, security, waf) and tiers (verified, trusted, community). Max 10 active tokens per user.
5. Call the feed API with the token (see Section 1 above).

Security: bcrypt cost 12, zod strict-mode input validation, NoSQL-injection guard, 5/hour signup rate-limit, 10-attempt account lockout (15 min), 2-phase login (wrong password and pending account return distinguishable errors only to the password holder).

2. Pulling feeds

All feeds follow the URL convention:

/v1/feeds/<kind>/<category>/<format>

Common combinations:

The full list of categories is available at GET /v1/public/sources (no auth required).

3. IOC scoring

Each IOC carries four 0-100 scores. The most useful in production is composite: a weighted aggregate of the other three.

Filtering by score (?min_score=N)

Vendor-native feed exports (fortinet.txt, paloalto.txt, checkpoint.csv, etc.) accept a min_score query parameter (0-100). The value is matched against the per-IOC confidence score recorded in the metadata sidecar.

Plain domains.txt / ips.txt serve the pre-built tier snapshot file as-is — they ignore min_score. Use a vendor format if you need score-gated output, or call /v1/lookup/... for per-IOC composite scores.

# Full feed (default)
curl -H "Authorization: Bearer $TOKEN" \
  https://cti.zedmos.net/v1/feeds/security/phishing/domains.txt

# Confidence ≥ 70 only (verified + corroborated)
curl -H "Authorization: Bearer $TOKEN" \
  "https://cti.zedmos.net/v1/feeds/security/phishing/fortinet.txt?min_score=70"

# Response carries X-Tihub-Min-Score, X-Tihub-Row-Count, X-Tihub-Row-Limit headers

Filtering by tier (?tiers=...)

The default ship list is verified ∪ trusted. To opt in to single-source community indicators, or to restrict to a single tier, pass ?tiers=:

# Only verified (highest precision)
curl -H "Authorization: Bearer $TOKEN" \
  "https://cti.zedmos.net/v1/feeds/security/phishing/fortinet.txt?tiers=verified"

# Verified + trusted + community (widest net)
curl -H "Authorization: Bearer $TOKEN" \
  "https://cti.zedmos.net/v1/feeds/security/phishing/fortinet.txt?tiers=verified,trusted,community"

Row caps + ?limit=N

Each firewall vendor has a documented EDL / block-list import limit. Zedmos applies a per-vendor default so the importer never silently truncates a too-large feed. Override with ?limit=N up to 500,000.

When the cap kicks in, indicators with metadata-sidecar enrichment (malware family, threat actor, MITRE) ship first.

Caching contract — 202 "warming"

Heavy aggregate endpoints (/v1/public/stats, /v1/public/transparency, /v1/public/verification, /v1/public/cti/categories, /v1/public/mitre/coverage, /v1/public/dashboard) run against an 11M-row catalog. Right after a hub restart the in-process cache is empty and the first request would otherwise hang for 10-30 s.

To prevent timeouts, those endpoints return 202 Accepted with body {"status":"warming","retry_after_s":5} until the background prime job populates the cache. Subsequent calls return 200 OK in < 100 ms. Treat 202 as transient — retry after the suggested interval. Response header X-Tihub-Cache distinguishes warming / process-hit / stale-revalidating.

Per-IOC lookup

curl -H "Authorization: Bearer $TOKEN" \
  https://cti.zedmos.net/v1/lookup/domain/example.com

Response includes tier, sources, categories, the four scores, effective MITRE techniques, and a recommendation string.

4. MITRE ATT&CK mapping

Each Zedmos category maps to a curated list of ATT&CK tactics + techniques (Enterprise v15). The mapping surfaces in:

• Sigma rules — tags: attack.t1566.001, attack.initial-access
• STIX bundles — kill_chain_phases + external_references to attack.mitre.org
• Lookup endpoint — mitre: { tactics, techniques } in the JSON response

Coverage matrix (public)

curl https://cti.zedmos.net/v1/public/mitre/coverage | jq '.techniques[0:5]'

The same data rendered as a grid lives at /mitre-coverage.html — no authentication required.

5. Vendor-native exports

The same IOCs, packaged for direct paste into the firewall console. All endpoints accept ?min_score=N.

Fortinet FortiGate

config system external-resource
  edit "zedmos-phishing"
    set type domain
    set resource "https://cti.zedmos.net/v1/feeds/security/phishing/fortinet.txt?min_score=70"
  next
end

Palo Alto Networks (External Dynamic List)

PAN-OS uses two separate EDL types — register each as its own object:

# Objects → External Dynamic Lists → Add → Type: IP List
# Source: https://cti.zedmos.net/v1/feeds/security/phishing/paloalto.txt
# Repeat every: Hour

# Objects → External Dynamic Lists → Add → Type: Domain List
# Source: https://cti.zedmos.net/v1/feeds/security/phishing/paloalto-domain.txt
# Repeat every: Hour

Check Point Quantum

ioc_feeds add \
  --feed_name Zedmos_Phishing \
  --transport_type web_url \
  --resource https://cti.zedmos.net/v1/feeds/security/phishing/checkpoint.csv \
  --feed_action prevent \
  --feed_format CSV

Sophos · Cisco Umbrella · Meraki · Juniper SRX · MikroTik · Pi-hole · OPNsense · Unbound RPZ

Config snippets for all 16 supported integrations: /integrations.

6. API reference

Public endpoints (no auth)

Self-service portal (session JWT or public)

TAXII 2.1 / STIX (bearer)

Sightings + closed loop (bearer)

Bearer-token endpoints

Response headers

Every feed response sets:

• ETag — SHA-256 of the body (use with If-None-Match for 304s — most firewall agents handle this natively so unchanged feeds re-download as zero bytes)
• Cache-Control: public, max-age=60
• X-Tihub-Min-Score — applied confidence gate (vendor formats only)
• X-Tihub-Row-Count — number of indicators in this response
• X-Tihub-Row-Limit — the cap applied (vendor default or ?limit= override)
• X-Tihub-Vendor — vendor id on the vendor-native endpoints
• X-Tihub-Body-Age-Ms — how stale the cached body is (0 on freshly-rebuilt)
• X-Tihub-Cache — process-hit / stale-revalidating / warming for cached aggregates
• X-Tihub-Tier + X-Tihub-Tier-Meaning — on plain domains.txt / ips.txt / verified-* / trusted-* / community-*

Need a token, a custom export format, or have a question? Contact your Zedmos representative.