Azuma¶
Yet another Sigma library for Python.
Note: This is a forked version of CybercentreCanada/pysigma. Most of the things in this library come from their hard work.
Requirements¶
- Python 3.10+
Installation¶
pip install azuma
Usage¶
from azuma import Rule, RuleSet
rule = Rule.model_validate_yaml(
"""
title: test
detection:
foo:
- bar
condition: foo
logsource:
category: test
"""
)
# Rule#match returns whether an event is matched with the rule or not
>>> rule.match({"foo": "bar"})
True
>>> rule.match({"foo": "-"})
False
# or you can create a rule from a file
rule = Rule.parse_file("./your_rule.yml")
# use RuleSet if you want to do bulk matches
rule_set = RuleSet.from_dir("./rules/")
# RuleSet#match_all returns a list of rules matches with an event
rule_set.match_all({...})
CLI¶
Scan¶
$ azuma scan --help
Usage: azuma scan [OPTIONS] PATH TARGET
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * path TEXT Path (or glob pattern) to rule YAML file(s) │
│ [default: None] │
│ [required] │
│ * target TEXT Path (or glob pattern) to event JSON file(s) │
│ [default: None] │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
# Scan by single rule & single event file
$ azuma scan rule.yml event.json
# Scan by multiple rules & multiple event files
$ azuma scan "rules/*.yml" "events/*.json"
Validate¶
$ azuma validate --help
Usage: azuma validate [OPTIONS] PATH...
╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * path PATH... Path(s) (or glob pattern(s)) to rule YAML file(s) [default: None] [required] │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --check-id --no-check-id Check for missing 'id' field [default: no-check-id] │
│ --check-license --no-check-license Check for missing 'license' field [default: no-check-license] │
│ --check-author --no-check-author Check for missing 'author' field [default: no-check-author] │
│ --check-date --no-check-date Check for missing 'date' field [default: no-check-date] │
│ --check-modified --no-check-modified Check for missing 'modified' field [default: no-check-modified] │
│ --check-description --no-check-description Check for missing 'description' field [default: no-check-description] │
│ --check-status --no-check-status Check for missing 'status' field [default: no-check-status] │
│ --check-level --no-check-level Check for missing 'level' field [default: no-check-level] │
│ --check-references --no-check-references Check for missing 'references' field [default: no-check-references] │
│ --check-tags --no-check-tags Check for missing 'tags' field [default: no-check-tags] │
│ --check-falsepositives --no-check-falsepositives Check for missing 'falsepositives' field [default: no-check-falsepositives] │
│ --check-fields --no-check-fields Check for missing 'fields' field [default: no-check-fields] │
│ --check-related --no-check-related Check for missing 'related' field [default: no-check-related] │
│ --check-all --no-check-all Check for all the missing optional fields [default: no-check-all] │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
check option is for checking missing optional field such as id.
$ azuma validate /path/to/yml --check-id
.... has 1 validation error for Field required
id
Field required [type=missing, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.7/v/missing
--check-all checks presences of all the optional fields.
$ azuma validate /path/to/yml --check-id
... has 5 validation errors for Field required
license
Field required [type=missing, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.7/v/missing
id
Field required [type=missing, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.7/v/missing
modified
Field required [type=missing, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.7/v/missing
author
Field required [type=missing, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.7/v/missing
related
Field required [type=missing, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.7/v/missing
Validate With Hook Managers¶
pre-commit/pre-commit¶
- repo: https://github.com/ninoseki/azuma
rev: v0.4.0
hooks:
- id: azuma
If you want to validate only YAML files in rules directory:
- repo: https://github.com/ninoseki/azuma
rev: v0.4.0
hooks:
- id: azuma
files: rules/.*\.(yml|yaml)$
evilmartians/lefthook¶
pre-commit:
commands:
azuma:
run: azuma validate {staged_files}
glob: "*.{yaml,yml}"
If you want to validate only YAML files in rules directory:
pre-commit:
commands:
azuma:
root: "rules/"
run: azuma validate {staged_files}
glob: "*.{yaml,yml}"
Known limitations¶
Modifiers¶
The following modifiers are not supported.
- expand
- fieldref
In other words, the following modifiers are supported.
- all
- base64
- base64offset
- cased
- cidr
- contains
- endswith
- exists
- gt
- gte
- lt
- lte
- re
- startswith
- utf16
- utf16be
- utf16le
- wide
- windash
Correlations¶
Correlations is not supported.