Skip to content

Punch Modules

Abstract

The punch provides a set of Elastalert modules ready to be used.

Punch Alerters

Kafka

Definition

Any match returned by a rule are sent to a kafka topic of your choice.

rule.yaml example

---
alert: ["punch_elastalert.alerter.kafka_alerter.KafkaAlerter"]
bootstrap_servers: ["localhost:9092"]
close_timeout: 10
flush_timeout: 10

A more advance example with SSL active:

---
alert: ["punch_elastalert.alerter.kafka_alerter.KafkaAlerter"]
bootstrap_servers: ["localhost:9092"]
close_timeout: 10
flush_timeout: 10
kafka.ssl: True,
kafka.ssl_cafile: "/full/path/ca.pem",
kafka.ssl_certfile: "/full/path/server-cert.pem",
kafka.ssl_keyfile: "/full/path/server-key.pem",

Configurations

Name Type Default Mandatory Description
bootstrap_servers List of strings None True A list of kafka brokers to connect to as producer
close_timeout Integer None True Time to wait before closing connections to kafka brokers
flush_timeout Integer None True Time to wait before flushing alert content to kafka topic
kafka.ssl Boolean False False Mandatory if you plan on using SSL strategy
kafka.ssl_cafile String Empty False Absolute path to file
kafka.ssl_certfile String Empty False Absolute path to file
kafka.ssl_keyfile String Empty False Absolute path to file
kafka.ssl_hostname_verification Boolean False False Absolute path to file

Cybels Kafka

Definition

Sends a single document to a kafka topic (even if multiples documents are matched) with additional fields and formatted to be ECS 1.5 compatible.

rule.yaml example

If you need to test a whole configuration, you can uncomment the lines below.

---
# name: ES Stdout
# "@timestamp": "2020-09-23T14:47:02.448Z"
# es_host: localhost
# es_port: 9200
# index: customers-*
# filter: []
# type: punch_elastalert.rules.suspect_name.SuspectName
# suspect_names:
#   - Jeff Meza
#   - Chritiano Ronaldo
#   - Jack Mao
# match_enhancements:
#   - punch_elastalert.enhancement.discover_country.DiscoverCountry
alert: punch_elastalert.alerter.kafka_alerter.CybelsKafkaAlerter
topic: cybels
bootstrap_servers:
  - localhost:9092
close_timeout: 10
flush_timeout: 10
# provider: Cybels Analytics correlator
# start: "2015-09-23T14:47:02.448Z"
# use_ssl: false
alert example

{
  "ecs": {
    "version": "1.5"
  },
  "event": {
    "kind": "alert",
    "provider": "Cybels Analytics correlator",
    "severity": "2",
    "logs": {
      "count": 1,
      "ids": [
        "test123"
      ]
    },
    "original": [
      {
        "@timestamp": "2022-06-29T08:16:00.448Z",
        "name": "Jack Mao",
        "_id": "test123",
        "_index": "customers-2022.06.27",
        "_type": "_doc",
        "num_hits": 1,
        "num_matches": 1,
        "country": "USA"
      }
    ],
    "start": "2022-06-29 08:16:00.448000+00:00",
    "end": "2022-06-29 08:16:00.448000+00:00",
    "duration": "0:00:00"
  },
  "rule": {
    "name": "ES Stdout",
    "description": "",
    "id": "1" #corresponding to _id field of the Elasticsearch/Opensearch rule doc 
  }
}
More advanced rule In Elasticsearch
{
  "_index": ".elastalert-rules-mytenant",
  "_type": "_doc",
  "_id": "12345-2344",
  "_version": 1,
  "_score": 0,
  "_source": {
    "name": "rule1.yml",
    "rule": {
      "id": "12345-2344"
    },
    "elastalert_rule": "alert:\n- punch_elastalert.alerter.kafka_alerter.CybelsKafkaAlerter\ncybels_kafka_url:\n- onenode1:9092\ndescription: Detects Windows 10 and Windows Server 2016 successful login\nfilter:\n- query:\n    query_string:\n      query: event.code:\"4624\"\nid: 12345-2344\nindex: cybels-logs-winlogbeat-*\nlevel: high\nname: Windows-login_@@@_12345-2344\npriority: 2\nrealert:\n  minutes: 5\ntags:\n- NOT-DEF\ntitle: Windows login\ntype: any\n\n",
    "type": "raw",
    "original_type": "sigma",
    "@timestamp": "2022-07-05"
  },
  "fields": {
    "@timestamp": [
      "2022-07-05T00:00:00.000Z"
    ]
  }
}
More advanced document trigerring the alert In Elasticsearch, within an index called "cybels-logs-winlogbeat-1234"
{
  "@metadata": {
    "beat": "winlogbeat",
    "type": "_doc",
    "version": "7.9.2"
  },
  "@timestamp": "2022-07-04T15:30:21.386983Z",
  "agent": {
    "ephemeral_id": "97b23f3d-0e5d-4e03-bd26-6f72587ae27d",
    "hostname": "DADA3",
    "id": "2799048b-5a9c-4a6a-9ac3-77f79b6c33d9",
    "name": "PAPA333333",
    "type": "winlogbeat",
    "version": "7.9.2"
  },
  "event": {
    "action": "Logon",
    "code": 4624,
    "created": "2020-10-04T17:21:15.527Z",
    "kind": "event",
    "outcome": "success",
    "provider": "Microsoft-Windows-Security-Auditing"
  },
  "host": {
    "name": "HIHIHIHI"
  },
  "log": {
    "level": "information"
  },
  "event_id": 4624,
  "keywords": [
    "Audit Success"
  ],
  "opcode": "Info",
  "process": {
    "pid": 624,
    "thread": {
      "id": 668
    }
  },
  "provider_guid": "{54849625-5478-4994-a5ba-3e3b0328c30d}",
  "provider_name": "Microsoft-Windows-Security-Auditing",
  "record_id": 592246,
  "task": "Logon"
}
Configurations

