Enrichment

Local enrichment. Nothing in this module contacts the network.

Functions:

• enrich –

  Build local enrichment for one indicator.

enrich

enrich(kind: str, value: str, normalized: str, tags: tuple[str, ...]) -> Enrichment

Build local enrichment for one indicator.

IP flags come from :mod:ipaddress plus the sieve's CGNAT tag. Domain and URL host splits use :func:qarbaal.tlds.split_domain. Hash names prefer the indicator type, then the digest length.

Parameters:

• kind (str) –

  Type key.

• value (str) –

  Sieve value.

• normalized (str) –

  Canonical value.

• tags (tuple[str, ...]) –

  Noise tags already assigned by the sieve.

Returns:

• An ( Enrichment ) –

  class:~qarbaal.types.Enrichment instance.

Enrichment links. qarbaal builds the URLs and does not open them.

Functions:

• pivots_for –

  Return (name, url) pivots for one indicator.

pivots_for

pivots_for(kind: str, value: str) -> tuple[tuple[str, str], ...]

Return (name, url) pivots for one indicator.

The set matches the sieve for the original types: VirusTotal, AbuseIPDB, Shodan, urlscan, WHOIS, MalwareBazaar, NVD, MITRE, and Blockchain.com. Added types get a pivot only where a stable public search URL exists.

Parameters:

• kind (str) –

  Type key.

• value (str) –

  Sieve value, not the defanged form.

Returns:

• tuple[tuple[str, str], ...] –

  Zero or more links. Email addresses and registry keys have none.

IANA root-zone TLDs, plus a short special-use set.

Functions:

• iana_tlds –

  Return the bundled root-zone TLD list, lower case, without comments.

• tld_recognized –

  Return whether tld is in the root zone or the special-use set.

• split_domain –

  Split a domain into (tld, registered_domain, subdomain).

Attributes:

• SPECIAL_USE_TLDS (frozenset[str]) –
• MULTI_LABEL_SUFFIXES (frozenset[str]) –

SPECIAL_USE_TLDS module-attribute

SPECIAL_USE_TLDS: frozenset[str] = frozenset({'example', 'invalid', 'localhost', 'test', 'local', 'onion', 'internal'})

MULTI_LABEL_SUFFIXES module-attribute

MULTI_LABEL_SUFFIXES: frozenset[str] = frozenset({'co.uk', 'org.uk', 'ac.uk', 'gov.uk', 'ltd.uk', 'plc.uk', 'net.uk', 'sch.uk', 'com.au', 'net.au', 'org.au', 'edu.au', 'gov.au', 'asn.au', 'id.au', 'co.jp', 'or.jp', 'ne.jp', 'ac.jp', 'go.jp', 'co.kr', 'or.kr', 'ne.kr', 'go.kr', 'com.br', 'net.br', 'org.br', 'gov.br', 'com.cn', 'net.cn', 'org.cn', 'gov.cn', 'com.mx', 'com.tr', 'com.sg', 'com.hk', 'com.tw', 'com.ar', 'com.co', 'co.za', 'co.nz', 'co.in', 'net.in', 'org.in', 'com.ua', 'co.il', 'org.il', 'ac.il', 'gov.il', 'com.pl', 'co.id', 'co.th'})

iana_tlds cached

iana_tlds() -> frozenset[str]

Return the bundled root-zone TLD list, lower case, without comments.

The file is the IANA tlds-alpha-by-domain list shipped with the package. Special-use names live in :data:SPECIAL_USE_TLDS and are not mixed in here.

tld_recognized

tld_recognized(tld: str) -> bool

Return whether tld is in the root zone or the special-use set.

split_domain

split_domain(domain: str) -> tuple[str | None, str | None, str | None]

Split a domain into (tld, registered_domain, subdomain).

The TLD is the last label, or the last two labels when they are in :data:MULTI_LABEL_SUFFIXES (co.uk and similar). The registered domain is the suffix plus one label. Everything in front of that is the subdomain.

This is intentionally not a Public Suffix List. Private suffixes such as blogspot.com are not treated as registry boundaries.

Parameters:

• domain (str) –

  A host name without a scheme. A trailing dot is ignored.

Returns:

• str | None –

  (tld, registered_domain, subdomain). subdomain is None when

• str | None –

  the name has no labels in front of the registered domain.