Skip to content

Commit 0ff05eb

Browse files
andrewkrohandrewkroh
authored
Add documentation for Winlogbeat modules (#12361)
Add documentation for the security and sysmon modules that explains what the modules accomplish and how to configure them. Relates #11651
1 parent 3ab727b commit 0ff05eb

9 files changed

Lines changed: 301 additions & 2 deletions

File tree

‎winlogbeat/docs/index.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ include::./upgrading.asciidoc[]
3232

3333
include::./configuring-howto.asciidoc[]
3434

35+
include::./modules.asciidoc[]
36+
3537
include::./fields.asciidoc[]
3638

3739
include::{libbeat-dir}/docs/monitoring/monitoring-beats.asciidoc[]

‎winlogbeat/docs/modules.asciidoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
[id="{beatname_lc}-modules"]
2+
[role="xpack"]
3+
= Modules
4+
5+
[partintro]
6+
--
7+
This section contains detailed information about the available Windows event
8+
log processing modules contained in {beatname_uc}. More details about each
9+
module can be found in the module's documentation.
10+
11+
Winlogbeat modules are constructed using the
12+
<<processor-script,script processor>> where all processing happens within
13+
Winlogbeat before the events are delivered to the output.
14+
15+
The general goal of each module is to transform events by renaming fields to
16+
comply with the {ecs-ref}/index.html[Elastic Common Schema] (ECS). The modules
17+
may also apply additional categorization, tagging, and parsing as necessary.
18+
19+
The default configuration file included in packages has each of the modules
20+
configured. To apply the modules to your own configuration file you must add
21+
a `script` processor to your configuration file and point it at the included
22+
script file for the module. The documentation for each module includes an
23+
example.
24+
25+
[float]
26+
=== Usage with Forwarded Events
27+
28+
The `ForwardedEvents` channel can contain events from multiple producers so you
29+
may want to use multiple modules. This can be achieved by applying multiple
30+
script processors that are guarded by a conditional `when` statement.
31+
32+
[source,yaml]
33+
----
34+
winlogbeat.event_logs:
35+
- name: ForwardedEvents
36+
tags: [forwarded]
37+
processors:
38+
- script:
39+
when.equals.winlog.channel: Security
40+
lang: javascript
41+
id: security
42+
file: ${path.home}/module/security/config/winlogbeat-security.js
43+
- script:
44+
when.equals.winlog.channel: Microsoft-Windows-Sysmon/Operational
45+
lang: javascript
46+
id: sysmon
47+
file: ${path.home}/module/sysmon/config/winlogbeat-sysmon.js
48+
----
49+
50+
[float]
51+
=== Modules
52+
//pass macro block used here to remove Edit links from modules documentation because it is generated
53+
pass::[<?edit_url?>]
54+
include::modules_list.asciidoc[]
55+
56+
57+

‎winlogbeat/docs/modules/security.asciidoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
[[winlogbeat-module-security]]
2+
[role="xpack"]
3+
== Security Module
4+
5+
beta[]
6+
7+
The security module processes event log records from the Security log.
8+
9+
The module has transformations for the following event IDs:
10+
11+
* 4624 - An account was successfully logged on.
12+
* 4625 - An account failed to log on.
13+
* 4648 - A logon was attempted using explicit credentials.
14+
15+
More event IDs will be added.
16+
17+
[float]
18+
=== Configuration
19+
20+
[source,yaml]
21+
----
22+
winlogbeat.event_logs:
23+
- name: Security
24+
processors:
25+
- script:
26+
lang: javascript
27+
id: security
28+
file: ${path.home}/module/security/config/winlogbeat-security.js
29+
----

‎winlogbeat/docs/modules/sysmon.asciidoc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
[[winlogbeat-module-sysmon]]
2+
[role="xpack"]
3+
== Sysmon Module
4+
5+
beta[]
6+
7+
The sysmon module processes event log records from the
8+
https://docs.microsoft.com/en-us/sysinternals/downloads/sysmon[Sysinternals
9+
System Monitor] (Sysmon) which is a Windows service and device driver that logs
10+
system activity to the event log. Sysmon is not bundled with Windows or
11+
Winlogbeat and must be installed independently.
12+
13+
The default configuration file includes configuration for Sysmon. If you do not
14+
have Sysmon installed Winlogbeat will log a warning that it could not read from
15+
the `Microsoft-Windows-Sysmon/Operational` channel. It will continue to read
16+
from the other configured channels. If you do install Sysmon at a later time
17+
then a restart of Winlogbeat is required to make it begin reading from the
18+
channel.
19+
20+
This module was built based on Sysmon v9 event manifests. It contains
21+
transformations for each of the defined event IDs.
22+
23+
[float]
24+
=== Configuration
25+
26+
[source,yaml]
27+
----
28+
winlogbeat.event_logs:
29+
- name: Microsoft-Windows-Sysmon/Operational
30+
processors:
31+
- script:
32+
lang: javascript
33+
id: sysmon
34+
file: ${path.home}/module/sysmon/config/winlogbeat-sysmon.js
35+
----

