Exports

Exporters. STIX, MISP, and OpenIOC are built with the standard library.

Pass path and filename to write the same text to a file. The call then returns an ExportFile. Omit both and the function returns the text.

YARA and Sigma are not generated. A file hash is not a YARA rule on its own, and a Sigma rule needs a log source and field selection that an indicator list does not carry. Suricata and Snort rules are emitted only for IPs, CIDR ranges, domains, and URLs.

Classes:

• ExportFile –

  A file written by an export function.

Functions:

• to_csv –

  Render indicators as CSV.

• to_json –

  Render indicators as JSON.

• to_jsonl –

  Render one JSON object per indicator, followed by a newline.

• to_defanged_list –

  Render one defanged indicator per line, in export order.

• to_stix –

  Render a STIX 2.1 bundle.

• to_misp –

  Render a MISP event containing one attribute per indicator.

• to_openioc –

  Render an OpenIOC 1.1 document.

• to_suricata –

  Render Suricata rules for IPs, CIDR ranges, domains, and URLs.

• to_snort –

  Render Snort rules for IPs, CIDR ranges, domains, and URLs.

• indicator_to_dict –

  Return a JSON-ready mapping for one indicator.

• isoformat_z –

  Format a timestamp as YYYY-MM-DDTHH:MM:SS.sssZ.

Attributes:

• IdFactory –

IdFactory module-attribute

IdFactory = Callable[[str], str]

ExportFile

Bases: BaseModel

A file written by an export function.

An exporter returns this model when path or filename is set. With neither argument it returns the serialized text instead.

Attributes:

• path (str) –

  Absolute path of the written file.

• filename (str) –

  File name, without a directory.

• size (int) –

  File size in bytes.

• format (str) –

  Export format, such as csv, json, or stix.

• count (int) –

  Indicators represented in the file. Suricata and Snort count emitted rules. A STIX bundle counts the objects in the bundle.

• sha256 (str) –

  SHA-256 hex digest of the file bytes.

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

path instance-attribute

path: str

filename instance-attribute

filename: str

size instance-attribute

size: int

format instance-attribute

format: str

count instance-attribute

count: int

sha256 instance-attribute

sha256: str

to_csv

to_csv(result: Extraction, *, hide_private: bool = False, detailed: bool = False, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render indicators as CSV.

The compact form is type,value,tags with a UTF-8 BOM, CRLF line breaks, and every field quoted. Tags are joined with |. There is no trailing line break after the last row.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged IP, IPv6, and CIDR rows.

• detailed (bool, default: False ) –

  Add normalized value, fingerprint, provenance, and confidence.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.csv. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  CSV text, or an ExportFile when a file is written.

to_json

to_json(result: Extraction, *, hide_private: bool = False, detailed: bool = False, generated: datetime | None = None, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render indicators as JSON.

The compact document is {"tool", "generated", "iocs"} where iocs maps a type key to a list of sieve values. Types with no values are omitted. detailed=True writes one object per indicator, including provenance.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged IP, IPv6, and CIDR values.

• detailed (bool, default: False ) –

  Write the full indicator records.

• generated (datetime | None, default: None ) –

  Timestamp used for generated. Defaults to the current time.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.json. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  JSON text, or an ExportFile when a file is written.

to_jsonl

to_jsonl(result: Extraction, *, hide_private: bool = False, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render one JSON object per indicator, followed by a newline.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged IP, IPv6, and CIDR rows.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.jsonl. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  JSONL text, or an ExportFile when a file is written.

to_defanged_list

to_defanged_list(result: Extraction, *, hide_private: bool = False, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render one defanged indicator per line, in export order.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged IP, IPv6, and CIDR rows.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.defanged.txt. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  Plain text, or an ExportFile when a file is written.

to_stix

to_stix(result: Extraction, *, hide_private: bool = False, generated: datetime | None = None, id_factory: IdFactory | None = None, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render a STIX 2.1 bundle.

IPs, domains, URLs, hashes, email addresses, registry keys, MAC addresses, and mutexes become indicator objects. CVE identifiers become vulnerability objects. ASN values become indicators with an autonomous-system:number pattern. Types without a single clear STIX pattern (CIDR, JA3, JA3S, JARM, file paths, user agents, wallets, ATT&CK technique IDs) are left out of the bundle.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged IP and IPv6 objects.

• generated (datetime | None, default: None ) –

  Timestamp applied to every object.

• id_factory (IdFactory | None, default: None ) –

  Callable that receives bundle, indicator, or vulnerability and returns the full STIX id.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.stix.json. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  Bundle JSON, or an ExportFile when a file is written.

to_misp

to_misp(result: Extraction, *, hide_private: bool = False, generated: datetime | None = None, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render a MISP event containing one attribute per indicator.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged IP, IPv6, and CIDR attributes.

• generated (datetime | None, default: None ) –

  Event date. Defaults to the current UTC day.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.misp.json. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  MISP JSON, or an ExportFile when a file is written.

to_openioc

to_openioc(result: Extraction, *, hide_private: bool = False, generated: datetime | None = None, id_factory: IdFactory | None = None, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render an OpenIOC 1.1 document.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged IP, IPv6, and CIDR items.

• generated (datetime | None, default: None ) –

  last-modified and authored_date timestamp.

• id_factory (IdFactory | None, default: None ) –

  Callable used for the document id and each indicator item.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.openioc.xml. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  OpenIOC XML, or an ExportFile when a file is written.

to_suricata

to_suricata(result: Extraction, *, hide_private: bool = False, sid_start: int = 1000001, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render Suricata rules for IPs, CIDR ranges, domains, and URLs.

Other types are omitted. A value containing a quote, semicolon, or backslash is omitted rather than escaped into a broken rule.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged addresses.

• sid_start (int, default: 1000001 ) –

  First SID. Each rule increments it by one.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.suricata.rules. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  Rule text, or an ExportFile when a file is written.

to_snort

to_snort(result: Extraction, *, hide_private: bool = False, sid_start: int = 1000001, path: str | PathLike[str] | None = None, filename: str | None = None) -> str | ExportFile

Render Snort rules for IPs, CIDR ranges, domains, and URLs.

Domain rules match the name in DNS traffic (UDP port 53). Suricata rules use dns.query instead. The same character limits as :func:to_suricata apply.

Parameters:

• result (Extraction) –

  Extraction to render.

• hide_private (bool, default: False ) –

  Drop tagged addresses.

• sid_start (int, default: 1000001 ) –

  First SID.

• path (str | PathLike[str] | None, default: None ) –

  Directory for the file. Created when missing. The current working directory is used when only filename is set.

• filename (str | None, default: None ) –

  File name to write. The default is qarbaal.snort.rules. A name that contains a directory is rejected.

Returns:

• str | ExportFile –

  Rule text, or an ExportFile when a file is written.

indicator_to_dict

indicator_to_dict(indicator: Indicator) -> dict[str, object]

Return a JSON-ready mapping for one indicator.

Parameters:

• indicator (Indicator) –

  Indicator to describe.

Returns:

• dict[str, object] –

  A dictionary of plain JSON types.

isoformat_z

isoformat_z(moment: datetime | None = None) -> str

Format a timestamp as YYYY-MM-DDTHH:MM:SS.sssZ.

Parameters:

• moment (datetime | None, default: None ) –

  Aware or naive datetime. Naive values are treated as UTC. Defaults to the current time.

Returns:

• str –

  A UTC timestamp with millisecond precision and a Z suffix.