Monitors, dashboards and detections as code

Tracix takes two kinds of content from Git. Detection rules, value lists and YARA rulesets live as plain files in a detection repository. Monitors, visualizations, dashboards and APM service groups are described in tracix.io/v1 JSON bundles. Both are published the same way: validate, then plan, then apply the plan you reviewed.

How content managed as code behaves

• Git owns the definition. Each published object gets a stable ID, code:<package>:<kind>:<uid>, and is marked as managed as code.
• The workspace won't edit it. Editing or deleting a managed definition in the workspace is refused, for admins too. To change one for yourself, duplicate it: the copy is an ordinary object you own.
• Operational controls stay yours. You can still enable, disable and snooze a managed monitor and change where it notifies, and enable or disable a managed detection rule or YARA ruleset. These settings survive later publishes.
• A package owns its objects. Everything a repository or bundle publishes belongs to the package it names.

Integration packages from the catalog install their monitors and dashboards the same way, so those are managed as code too.

Validate, plan and apply

• Apply refuses a stale plan. If anything changed since the review, apply answers 409 and you plan again.
• Plans survive a merge. The plan hash covers each object's action, definition and live version, not the commit, so a plan reviewed on a pull request still applies at the merge commit when the content is the same.
• Apply isn't a transaction. Each write is safe to repeat, but a failure part way leaves the earlier writes in place. Plan again and apply again.
• Roll back from Git. Revert the commit and apply it. For detection content, only the rules whose definition changes are written.

Detection repositories

A detection repository holds plain files, and its Sigma rules stay readable by sigma-cli and pySigma.

tracix-detections.yaml    the manifest: package, defaults, overrides
sigma/**/*.yml|yaml       Sigma rules, verbatim (up to 50 documents per file)
native/**/*.yml|yaml      native rules: sql, sequence, new_terms, cardinality, watchlist
lists/**/*.yml|yaml       value lists: name, description, items
yara/**/*.yar|yara        YARA rulesets, one per file
tests/**/*.yml|yaml       fixtures: events each rule must or must not match

Other files, such as a README or CI configuration, are ignored. A repository can keep its detections in a subfolder. It can hold up to 5,000 detection files and 50 MB of content, and publish up to 5,000 objects.

The manifest

tracix-detections.yaml at the repository root names the package and tunes the rules. Unknown keys and values that would need converting fail validation, so a typo never becomes a silent default.

package: acme-soc

defaults:
  intervalSeconds: 60   # how often each rule's monitor runs
  windowMinutes: 5      # how far back each run looks
  rbacFloor: editor     # who sees the published rules: viewer | editor | admin
  license: custom       # for Sigma documents that declare no license

overrides:
  # One rule, by its Sigma id: tuning lives here, not in the Sigma file.
  "0dc16a63-818e-4162-95ea-d8f9e5740ef7":
    severity: high
    exceptions:
      - User: list:service-accounts
    suppress:
      byFields: [host.name]
      windowMinutes: 60

  # A glob over repository paths: new network rules start in shadow mode.
  "sigma/network/**":
    stage: test

prune: true

Stages

Every rule runs at a stage. A rule's stage comes from the manifest; without one, a Sigma rule's status decides: experimental and test start in test, stable in production, and deprecated or unsupported documents are errors.

Promote a rule with a pull request that changes its stage. A rule that doesn't compile is published disabled, with its reasons, never dropped.

Fixtures

Files under tests/ hold events a rule must or must not match. Validate and plan run every case against the compiled rule on one synthetic row: nothing is written and nothing alerts.

rule: 0dc16a63-818e-4162-95ea-d8f9e5740ef7
cases:
  - name: whoami run by a person
    event:
      Image: 'C:\Windows\System32\whoami.exe'
      User: alice
    expect: match

  - name: service account excluded by the exception
    event:
      Image: 'C:\Windows\System32\whoami.exe'
      User: svc_backup
    expect: no_match
    withExceptions: true

• Sigma and SQL rules run fixtures. Sequence, new terms, cardinality and watchlist rules need several events or history, so their cases report unsupported and the rules are checked by compiling them.
• A file that names a ruleset holds YARA fixtures: text or base64 samples and the exact set of rules that must match.
• A file holds up to 100 cases. A failing case makes validate and plan report valid: false, so the CLI exits with 1 before apply.

Conflicts

A repository rule whose rule ID matches a rule created in the UI or installed from the Sigma pack plans a conflict. Apply refuses the whole plan until you confirm the replacement with --replace. The older rule is then disabled and linked to the new one, never taken over in place. Value lists can't be replaced: a list name that another list already uses blocks the plan.

