qarbaal

Extract, normalize, validate, and export indicators of compromise from text and files.

Documentation: https://ahur4.github.io/Qarbaal/

qarbaal reads reports, logs, and message files on your machine and returns classified indicators. It refangs defanged text, records where each value came from, and writes CSV, JSON, STIX 2.1, MISP, OpenIOC, and network rules. The base install uses only the Python standard library. It does not call an enrichment API.

Installation

Python 3.10 or newer.

pip install qarbaal

That install has no runtime dependencies. Optional readers are separate extras:

pip install "qarbaal[html]"    # HTML
pip install "qarbaal[pdf]"     # PDF
pip install "qarbaal[docx]"    # Word
pip install "qarbaal[yaml]"    # YAML
pip install "qarbaal[pcap]"    # packet captures
pip install "qarbaal[pydantic]"
pip install "qarbaal[all]"

Quickstart

from qarbaal import IOCExtractor, extract

report = """
From: support[at]corp-it-desk[.]com
Lure: hxxps://login[.]corp-it-desk[.]com/session
Beacon: 185.220.101.42
MD5: d41d8cd98f00b204e9800998ecf8427e
"""

result = extract(report)
for indicator in result:
    print(indicator.type, indicator.value, indicator.tags, indicator.line)

extractor = IOCExtractor(
    extract_types=["ipv4", "domain", "url", "hash", "email"],
    normalize=True,
    validate=True,
    deduplicate=True,
)
same = extractor.extract(report, source="ticket-14")

extract() uses the default type set. File paths, mutex names, and User-Agent strings stay out of that set until you ask for them with extract_types or "all".

A synthetic incident is included:

from qarbaal import SAMPLE, extract

print(extract(SAMPLE).stats.counts)

What you get back

Each indicator keeps three strings:

It also carries noise tags, a validation result, a confidence heuristic, local enrichment, pivot links, and one sighting per occurrence (source, line, offset, and page when the file has pages).

Command line

qarbaal report.txt
qarbaal mail.eml notes.json -f stix -o bundle.json
qarbaal --hide-private --defang -f table alerts.log
qarbaal --types all -f suricata capture.txt

With no file, qarbaal reads stdin. Formats: table, csv, json, jsonl, stix, list, misp, openioc, suricata, snort.

Further reading

• Installation
• Indicator types
• Defanging
• Normalization
• Exports
• Command line
• API reference
• Changelog