[Filebeat] Cisco ASA module (elastic#11171)

This adds a cisco module to x-pack/filebeat. The only fileset currently, asa, will ingest Cisco ASA logs received over syslog.

Closes elastic#9200

CHANGELOG.next.asciidoc

@@ -316,6 +316,7 @@ https://github.com/elastic/beats/compare/v7.0.0-alpha2...master[Check the HEAD d
 - Added categorization fields for SSH login events in the system/auth fileset. {pull}11334[11334]
 - Add support for MySQL 8.0 slow logs and tests also for Percona 8.0 and MariaDB 10.3. {pull}11417[11417]
 - New Filebeat coredns module to ingest coredns logs. It supports both native coredns deployment and coredns deployment in kubernetes. {pull}11200[11200]
+- New module for Cisco ASA logs. {issue}9200[9200] {pull}11171[11171]
 
 *Heartbeat*
 

filebeat/docs/fields.asciidoc

@@ -15,6 +15,7 @@ grouped in the following categories:
 * <<exported-fields-apache>>
 * <<exported-fields-auditd>>
 * <<exported-fields-beat>>
+* <<exported-fields-cisco>>
 * <<exported-fields-cloud>>
 * <<exported-fields-coredns>>
 * <<exported-fields-docker-processor>>
@@ -1047,6 +1048,189 @@ type: alias
 
 alias to: agent.hostname
 
+--
+
+[[exported-fields-cisco]]
+== Cisco fields
+
+Module for handling Cisco network device logs.
+
+
+
+[float]
+== cisco fields
+
+Fields from Cisco logs.
+
+
+
+[float]
+== asa fields
+
+Fields for Cisco ASA Firewall.
+
+
+
+*`cisco.asa.message_id`*::
++
+--
+type: keyword
+
+The Cisco ASA message identifier.
+
+
+--
+
+*`cisco.asa.suffix`*::
++
+--
+type: keyword
+
+example: session
+
+Optional suffix after %ASA identifier.
+
+
+--
+
+*`cisco.asa.source_interface`*::
++
+--
+type: keyword
+
+Source interface for the flow or event.
+
+
+--
+
+*`cisco.asa.destination_interface`*::
++
+--
+type: keyword
+
+Destination interface for the flow or event.
+
+
+--
+
+*`cisco.asa.list_id`*::
++
+--
+type: keyword
+
+Name of the Access Control List that matched this event.
+
+
+--
+
+*`cisco.asa.source_username`*::
++
+--
+type: keyword
+
+Name of the user that is the source for this event.
+
+
+--
+
+*`cisco.asa.destination_username`*::
++
+--
+type: keyword
+
+Name of the user that is the destination for this event.
+
+
+--
+
+*`cisco.asa.mapped_source_ip`*::
++
+--
+type: ip
+
+The translated source IP address.
+
+
+--
+
+*`cisco.asa.mapped_source_port`*::
++
+--
+type: long
+
+The translated source port.
+
+
+--
+
+*`cisco.asa.mapped_destination_ip`*::
++
+--
+type: ip
+
+The translated destination IP address.
+
+
+--
+
+*`cisco.asa.mapped_destination_port`*::
++
+--
+type: long
+
+The translated destination port.
+
+
+--
+
+*`cisco.asa.threat_level`*::
++
+--
+type: keyword
+
+Threat level for malware / botnet traffic. One of very-low, low, moderate, high or very-high.
+
+
+--
+
+*`cisco.asa.threat_category`*::
++
+--
+type: keyword
+
+Category for the malware / botnet traffic. For example: virus, botnet, trojan, etc.
+
+
+--
+
+*`cisco.asa.connection_id`*::
++
+--
+type: keyword
+
+Unique identifier for a flow.
+
+
+--
+
+*`cisco.asa.icmp_type`*::
++
+--
+type: short
+
+ICMP type.
+
+
+--
+
+*`cisco.asa.icmp_code`*::
++
+--
+type: short
+
+ICMP code.
+
+
 --
 
 [[exported-fields-cloud]]

filebeat/docs/modules/cisco.asciidoc

@@ -0,0 +1,103 @@
+////
+This file is generated! See scripts/docs_collector.py
+////
+
+[[filebeat-module-cisco]]
+[role="xpack"]
+
+:modulename: cisco
+:has-dashboards: true
+
+== Cisco module
+
+This is a module for Cisco network device's logs. Currently supports the `asa`
+fileset for Cisco ASA firewall logs received over syslog or read from a file.
+
+Cisco ASA devices also support exporting flow records using NetFlow, which is
+supported by the {filebeat-ref}/filebeat-module-netflow.html[netflow module] in
+{beatname_uc}.
+
+include::../include/what-happens.asciidoc[]
+
+[float]
+=== Compatibility
+
+This module requires the {plugins}/ingest-geoip.html[ingest-geoip]
+Elasticsearch plugin.
+
+include::../include/running-modules.asciidoc[]
+
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard:
+
+[role="screenshot"]
+image::./images/kibana-cisco-asa.png[]
+
+include::../include/configuring-intro.asciidoc[]
+
+The module is by default configured to run via syslog on port 9001. However
+it can also be configured to read from a file path. See the following example.
+
+["source","yaml",subs="attributes"]
+-----
+- module: cisco
+  asa:
+    enabled: true
+    var.paths: ["/var/log/cisco-asa.log"]
+    var.input: "file"
+-----
+
+:fileset_ex: asa
+
+include::../include/config-option-intro.asciidoc[]
+
+[float]
+==== `asa` fileset settings
+
+Example config:
+
+[source,yaml]
+----
+  asa:
+    var.log_level: 5
+----
+
+include::../include/var-paths.asciidoc[]
+
+*`var.log_level`*::
+
+An integer between 1 and 7 that allows to filter messages based on the
+severity level. The different severity levels supported by the Cisco ASA are:
+
+[width="30%",cols="^1,2",options="header"]
+|===========================
+| log_level | severity
+|     1     | Alert
+|     2     | Critical
+|     3     | Error
+|     4     | Warning
+|     5     | Notification
+|     6     | Informational
+|     7     | Debugging
+|===========================
+
+A value of 7 (default) will not filter any messages. A lower value will drop
+any messages with a severity level higher than the specified value. For
+example, `var.log_level: 3` will allow messages of level 1 (Alert), 2 (Critical)
+and 3 (Error). All other messages will be dropped.
+
+:has-dashboards!:
+
+:fileset_ex!:
+
+:modulename!:
+
+
+[float]
+=== Fields
+
+For a description of each field in the module, see the
+<<exported-fields-cisco,exported fields>> section.
+

filebeat/docs/modules_list.asciidoc

@@ -5,6 +5,7 @@ This file is generated! See scripts/docs_collector.py
   * <<filebeat-modules-overview>>
   * <<filebeat-module-apache>>
   * <<filebeat-module-auditd>>
+  * <<filebeat-module-cisco>>
   * <<filebeat-module-coredns>>
   * <<filebeat-module-elasticsearch>>
   * <<filebeat-module-haproxy>>
@@ -34,6 +35,7 @@ This file is generated! See scripts/docs_collector.py
 include::modules-overview.asciidoc[]
 include::modules/apache.asciidoc[]
 include::modules/auditd.asciidoc[]
+include::modules/cisco.asciidoc[]
 include::modules/coredns.asciidoc[]
 include::modules/elasticsearch.asciidoc[]
 include::modules/haproxy.asciidoc[]

x-pack/filebeat/filebeat.reference.yml

@@ -82,6 +82,23 @@ filebeat.modules:
     # can be added under this section.
     #input:
 
+#-------------------------------- Cisco Module --------------------------------
+- module: cisco
+  asa:
+    enabled: true
+
+    # Set which input to use between syslog (default) or file.
+    #var.input:
+
+    # Set custom paths for the log files. If left empty,
+    # Filebeat will choose the paths depending on your OS.
+    #var.paths:
+
+    # Set the log level from 1 (alerts only) to 7 (include all messages).
+    # Messages with a log level higher than the specified will be dropped.
+    # See https://www.cisco.com/c/en/us/td/docs/security/asa/syslog/b_syslog/syslogs-sev-level.html
+    #var.log_level: 7
+
 #------------------------------- Coredns Module -------------------------------
 - module: coredns
   # Fileset for native deployment

x-pack/filebeat/module/cisco/README.md

@@ -0,0 +1,6 @@
+# Cisco module
+
+## Caveats
+
+* Module is to be considered _beta_.
+

x-pack/filebeat/module/cisco/_meta/config.yml

@@ -0,0 +1,15 @@
+- module: cisco
+  asa:
+    enabled: true
+
+    # Set which input to use between syslog (default) or file.
+    #var.input:
+
+    # Set custom paths for the log files. If left empty,
+    # Filebeat will choose the paths depending on your OS.
+    #var.paths:
+
+    # Set the log level from 1 (alerts only) to 7 (include all messages).
+    # Messages with a log level higher than the specified will be dropped.
+    # See https://www.cisco.com/c/en/us/td/docs/security/asa/syslog/b_syslog/syslogs-sev-level.html
+    #var.log_level: 7