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