hunt.md

What it is

hunt.md is a Markdown format for threat-hunting playbooks, plus huntmd, its reference validator/converter. Currently draft SPEC v0.6, evolving in the open. A hunt is YAML frontmatter (type, labels, severity, hypothesis, parameters, targets) followed by one ## heading per step, with fenced blocks holding the work (kql, agent, etc.) tagged with target= and params=, and → arrows for decisions/flow.

How it works

huntmd is stdlib + PyYAML only, so it vendors cleanly into a runtime's import path. Install and use:

cd tools && pip install -e .
huntmd validate ../hunts/kerberoasting.md              # lint against a profile
huntmd convert  ../hunts/kerberoasting.md              # → Huntbase definition YAML
huntmd convert  ../hunts/kerberoasting.md --to cacao   # → CACAO v2 playbook JSON
huntmd convert  ../hunts/kerberoasting.md --to misp    # → MISP event
huntmd convert  ../my-hunt.definition.yaml             # → hunt.md (inverse)
huntmd validate ../examples/results/kerberoasting-run.yaml  # lint a run result

validate checks step reachability, variable use, agent bounds, and gated destructive actions — not just YAML well-formedness. Profiles adapt the neutral format to a target and declare what it supports; a capability matrix shows per-runtime support, and a missing feature is framed as a runtime limit, never a format one.

Conversion fidelity (the part that decides trust)

The round-trip guarantees differ by target — this matters if you plan to share hunts across platforms:

flowchart LR
  H[hunt.md]
  H -->|export/import| CACAO[CACAO v2]
  CACAO -->|round-trip| EX1[exact]
  H -->|export| MISP[MISP event]
  MISP -->|"if exported by huntmd (source attached)"| EX2[exact]
  MISP -->|otherwise| D1[draft]
  CACAO2[3rd-party CACAO] -->|import| D2[draft]

• CACAO import/export is round-trip exact, tested against 49 real playbooks from six independent projects.
• MISP export uses the HUNT-EX taxonomy and threat-hunt-* objects; the source travels as an attachment, so re-import is exact only if huntmd produced it — otherwise a draft.
• Importing a foreign CACAO playbook yields a draft, not an exact hunt.

What to do

To author: copy templates/hunt-template.md into hunts/<short-slug>.md, fill hypothesis/targets/parameters/steps per SPEC.md, huntmd validate, then open a PR describing threat, data sources, and known false positives. To operationalize: convert to a Huntbase definition to run, or to CACAO to share.

Caveats

Pre-1.0 draft spec (v0.6), explicitly still changing — check CHANGELOG.md for compatibility before depending on it. "Exact" conversion is a property of huntmd-originated artifacts only; anything arriving from a third-party tool lands as a draft you'll need to review.