In this release, a repository refuses Sigma correlation and filter documents. Write a correlation as a native sequence or cardinality rule, and a filter as manifest exceptions.

Run the CLI

tracix-detections is a single Node.js 20 or later file with no dependencies. Your workspace serves the build that matches its API.

1. 1

   Point it at your workspace

   Set your workspace's address and a CI key with security.read:

   bashCopy

   export TRACIX_URL=https://production-a7k3p2q9.app.tracix.io
   export TRACIX_API_KEY=txk_...

2. 2

   Download the CLI

   bashCopy

   curl -fsS -H "X-API-Key: $TRACIX_API_KEY" \
   "$TRACIX_URL/api/security/detections/cli" -o tracix-detections.mjs

   The response's X-Tracix-Cli-Sha256 header carries the file's SHA-256, so CI can pin a reviewed build.

3. 3

   Validate and plan

   bashCopy

   node tracix-detections.mjs validate .
   node tracix-detections.mjs plan . plan.json

   The plan lists what apply would create, update, delete or replace, and is saved for review.

4. 4

   Apply the reviewed plan

   With a key that carries security.manage:

   bashCopy

   node tracix-detections.mjs apply . plan.json

   More than 200 writes run in the background, and the CLI follows the job to the end.

CLI reference

The CLI exits with 0 on success, 1 for compile errors, failing fixtures, unconfirmed conflicts, a blocked plan or a failed request, and 2 for usage or configuration errors. It sends the key only in a header to TRACIX_URL, refuses redirects and masks the key in everything it prints. A plan is bound to the workspace it was made against, and apply refuses a plan made for another TRACIX_URL.

Sync a repository from your workspace

Your workspace can follow a repository without any CI. An admin connects it under Security › Detection rules › Repositories with Connect repository, or with Keep in sync when importing rules from a Git repository, using a GitHub or GitLab credential stored in the workspace.

Every other plan waits for an admin to review it, with a diff per rule, and apply or discard it. To roll back, Sync to commit pins the repository to an earlier commit and plans it.

Export rules you wrote in the UI

Security › Detection rules › Export, or Export to git on one rule, turns rules authored in the UI into repository files: a download, or one pull request on a connected GitHub repository (GitLab repositories export as files). After the merge, the next plan shows each exported rule as a conflict that replaces its UI rule; confirm it to hand the rule to Git.

To get a published package back as files, run node tracix-detections.mjs export <package> <outdir>. Fixtures aren't stored in the workspace, so they aren't exported.

Monitor and dashboard bundles

A bundle is one JSON file that describes monitors, visualizations, dashboards and APM service groups.

{
  "apiVersion": "tracix.io/v1",
  "package": "team-operations",
  "revision": "1.0.0",
  "resources": [
    {
      "kind": "monitor",
      "uid": "service-error-rate",
      "attributes": {
        "name": "Service error rate",
        "description": "Sustained server error ratio above 5 percent.",
        "templateId": "apm.error_rate",
        "enabled": false,
        "condition": "above",
        "thresholds": { "alert": 5, "warn": 2 },
        "windowMinutes": 15,
        "pendingForMinutes": 5,
        "noData": "last_known",
        "sharing": { "visibility": "team", "rbacFloor": "viewer" }
      },
      "tests": [
        { "name": "healthy", "value": 1, "expected": "ok" },
        { "name": "warning", "value": 3, "expected": "warn" },
        { "name": "alert", "value": 6, "expected": "alert" }
      ]
    }
  ]
}

Validation is strict: an unknown field fails, and a monitor value that would have to be converted or clamped fails instead of being adjusted. Detection content can't go in a bundle; it comes from a detection repository.

Tests

A value-threshold monitor can carry tests: a name, a numeric value, an optional currentLevel and the expected level (ok, warn or alert). Validation runs the real threshold logic, including recovery. Tests don't replay queries, pending periods, missing data timing, notifications or anomaly learning, so check those with real telemetry in a staging workspace.

Delete and restore

Leaving an object out of a bundle never deletes it. To delete one, keep it in the bundle with "state": "absent", plan and apply: the plan shows delete. Set it back to present to restore it. Apply writes visualizations before the dashboards that use them and deletes dashboards first, so delete or update the dashboards that reference a visualization in the same change.

Publish a bundle

An export captures each object's current definition and operational controls. It isn't a backup of your Git file: tests and comments aren't stored in the workspace.

Next steps