Types

Indicator types, sightings, and extraction results.

Results are pydantic models. :class:IOCType is the type you pass and the type you get back.

Classes:

• IOCType –

  Supported indicator types.

• Sighting –

  One place an indicator was observed.

• Enrichment –

  Local facts derived from an indicator. No network calls.

• Indicator –

  One deduplicated indicator and every place it was seen.

• ExtractionStats –

  Counts for one extraction or a merged set of extractions.

• Extraction –

  Indicators produced by one extract call or a merge of several.

Functions:

• parse_type –

  Return the enum member whose export key is value.

• type_key –

  Return the canonical string key for a type name or enum member.

Attributes:

• OUTPUT_ORDER (tuple[str, ...]) –
• DEFAULT_TYPES (tuple[str, ...]) –
• OPT_IN_TYPES (tuple[str, ...]) –
• HASH_TYPES (tuple[str, ...]) –
• TYPE_LABELS (dict[str, str]) –

OUTPUT_ORDER module-attribute

OUTPUT_ORDER: tuple[str, ...] = (IOCType.IPV4.value, IOCType.IPV6.value, IOCType.DOMAIN.value, IOCType.URL.value, IOCType.MD5.value, IOCType.SHA1.value, IOCType.SHA256.value, IOCType.EMAIL.value, IOCType.CVE.value, IOCType.ATTACK.value, IOCType.REGISTRY.value, IOCType.WALLET.value, IOCType.SHA512.value, IOCType.CIDR.value, IOCType.MAC.value, IOCType.ASN.value, IOCType.JA3.value, IOCType.JA3S.value, IOCType.JARM.value, IOCType.MUTEX.value, IOCType.PATH.value, IOCType.USER_AGENT.value)

DEFAULT_TYPES module-attribute

DEFAULT_TYPES: tuple[str, ...] = tuple(key for key in OUTPUT_ORDER if key not in {IOCType.MUTEX.value, IOCType.PATH.value, IOCType.USER_AGENT.value})

OPT_IN_TYPES module-attribute

OPT_IN_TYPES: tuple[str, ...] = (IOCType.MUTEX.value, IOCType.PATH.value, IOCType.USER_AGENT.value)

HASH_TYPES module-attribute

HASH_TYPES: tuple[str, ...] = (IOCType.MD5.value, IOCType.SHA1.value, IOCType.SHA256.value, IOCType.SHA512.value)

TYPE_LABELS module-attribute

TYPE_LABELS: dict[str, str] = {IOCType.IPV4.value: 'IPv4 addresses', IOCType.IPV6.value: 'IPv6 addresses', IOCType.DOMAIN.value: 'Domains', IOCType.URL.value: 'URLs', IOCType.MD5.value: 'MD5 hashes', IOCType.SHA1.value: 'SHA-1 hashes', IOCType.SHA256.value: 'SHA-256 hashes', IOCType.SHA512.value: 'SHA-512 hashes', IOCType.EMAIL.value: 'Email addresses', IOCType.CVE.value: 'CVE identifiers', IOCType.ATTACK.value: 'MITRE ATT&CK techniques', IOCType.REGISTRY.value: 'Registry keys', IOCType.WALLET.value: 'Crypto wallets', IOCType.CIDR.value: 'CIDR ranges', IOCType.MAC.value: 'MAC addresses', IOCType.ASN.value: 'AS numbers', IOCType.JA3.value: 'JA3 fingerprints', IOCType.JA3S.value: 'JA3S fingerprints', IOCType.JARM.value: 'JARM fingerprints', IOCType.MUTEX.value: 'Mutexes', IOCType.PATH.value: 'File paths', IOCType.USER_AGENT.value: 'User-Agent strings'}

IOCType

Bases: str, Enum

Supported indicator types.

Pass members, not strings: IOCType.IPV4, IOCType.EMAIL, IOCType.URL. The value of each member is the short key used in exports (IOCType.IPV4.value == "ip").

Attributes:

• IPV4 –
• IPV6 –
• DOMAIN –
• URL –
• MD5 –
• SHA1 –
• SHA256 –
• SHA512 –
• EMAIL –
• CVE –
• ATTACK –
• REGISTRY –
• WALLET –
• CIDR –
• MAC –
• ASN –
• JA3 –
• JA3S –
• JARM –
• MUTEX –
• PATH –
• USER_AGENT –

IPV4 class-attribute instance-attribute

IPV4 = 'ip'

IPV6 class-attribute instance-attribute

IPV6 = 'ip6'

DOMAIN class-attribute instance-attribute

DOMAIN = 'domain'

URL class-attribute instance-attribute

URL = 'url'

MD5 class-attribute instance-attribute

MD5 = 'md5'

SHA1 class-attribute instance-attribute

SHA1 = 'sha1'

SHA256 class-attribute instance-attribute

SHA256 = 'sha256'

SHA512 class-attribute instance-attribute

