Reactor

Reactor begann als Fork des Open-Source-Projekts ElastAlert. Der Betreuer dieses Projekts sollte die Änderungen an ElastAlert (mit Ausnahme der zusätzlichen Alerter) genau im Auge behalten und sicherstellen, dass alle relevanten Fehlerbehebungen übernommen und nützliche Funktionen portiert werden.

Reactor ist eine Alerting-Engine, die eine Reihe von Regeln mit benutzerdefinierten Filtern aufnimmt und bei Übereinstimmungen alarmiert. Reactor aktualisiert automatisch stummgeschaltete Alarme mit Informationen zu wiederholten Alarmen.

Patchverlauf von ElastAlert

Unterstützte Versionen

Derzeit unterstützt Reactor ElasticSearch 5.x.x, 6.x.x und 7.x.x. Sobald neue Versionen von Elasticsearch verfügbar sind, wird Reactor aktualisiert, um diese zu unterstützen. Es ist nicht beabsichtigt, Unterstützung für ältere Versionen von ElasticSearch hinzuzufügen. Derzeit gibt es kein Datum für die Entfernung der Unterstützung älterer Versionen von ElasticSearch. Falls die Python-Bibliothek von ElasticSearch die Unterstützung entfernt, werden wir dies wahrscheinlich übernehmen.

Kompatibilität

Gemäß den Richtlinien der Python-Bibliothek von ElasticSearch wird empfohlen, die Version der Bibliothek mit derselben Hauptversion wie der Cluster zu installieren.

Für Elasticsearch 7.0 und neuer verwenden Sie die Hauptversion 7 (elasticsearch<8.0.0,>=7.0.0).

Für Elasticsearch 6.0 und neuer verwenden Sie die Hauptversion 6 (elasticsearch<7.0.0,>=6.0.0).

Für Elasticsearch 5.0 und neuer verwenden Sie die Hauptversion 5 (elasticsearch<6.0.0,>=5.0.0).

Bitte beachten Sie, dass es einen bekannten Fehler gibt, der in Version 6.4.0 der ElasticSearch-Bibliothek eingeführt und in 7.0.4 behoben wurde, jedoch nicht in Hauptversion 6. Der Fehler legt die scroll_id in den Query-Parameter, was dazu führen kann, dass Elasticsearch für gültige Scroll-IDs den Statuscode 400 zurückgibt.

Entwicklung

Sie können für die lokale Entwicklung eine Elasticsearch-Instanz in Docker mit dem folgenden Befehl starten:

$ docker run -d -p 9200:9200/tcp --name elasticsearch docker.elastic.co/elasticsearch/elasticsearch:<version>

Und die folgende Konfiguration in config.yaml:

writeback_index: reactor
alert_alias: reactor_alerts

elasticsearch: &elasticsearch
  host: localhost
  port: 9200

# Global settings to be applied to every run
rule:
  elasticsearch: *elasticsearch

Git-Hooks

Dieses Projekt bietet Git-Hooks, um Benutzerfehler zu vermeiden. Bitte führen Sie die folgenden Befehle aus:

$ cp .git-hooks-pre-push .git/hooks/pre-push

Tests ausführen

Reactor wird durch zwei Arten von Tests abgedeckt: Unit- und Integrationstests. Unit-Tests stellen sicher, dass einzelne Funktionen und Logikabläufe korrekt funktionieren; Integrationstests stellen sicher, dass das gesamte System zusammenspielt.

Unit

Die Unit-Tests sind mit PyTest geschrieben. Führen Sie den folgenden Befehl aus, um alle Tests auszuführen:

$ py.test

Integration

Die Unit-Tests werden in Docker ausgeführt und benötigen eine .env-Datei im Stammverzeichnis des Projekts. Die Tests erfordern den folgenden Inhalt in der .env-Datei:

# The ElasticSearch version to be tested, reactor supports >= 5.x.x
ES_VERSION=6.3.2
# Basic configuration information so that reactor can query ElasticSearch
ES_HOST=elasticsearch
ES_USER=elastic
ES_PASSWORD=changeme

Die Integrations-Docker-Compose-Datei test.docker-compose.yml enthält 3 Umgebungsvariablen, die für >= v7.x.x erforderlich sind und ältere Versionen brechen:

node.name=elasticsearch
discovery.seed_hosts=elasticsearch
cluster.initial_master_nodes=elasticsearch

Um die Integrationstests auszuführen, führen Sie den folgenden Befehl aus:

$ docker-compose -f docker-compose-test.yml up --abort-on-container-exit --build  reactor elasticsearch

SSL-Zertifikate für die RAFT-Führung erstellen

Der folgende Satz von Befehlen (ausgeführt in ./certs/) erstellt eine CA- und ein Gerätezertifikat für den Betrieb des Mock-Clusters auf localhost:

# Only do once: generate the root CA key:
$ openssl genrsa -out transport-ca.key 4096

# Generate the root CA certificate:
## Country Name (2 letter code) []:GB
## State or Province Name (full name) []:.
## Locality Name (eg, city) []:.
## Organization Name (eg, company) []:.
## Organizational Unit Name (eg, section) []:.
## Common Name (eg, fully qualified host name) []:PyRaftLog
## Email Address []:.
$ openssl req -x509 -new -nodes -key transport-ca.key -sha256 -days 1024 -out transport-ca.pem

# Generate device certificates
# Only do once: generate device key:
$ openssl genrsa -out transport-consensus.key 4096

# Generate device certificate signing request:
## Country Name (2 letter code) []:GB
## State or Province Name (full name) []:.
## Locality Name (eg, city) []:.
## Organization Name (eg, company) []:.
## Organizational Unit Name (eg, section) []:.
## Common Name (eg, fully qualified host name) []:localhost
## Email Address []:.
$ openssl req -new -key transport-consensus.key -out transport-consensus.csr

# Generate a signed device certificate:
$ openssl x509 -req -in transport-consensus.csr -CA transport-ca.pem -CAkey transport-ca.key -CAcreateserial -out transport-consensus.crt -days 500 -sha256

Dokumentation erstellen

Um die Dokumentation zu erstellen:

$ pip install -r requirements-docs.txt
$ cd docs
$ sphinx-build -b html -d build/doctrees -W source build/html

Auf PyPi veröffentlichen

1. pip install --upgrade setuptools wheel
2. pip install --upgrade twine
3. python3 setup.py sdist bdist_wheel
4. twine check dist/*
5. twine upload --skip-existing dist/* --verbose