‎winlogbeat/docs/modules_list.asciidoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
////
2+
This file is generated! See scripts/mage/docs.go or run 'mage docs'.
3+
////
4+
5+
* <<{beatname_lc}-module-security,Security>>
6+
* <<{beatname_lc}-module-sysmon,Sysmon>>
7+
8+
--
9+
10+
11+
include::./modules/security.asciidoc[]
12+
include::./modules/sysmon.asciidoc[]

‎winlogbeat/scripts/mage/docs.go‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// Licensed to Elasticsearch B.V. under one or more contributor
2+
// license agreements. See the NOTICE file distributed with
3+
// this work for additional information regarding copyright
4+
// ownership. Elasticsearch B.V. licenses this file to you under
5+
// the Apache License, Version 2.0 (the "License"); you may
6+
// not use this file except in compliance with the License.
7+
// You may obtain a copy of the License at
8+
//
9+
// http://www.apache.org/licenses/LICENSE-2.0
10+
//
11+
// Unless required by applicable law or agreed to in writing,
12+
// software distributed under the License is distributed on an
13+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
// KIND, either express or implied. See the License for the
15+
// specific language governing permissions and limitations
16+
// under the License.
17+
18+
package mage
19+
20+
import (
21+
"fmt"
22+
"io/ioutil"
23+
"os"
24+
"path/filepath"
25+
"regexp"
26+
"strings"
27+
28+
"github.com/pkg/errors"
29+
30+
"github.com/elastic/beats/dev-tools/mage"
31+
)
32+
33+
const moduleDocsGlob = "module/*/_meta/docs.asciidoc"
34+
35+
var moduleNameRegex = regexp.MustCompile(`module\/(.*)\/_meta\/docs.asciidoc`)
36+
37+
var modulesListTmpl = `
38+
////
39+
This file is generated! See scripts/mage/docs.go or run 'mage docs'.
40+
////
41+
{{range $module := .Modules}}
42+
* <<{beatname_lc}-module-{{$module}},{{$module | title}}>>
43+
{{- end}}
44+
45+
--
46+
47+
{{range $module := .Modules}}
48+
include::./modules/{{$module}}.asciidoc[]
49+
{{- end}}
50+
`[1:]
51+
52+
func moduleDocs() error {
53+
searchPath := filepath.Join(mage.XPackBeatDir(moduleDocsGlob))
54+
55+
// Find module docs.
56+
files, err := mage.FindFiles(searchPath)
57+
if err != nil {
58+
return err
59+
}
60+
if len(files) == 0 {
61+
return errors.Errorf("No modules found matching %v", searchPath)
62+
}
63+
64+
// Clean existing files.
65+
if err := os.RemoveAll(mage.OSSBeatDir("docs/modules")); err != nil {
66+
return err
67+
}
68+
69+
// Extract module name from path and copy the file.
70+
var names []string
71+
for _, f := range files {
72+
matches := moduleNameRegex.FindStringSubmatch(filepath.ToSlash(f))
73+
if len(matches) != 2 {
74+
return errors.Errorf("module path %v does not match regexp", f)
75+
}
76+
name := matches[1]
77+
names = append(names, name)
78+
79+
// Copy to the docs dirs.
80+
if err = mage.Copy(f, mage.CreateDir(mage.OSSBeatDir("docs/modules", name+".asciidoc"))); err != nil {
81+
return err
82+
}
83+
}
84+
85+
// Generate and write the docs/modules_list.asciidoc file.
86+
content, err := mage.Expand(modulesListTmpl, map[string]interface{}{
87+
"Modules": names,
88+
})
89+
if err != nil {
90+
return err
91+
}
92+
93+
fmt.Printf(">> update:moduleDocs: Collecting module documentation for %v.\n", strings.Join(names, ", "))
94+
return ioutil.WriteFile(mage.OSSBeatDir("docs/modules_list.asciidoc"), []byte(content), 0644)
95+
}