SHA512 = 'sha512'

EMAIL class-attribute instance-attribute

EMAIL = 'email'

CVE class-attribute instance-attribute

CVE = 'cve'

ATTACK class-attribute instance-attribute

ATTACK = 'attack'

REGISTRY class-attribute instance-attribute

REGISTRY = 'registry'

WALLET class-attribute instance-attribute

WALLET = 'wallet'

CIDR class-attribute instance-attribute

CIDR = 'cidr'

MAC class-attribute instance-attribute

MAC = 'mac'

ASN class-attribute instance-attribute

ASN = 'asn'

JA3 class-attribute instance-attribute

JA3 = 'ja3'

JA3S class-attribute instance-attribute

JA3S = 'ja3s'

JARM class-attribute instance-attribute

JARM = 'jarm'

MUTEX class-attribute instance-attribute

MUTEX = 'mutex'

PATH class-attribute instance-attribute

PATH = 'path'

USER_AGENT class-attribute instance-attribute

USER_AGENT = 'user_agent'

Sighting

Bases: BaseModel

One place an indicator was observed.

Attributes:

• source (str) –

  Source label, usually a file name or a caller-supplied name.

• line (int) –

  1-based line number in that source.

• offset (int) –

  Start offset in characters, 0-based, in the source text.

• end_offset (int) –

  End offset, exclusive, in the source text.

• page (int | None) –

  Page number for paged documents such as PDF. None otherwise.

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

source instance-attribute

source: str

line instance-attribute

line: int

offset instance-attribute

offset: int

end_offset instance-attribute

end_offset: int

page class-attribute instance-attribute

page: int | None = None

Enrichment

Bases: BaseModel

Local facts derived from an indicator. No network calls.

Fields that do not apply are None or empty. :meth:as_dict drops those. Registered-domain and subdomain splits are a best-effort heuristic. They are not a Public Suffix List. See the enrichment guide.

Methods:

• as_dict –

  Return a JSON-ready mapping with empty fields removed.

Attributes:

• model_config –
• ip_version (int | None) –
• is_private (bool | None) –
• is_global (bool | None) –
• is_multicast (bool | None) –
• is_reserved (bool | None) –
• is_loopback (bool | None) –
• is_link_local (bool | None) –
• is_cgnat (bool | None) –
• tld (str | None) –
• registered_domain (str | None) –
• subdomain (str | None) –
• scheme (str | None) –
• port (int | None) –
• path (str | None) –
• host (str | None) –
• host_is_ip (bool | None) –
• query_parameters (tuple[tuple[str, tuple[str, ...]], ...]) –
• file_extension (str | None) –
• hash_algorithm (str | None) –
• asn_number (int | None) –
• cidr_prefix (int | None) –
• cidr_network (str | None) –
• mac_multicast (bool | None) –
• mac_locally_administered (bool | None) –
• wallet_format (str | None) –
• registry_hive (str | None) –

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

ip_version class-attribute instance-attribute

ip_version: int | None = None

is_private class-attribute instance-attribute

is_private: bool | None = None

is_global class-attribute instance-attribute

is_global: bool | None = None

is_multicast class-attribute instance-attribute

is_multicast: bool | None = None

is_reserved class-attribute instance-attribute

is_reserved: bool | None = None

is_loopback class-attribute instance-attribute

is_loopback: bool | None = None

is_link_local class-attribute instance-attribute

is_link_local: bool | None = None

is_cgnat class-attribute instance-attribute

is_cgnat: bool | None = None

tld class-attribute instance-attribute

tld: str | None = None

registered_domain class-attribute instance-attribute

registered_domain: str | None = None

subdomain class-attribute instance-attribute

subdomain: str | None = None

scheme class-attribute instance-attribute

scheme: str | None = None

port class-attribute instance-attribute

port: int | None = None

path class-attribute instance-attribute

path: str | None = None

host class-attribute instance-attribute

host: str | None = None

host_is_ip class-attribute instance-attribute

host_is_ip: bool | None = None

query_parameters class-attribute instance-attribute

query_parameters: tuple[tuple[str, tuple[str, ...]], ...] = ()

file_extension class-attribute instance-attribute

file_extension: str | None = None

hash_algorithm class-attribute instance-attribute

hash_algorithm: str | None = None

asn_number class-attribute instance-attribute

asn_number: int | None = None

cidr_prefix class-attribute instance-attribute

cidr_prefix: int | None = None

cidr_network class-attribute instance-attribute

cidr_network: str | None = None

mac_multicast class-attribute instance-attribute

mac_multicast: bool | None = None

mac_locally_administered class-attribute instance-attribute

mac_locally_administered: bool | None = None

wallet_format class-attribute instance-attribute

wallet_format: str | None = None

registry_hive class-attribute instance-attribute

registry_hive: str | None = None

as_dict

as_dict() -> dict[str, object]

