Skip to content

Indicators

An indicator is one blockable value stored for a source:

Field Description
type ipv4, ipv6, fqdn, url or json
data The value. IPs are stored as address + netmask (10.0.0.0 + 8); domains lowercased without a trailing dot.
sourceId Owning source. The same value in two sources is two indicators.
tags Tags of the indicator itself (source tags apply too, see below).
lastObservedAt When a fetch/import/add last saw it; drives pruning.
permanent Never pruned.

Adding indicators by hand

Since v1.25.0. Typically into a manual source:

# values as arguments (comma-separated works too), mark permanent, tag them
indicator:add --source customer-x-blocklist --tags c2,manual --permanent \
  evil.example.com 203.0.113.0/24 198.51.100.7

# from a file: one value per line, # comments allowed
indicator:add --source 12 --file blocklist.txt
  • The source can be given by ID or name.
  • Values are normalised exactly like feed data. Unrecognised values are reported and skipped.
  • Adding a value that already exists in the source refreshes it (and restores it if it was deleted) instead of creating a duplicate.

API: POST /api/v1/indicators with { "sourceId": 12, "values": [...], "tags": [...], "permanent": true } – see API Reference.

Permanent indicators

A permanent indicator is never removed by pruning, however long ago it was last observed – useful for values you add by hand that no feed will ever refresh.

indicator:update --id 42 --permanent       # set
indicator:update --id 42 --no-permanent    # clear
indicators --permanent                     # list only permanent ones

Adding an existing value again without --permanent never clears the flag. Indicators of manual sources are never pruned even without the flag.

Tags

  • Source tags (source:create --tags) apply to all indicators of the source.
  • Indicator tags come from per-item feed tags, ?tag= on import, indicator:add --tags, or indicator:update --tags (which replaces them).

Service tags: wherever tags are set (feeds, import, CLI, API, GUI), @service-<port>/<protocol> becomes the service name from the IANA port registry – @service-443/tcp → https, @service-25/tcp → smtp. A port the registry doesn't list stays as <port>/<protocol> (without the prefix). The registry is bundled; npm run update:service-names refreshes it – since v1.38.0.

The tag filter of exports matches either. indicators --tag in the CLI filters by source tag, GET /api/v1/indicators?tag= by indicator tag.

Is it listed?

Since v1.25.0. Find out whether – and by which source – a value is listed, including indirect matches:

indicators:search 10.20.30.40        # alias: lookup
indicators:search www.shop.example.com
indicators:search https://phish.example.net/login
Match Meaning
exact the value itself is an indicator
network an IP/CIDR indicator contains the address or network
parent domain a parent domain is listed – RPZ/dnsmasq/Unbound block subdomains too
domain a URL's host is listed as a domain

The GUI dashboard has the same check ("Is it listed?"), the API GET /api/v1/indicators/lookup?value=…. Results show the source (incl. whether it's private), tags and the permanent flag.

Listing and deleting

indicators --type fqdn --page 2 --limit 50
indicator:delete --id 42

Deleted indicators are soft-deleted (kept in the database, excluded everywhere). A later fetch that sees the value again restores it.