Rule

Mihari has Sigma like format to describe a set of search queries to express a rule.

Mihari has three main components to compose a rule.

graph LR
  Analyzers["Analyzers (Queries)"] --> |Artifacts| Enrichers[Enrichers]
  Enrichers --> |"(Enriched) Artifacts"| Emitters[Emitters]
  Emitters --> |Alert| Database[(Database)]

• Analyzers/Queries: a list of queries (analyzers) that builds a list of artifacts
• Enrichers: a list of enrichers that enriches a list of artifacts
• Emitters: a list of emitters that emits a list of artifacts as an alert

An artifact has five types:

• IP address (ip)
• Domain (domain)
• URL (url)
• Mail (mail)
• Hash (hash)

An alert can have multiple artifacts bundled by a rule.

Note

A rule is assumed to be continuously searched. An alert generated by a rule will only have new findings at that time.

Let's break down the following example:

id: c7f6968e-dbe1-4612-b0bb-8407a4fe05df
title: Example
description: Mihari rule example
created_on: "2023-01-01"
updated_on: "2023-01-02"
author: ninoseki
references:
  - https://github.com/ninoseki/mihari
related:
  - 6254bb74-5e5d-42ad-bc1e-231da0293b0f
tags:
  - foo
  - bar
queries:
  - analyzer: shodan
    query: ip:1.1.1.1
  - analyzer: censys
    query: ip:8.8.8.8
enrichers:
  - enricher: whois
  - enricher: mmdb
  - enricher: shodan
  - enricher: google_public_dns
emitters:
  - emitter: database
  - emitter: misp
  - emitter: slack
  - emitter: thehive
data_types:
  - hash
  - ip
  - domain
  - url
  - mail
falsepositives: []
artifact_ttl: null

Components

ID

id (string) is an unique ID of a rule. UUID v4 is recommended.

Title

title (string) is a title of a rule.

Description

description (string) is a short description of a rule.

Created/Updated On

created_on (date) is a date of a rule creation. Optional. Also a rule can have updated_on that is a date of a rule modification. Optional.

Tags

tags (array[:string]) is a list of tags of a rule. Optional. Defaults to [].

Author

author (string) is an author of a rule. Optional.

References

references (array[:string]) is a list of a references of a rule. Optional.

Related

related (array[:string]) is a list of related rule IDs. Optional.

Queries

queries is a list of queries/analyzers. See Analyzers to know details of each analyzer.

Enrichers

enrichers is a list of enrichers. See Enrichers to know details of each enricher.

Defaults to:

• google_public_dns
• mmdb
• shodan
• whois

Emitters

emitters is a list of emitters. See Emitters to know details of each emitter.

Defaults to:

• database

Data Types

data_types (array[:string]) is a list of data (artifact) types to allow by a rule. Types not defined in here will be automatically rejected.

Defaults to:

• ip
• domain
• url
• mail
• hash

False positives

falsepositives (array[:string]) is a list of false positive values. Optional. A string or regexp can be used in here.

For example,

falsepositives:
  - 127.0.0.1
  - /^example\.(com|net)$/

rejects:

• 127.0.0.1
• example.com
• example.net

Artifact TTL

artifact_ttl (integer) is an integer value of artifact TTL (Time-To-Live) in seconds. Optional.

Mihari rejects a duplicated artifact in a rule by default.

But you may want to get a same artifact after a certain period of time. artifact_ttl is for that. If a rule finds a same artifact after artifact_ttl seconds have been passed, that artifact will be included in an alert.

How to Run a Rule

Once you finish writing a rule, you can run the rule by mihari CLI.

Note

You have to initialize the database by mihari db migrate if you haven't already done.

mihari search /path/to/rule.yml

The command outputs an alert to the standard output. Also you can confirm it via CLI or web app.

mihari alert list
# or
mihari web