‎winlogbeat/scripts/mage/update.go‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ func init() {
3232

3333
dashboards.RegisterImportDeps(build.Build, Update.Dashboards)
3434

35-
docs.RegisterDeps(Update.FieldDocs)
35+
docs.RegisterDeps(Update.FieldDocs, Update.ModuleDocs)
3636
}
3737

3838
var (
@@ -45,7 +45,7 @@ type Update mg.Namespace
4545

4646
// All updates all generated content.
4747
func (Update) All() {
48-
mg.Deps(Update.Fields, Update.Dashboards, Update.Config, Update.FieldDocs)
48+
mg.Deps(Update.Fields, Update.Dashboards, Update.Config, Update.FieldDocs, Update.ModuleDocs)
4949
}
5050

5151
// Config updates the Beat's config files.
@@ -69,3 +69,8 @@ func (Update) FieldDocs() error {
6969
mg.Deps(fb.FieldsAllYML)
7070
return mage.Docs.FieldDocs(mage.FieldsAllYML)
7171
}
72+
73+
// ModuleDocs collects and updates the module documentation.
74+
func (Update) ModuleDocs() error {
75+
return moduleDocs()
76+
}

‎x-pack/winlogbeat/module/security/_meta/docs.asciidoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
[[winlogbeat-module-security]]
2+
[role="xpack"]
3+
== Security Module
4+
5+
beta[]
6+
7+
The security module processes event log records from the Security log.
8+
9+
The module has transformations for the following event IDs:
10+
11+
* 4624 - An account was successfully logged on.
12+
* 4625 - An account failed to log on.
13+
* 4648 - A logon was attempted using explicit credentials.
14+
15+
More event IDs will be added.
16+
17+
[float]
18+
=== Configuration
19+
20+
[source,yaml]
21+
----
22+
winlogbeat.event_logs:
23+
- name: Security
24+
processors:
25+
- script:
26+
lang: javascript
27+
id: security
28+
file: ${path.home}/module/security/config/winlogbeat-security.js
29+
----

‎x-pack/winlogbeat/module/sysmon/_meta/docs.asciidoc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
[[winlogbeat-module-sysmon]]
2+
[role="xpack"]
3+
== Sysmon Module
4+
5+
beta[]
6+
7+
The sysmon module processes event log records from the
8+
https://docs.microsoft.com/en-us/sysinternals/downloads/sysmon[Sysinternals
9+
System Monitor] (Sysmon) which is a Windows service and device driver that logs
10+
system activity to the event log. Sysmon is not bundled with Windows or
11+
Winlogbeat and must be installed independently.
12+
13+
The default configuration file includes configuration for Sysmon. If you do not
14+
have Sysmon installed Winlogbeat will log a warning that it could not read from
15+
the `Microsoft-Windows-Sysmon/Operational` channel. It will continue to read
16+
from the other configured channels. If you do install Sysmon at a later time
17+
then a restart of Winlogbeat is required to make it begin reading from the
18+
channel.
19+
20+
This module was built based on Sysmon v9 event manifests. It contains
21+
transformations for each of the defined event IDs.
22+
23+
[float]
24+
=== Configuration
25+
26+
[source,yaml]
27+
----
28+
winlogbeat.event_logs:
29+
- name: Microsoft-Windows-Sysmon/Operational
30+
processors:
31+
- script:
32+
lang: javascript
33+
id: sysmon
34+
file: ${path.home}/module/sysmon/config/winlogbeat-sysmon.js
35+
----

0 commit comments

Comments
 (0)