Add Filebeat module for monitoring Santa (#9540)

* Add Filebeat module for monitoring Santa

This adds a Filebeat module for monitoring and parsing the log file generated
by the Google Santa, a process monitoring tools for MacOS. This module includes
an overview dashboard.

https://github.com/google/santa

* Add grok pattern for action=DISKAPPEAR

CHANGELOG.asciidoc

@@ -103,6 +103,7 @@ https://github.com/elastic/beats/compare/v7.0.0-alpha1...master[Check the HEAD d
 - Added `syslog_host` variable to HAProxy module to allow syslog listener to bind to configured host. {pull}9366[9366]
 - Added support on Traefik for Common Log Format and Combined Log Format mixed which is the default Traefik format {issue}8015[8015] {issue}6111[6111] {pull}8768[8768].
 - Add support for multi-core thread_id in postgresql module {issue}9156[9156] {pull}9482[9482]
+- Added module for parsing Google Santa logs. {pull}9540[9540]
 
 *Heartbeat*
 

filebeat/docs/fields.asciidoc

@@ -34,6 +34,7 @@ grouped in the following categories:
 * <<exported-fields-osquery>>
 * <<exported-fields-postgresql>>
 * <<exported-fields-redis>>
+* <<exported-fields-santa>>
 * <<exported-fields-system>>
 * <<exported-fields-traefik>>
 
@@ -6873,6 +6874,151 @@ type: keyword
 The arguments with which the command was called.
 
 
+--
+
+[[exported-fields-santa]]
+== Google Santa fields
+
+Santa Module
+
+
+
+[float]
+== santa fields
+
+
+
+
+*`santa.action`*::
++
+--
+type: keyword
+
+example: EXEC
+
+Action
+
+--
+
+*`santa.decision`*::
++
+--
+type: keyword
+
+example: ALLOW
+
+Decision that santad took.
+
+--
+
+*`santa.reason`*::
++
+--
+type: keyword
+
+example: CERT
+
+Reason for the decsision.
+
+--
+
+*`santa.mode`*::
++
+--
+type: keyword
+
+example: M
+
+Operating mode of Santa.
+
+--
+
+[float]
+== disk fields
+
+Fields for DISKAPPEAR actions.
+
+
+*`santa.disk.volume`*::
++
+--
+The volume name.
+
+--
+
+*`santa.disk.bus`*::
++
+--
+The disk bus protocol.
+
+--
+
+*`santa.disk.serial`*::
++
+--
+The disk serial number.
+
+--
+
+*`santa.disk.bsdname`*::
++
+--
+example: disk1s3
+
+The disk BSD name.
+
+--
+
+*`santa.disk.model`*::
++
+--
+example: APPLE SSD SM0512L
+
+The disk model.
+
+--
+
+*`santa.disk.fs`*::
++
+--
+example: apfs
+
+The disk volume kind (filesystem type).
+
+--
+
+*`santa.disk.mount`*::
++
+--
+The disk volume path.
+
+--
+
+*`certificate.common_name`*::
++
+--
+type: keyword
+
+Common name from code signing certificate.
+
+--
+
+*`certificate.sha256`*::
++
+--
+type: keyword
+
+SHA256 hash of code signing certificate.
+
+--
+
+*`hash.sha256`*::
++
+--
+type: keyword
+
+Hash of process executable.
+
 --
 
 [[exported-fields-system]]

filebeat/docs/modules/santa.asciidoc

@@ -0,0 +1,71 @@
+////
+This file is generated! See scripts/docs_collector.py
+////
+
+[[filebeat-module-santa]]
+:modulename: santa
+:has-dashboards: true
+
+== Santa module
+
+The +{modulename}+ module collects and parses logs from
+https://github.com/google/santa[Google Santa], a security
+tool for macOS that monitors process executions and can blacklist/whitelist
+binaries.
+
+include::../include/what-happens.asciidoc[]
+
+[float]
+=== Compatibility
+
+The +{modulename}+ module was tested with logs from Santa 0.9.14.
+
+This module is available for MacOS only.
+
+include::../include/running-modules.asciidoc[]
+
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard showing and overview of the processes
+that are executing.
+
+[role="screenshot"]
+image::./images/kibana-santa-log-overview.png[]
+
+include::../include/configuring-intro.asciidoc[]
+
+The module is by default configured to read logs from `/var/log/santa.log`.
+
+["source","yaml",subs="attributes"]
+-----
+- module: santa
+  log:
+    enabled: true
+    var.paths: ["/var/log/santa.log"]
+    var.input: "file"
+-----
+
+:fileset_ex: log
+
+include::../include/config-option-intro.asciidoc[]
+
+
+[float]
+==== `log` fileset settings
+
+include::../include/var-paths.asciidoc[]
+
+:has-dashboards!:
+
+:fileset_ex!:
+
+:modulename!:
+
+
+[float]
+=== Fields
+
+For a description of each field in the module, see the
+<<exported-fields-santa,exported fields>> section.
+

filebeat/docs/modules_list.asciidoc

@@ -18,6 +18,7 @@ This file is generated! See scripts/docs_collector.py
   * <<filebeat-module-osquery>>
   * <<filebeat-module-postgresql>>
   * <<filebeat-module-redis>>
+  * <<filebeat-module-santa>>
   * <<filebeat-module-suricata>>
   * <<filebeat-module-system>>
   * <<filebeat-module-traefik>>
@@ -41,6 +42,7 @@ include::modules/nginx.asciidoc[]
 include::modules/osquery.asciidoc[]
 include::modules/postgresql.asciidoc[]
 include::modules/redis.asciidoc[]
+include::modules/santa.asciidoc[]
 include::modules/suricata.asciidoc[]
 include::modules/system.asciidoc[]
 include::modules/traefik.asciidoc[]

filebeat/filebeat.reference.yml

@@ -351,6 +351,14 @@ filebeat.modules:
     # Optional, the password to use when connecting to Redis.
     #var.password:
 
+#---------------------------- Google Santa Module ----------------------------
+- module: santa
+  log:
+    enabled: true
+    # Set custom paths for the log files. If left empty,
+    # Filebeat will choose the the default path.
+    #var.paths:
+
 #------------------------------- Traefik Module ------------------------------
 #- module: traefik
   # Access logs

filebeat/module/santa/_meta/config.yml

@@ -0,0 +1,6 @@
+- module: santa
+  log:
+    enabled: true
+    # Set custom paths for the log files. If left empty,
+    # Filebeat will choose the the default path.
+    #var.paths:

filebeat/module/santa/_meta/docs.asciidoc

@@ -0,0 +1,58 @@
+:modulename: santa
+:has-dashboards: true
+
+== Santa module
+
+The +{modulename}+ module collects and parses logs from
+https://github.com/google/santa[Google Santa], a security
+tool for macOS that monitors process executions and can blacklist/whitelist
+binaries.
+
+include::../include/what-happens.asciidoc[]
+
+[float]
+=== Compatibility
+
+The +{modulename}+ module was tested with logs from Santa 0.9.14.
+
+This module is available for MacOS only.
+
+include::../include/running-modules.asciidoc[]
+
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard showing and overview of the processes
+that are executing.
+
+[role="screenshot"]
+image::./images/kibana-santa-log-overview.png[]
+
+include::../include/configuring-intro.asciidoc[]
+
+The module is by default configured to read logs from `/var/log/santa.log`.
+
+["source","yaml",subs="attributes"]
+-----
+- module: santa
+  log:
+    enabled: true
+    var.paths: ["/var/log/santa.log"]
+    var.input: "file"
+-----
+
+:fileset_ex: log
+
+include::../include/config-option-intro.asciidoc[]
+
+
+[float]
+==== `log` fileset settings
+
+include::../include/var-paths.asciidoc[]
+
+:has-dashboards!:
+
+:fileset_ex!:
+
+:modulename!: