id: sigma-attack-mapping-audit
namespace: company.security
description: |
Audit Sigma rule technique tags against the real MITRE Enterprise ATT&CK
catalog. Report revoked, deprecated, unknown and malformed mappings, including
replacements explicitly recorded by MITRE. Keep the evidence before optionally
failing a release gate. This checks mapping maintenance, not detection coverage.
inputs:
- id: repository
type: STRING
defaults: https://github.com/SigmaHQ/sigma.git
description: Public HTTPS Git repository containing Sigma rules. Its code is not
executed.
validator: '^https://[^\s]+$'
- id: branch
type: STRING
defaults: master
description: Branch to audit. The checked-out commit is recorded in the report.
- id: rules_path
type: STRING
defaults: rules
description: Directory of Sigma YAML rules, relative to the repository root.
- id: attack_url
type: STRING
defaults: https://raw.githubusercontent.com/mitre-attack/attack-stix-data/master/enterprise-attack/enterprise-attack.json
description: Enterprise ATT&CK STIX bundle. Use a version-specific MITRE URL to
reproduce an older audit.
validator: '^https://[^\s]+$'
- id: fail_on_findings
type: BOOL
defaults: false
description: Fail after saving reports if any revoked, deprecated, unknown or
malformed technique tag is found.
triggers:
- id: weekly
type: io.kestra.plugin.core.trigger.Schedule
cron: "0 7 * * 1"
disabled: true
tasks:
- id: sources
type: io.kestra.plugin.core.flow.Parallel
tasks:
- id: download_attack
type: io.kestra.plugin.core.http.Download
uri: "{{ inputs.attack_url }}"
retry:
type: exponential
interval: PT2S
maxInterval: PT20S
maxAttempts: 3
- id: workspace
type: io.kestra.plugin.core.flow.WorkingDirectory
tasks:
- id: clone_rules
type: io.kestra.plugin.git.Clone
url: "{{ inputs.repository }}"
branch: "{{ inputs.branch }}"
directory: ruleset
depth: 1
- id: inventory
type: io.kestra.plugin.scripts.python.Script
description: Parse rules without executing repository code; reject unreadable
YAML and empty selections.
containerImage: python:3.13-slim
taskRunner:
type: io.kestra.plugin.scripts.runner.docker.Docker
beforeCommands:
- pip install --disable-pip-version-check PyYAML==6.0.2
env:
RULES_PATH: "{{ inputs.rules_path }}"
REPOSITORY: "{{ inputs.repository }}"
BRANCH: "{{ inputs.branch }}"
outputFiles:
- inventory.json
script: |
import json
import os
import re
from pathlib import Path
import yaml
repo = Path("ruleset").resolve()
root = (repo / os.environ["RULES_PATH"]).resolve()
if not root.is_relative_to(repo) or not root.is_dir():
raise ValueError("rules_path must be an existing directory inside the repository")
git = repo / ".git"
head = (git / "HEAD").read_text().strip()
if head.startswith("ref: "):
ref = head[5:]
ref_file = (git / ref).resolve()
if not ref_file.is_relative_to(git.resolve()):
raise ValueError("Git HEAD points outside the metadata directory")
if ref_file.is_file():
head = ref_file.read_text().strip()
else:
packed = (git / "packed-refs").read_text().splitlines()
head = next((line.split()[0] for line in packed
if line.endswith(" " + ref)), "")
if not re.fullmatch(r"[0-9a-f]{40,64}", head):
raise ValueError("Could not determine the checked-out Git commit")
rules = []
for folder, dirs, files in os.walk(root, followlinks=False):
if any((Path(folder) / name).is_symlink() for name in dirs + files):
raise ValueError(f"Symbolic link in selected rule directory: {folder}")
for name in sorted(files):
if Path(name).suffix.lower() not in (".yml", ".yaml"):
continue
path = Path(folder) / name
relative = path.relative_to(repo).as_posix()
if path.stat().st_size > 1024 * 1024:
raise ValueError(f"Rule exceeds 1 MiB: {relative}")
try:
rule = yaml.safe_load(path.read_text(encoding="utf-8"))
except (yaml.YAMLError, UnicodeError) as error:
raise ValueError(f"Cannot parse {relative}: {error}") from error
if not isinstance(rule, dict) or not ("detection" in rule or "correlation" in rule):
raise ValueError(f"Not a Sigma detection or correlation rule: {relative}")
tags = rule.get("tags", [])
if not isinstance(tags, list) or any(not isinstance(tag, str) for tag in tags):
raise ValueError(f"tags must be a list of strings: {relative}")
rules.append({
"path": relative, "id": str(rule.get("id", "")),
"title": str(rule.get("title", "")),
"tags": sorted({tag.lower() for tag in tags if tag.lower().startswith("attack.t")}),
})
if not rules:
raise ValueError("No Sigma YAML rules found; an empty selection is not a clean audit")
if not any(rule["tags"] for rule in rules):
raise ValueError("No ATT&CK technique tags found in the selected rules")
inventory = {
"repository": os.environ["REPOSITORY"], "branch": os.environ["BRANCH"],
"commit": head, "rules": sorted(rules, key=lambda rule: rule["path"]),
}
Path("inventory.json").write_text(json.dumps(inventory, indent=2), encoding="utf-8")
print("::" + json.dumps({"outputs": {"rules": len(rules), "commit": head}}) + "::")
- id: audit
type: io.kestra.plugin.scripts.python.Script
description: Resolve technique status and MITRE's explicit replacement
relationships against one downloaded snapshot.
containerImage: python:3.13-slim
taskRunner:
type: io.kestra.plugin.scripts.runner.docker.Docker
inputFiles:
inventory.json: "{{ outputs.inventory.outputFiles['inventory.json'] }}"
attack.json: "{{ outputs.download_attack.uri }}"
env:
ATTACK_URL: "{{ inputs.attack_url }}"
outputFiles:
- audit.json
script: |
import hashlib
import json
import os
import re
from collections import Counter, defaultdict
from pathlib import Path
inventory = json.loads(Path("inventory.json").read_text(encoding="utf-8"))
raw = Path("attack.json").read_bytes()
bundle = json.loads(raw)
if bundle.get("type") != "bundle" or not isinstance(bundle.get("objects"), list):
raise ValueError("Expected an ATT&CK STIX bundle with an objects array")
objects = {}
for obj in bundle["objects"]:
if not isinstance(obj, dict) or not isinstance(obj.get("id"), str):
raise ValueError("Malformed STIX object")
previous = objects.get(obj["id"], {})
if obj.get("modified", "") >= previous.get("modified", ""):
objects[obj["id"]] = obj
def external_id(obj):
return next((ref.get("external_id", "") for ref in obj.get("external_references", [])
if ref.get("source_name") == "mitre-attack"
and re.fullmatch(r"T\d{4}(?:\.\d{3})?", ref.get("external_id", ""))), "")
def status(obj):
if obj.get("revoked", False):
return "revoked"
return "deprecated" if obj.get("x_mitre_deprecated", False) else "active"
techniques = {external_id(obj): obj for obj in objects.values()
if obj.get("type") == "attack-pattern" and external_id(obj)}
if not techniques:
raise ValueError("No ATT&CK technique objects found in the supplied bundle")
replacements = defaultdict(set)
for obj in objects.values():
if (obj.get("type") == "relationship" and obj.get("relationship_type") == "revoked-by"
and not obj.get("revoked", False) and not obj.get("x_mitre_deprecated", False)):
target = objects.get(obj.get("target_ref"), {})
target_id = external_id(target)
if target_id:
replacements[obj["source_ref"]].add(f"{target_id} ({status(target)})")
rows = []
for rule in inventory["rules"]:
for tag in rule["tags"]:
technique_id = tag.removeprefix("attack.").upper()
valid = re.fullmatch(r"attack\.t\d{4}(?:\.\d{3})?", tag)
obj = techniques.get(technique_id)
state = "malformed" if not valid else (status(obj) if obj else "unknown")
rows.append({
"path": rule["path"], "rule_id": rule["id"], "title": rule["title"],
"tag": tag, "technique_id": technique_id,
"technique_name": obj.get("name", "") if obj else "",
"status": state,
"replaced_by": "; ".join(sorted(replacements.get(obj["id"], []))) if obj else "",
})
counts = Counter(row["status"] for row in rows)
finding_count = sum(count for state, count in counts.items() if state != "active")
report = {
"schema": "sigma-attack-mapping-audit/1",
"source": {key: inventory[key] for key in ("repository", "branch", "commit")},
"reference": {"url": os.environ["ATTACK_URL"], "sha256": hashlib.sha256(raw).hexdigest()},
"rules_scanned": len(inventory["rules"]),
"rules_without_technique_tags": sum(not rule["tags"] for rule in inventory["rules"]),
"status_counts": dict(sorted(counts.items())), "finding_count": finding_count,
"mappings": rows,
}
Path("audit.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
print("::" + json.dumps({"outputs": {"finding_count": finding_count,
"status_counts": report["status_counts"]}}) + "::")
- id: render_report
type: io.kestra.plugin.scripts.python.Script
description: Save every mapping as CSV and a reviewable Markdown finding list
before the optional gate.
containerImage: python:3.13-slim
taskRunner:
type: io.kestra.plugin.scripts.runner.docker.Docker
inputFiles:
audit.json: "{{ outputs.audit.outputFiles['audit.json'] }}"
outputFiles:
- mappings.csv
- report.md
script: |
import csv
import html
import json
from pathlib import Path
report = json.loads(Path("audit.json").read_text(encoding="utf-8"))
fields = ["path", "rule_id", "title", "tag", "technique_id",
"technique_name", "status", "replaced_by"]
with Path("mappings.csv").open("w", newline="", encoding="utf-8") as handle:
writer = csv.DictWriter(handle, fieldnames=fields)
writer.writeheader()
writer.writerows(report["mappings"])
def cell(value):
return html.escape(str(value)).replace("|", "\\|").replace("\n", " ").replace("`", "'")
lines = [
"# Sigma ATT&CK mapping audit", "",
f"Repository: {cell(report['source']['repository'])}",
f"Commit: `{report['source']['commit']}`",
f"Reference: {cell(report['reference']['url'])}",
f"Reference SHA-256: `{report['reference']['sha256']}`", "",
f"Rules scanned: {report['rules_scanned']}",
f"Rules without technique tags: {report['rules_without_technique_tags']}",
f"Mappings requiring review: {report['finding_count']}", "",
"| Mapping status | Count |", "| --- | ---: |",
]
for state, count in report["status_counts"].items():
lines.append(f"| {state} | {count} |")
lines += ["", "## Mappings requiring review", "",
"| Rule file | Tag | Status | MITRE replacement |",
"| --- | --- | --- | --- |"]
for row in report["mappings"]:
if row["status"] != "active":
lines.append("| " + " | ".join(cell(row[key]) for key in
("path", "tag", "status", "replaced_by")) + " |")
if not report["finding_count"]:
lines += ["", "No stale or unrecognized technique mappings found in this selection."]
lines += ["", "## Interpretation", "",
"Unknown means absent from this Enterprise ATT&CK snapshot; a tag may belong to another domain.",
"Replacements are explicit, immediate MITRE relationships, with their own status shown.",
"Review rule semantics before changing a tag. No rule is modified by this flow.",
"Active tags do not establish detection coverage or detection quality."]
Path("report.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
- id: gate
type: io.kestra.plugin.core.flow.If
condition: "{{ inputs.fail_on_findings and outputs.audit.vars.finding_count > 0 }}"
then:
- id: needs_review
type: io.kestra.plugin.core.execution.Fail
errorMessage: "{{ outputs.audit.vars.finding_count }} technique mappings need
review. Reports are saved in render_report outputs."
else:
- id: audit_complete
type: io.kestra.plugin.core.log.Log
message: "Audited {{ outputs.inventory.vars.rules }} rules at {{
outputs.inventory.vars.commit }}. Findings: {{
outputs.audit.vars.finding_count }}; counts: {{
outputs.audit.vars.status_counts }}."
outputs:
- id: report
type: FILE
required: false
value: "{{ outputs.render_report.outputFiles['report.md'] ?? null }}"
- id: mappings
type: FILE
required: false
value: "{{ outputs.render_report.outputFiles['mappings.csv'] ?? null }}"
- id: audit
type: FILE
required: false
value: "{{ outputs.audit.outputFiles['audit.json'] ?? null }}"