From 2e263a03a0c64d65f22343c73cbf6d4d4fe11ea2 Mon Sep 17 00:00:00 2001 From: Rehan Khan Date: Sun, 23 Aug 2026 20:44:16 +0500 Subject: [PATCH] Add Vestrix integration --- integrations/vestrix_integration/README.md | 137 ++++++++++++++++++ .../active_response/README.md | 4 + .../vestrix_integration/dashboards/README.md | 4 + .../decoders/0585-vestrix_decoders.xml | 9 ++ .../ruleset/rules/1000-vestrix_rules.xml | 64 ++++++++ .../ruleset/testing/test.ini | 25 ++++ .../vestrix_integration/sca/README.md | 4 + .../threat_intel/README.md | 4 + 8 files changed, 251 insertions(+) create mode 100644 integrations/vestrix_integration/README.md create mode 100644 integrations/vestrix_integration/active_response/README.md create mode 100644 integrations/vestrix_integration/dashboards/README.md create mode 100644 integrations/vestrix_integration/ruleset/decoders/0585-vestrix_decoders.xml create mode 100644 integrations/vestrix_integration/ruleset/rules/1000-vestrix_rules.xml create mode 100644 integrations/vestrix_integration/ruleset/testing/test.ini create mode 100644 integrations/vestrix_integration/sca/README.md create mode 100644 integrations/vestrix_integration/threat_intel/README.md diff --git a/integrations/vestrix_integration/README.md b/integrations/vestrix_integration/README.md new file mode 100644 index 0000000..055202b --- /dev/null +++ b/integrations/vestrix_integration/README.md @@ -0,0 +1,137 @@ +# Vestrix-Wazuh Integration + +## Table of Contents + +* [Introduction](#introduction) +* [Prerequisites](#prerequisites) +* [Installation and Configuration](#installation-and-configuration) + * [Installing Vestrix](#installing-vestrix) + * [Initial Vestrix Configuration](#initial-vestrix-configuration) + * [Installing Wazuh](#installing-wazuh) + * [Initial Wazuh Configuration](#initial-wazuh-configuration) + * [Using the Integration Files](#using-the-integration-files) +* [Integration Steps](#integration-steps) +* [Integration Testing](#integration-testing) +* [Included and Omitted Components](#included-and-omitted-components) +* [Provenance and Maintenance](#provenance-and-maintenance) +* [Sources](#sources) + +## Introduction + +This integration decodes Vestrix JSON physical-security events and applies +Wazuh rules for high-confidence intrusion, missing PACS correlation, sensor +tampering, and a composite authentication-anomaly correlation. + +## Prerequisites + +* A Wazuh manager. Version 4.14.5 is the only version tested. +* Vestrix producing one-line JSON events containing `"source":"vestrix"`. +* Prevalidated `confidence_level` values from Vestrix. +* An upstream PACS enricher for rule `100202`, if missing-badge correlation is + required. + +Compatibility with earlier Wazuh 4.x versions is untested. Rules `100210` and +`100211` depend on Wazuh 4.14.5 built-in OpenSSH rule IDs `5712` and `5763`. + +## Installation and Configuration + +### Installing Vestrix + +Install Vestrix using the instructions in the +[Vestrix repository](https://github.com/dev-rehaann/VESTRIX). This contribution +contains only the Wazuh decoder and rules; it does not install Vestrix or a log +transport. + +### Initial Vestrix Configuration + +Configure the Vestrix-to-Wazuh transport to deliver one mapped JSON object per +log record. Each record must contain `"source":"vestrix"`. The Wazuh rules +consume the mapped `confidence_level`; they do not calculate that value. + +### Installing Wazuh + +A standard Wazuh manager installation is sufficient. Follow the +[official installation guide](https://documentation.wazuh.com/current/installation-guide/index.html) +if Wazuh is not already installed. + +### Initial Wazuh Configuration + +Configure the manager's existing log collection path to receive the Vestrix +JSON records. No additional API key, Python dependency, or network listener is +provided by this ruleset-only integration. + +### Using the Integration Files + +From this integration directory, install the decoder and rules in Wazuh's +custom-content directories: + +```console +sudo install -m 0640 ruleset/decoders/0585-vestrix_decoders.xml /var/ossec/etc/decoders/0585-vestrix_decoders.xml +sudo install -m 0640 ruleset/rules/1000-vestrix_rules.xml /var/ossec/etc/rules/1000-vestrix_rules.xml +sudo systemctl restart wazuh-manager +``` + +Preserve any existing local files and apply the owner and group used by other +files in those directories. The default Wazuh configuration loads custom XML +from these directories, so no additional `ossec.conf` entry is required. + +## Integration Steps + +1. Vestrix classifies a physical-security event and maps it to one JSON record. +2. The configured transport delivers that record to the Wazuh manager. +3. The `vestrix` decoder selects records whose `source` is `vestrix` and uses + Wazuh's `JSON_Decoder` to extract fields. +4. Rule `100200` groups the event; child rules generate alerts for supported + intrusion, PACS, tamper, and authentication-correlation conditions. + +Example input: + +```json +{"class":"intrusion","confidence":0.97,"confidence_level":"high","node_id":"node-07","site_id":"hq-karachi","source":"vestrix","zone_id":"server-room-west"} +``` + +The example selects decoder `vestrix` and alert rule `100201` at level 10. + +## Integration Testing + +After installing the XML files, verify the positive detection on the manager: + +```console +printf '%s\n' '{"class":"intrusion","confidence":0.97,"confidence_level":"high","node_id":"node-07","site_id":"hq-karachi","source":"vestrix","zone_id":"server-room-west"}' | sudo /var/ossec/bin/wazuh-logtest -U 100201:10:vestrix +``` + +A successful run ends with `Unit test OK`. The +`ruleset/testing/test.ini` file also contains a positive detection, a negative +non-match, and a regression case for the JSON decoder-name collision. + +For events delivered through the configured transport, inspect +`/var/ossec/logs/alerts/alerts.json` or the Wazuh dashboard's Security Events +view and confirm that the expected rule ID and level are present. + +## Included and Omitted Components + +* Rules and decoder: included. +* Active response: not applicable; alerting/logging only. +* SCA: not applicable to this physical-layer sensor integration. +* Threat intelligence: not currently provided or consumed. +* Dashboard: planned, not yet built. + +## Provenance and Maintenance + +* Original source: [Vestrix](https://github.com/dev-rehaann/VESTRIX). +* Adapted by: Vestrix contributors. +* Adaptation: packages the tested Vestrix decoder and rules for this repository; + the decoder, rule, and test logic is unchanged. +* Tested versions: Wazuh 4.14.5 with the Vestrix submission package from + [commit `fbfed6c`](https://github.com/dev-rehaann/VESTRIX/commit/fbfed6ce494cd06dfcdd2117ad7b9edf1388194a). +* Maintainer: Vestrix project maintainers. +* Support boundary: community-maintained through + [Vestrix GitHub issues](https://github.com/dev-rehaann/VESTRIX/issues) and + provided as-is. + +## Sources + +* [Wazuh integrations repository](https://github.com/wazuh/integrations) +* [Wazuh integrations contribution guide](https://github.com/wazuh/integrations/blob/main/CONTRIBUTING.md) +* [Wazuh custom decoder documentation](https://documentation.wazuh.com/current/user-manual/ruleset/decoders/custom.html) +* [Wazuh custom rule documentation](https://documentation.wazuh.com/current/user-manual/ruleset/rules/custom.html) diff --git a/integrations/vestrix_integration/active_response/README.md b/integrations/vestrix_integration/active_response/README.md new file mode 100644 index 0000000..d50937e --- /dev/null +++ b/integrations/vestrix_integration/active_response/README.md @@ -0,0 +1,4 @@ +# Active response + +Not applicable — Vestrix does not currently implement active response actions; +alerting/logging only. diff --git a/integrations/vestrix_integration/dashboards/README.md b/integrations/vestrix_integration/dashboards/README.md new file mode 100644 index 0000000..385ed8b --- /dev/null +++ b/integrations/vestrix_integration/dashboards/README.md @@ -0,0 +1,4 @@ +# Dashboards + +Planned but not yet built. A Wazuh dashboard for Vestrix physical-intrusion and +sensor-tamper alerts is a known future work item. diff --git a/integrations/vestrix_integration/ruleset/decoders/0585-vestrix_decoders.xml b/integrations/vestrix_integration/ruleset/decoders/0585-vestrix_decoders.xml new file mode 100644 index 0000000..a6ded5f --- /dev/null +++ b/integrations/vestrix_integration/ruleset/decoders/0585-vestrix_decoders.xml @@ -0,0 +1,9 @@ + + + json + "source"\s*:\s*"vestrix" + true + JSON_Decoder + discard + array + diff --git a/integrations/vestrix_integration/ruleset/rules/1000-vestrix_rules.xml b/integrations/vestrix_integration/ruleset/rules/1000-vestrix_rules.xml new file mode 100644 index 0000000..780f159 --- /dev/null +++ b/integrations/vestrix_integration/ruleset/rules/1000-vestrix_rules.xml @@ -0,0 +1,64 @@ + + + + vestrix + ^vestrix$ + Vestrix canonical SOC event + no_full_log + + + + + 100200 + ^intrusion$ + ^high$ + Vestrix: high-confidence physical intrusion at $(site_id)/$(zone_id), sensor $(node_id) + physical_security,intrusion_detection, + + + + + 100200 + ^intrusion$ + ^missing$ + Vestrix: physical intrusion with no corresponding badge/PACS event at $(site_id)/$(zone_id) + physical_security,access_control, + + + + 100200 + ^sensor_tamper$ + Vestrix: sensor tamper detected on $(node_id) at $(site_id)/$(zone_id) + physical_security,sensor_tamper,defense_evasion, + + + + + 5712,5763 + Vestrix correlation helper: recent SSH authentication anomaly + no_log + vestrix_auth_anomaly, + + + + + 100201 + 100210 + Vestrix: physical intrusion within 120s of an SSH authentication anomaly at $(site_id)/$(zone_id) + physical_security,authentication_failures,correlation, + + diff --git a/integrations/vestrix_integration/ruleset/testing/test.ini b/integrations/vestrix_integration/ruleset/testing/test.ini new file mode 100644 index 0000000..1dcd47c --- /dev/null +++ b/integrations/vestrix_integration/ruleset/testing/test.ini @@ -0,0 +1,25 @@ +; Copyright (C) 2026, Vestrix contributors +; +; Tests for product: +; Vestrix +; +; Candidate rule IDs remain unchanged from the live-tested local integration. +; They require an upstream core-ID allocation before submission. + +[High-confidence Vestrix intrusion] +log 1 pass = {"class":"intrusion","confidence":0.97,"confidence_level":"high","csi_window_sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","event_id":"vestrix-20260713T201501Z-node-07-0042","model_id":"rf-csi-v1.4.2","node_id":"node-07","pacs_event_id":"pacs-884103","pacs_event_status":"matched","pacs_reader_id":"reader-west-02","record_hash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","schema_version":"1.0","seq":1201,"sequence_number":4421,"shap_top_feature":"subcarrier_variance_12_18","shap_top_value":0.41,"site_id":"hq-karachi","source":"vestrix","ts_utc":"2026-07-13T20:15:01Z","zone_id":"server-room-west"} +rule = 100201 +alert = 10 +decoder = vestrix + +[Non-Vestrix JSON does not match the Vestrix decoder and base rule] +log 1 fail = {"class":"intrusion","confidence":0.97,"confidence_level":"high","csi_window_sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","event_id":"not-vestrix-20260713T201501Z-node-07-0042","model_id":"rf-csi-v1.4.2","node_id":"node-07","pacs_event_id":"pacs-884103","pacs_event_status":"matched","pacs_reader_id":"reader-west-02","record_hash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","schema_version":"1.0","seq":1201,"sequence_number":4421,"shap_top_feature":"subcarrier_variance_12_18","shap_top_value":0.41,"site_id":"hq-karachi","source":"not-vestrix","ts_utc":"2026-07-13T20:15:01Z","zone_id":"server-room-west"} +rule = 100200 +alert = 0 +decoder = vestrix + +[Regression - generic JSON parent retains the Vestrix decoder name] +log 1 pass = {"class":"normal","confidence":0.98,"confidence_level":"high","csi_window_sha256":"3456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef012","event_id":"vestrix-20260713T202001Z-node-07-normal-01","model_id":"rf-csi-v1.4.2","node_id":"node-07","pacs_event_status":"not_applicable","record_hash":"456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123","schema_version":"1.0","seq":1206,"sequence_number":4424,"shap_top_feature":"stationary_baseline_similarity","shap_top_value":0.61,"site_id":"hq-karachi","source":"vestrix","ts_utc":"2026-07-13T20:20:01Z","zone_id":"server-room-west"} +rule = 100200 +alert = 0 +decoder = vestrix diff --git a/integrations/vestrix_integration/sca/README.md b/integrations/vestrix_integration/sca/README.md new file mode 100644 index 0000000..68afb74 --- /dev/null +++ b/integrations/vestrix_integration/sca/README.md @@ -0,0 +1,4 @@ +# Security Configuration Assessment + +Not applicable — Vestrix is a physical-layer CSI sensor integration, not a +configuration or compliance-assessment source. diff --git a/integrations/vestrix_integration/threat_intel/README.md b/integrations/vestrix_integration/threat_intel/README.md new file mode 100644 index 0000000..ab47827 --- /dev/null +++ b/integrations/vestrix_integration/threat_intel/README.md @@ -0,0 +1,4 @@ +# Threat intelligence + +Not applicable — Vestrix emits locally classified physical-security events and +does not currently provide or consume a threat-intelligence feed.