Name Type Default Mandatory Description
bootstrap_servers List of strings None True A list of kafka brokers to connect to as producer
close_timeout Integer None True Time to wait before closing connections to kafka brokers
flush_timeout Integer None True Time to wait before flushing alert content to kafka topic
provider String None True A provider name to be added as a field in resulting alert
kafka.ssl Boolean False False Mandatory if you plan on using SSL strategy
kafka.ssl_cafile String Empty False Absolute path to file
kafka.ssl_certfile String Empty False Absolute path to file
kafka.ssl_keyfile String Empty False Absolute path to file
kafka.ssl_hostname_verification Boolean False False Absolute path to file

Stdout

Definition

Prints a matched document by a rule on stdout.

rule.yaml example

alert: ["punch_elastalert.alerter.stdout.Stdout"]
stdout_command: true

Configurations

Name Type Default Mandatory Description
stdout_command Boolean None True If an alert is detected, print the alert content to stdout or not

Http Post

Definition

Make a post request for each matched document against a rule where the body will be the matched document.

rule.yaml example

---
alert: ["punch_elastalert.alerter.http_alerter.HttpAlerter"]
http_post_url: http://myserver:1234

A more advance example with SSL:

---
alert: ["punch_elastalert.alerter.http_alerter.HttpAlerter"]
http_post_url: https://myserver:1234
http.ssl: True,
http.ssl_cafile: "/full/path/ca.pem",
http.ssl_certfile: "/full/path/server-cert.pem",
http.ssl_keyfile: "/full/path/server-key.pem",

Configurations

Name Type Default Mandatory Description
http_post_url String None True Endpoint to which alert data will be POST
http.ssl Boolean False False Enable SSL or not
http.ssl_cafile String Empty False An absolute path
http.ssl_certfile String Empty False An absolute path
http.ssl_keyfile String Empty False An absolute path

Cybels Http Post

Definition

Sends a single post request. The sent document is ECS 1.5 compatible with additional fields.

rule.yaml example

---
alert: ["punch_elastalert.alerter.http_alerter.CybelsHttpAlerter"]
http_post_url: http://myserver:1234

Configurations

Name Type Default Mandatory Description
http_post_url String None True Endpoint to which alert data will be POST
http.ssl Boolean False False Enable SSL or not
http.ssl_cafile String Empty False An absolute path
http.ssl_certfile String Empty False An absolute path
http.ssl_keyfile String Empty False An absolute path

Zabbix Alerter

Definition

Send tracked event as trap to a zabbix backend.

Similarly to Jira aleter (...), this alerter enable you to use:

  • alert_subject
  • alert_text

Output response is a JSON string with the format below:

{ "subject": "<alert_subject>", "message": "<alert_content>" }

Where:

  • message value can either be a text or a json string
  • subject key-value is omitted if no alert_subject is defined within your rule.yaml

