[Auditbeat] Login metricset (elastic#9327)

Adds the login metricset to the Auditbeat system module as the last of the six initial metricsets. It only works on Linux, and detects not just user logins and logouts, but also system boots and shutdowns. It works by reading the /var/log/wtmp and /var/log/btmp file (and rotated files) present on Linux systems. In reading a file, it is similar to Filebeat, except that UTMP is a binary format, so reading happens using a binary Go reader.
cwurm · Jan 30, 2019 · 1566e66 · 1566e66
1 parent 12a6041
commit 1566e66
Show file tree

Hide file tree

Showing 22 changed files with 1,164 additions and 6 deletions.
diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc
@@ -192,6 +192,7 @@ https://github.com/elastic/beats/compare/v7.0.0-alpha2...master[Check the HEAD d
 - Add `group.id` (GID) and `group.name` for ECS. {pull}10195[10195]
 - System module `process` dataset: Add user information to processes. {pull}9963[9963]
 - Add system `package` dataset. {pull}10225[10225]
+- Add system module `login` dataset. {pull}9327[9327]
 
 *Filebeat*
 

diff --git a/auditbeat/docs/fields.asciidoc b/auditbeat/docs/fields.asciidoc
@@ -6175,6 +6175,28 @@ These are the fields generated by the system module.
 
 
 
+
+*`event.origin`*::
++
+--
+type: keyword
+
+Origin of the event. This can be a file path (e.g. `/var/log/log.1`), or the name of the system component that supplied the data (e.g. `netlink`).
+
+
+--
+
+
+*`user.terminal`*::
++
+--
+type: keyword
+
+Terminal of the user.
+
+
+--
+
 [float]
 == system.audit fields
 

diff --git a/x-pack/auditbeat/auditbeat.reference.yml b/x-pack/auditbeat/auditbeat.reference.yml
@@ -117,6 +117,7 @@ auditbeat.modules:
 - module: system
   datasets:
     - host    # General host information, e.g. uptime, IPs
+    - login   # User logins, logouts, and system boots.
     - package # Installed, updated, and removed packages
     - process # Started and stopped processes
     - socket  # Opened and closed sockets
@@ -139,6 +140,12 @@ auditbeat.modules:
   # detect any changes.
   user.detect_password_changes: true
 
+  # File patterns of the login record files.
+  # wtmp: History of successful logins, logouts, and system shutdowns and boots.
+  # btmp: Failed login attempts.
+  login.wtmp_file_pattern: /var/log/wtmp*
+  login.btmp_file_pattern: /var/log/btmp*
+
 #================================ General ======================================
 
 # The name of the shipper that publishes the network data. It can be used to group

diff --git a/x-pack/auditbeat/auditbeat.yml b/x-pack/auditbeat/auditbeat.yml
@@ -50,6 +50,7 @@ auditbeat.modules:
 - module: system
   datasets:
     - host    # General host information, e.g. uptime, IPs
+    - login   # User logins, logouts, and system boots.
     - package # Installed, updated, and removed packages
     - process # Started and stopped processes
     - socket  # Opened and closed sockets
@@ -65,6 +66,10 @@ auditbeat.modules:
   # detect any changes.
   user.detect_password_changes: true
 
+  # File patterns of the login record files.
+  login.wtmp_file_pattern: /var/log/wtmp*
+  login.btmp_file_pattern: /var/log/btmp*
+
 #==================== Elasticsearch template setting ==========================
 setup.template.settings:
   index.number_of_shards: 3

diff --git a/x-pack/auditbeat/docs/modules/system.asciidoc b/x-pack/auditbeat/docs/modules/system.asciidoc
@@ -51,6 +51,7 @@ sample suggested configuration.
 - module: system
   datasets:
     - host
+    - login
     - package
     - process
     - socket
@@ -87,6 +88,7 @@ so a longer polling interval can be used.
 - module: system
   datasets:
     - host
+    - login
     - package
     - user
   period: 1m
@@ -113,6 +115,7 @@ auditbeat.modules:
 - module: system
   datasets:
     - host    # General host information, e.g. uptime, IPs
+    - login   # User logins, logouts, and system boots.
     - package # Installed, updated, and removed packages
     - process # Started and stopped processes
     - socket  # Opened and closed sockets
@@ -127,6 +130,10 @@ auditbeat.modules:
   # /etc/passwd and /etc/shadow and store a hash locally to
   # detect any changes.
   user.detect_password_changes: true
+
+  # File patterns of the login record files.
+  login.wtmp_file_pattern: /var/log/wtmp*
+  login.btmp_file_pattern: /var/log/btmp*
 ----
 
 [float]
@@ -136,6 +143,8 @@ The following datasets are available:
 
 * <<{beatname_lc}-dataset-system-host,host>>
 
+* <<{beatname_lc}-dataset-system-login,login>>
+
 * <<{beatname_lc}-dataset-system-package,package>>
 
 * <<{beatname_lc}-dataset-system-process,process>>
@@ -146,6 +155,8 @@ The following datasets are available:
 
 include::system/host.asciidoc[]
 
+include::system/login.asciidoc[]
+
 include::system/package.asciidoc[]
 
 include::system/process.asciidoc[]

diff --git a/x-pack/auditbeat/docs/modules/system/login.asciidoc b/x-pack/auditbeat/docs/modules/system/login.asciidoc
@@ -0,0 +1,21 @@
+////
+This file is generated! See scripts/docs_collector.py
+////
+
+[id="{beatname_lc}-dataset-system-login"]
+=== System login dataset
+
+include::../../../module/system/login/_meta/docs.asciidoc[]
+
+
+==== Fields
+
+For a description of each field in the dataset, see the
+<<exported-fields-system,exported fields>> section.
+
+Here is an example document generated by this dataset:
+
+[source,json]
+----
+include::../../../module/system/login/_meta/data.json[]
+----
diff --git a/x-pack/auditbeat/include/list.go b/x-pack/auditbeat/include/list.go
diff --git a/x-pack/auditbeat/module/system/_meta/config.yml.tmpl b/x-pack/auditbeat/module/system/_meta/config.yml.tmpl
@@ -7,6 +7,9 @@
 - module: system
   datasets:
     - host    # General host information, e.g. uptime, IPs
+    {{ if eq .GOOS "linux" -}}
+    - login   # User logins, logouts, and system boots.
+    {{- end }}
     {{ if ne .GOOS "windows" -}}
     - package # Installed, updated, and removed packages
     {{- end }}
@@ -38,3 +41,13 @@
   # detect any changes.
   user.detect_password_changes: true
   {{- end }}
+
+  {{ if eq .GOOS "linux" -}}
+  # File patterns of the login record files.
+{{- if .Reference }}
+  # wtmp: History of successful logins, logouts, and system shutdowns and boots.
+  # btmp: Failed login attempts.
+{{- end }}
+  login.wtmp_file_pattern: /var/log/wtmp*
+  login.btmp_file_pattern: /var/log/btmp*
+  {{- end }}
diff --git a/x-pack/auditbeat/module/system/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/_meta/docs.asciidoc
@@ -46,6 +46,7 @@ sample suggested configuration.
 - module: system
   datasets:
     - host
+    - login
     - package
     - process
     - socket
@@ -82,6 +83,7 @@ so a longer polling interval can be used.
 - module: system
   datasets:
     - host
+    - login
     - package
     - user
   period: 1m

diff --git a/x-pack/auditbeat/module/system/_meta/fields.yml b/x-pack/auditbeat/module/system/_meta/fields.yml
@@ -4,7 +4,25 @@
     These are the fields generated by the system module.
   release: experimental
   fields:
-    - name: system.audit
-      type: group
+
+  - name: event
+    type: group
+    fields:
+    - name: origin
+      type: keyword
       description: >
-      fields:
+        Origin of the event. This can be a file path (e.g. `/var/log/log.1`),
+        or the name of the system component that supplied the data (e.g. `netlink`).
+
+  - name: user
+    type: group
+    fields:
+    - name: terminal
+      type: keyword
+      description: >
+        Terminal of the user.
+
+  - name: system.audit
+    type: group
+    description: >
+    fields:
diff --git a/x-pack/auditbeat/module/system/fields.go b/x-pack/auditbeat/module/system/fields.go
diff --git a/x-pack/auditbeat/module/system/login/_meta/data.json b/x-pack/auditbeat/module/system/login/_meta/data.json
@@ -0,0 +1,30 @@
+{
+    "@timestamp": "2017-10-12T08:05:34.853Z",
+    "agent": {
+        "hostname": "host.example.com",
+        "name": "host.example.com"
+    },
+    "event": {
+        "action": "user_login",
+        "dataset": "login",
+        "module": "system",
+        "origin": "/var/log/wtmp.1",
+        "outcome": "success",
+        "type": "event"
+    },
+    "message": "Login by user vagrant (UID: 1000) on pts/1 (PID: 17559) from 10.0.2.2 (IP: 10.0.2.2)",
+    "process": {
+        "pid": 17559
+    },
+    "service": {
+        "type": "system"
+    },
+    "source": {
+        "ip": "10.0.2.2"
+    },
+    "user": {
+        "id": 1000,
+        "name": "vagrant",
+        "terminal": "pts/1"
+    }
+}
diff --git a/x-pack/auditbeat/module/system/login/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/login/_meta/docs.asciidoc
@@ -0,0 +1,7 @@
+[role="xpack"]
+
+experimental[]
+
+This is the `login` dataset of the system module.
+
+It is implemented for Linux only.
diff --git a/x-pack/auditbeat/module/system/login/config.go b/x-pack/auditbeat/module/system/login/config.go
@@ -0,0 +1,20 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License;
+// you may not use this file except in compliance with the Elastic License.
+
+// +build linux
+
+package login
+
+// config defines the metricset's configuration options.
+type config struct {
+	WtmpFilePattern string `config:"login.wtmp_file_pattern"`
+	BtmpFilePattern string `config:"login.btmp_file_pattern"`
+}
+
+func defaultConfig() config {
+	return config{
+		WtmpFilePattern: "/var/log/wtmp*",
+		BtmpFilePattern: "/var/log/btmp*",
+	}
+}