m5c detection imports

Detection imports let teams bring foreign rule formats into the Mach5 package workflow. Imports are source inputs, not the runtime format.

Mach5 currently supports Sigma import preview/export for simple match-style rules.

Where import files live

m5c discovers detection import configurations from import.yaml files under packages/**/detection_imports/**.

A typical layout is:

packages/security-analytics/
  detection_imports/
    sigma/
      import.yaml
      field-mapping.yaml
      sources/
        okta-failed-login.yml
        github-push-event.yml

Keep the original foreign rules committed next to the import configuration so translations are reproducible.

Build an import configuration

Build an import in this order:

1. Choose the source language.
2. Add source file globs.
3. Add a field mapping file when defaults are not enough.
4. Preview the import into a temporary directory.
5. Review diagnostics for partial, requires_contract_mapping, or unsupported rules.
6. Promote translated Detection IR only when your team intentionally wants native copies.
7. Keep the original source rules as the source of truth unless you deliberately migrate.

Import document

kind: DetectionImport
apiVersion: semantic-catalog.mach5.io/v1alpha1
metadata:
  name: sigma-security-analytics
spec:
  source_language: sigma
  sources:
    - sources/*.yml
  field_mapping: field-mapping.yaml
  default_status: review
  on_unsupported: disable

Top-level fields

Source files

sources accepts relative file paths or simple filename globs with *.

sources:
  - sources/*.yml
  - more-rules/specific-rule.yaml

Glob expansion is intentionally simple: the * applies to the filename portion in one directory. Use multiple entries for multiple directories.

Sigma rule shape

A simple Sigma source rule looks like this:

title: Okta Failed Authentication Event
id: M5-SA-SIGMA-OKTA-FAILURE-001
status: test
description: Okta authentication failure translated into identity authentication contract matcher.
logsource:
  product: okta
  service: system
detection:
  selection:
    outcome.result: FAILURE
  condition: selection
tags:
  - attack.credential_access
  - okta
level: medium

V1 import works best for rules with a single named selection and a condition that directly names that selection.

Supported condition shape:

detection:
  selection:
    event_type: PushEvent
  condition: selection

Compound conditions such as selection and not filter are imported as partial when possible and should be reviewed.

Field mapping file

A field mapping translates Sigma field names into contract fields, family/detector selection, and output entity defaults.

mappings:
  outcome.result:
    contract: identity.authentication_event.v1
    field: status_id
    family: identity_access
    detector: event_match
    entity_kind: principal
    entity_field: actor.user.email_addr
  source.ip:
    contract: identity.authentication_event.v1
    field: src_endpoint.ip
    family: identity_access
    detector: event_match
    entity_kind: ip
    entity_field: src_endpoint.ip
  event_type:
    contract: repo.activity.v1
    field: event_type
    family: repo_activity
    detector: event_match
    entity_kind: repository
    entity_field: repository.full_name

Field mapping entries are keyed by source-language field name. Each entry can define:

When no field mapping file is provided, m5c uses built-in defaults for common Okta and GitHub fields such as outcome.result, source.ip, actor.alternateId, event_type, and repository.full_name.

Value translation

The Sigma importer converts simple field matchers to Detection IR matchers.

For status_id mappings, common authentication strings are normalized:

Unsupported field modifiers or unmapped fields produce import diagnostics.

Preview Sigma output

m5c import sigma packages/security-analytics/detection_imports/sigma \
  --out /tmp/m5c-sigma-import/detections \
  --reports /tmp/m5c-sigma-import/reports \
  --field-mapping packages/security-analytics/detection_imports/sigma/field-mapping.yaml

The command writes Detection IR preview files and import diagnostics. It prints a summary:

imported 10 Sigma rule(s): 8 translated, 1 partial, 1 unsupported

A non-zero exit code indicates unsupported rules were present.

Generated Detection IR

A translated Sigma rule becomes a native Detection document similar to this:

kind: Detection
apiVersion: semantic-catalog.mach5.io/v1alpha1
metadata:
  name: okta-failed-authentication-event
  labels:
    source: sigma
  annotations:
    mach5.io/import.source_language: sigma
    mach5.io/import.source_ref: sources/okta-failed-login.yml
    mach5.io/import.status: translated
spec:
  id: M5-SA-SIGMA-OKTA-FAILURE-001
  title: Okta Failed Authentication Event
  family: identity_access
  detector: event_match
  level: medium
  enabled: true
  requires:
    contracts:
      identity.authentication_event.v1: ">=1.0.0 <2.0.0"
  matchers:
    - field: status_id
      operator: eq
      value: 2
  dedupe:
    strategy: event_entity
    fields: [detection_id, actor.user.email_addr, event_uid]

Review generated files before enabling or promoting them.

Import statuses

Unsupported preview files are generated as disabled detections with import diagnostic annotations.

Source of truth

Keep the foreign source files and import configuration as the source of truth unless your team intentionally promotes generated Detection IR.

Recommended workflow:

1. Commit import.yaml, source rules, and field mappings.
2. Run m5c validate and m5c lower; normal package flow imports configured sources in memory.
3. Use m5c import sigma only when you need preview files or diagnostics for review.
4. Avoid committing generated previews as a second source of truth.

Validate and lower workflow

m5c validate apps/security-analytics --workspace --offline
m5c lower apps/security-analytics --dev --out /tmp/m5c-lowered

Validation loads import configuration. Lowering can include imported detections in the package flow. Use the preview command when you want files and per-rule diagnostics for human review.

Common mistakes

Best practices

• Map fields into contracts, not directly into vendor-specific runtime names.
• Review partial translations before enabling them.
• Keep unsupported imports disabled.
• Add native Detection IR for rules that need semantics beyond simple Sigma matching.
• Use preview reports in pull requests when adding or changing imported rules.