Integration guides

Integration guides

A feed is worth nothing until something enforces it. These guides cover putting the SciScope Scanner Feed into the places it usually needs to land, with working configuration, the failure modes that matter, and no step that says "and then integrate it".

Every guide assumes an Entry-tier key or better, since /v1/feeds/blocklist.txt is an Entry endpoint. A 14-day trial on the full Pro feature set is enough to work through any of them.

The two endpoints these guides use

The high-confidence blocklist: plain text, one address per line, comments prefixed with #. This is what goes into a firewall:

curl -fsSL -H "Authorization: Bearer $SCISCOPE_KEY" \
     https://api.sciscope.ee/v1/feeds/blocklist.txt

The scored feed: every address with its score, tags and evidence. This is what goes into a SIEM or an IDS that can act on a score rather than a yes/no:

curl -fsSL -H "Authorization: Bearer $SCISCOPE_KEY" \
     https://api.sciscope.ee/v1/feeds/feed.json

CSV is available as feed.csv, and the opt-in crawler-identity list as crawlers.json or crawlers.csv.

What the files actually look like, so your parser does not have to discover it:

• blocklist.txt: three # comment lines (threshold, count, licence) followed by one address per line. Strip lines beginning with # and you have the list.
• feed.json: one object with license, terms, generated_utc, count and an indicators array. Each indicator has ip, score, tags, first_seen, last_seen, signal_events_30d, sensor_continents, and coarse geo and asn context.
• feed.csv: one # licence line, then a header row, then the same fields with multi-valued columns joined by |.

Authenticating from something that cannot set a header

Firewall appliances and cron fetchers frequently cannot send an Authorization header. The API therefore also accepts the key as X-API-Key or as a ?key= query parameter:

https://api.sciscope.ee/v1/feeds/blocklist.txt?key=YOUR_KEY

Use it only where a header genuinely is not possible. A key in a URL ends up in proxy logs, shell history, configuration backups and screenshots in support tickets; a key in a header mostly does not. If a key does leak, email hello@sciscope.ee; rotation is immediate and free.

Refresh interval and failure behaviour

The feed bundle is rebuilt hourly. Refreshing more often than that gains you nothing and burns your rate limit; hourly, or every few hours, is the right setting for every integration below.

Two rules that every one of these guides applies, because they are what separates a blocklist that helps from one that causes an outage:

• Never install an empty list. Check that the download is non-empty and credibly sized before it replaces the current one. A failed fetch must leave yesterday's list in place.
• Update atomically. Flushing a set and then refilling it leaves a window of seconds, sometimes minutes, during which nothing is blocked, or worse, during which a default-deny rule blocks everything. Every guide here uses the atomic primitive its platform provides.

Rate limits

Entry allows 20 requests per minute and 2,000 per day; Pro allows 60 and 20,000. Hourly refreshes across a handful of devices sit nowhere near either. If you are distributing to many enforcement points, fetch once centrally and push internally rather than having every device pull. That is also what the MSSP/Enterprise tier is for.