Return a JSON-ready mapping with empty fields removed.

Indicator

Bases: BaseModel

One deduplicated indicator and every place it was seen.

value keeps the first-seen sieve form (hashes lower case, CVE identifiers upper case, domains lower case). raw is the exact source slice, which may still be defanged. normalized is the canonical form used for the fingerprint. Neither field overwrites the other.

Attributes:

• type (IOCType) –

  :class:IOCType member, for example IOCType.IPV4.

• value (str) –

  First-seen sieve value.

• normalized (str) –

  Canonical value. Equal to value when normalization is off.

• raw (str) –

  Exact slice of the original source for the first sighting.

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

  Noise tags such as private or loopback. Empty when none apply.

• fingerprint (str) –

  SHA-256 hex digest of the type and the correlation key.

• valid (bool | None) –

  True or False when validation ran, otherwise None.

• confidence (float) –

  Deterministic heuristic in the range 0.01 to 0.99.

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

  Stable reason codes. Empty when nothing failed.

• enrichment (Enrichment) –

  Local enrichment. Never fetched from the network.

• sightings (tuple[Sighting, ...]) –

  Every observation, first seen first.

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

type instance-attribute

type: IOCType

value instance-attribute

value: str

normalized instance-attribute

normalized: str

raw instance-attribute

raw: str

tags instance-attribute

tags: tuple[str, ...]

fingerprint instance-attribute

fingerprint: str

valid instance-attribute

valid: bool | None

confidence instance-attribute

confidence: float

validation_notes instance-attribute

validation_notes: tuple[str, ...]

enrichment instance-attribute

enrichment: Enrichment

sightings instance-attribute

sightings: tuple[Sighting, ...]

occurrences property

occurrences: int

Number of sightings, including repeats inside one source.

source property

source: str

Source label of the first sighting, or an empty string.

line property

line: int | None

Line number of the first sighting.

offset property

offset: int | None

Character offset of the first sighting.

end_offset property

end_offset: int | None

Exclusive end offset of the first sighting.

page property

page: int | None

Page number of the first sighting, when the source has pages.

sources property

sources: tuple[str, ...]

Distinct source labels in first-seen order.

pivots property

pivots: tuple[tuple[str, str], ...]

Enrichment links for this indicator. The links are not fetched.

ExtractionStats

Bases: BaseModel

Counts for one extraction or a merged set of extractions.

Attributes:

• counts (Mapping[str, int]) –

  Unique indicators per type. Missing keys mean zero.

• total (int) –

  Number of unique indicators.

• sightings (int) –

  Number of observations, counting repeats.

• input_characters (int) –

  Characters actually scanned.

• truncated (bool) –

  True when a size limit cut the input short.

• match_limit_hit (bool) –

  True when a per-type match cap stopped the scan.

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

  Source labels included in the result.

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

counts instance-attribute

counts: Mapping[str, int]

total instance-attribute

total: int

sightings instance-attribute

sightings: int

input_characters instance-attribute

input_characters: int

truncated instance-attribute

truncated: bool

match_limit_hit instance-attribute

match_limit_hit: bool

sources instance-attribute

sources: tuple[str, ...]

Extraction

Bases: BaseModel

Indicators produced by one extract call or a merge of several.

Iterate the extraction to walk indicators in export order. :meth:get and :meth:values take an :class:IOCType member. :meth:shared returns indicators that showed up in at least two sources.

Methods:

• model_post_init –
• __iter__ –
• __len__ –
• __repr__ –
• get –

  Return indicators of one type, in first-seen order.

• values –

  Return the sieve values of one type, in first-seen order.

• shared –

  Return indicators observed in two or more sources.

Attributes:

• model_config –
• indicators (tuple[Indicator, ...]) –
• stats (ExtractionStats) –
• truncated (bool) –

  Whether a size limit cut the input short.

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

indicators instance-attribute

indicators: tuple[Indicator, ...]

stats instance-attribute

stats: ExtractionStats

truncated property

truncated: bool

Whether a size limit cut the input short.

model_post_init

model_post_init(context: Any) -> None

__iter__

__iter__() -> Iterator[Indicator]

__len__

__len__() -> int

__repr__

__repr__() -> str

get

get(kind: IOCType) -> tuple[Indicator, ...]

Return indicators of one type, in first-seen order.

Parameters:

• kind (IOCType) –

  Indicator type, for example IOCType.IPV4.

values

values(kind: IOCType) -> tuple[str, ...]

Return the sieve values of one type, in first-seen order.

Parameters:

• kind (IOCType) –

  Indicator type, for example IOCType.DOMAIN.

shared

shared() -> tuple[Indicator, ...]

Return indicators observed in two or more sources.

parse_type

parse_type(value: str) -> IOCType

Return the enum member whose export key is value.

type_key

type_key(value: IOCType | str) -> str

Return the canonical string key for a type name or enum member.