Note, there are other severals parameters that can be coupled with alert_subject and/or alert_text not listed in our available configuration list. Refer to elastalert official documentation on how to use them:

rule.yaml example

---
alert: [punch_elastalert.alerter.zabbix_alerter.ZabbixAlerter]
zabbix.server_url: http://localhost:8081
zabbix.server_user: Admin
zabbix.server_password: zabbix
zabbix.sender_hostname: "0.0.0.0"
zabbix.metric_key: trapdev
zabbix.metric_host: dev.server.io
alert_subject: "Suspect name detected: {0} | Detection time {1}"
alert_subject_args:
- name
- "@timestamp"

A more advance example with SSL:

---
alert: [punch_elastalert.alerter.zabbix_alerter.ZabbixAlerter]
zabbix.server_url: http://localhost:8081
zabbix.server_user: Admin
zabbix.server_password: zabbix
zabbix.sender_hostname: "0.0.0.0"
zabbix.metric_key: trapdev
zabbix.metric_host: dev.server.io
zabbix.security: True
zabbix.ssl_cafile: /full/path/to/cafile
zabbix.ssl_certfile: /full/path/to/certfile
zabbix.ssl_keyfile: /full/path/to/keyfile

Configurations

Name Type Default Mandatory Description
zabbix.server_url String None True Zabbix server URL
zabbix.server_user String False True Zabbix username that will be used for sending alert
zabbix.server_password String False True Zabbix username password
zabbix.sender_hostname String False True Zabbix sender server
zabbix.metric_key String False True Key name defined in your zabbix configuration
zabbix.metric_host String False True Then sender hostname (i.e. value of hostname)
zabbix.security Boolean False False Enable SSL or not
zabbix.ssl_cafile String Empty False An absolute path
zabbix.ssl_certfile String Empty False An absolute path
zabbix.ssl_keyfile String Empty False An absolute path
alert_subject String Empty False See elastalert official documentation
alert_text String Empty False See elastalert official documentation

Punch Rules Loaders

Elasticsearch

Definition

Load rules dynamically from an elasticsearch index instead from a local filesystem. A checksum is calculated for each fetched rules. At periodic intervals, Elastalert will query the same index and will compare the checksum of the one loaded in memory, and the new fetched one's. In case some rules does not match the stored checksum, they are reloaded.

config.yaml example

Each document is a YAML file

---
es_host: localhost
es_port: 9200
writeback_index: elastalert
run_every:
  minutes: 2
buffer_time:
  minutes: 1
rules_loader: "punch_elastalert.rule_loader.elasticsearch_loader.ElasticsearchLoader"
rules_index: myrule
rules_hosts: ["http://localhost:9200"]

Each field of a given document is a YAML file

---
es_host: localhost
es_port: 9200
writeback_index: elastalert
run_every:
  minutes: 2
buffer_time:
  minutes: 1
rules_loader: "punch_elastalert.rule_loader.elasticsearch_loader.ElasticsearchLoader"
rules_index: myrule
rules_hosts: ["http://localhost:9200"]
rule_from_field: my_field

A more advance example with SSL:

---
# elastalert scheduler
es_host: localhost
es_port: 9200
writeback_index: elastalert
run_every:
  minutes: 2
buffer_time:
  minutes: 1
ca_certs: "/full/path/ca.pem",
client_key: "/full/path/server-key.pem",
client_cert: "/full/path/server-cert.pem"

# es rule loader
rules_loader: "punch_elastalert.rule_loader.elasticsearch_loader.ElasticsearchLoader"
rules_index: myrule
rules_hosts: ["https://localhost:9200"]
rule_from_field: my_field
es.ssl: True,
es.ssl_cafile: "/full/path/ca.pem",
es.ssl_certfile: "/full/path/server-cert.pem",
es.ssl_keyfile: "/full/path/server-key.pem",

Configurations

Name Type Default Mandatory Description
rules_index String None True Index where rules are located
rules_hosts List of String None True Your elasticsearch Hosts (RFC-1738 formatted URLs)
rules_index_query String Match all False By default a match all query is made. In case you want to filter rules, you can specify a query in json format (one line)
rule_from_field String None False Content of your rule.yaml file as string (one line)
es.ssl Boolean False False Mandatory if you plan on using SSL strategy
es.ssl_cafile String Empty False Absolute path to file
es.ssl_certfile String Empty False Absolute path to file
es.ssl_keyfile String Empty False Absolute path to file
es.ssl_hostname_verification Boolean False False Verify host name for ssl certificate