diff --git a/auditbeat/docs/fields.asciidoc b/auditbeat/docs/fields.asciidoc index 110ed335641a..a89811c0eac4 100644 --- a/auditbeat/docs/fields.asciidoc +++ b/auditbeat/docs/fields.asciidoc @@ -21,6 +21,7 @@ grouped in the following categories: * <> * <> * <> +* <> -- [[exported-fields-auditd]] @@ -4956,3 +4957,284 @@ Kubernetes container image -- +[[exported-fields-system]] +== System fields + +These are the fields generated by the system module. + + + +[float] +== system.audit fields + + + + +[float] +== host fields + +`host` contains general host information. + + + +*`system.audit.host.uptime`*:: ++ +-- +type: long + +Uptime in nanoseconds. + + +-- + +*`system.audit.host.boottime`*:: ++ +-- +type: date + +Boot time. + + +-- + +*`system.audit.host.containerized`*:: ++ +-- +type: boolean + +Set if host is a container. + + +-- + +*`system.audit.host.timezone.name`*:: ++ +-- +type: keyword + +Name of the timezone of the host, e.g. BST. + + +-- + +*`system.audit.host.timezone.offset.sec`*:: ++ +-- +type: long + +Timezone offset in seconds. + + +-- + +*`system.audit.host.hostname`*:: ++ +-- +type: keyword + +Hostname. + + +-- + +*`system.audit.host.id`*:: ++ +-- +type: keyword + +Host ID. + + +-- + +*`system.audit.host.architecture`*:: ++ +-- +type: keyword + +Host architecture (e.g. x86_64). + + +-- + +*`system.audit.host.mac`*:: ++ +-- +type: keyword + +MAC addresses. + + +-- + +*`system.audit.host.ip`*:: ++ +-- +type: ip + +IP addresses. + + +-- + +[float] +== os fields + +`os` contains information about the operating system. + + + +*`system.audit.host.os.platform`*:: ++ +-- +type: keyword + +OS platform (e.g. centos, ubuntu, windows). + + +-- + +*`system.audit.host.os.name`*:: ++ +-- +type: keyword + +OS name (e.g. Mac OS X). + + +-- + +*`system.audit.host.os.family`*:: ++ +-- +type: keyword + +OS family (e.g. redhat, debian, freebsd, windows). + + +-- + +*`system.audit.host.os.version`*:: ++ +-- +type: keyword + +OS version. + + +-- + +*`system.audit.host.os.kernel`*:: ++ +-- +type: keyword + +The operating system's kernel version. + + +-- + +[float] +== user fields + +`user` contains information about the users on a system. + + + +*`system.audit.user.name`*:: ++ +-- +type: keyword + +User name. + + +-- + +*`system.audit.user.uid`*:: ++ +-- +type: integer + +User ID. + + +-- + +*`system.audit.user.gid`*:: ++ +-- +type: integer + +Group ID. + + +-- + +*`system.audit.user.dir`*:: ++ +-- +type: keyword + +User's home directory. + + +-- + +*`system.audit.user.shell`*:: ++ +-- +type: keyword + +Program to run at login. + + +-- + +*`system.audit.user.user_information`*:: ++ +-- +type: text + +General user information. On Linux, this is the gecos field. + + +-- + +*`system.audit.user.group`*:: ++ +-- +type: object + +`group` contains information about any groups the user is part of (beyond the user's primary group). + + +-- + +[float] +== password fields + +`password` contains information about a user's password (not the password itself). + + + +*`system.audit.user.password.type`*:: ++ +-- +type: keyword + +A user's password type. Possible values are `shadow_password` (the password hash is in the shadow file), `password_disabled`, `no_password` (this is dangerous as anyone can log in), and `crypt_password` (when the password field in /etc/passwd seems to contain an encrypted password). + + +-- + +*`system.audit.user.password.last_changed`*:: ++ +-- +type: date + +The day the user's password was last changed. + + +-- + diff --git a/auditbeat/docs/modules_list.asciidoc b/auditbeat/docs/modules_list.asciidoc index 84c110b16c35..ed367bac1d09 100644 --- a/auditbeat/docs/modules_list.asciidoc +++ b/auditbeat/docs/modules_list.asciidoc @@ -4,9 +4,11 @@ This file is generated! See scripts/docs_collector.py * <<{beatname_lc}-module-auditd,Auditd>> * <<{beatname_lc}-module-file_integrity,File Integrity>> + * <<{beatname_lc}-module-system,System>> -- -include::modules/auditd.asciidoc[] -include::modules/file_integrity.asciidoc[] +include::./modules/auditd.asciidoc[] +include::./modules/file_integrity.asciidoc[] +include::../../x-pack/auditbeat/docs/modules/system.asciidoc[] diff --git a/auditbeat/magefile.go b/auditbeat/magefile.go index 54551bb9c6c3..de1f2b31c241 100644 --- a/auditbeat/magefile.go +++ b/auditbeat/magefile.go @@ -121,8 +121,23 @@ func Config() error { // Update is an alias for running fields, dashboards, config, includes. func Update() { mg.SerialDeps(Fields, Dashboards, Config, - mage.GenerateModuleIncludeListGo, - auditbeat.CollectDocs) + mage.GenerateModuleIncludeListGo, Docs) +} + +// Docs collects the documentation. +func Docs() { + mg.SerialDeps(xpackFields, combinedDocs) +} + +// combinedDocs builds combined documentation for both OSS and X-Pack. +func combinedDocs() error { + return auditbeat.CollectDocs(mage.OSSBeatDir(), auditbeat.XpackBeatDir()) +} + +// xpackFields creates x-pack/auditbeat/fields.yml - necessary to build +// a combined documentation. +func xpackFields() error { + return mage.Mage(auditbeat.XpackBeatDir(), "fields") } // Fmt formats source code and adds file headers. diff --git a/auditbeat/scripts/docs_collector.py b/auditbeat/scripts/docs_collector.py index d843f1932a55..87e1d3104aa2 100644 --- a/auditbeat/scripts/docs_collector.py +++ b/auditbeat/scripts/docs_collector.py @@ -6,10 +6,13 @@ # Collects docs for all modules and metricset -def collect(beat_name): +def collect(base_paths): - base_dir = "module" - path = os.path.abspath("module") + # Always use the auditbeat/docs/ directory, regardless + # of where this script was called from. + docs_path = os.path.abspath(os.path.join(__file__, os.pardir, os.pardir, "docs")) + + beat_name = os.path.basename(base_paths[0]) generated_note = """//// This file is generated! See scripts/docs_collector.py @@ -19,17 +22,25 @@ def collect(beat_name): modules_list = {} + # Dict: module name -> module path + module_dirs = {} + for path in base_paths: + module_dir = os.path.join(path, "module") + for module_name in os.listdir(module_dir): + module_dirs[module_name] = os.path.join(module_dir, module_name) + # Iterate over all modules - for module in sorted(os.listdir(base_dir)): + for module in sorted(module_dirs): + module_dir = module_dirs[module] - module_doc = path + "/" + module + "/_meta/docs.asciidoc" + module_doc = os.path.join(module_dir, "_meta/docs.asciidoc") # Only check folders where docs.asciidoc exists if os.path.isfile(module_doc) == False: continue # Create directory for each module - os.mkdir(os.path.abspath("docs") + "/modules/" + module) + os.mkdir(os.path.join(module_docs_path(module_dir), "modules", module)) module_file = generated_note module_file += "[id=\"{beatname_lc}-module-" + module + "\"]\n" @@ -37,7 +48,7 @@ def collect(beat_name): with open(module_doc) as f: module_file += f.read() - beat_path = path + "/" + module + "/_meta" + beat_path = os.path.join(module_dir, "_meta") # Load title from fields.yml with open(beat_path + "/fields.yml") as f: @@ -76,9 +87,9 @@ def collect(beat_name): module_includes = "" # Iterate over all metricsets - for metricset in sorted(os.listdir(base_dir + "/" + module)): + for metricset in sorted(os.listdir(module_dir)): - metricset_docs = path + "/" + module + "/" + metricset + "/_meta/docs.asciidoc" + metricset_docs = os.path.join(module_dir, metricset, "_meta/docs.asciidoc") # Only check folders where fields.yml exists if os.path.isfile(metricset_docs) == False: @@ -96,6 +107,10 @@ def collect(beat_name): # Add reference to metricset file and include file metricset_file += reference + "\n" + + # Create title out of module and metricset set name + metricset_file += "=== {} {} metricset\n\n".format(title, metricset) + metricset_file += 'include::../../../module/' + module + '/' + metricset + '/_meta/docs.asciidoc[]' + "\n" # TODO: This should point directly to the exported fields of the metricset, not the whole module @@ -108,7 +123,7 @@ def collect(beat_name): """ - data_file = path + "/" + module + "/" + metricset + "/_meta/data.json" + data_file = os.path.join(module_dir, metricset, "_meta/data.json") # Add data.json example json document if os.path.isfile(data_file) == True: @@ -121,7 +136,7 @@ def collect(beat_name): metricset_file += "----\n" # Write metricset docs - with open(os.path.abspath("docs") + "/modules/" + module + "/" + metricset + ".asciidoc", 'w') as f: + with open(os.path.join(module_docs_path(module_dir), "modules", module, metricset + ".asciidoc"), 'w') as f: f.write(metricset_file) if len(module_links) > 0: @@ -133,7 +148,7 @@ def collect(beat_name): module_file += module_includes # Write module docs - with open(os.path.abspath("docs") + "/modules/" + module + ".asciidoc", 'w') as f: + with open(os.path.join(module_docs_path(module_dir), "modules", module + ".asciidoc"), 'w') as f: f.write(module_file) module_list_output = generated_note @@ -141,20 +156,30 @@ def collect(beat_name): module_list_output += " * <<{beatname_lc}-module-" + m + "," + title + ">>\n" module_list_output += "\n\n--\n\n" - for m, title in sorted(six.iteritems(modules_list)): - module_list_output += "include::modules/" + m + ".asciidoc[]\n" + for module_name, module_path in sorted(six.iteritems(module_dirs)): + rel_path_to_module_docs = os.path.relpath(module_docs_path(module_path), docs_path) + module_list_output += "include::" + \ + os.path.join(rel_path_to_module_docs, "modules", module_name + ".asciidoc") + "[]\n" # Write module link list - with open(os.path.abspath("docs") + "/modules_list.asciidoc", 'w') as f: + with open(os.path.join(docs_path, "modules_list.asciidoc"), 'w') as f: f.write(module_list_output) +def module_docs_path(module_path): + """ + Returns the docs path for a module. + E.g. modules in x-pack/auditbeat/modules are put in x-pack/auditbeat/docs + (but linked to from beats/auditbeat/docs/modules_list.asciidoc) + """ + return os.path.abspath(os.path.join(module_path, os.pardir, os.pardir, "docs")) + + if __name__ == "__main__": parser = argparse.ArgumentParser( description="Collects modules docs") - parser.add_argument("--beat", help="Beat name") + parser.add_argument("--base-paths", dest='base_paths', nargs='+', help="Base paths") args = parser.parse_args() - beat_name = args.beat - collect(beat_name) + collect(args.base_paths) diff --git a/auditbeat/scripts/mage/docs.go b/auditbeat/scripts/mage/docs.go index 8b283152ee3d..d8c70bbae16e 100644 --- a/auditbeat/scripts/mage/docs.go +++ b/auditbeat/scripts/mage/docs.go @@ -19,6 +19,7 @@ package mage import ( "os" + "path/filepath" "strings" "github.com/magefile/mage/sh" @@ -28,13 +29,17 @@ import ( ) // CollectDocs collects documentation from modules. -// -// TODO: This needs to be updated to collect docs from x-pack/auditbeat. -func CollectDocs() error { +func CollectDocs(basePaths ...string) error { + // Generate config.yml files for each module. - configFiles, err := mage.FindFiles(ConfigTemplateGlob) - if err != nil { - return errors.Wrap(err, "failed to find config templates") + var configFiles []string + for _, path := range basePaths { + files, err := mage.FindFiles(filepath.Join(path, ConfigTemplateGlob)) + if err != nil { + return errors.Wrap(err, "failed to find config templates") + } + + configFiles = append(configFiles, files...) } var configs []string @@ -52,11 +57,13 @@ func CollectDocs() error { defer mage.Clean(configs) // Remove old. - if err = os.RemoveAll(mage.OSSBeatDir("docs/modules")); err != nil { - return err - } - if err = os.MkdirAll(mage.OSSBeatDir("docs/modules"), 0755); err != nil { - return err + for _, path := range basePaths { + if err := os.RemoveAll(filepath.Join(path, "docs/modules")); err != nil { + return err + } + if err := os.MkdirAll(filepath.Join(path, "docs/modules"), 0755); err != nil { + return err + } } // Run the docs_collector.py script. @@ -71,7 +78,24 @@ func CollectDocs() error { } // TODO: Port this script to Go. - return sh.Run(python, - mage.OSSBeatDir("scripts/docs_collector.py"), - "--beat", mage.BeatName) + args := []string{mage.OSSBeatDir("scripts/docs_collector.py"), "--base-paths"} + args = append(args, basePaths...) + + err = sh.Run(python, args...) + if err != nil { + return err + } + + esBeats, err := mage.ElasticBeatsDir() + if err != nil { + return err + } + + return sh.Run(python, mage.LibbeatDir("scripts/generate_fields_docs.py"), + XpackBeatDir(), mage.BeatName, esBeats, "--output_path", mage.OSSBeatDir()) +} + +// XpackBeatDir returns the x-pack/{beatname} directory for a Beat. +func XpackBeatDir() string { + return mage.OSSBeatDir("../x-pack", mage.BeatName) } diff --git a/libbeat/scripts/generate_fields_docs.py b/libbeat/scripts/generate_fields_docs.py index 0aa6a31a8777..da029940a50a 100644 --- a/libbeat/scripts/generate_fields_docs.py +++ b/libbeat/scripts/generate_fields_docs.py @@ -146,11 +146,12 @@ def fields_to_asciidoc(input, output, beat): parser.add_argument("path", help="Path to the beat folder") parser.add_argument("beattitle", help="The beat title") parser.add_argument("es_beats", help="The path to the general beats folder") + parser.add_argument("--output_path", default="", dest="output_path", help="Output path, if different from path") args = parser.parse_args() beat_path = args.path - beat_title = args.beattitle + beat_title = args.beattitle.title() es_beats = args.es_beats fields_yml = beat_path + "/fields.yml" @@ -159,7 +160,10 @@ def fields_to_asciidoc(input, output, beat): with open(fields_yml) as f: fields = f.read() - output = open(beat_path + "/docs/fields.asciidoc", 'w') + if args.output_path is not "": + output = open(os.path.join(args.output_path, "docs/fields.asciidoc"), 'w') + else: + output = open(os.path.join(beat_path, "docs/fields.asciidoc"), 'w') try: fields_to_asciidoc(fields, output, beat_title) diff --git a/x-pack/auditbeat/auditbeat.reference.yml b/x-pack/auditbeat/auditbeat.reference.yml index 2e84b1c00ef7..66b18470f9f9 100644 --- a/x-pack/auditbeat/auditbeat.reference.yml +++ b/x-pack/auditbeat/auditbeat.reference.yml @@ -108,22 +108,33 @@ auditbeat.modules: # Detect changes to files included in subdirectories. Disabled by default. recursive: false +# The system module collects security related information about a host. +# All metricsets send both periodic state information (e.g. all currently +# running processes) and real-time changes (e.g. when a new process starts +# or stops). - module: system - metricsets: - - host - - process - - socket - - user - + - host # General host information, e.g. uptime, IPs + - process # Started and stopped processes + - socket # Opened and closed sockets + - user # User information + + # How often metricsets send state updates with the + # current state of the system (e.g. all currently + # running processes, all open sockets). state.period: 12h + # The state.period can be overridden for any metricset. + # host.state.period: 12h + # process.state.period: 12h + # socket.state.period: 12h + # user.state.period: 12h + # Enabled by default. Auditbeat will read password fields in # /etc/passwd and /etc/shadow and store a hash locally to # detect any changes. user.detect_password_changes: true - #================================ 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 index 630237c7e8bb..6980859ec4df 100644 --- a/x-pack/auditbeat/auditbeat.yml +++ b/x-pack/auditbeat/auditbeat.yml @@ -47,13 +47,15 @@ auditbeat.modules: - /etc - module: system - metricsets: - - host - - process - - socket - - user - + - host # General host information, e.g. uptime, IPs + - process # Started and stopped processes + - socket # Opened and closed sockets + - user # User information + + # How often metricsets send state updates with the + # current state of the system (e.g. all currently + # running processes, all open sockets). state.period: 12h # Enabled by default. Auditbeat will read password fields in @@ -61,7 +63,6 @@ auditbeat.modules: # detect any changes. user.detect_password_changes: true - #==================== 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 new file mode 100644 index 000000000000..abbd8844b86c --- /dev/null +++ b/x-pack/auditbeat/docs/modules/system.asciidoc @@ -0,0 +1,148 @@ +//// +This file is generated! See scripts/docs_collector.py +//// + +[id="{beatname_lc}-module-system"] +[role="xpack"] + +== System Module + +experimental[] + +The `system` module collects various security related information about +a system. All metricsets send both periodic state information (e.g. all currently +running processes) and real-time changes (e.g. when a new process starts +or stops). + +The module is fully implemented for Linux, and partially implemented +for macOS (Darwin). + +[float] +=== How it works + +Each metricset sends two kinds of information: state and events. + +State information is sent periodically and on startup (for some metricsets). +A state update will consist of one event per object that is currently +active on the system (e.g. a process). All events belonging to the same state +update will share the same UUID in `event.id`. + +The frequency of state updates can be controlled for all metricsets using the +`state.period` configuration option. Overrides are available per metricset. +The default is `12h`. + +Event information is sent as the events occur (e.g. a process starts or stops). +All metricsets are currently using a poll model to retrieve their data. +The frequency of these polls is controlled using the `period` configuration +parameter. + +[float] +=== Configuration options + +This module has some configuration options for controlling its behavior. The +following example shows all configuration options with their default values for +Linux. + +NOTE: It is recommended to configure some metricsets separately. See below for a +sample suggested configuration. + +[source,yaml] +---- +- module: system + metricsets: + - host + - process + - socket + - user + period: 10s + state.period: 12h + user.detect_password_changes: true +---- + +*`period`*:: The frequency at which the metricsets check for changes. For most +metricsets - esp. `process` and `socket` - a shorter period is recommended. + +*`state.period`*:: The frequency at which the metricsets send full state information. +This option can be overridden per metricset using `{metricset}.state.period`. + +*`user.detect_password_changes`*:: If the `user` metricset is configured and +this option is set to `true`, Auditbeat will read password information in `/etc/passwd` +and `/etc/shadow` to detect password changes. A hash will be kept locally in +the `beat.db` file to detect changes between Auditbeat restarts. The `beat.db` file +should be readable only by the root user and be treated similar to the shadow file +itself. + +[float] +=== Suggested configuration + +Processes and sockets can be short-lived, so the chance of missing an update +increases if the polling interval is too large. + +On the other hand, host and user information is unlikely to change frequently, +so a longer polling interval can be used. + +[source,yaml] +---- +- module: system + metricsets: + - host + - user + period: 1m + user.detect_password_changes: true + +- module: system + - process + - socket + period: 1s +---- + + +[float] +=== Example configuration + +The System module supports the common configuration options that are +described under <>. Here +is an example configuration: + +[source,yaml] +---- +auditbeat.modules: +- module: system + metricsets: + - host # General host information, e.g. uptime, IPs + - process # Started and stopped processes + - socket # Opened and closed sockets + - user # User information + + # How often metricsets send state updates with the + # current state of the system (e.g. all currently + # running processes, all open sockets). + state.period: 12h + + # Enabled by default. Auditbeat will read password fields in + # /etc/passwd and /etc/shadow and store a hash locally to + # detect any changes. + user.detect_password_changes: true +---- + +[float] +=== Metricsets + +The following metricsets are available: + +* <<{beatname_lc}-metricset-system-host,host>> + +* <<{beatname_lc}-metricset-system-process,process>> + +* <<{beatname_lc}-metricset-system-socket,socket>> + +* <<{beatname_lc}-metricset-system-user,user>> + +include::system/host.asciidoc[] + +include::system/process.asciidoc[] + +include::system/socket.asciidoc[] + +include::system/user.asciidoc[] + diff --git a/x-pack/auditbeat/docs/modules/system/host.asciidoc b/x-pack/auditbeat/docs/modules/system/host.asciidoc new file mode 100644 index 000000000000..484702d801b0 --- /dev/null +++ b/x-pack/auditbeat/docs/modules/system/host.asciidoc @@ -0,0 +1,21 @@ +//// +This file is generated! See scripts/docs_collector.py +//// + +[id="{beatname_lc}-metricset-system-host"] +=== System host metricset + +include::../../../module/system/host/_meta/docs.asciidoc[] + + +==== Fields + +For a description of each field in the metricset, see the +<> section. + +Here is an example document generated by this metricset: + +[source,json] +---- +include::../../../module/system/host/_meta/data.json[] +---- diff --git a/x-pack/auditbeat/docs/modules/system/process.asciidoc b/x-pack/auditbeat/docs/modules/system/process.asciidoc new file mode 100644 index 000000000000..605d20d055ca --- /dev/null +++ b/x-pack/auditbeat/docs/modules/system/process.asciidoc @@ -0,0 +1,21 @@ +//// +This file is generated! See scripts/docs_collector.py +//// + +[id="{beatname_lc}-metricset-system-process"] +=== System process metricset + +include::../../../module/system/process/_meta/docs.asciidoc[] + + +==== Fields + +For a description of each field in the metricset, see the +<> section. + +Here is an example document generated by this metricset: + +[source,json] +---- +include::../../../module/system/process/_meta/data.json[] +---- diff --git a/x-pack/auditbeat/docs/modules/system/socket.asciidoc b/x-pack/auditbeat/docs/modules/system/socket.asciidoc new file mode 100644 index 000000000000..9c63d7bbb2d4 --- /dev/null +++ b/x-pack/auditbeat/docs/modules/system/socket.asciidoc @@ -0,0 +1,21 @@ +//// +This file is generated! See scripts/docs_collector.py +//// + +[id="{beatname_lc}-metricset-system-socket"] +=== System socket metricset + +include::../../../module/system/socket/_meta/docs.asciidoc[] + + +==== Fields + +For a description of each field in the metricset, see the +<> section. + +Here is an example document generated by this metricset: + +[source,json] +---- +include::../../../module/system/socket/_meta/data.json[] +---- diff --git a/x-pack/auditbeat/docs/modules/system/user.asciidoc b/x-pack/auditbeat/docs/modules/system/user.asciidoc new file mode 100644 index 000000000000..6d64e9884885 --- /dev/null +++ b/x-pack/auditbeat/docs/modules/system/user.asciidoc @@ -0,0 +1,21 @@ +//// +This file is generated! See scripts/docs_collector.py +//// + +[id="{beatname_lc}-metricset-system-user"] +=== System user metricset + +include::../../../module/system/user/_meta/docs.asciidoc[] + + +==== Fields + +For a description of each field in the metricset, see the +<> section. + +Here is an example document generated by this metricset: + +[source,json] +---- +include::../../../module/system/user/_meta/data.json[] +---- diff --git a/x-pack/auditbeat/magefile.go b/x-pack/auditbeat/magefile.go index 7a20d10a0110..7a1a001f49b1 100644 --- a/x-pack/auditbeat/magefile.go +++ b/x-pack/auditbeat/magefile.go @@ -108,7 +108,13 @@ func Config() error { // Update is an alias for running fields, dashboards, config. func Update() { - mg.SerialDeps(Fields, Dashboards, Config, mage.GenerateModuleIncludeListGo) + mg.SerialDeps(Fields, Dashboards, Config, mage.GenerateModuleIncludeListGo, + Docs) +} + +// Docs collects the documentation. +func Docs() error { + return auditbeat.CollectDocs(mage.OSSBeatDir(), auditbeat.XpackBeatDir()) } // Fmt formats source code and adds file headers. diff --git a/x-pack/auditbeat/module/system/_meta/config.yml.tmpl b/x-pack/auditbeat/module/system/_meta/config.yml.tmpl index 62b498c369ec..94893b4ed61c 100644 --- a/x-pack/auditbeat/module/system/_meta/config.yml.tmpl +++ b/x-pack/auditbeat/module/system/_meta/config.yml.tmpl @@ -1,21 +1,33 @@ +{{ if ne .GOOS "windows" -}} {{ if .Reference -}} +# The system module collects security related information about a host. +# All metricsets send both periodic state information (e.g. all currently +# running processes) and real-time changes (e.g. when a new process starts +# or stops). {{ end -}} -{{ if ne .GOOS "windows" -}} - module: system - metricsets: - - host + - host # General host information, e.g. uptime, IPs {{ if false -}} - - packages + - packages # Installed packages {{- end -}} - - process + - process # Started and stopped processes {{ if eq .GOOS "linux" -}} - - socket - - user + - socket # Opened and closed sockets + - user # User information {{- end }} + # How often metricsets send state updates with the + # current state of the system (e.g. all currently + # running processes, all open sockets). state.period: 12h - +{{ if .Reference }} + # The state.period can be overridden for any metricset. + # host.state.period: 12h + # process.state.period: 12h + # socket.state.period: 12h + # user.state.period: 12h +{{ end }} {{ if eq .GOOS "linux" -}} # Enabled by default. Auditbeat will read password fields in # /etc/passwd and /etc/shadow and store a hash locally to @@ -27,5 +39,3 @@ report_changes: true {{- end -}} {{- end }} -{{ if .Reference }} -{{- end }} diff --git a/x-pack/auditbeat/module/system/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/_meta/docs.asciidoc index d20f430847e4..e402da99d2ed 100644 --- a/x-pack/auditbeat/module/system/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/_meta/docs.asciidoc @@ -1,22 +1,92 @@ +[role="xpack"] + == System Module -The `system` module ... TODO. +experimental[] + +The `system` module collects various security related information about +a system. All metricsets send both periodic state information (e.g. all currently +running processes) and real-time changes (e.g. when a new process starts +or stops). -The module is implemented for Linux, macOS (Darwin), and Windows. +The module is fully implemented for Linux, and partially implemented +for macOS (Darwin). [float] === How it works -TODO +Each metricset sends two kinds of information: state and events. + +State information is sent periodically and on startup (for some metricsets). +A state update will consist of one event per object that is currently +active on the system (e.g. a process). All events belonging to the same state +update will share the same UUID in `event.id`. + +The frequency of state updates can be controlled for all metricsets using the +`state.period` configuration option. Overrides are available per metricset. +The default is `12h`. + +Event information is sent as the events occur (e.g. a process starts or stops). +All metricsets are currently using a poll model to retrieve their data. +The frequency of these polls is controlled using the `period` configuration +parameter. [float] === Configuration options -TODO +This module has some configuration options for controlling its behavior. The +following example shows all configuration options with their default values for +Linux. + +NOTE: It is recommended to configure some metricsets separately. See below for a +sample suggested configuration. [source,yaml] ---- - module: system + metricsets: + - host + - process + - socket + - user + period: 10s + state.period: 12h + user.detect_password_changes: true ---- -*`some_option`*:: TODO +*`period`*:: The frequency at which the metricsets check for changes. For most +metricsets - esp. `process` and `socket` - a shorter period is recommended. + +*`state.period`*:: The frequency at which the metricsets send full state information. +This option can be overridden per metricset using `{metricset}.state.period`. + +*`user.detect_password_changes`*:: If the `user` metricset is configured and +this option is set to `true`, Auditbeat will read password information in `/etc/passwd` +and `/etc/shadow` to detect password changes. A hash will be kept locally in +the `beat.db` file to detect changes between Auditbeat restarts. The `beat.db` file +should be readable only by the root user and be treated similar to the shadow file +itself. + +[float] +=== Suggested configuration + +Processes and sockets can be short-lived, so the chance of missing an update +increases if the polling interval is too large. + +On the other hand, host and user information is unlikely to change frequently, +so a longer polling interval can be used. + +[source,yaml] +---- +- module: system + metricsets: + - host + - user + period: 1m + user.detect_password_changes: true + +- module: system + - process + - socket + period: 1s +---- diff --git a/x-pack/auditbeat/module/system/host/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/host/_meta/docs.asciidoc index d8e6689c4694..a8041d169c3d 100644 --- a/x-pack/auditbeat/module/system/host/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/host/_meta/docs.asciidoc @@ -1,8 +1,7 @@ -The System `host` metricset provides ... TODO. +[role="xpack"] -The module is implemented for Linux, macOS (Darwin), and Windows. +experimental[] -[float] -=== Configuration options +This is the `host` metricset of the system module. -TODO +It is implemented for Linux and macOS (Darwin). diff --git a/x-pack/auditbeat/module/system/process/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/process/_meta/docs.asciidoc index 339f7f411abc..8aea28521556 100644 --- a/x-pack/auditbeat/module/system/process/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/process/_meta/docs.asciidoc @@ -1,8 +1,7 @@ -The System `process` metricset provides ... TODO. +[role="xpack"] -The module is implemented for Linux, macOS (Darwin), and Windows. +experimental[] -[float] -=== Configuration options +This is the `process` metricset of the system module. -TODO +It is implemented for Linux and macOS (Darwin). diff --git a/x-pack/auditbeat/module/system/socket/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/socket/_meta/docs.asciidoc index fc902d7cf674..61e98483311e 100644 --- a/x-pack/auditbeat/module/system/socket/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/socket/_meta/docs.asciidoc @@ -1,8 +1,7 @@ -The System `socket` metricset provides ... TODO. +[role="xpack"] -The module is implemented for Linux only. +experimental[] -[float] -=== Configuration options +This is the `process` metricset of the system module. -TODO +It is implemented for Linux only. diff --git a/x-pack/auditbeat/module/system/user/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/user/_meta/docs.asciidoc index d4d77ce0cf21..dd5af6ead89f 100644 --- a/x-pack/auditbeat/module/system/user/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/user/_meta/docs.asciidoc @@ -1,8 +1,7 @@ -The System `user` metricset provides ... TODO. +[role="xpack"] -The module is implemented for Linux. +experimental[] -[float] -=== Configuration options +This is the `user` metricset of the system module. -TODO +It is implemented for Linux only.