From b46864c8e954d0e00fe9d0ef852a8ff523b85217 Mon Sep 17 00:00:00 2001 From: Lynette Miles Date: Wed, 2 Jul 2025 13:32:47 -0700 Subject: [PATCH 1/2] Pipeline: input: win event log: style Signed-off-by: Lynette Miles --- .../inputs/windows-event-log-winevtlog.md | 95 ++++++++++--------- vale-styles/FluentBit/Acronyms.yml | 1 + 2 files changed, 50 insertions(+), 46 deletions(-) diff --git a/pipeline/inputs/windows-event-log-winevtlog.md b/pipeline/inputs/windows-event-log-winevtlog.md index a2e92f0d8..7aea04394 100644 --- a/pipeline/inputs/windows-event-log-winevtlog.md +++ b/pipeline/inputs/windows-event-log-winevtlog.md @@ -1,40 +1,56 @@ -# Windows Event Log (winevtlog) +# Windows Event Log -The **winevtlog** input plugin allows you to read Windows Event Log with new API from `winevt.h`. +The _Windows Event Log_ (`winevtlog`) input plugin lets you read Windows Event Log with the API from `winevt.h`. -## Configuration Parameters +## Configuration parameters The plugin supports the following configuration parameters: | Key | Description | Default | | :--- | :--- | :--- | -| Channels | A comma-separated list of channels to read from. | | -| Interval\_Sec | Set the polling interval for each channel. \(optional\) | 1 | -| Interval\_NSec | Set the polling interval for each channel (sub seconds. \(optional\) | 0 | -| Read\_Existing\_Events | Whether to read existing events from head or tailing events at last on subscribing. \(optional\) | False | -| DB | Set the path to save the read offsets. \(optional\) | | -| String\_Inserts | Whether to include StringInserts in output records. \(optional\) | True | -| Render\_Event\_As\_XML | Whether to render system part of event as XML string or not. \(optional\) | False | -| Ignore\_Missing\_Channels | Whether to ignore event channels not present in the event log, and continue running with subscribed channels. \(optional\) | False | -| Use\_ANSI | Use ANSI encoding on eventlog messages. If you have issues receiving blank strings with old Windows versions (Server 2012 R2), setting this to True may solve the problem. \(optional\) | False | -| Event\_Query | Specify XML query for filtering events. | `*` | -| Read\_Limit\_Per\_Cycle | Specify read limit per cycle. | 512KiB | +| `Channels` | A comma-separated list of channels to read from. | _none_ | +| `Interval_Sec` | Optional. Set the polling interval for each channel. | `1` | +| `Interval_NSec` | Optional. Set the polling interval for each channel. (nanoseconds) | `0 `| +| `Read_Existing_Events` | Optional. Whether to read existing events from head or tailing events at last on subscribing. | `False` | +| `DB` | Optional. Set the path to save the read offsets. | _none_ | +| `String_Inserts` | Optional. Whether to include string inserts in output records. | `True` | +| `Render_Event_As_XML` | Optional. Whether to render the system part of an event as an XML string or not. | `False` | +| `Ignore_Missing_Channels` | Optional. Whether to ignore event channels not present in the event log, and continue running with subscribed channels. | `False` | +| `Use_ANSI` | Optional. Use ANSI encoding on `eventlog` messages. If you have issues receiving blank strings with old Windows versions (Server 2012 R2), setting this to `True` might solve the problem. | `False` | +| `Event_Query` | Specify XML query for filtering events. | `*` | +| `Read_Limit_Per_Cycle` | Specify read limit per cycle. | `512KiB` | | Threaded | Indicates whether to run this input in its own [thread](../../administration/multithreading.md#inputs). | `false` | -| Remote.Server | Specify server name of remote access for Windows EventLog. | | -| Remote.Domain | Specify domain name of remote access for Windows EventLog. | | -| Remote.Username | Specify user name of remote access for Windows EventLog. | | -| Remote.Password | Specify password of remote access for Windows EventLog. | | +| `Remote.Server` | Specify server name of remote access for Windows EventLog. | _none_ | +| `Remote.Domain` | Specify domain name of remote access for Windows EventLog. | _none_ | +| `Remote.Username` | Specify user name of remote access for Windows EventLog. | _none_ | +| `Remote.Password` | Specify password of remote access for Windows EventLog. | _none_ | -Note that if you do not set _db_, the plugin will tail channels on each startup. +If `db` isn't set, the plugin will tail channels on each startup. -## Configuration Examples +## Configuration examples -### Configuration File +### Configuration file Here is a minimum configuration example. {% tabs %} +{% tab title="fluent-bit.yaml" %} + +```yaml +pipeline: + inputs: + - name: winevtlog + channels: Setup,Windows PowerShell + interval_sec: 1 + db: winevtlog.sqllite + outputs: + - name: stdout + match: '*' +``` + +{% endtab %} {% tab title="fluent-bit.conf" %} + ```python [INPUT] Name winevtlog @@ -46,42 +62,29 @@ Here is a minimum configuration example. Name stdout Match * ``` -{% endtab %} -{% tab title="fluent-bit.yaml" %} -```yaml -pipeline: - inputs: - - name: winevtlog - channels: Setup,Windows PowerShell - interval_sec: 1 - db: winevtlog.sqllite - outputs: - - name: stdout - match: '*' -``` {% endtab %} {% endtabs %} -Note that some Windows Event Log channels \(like `Security`\) requires an admin privilege for reading. In this case, you need to run fluent-bit as an administrator. +Some Windows Event Log channels, like `Security`, require administrative privilege for reading. In this case, you must run Fluent Bit as an administrator. + +The default value of `Read_Limit_Per_Cycle` is `512KiB`. -The default value of Read\_Limit\_Per\_Cycle is set up as 512KiB. -Note that 512KiB(= 0x7ffff = 512 * 1024 * 1024) does not equals to 512KB (= 512 * 1000 * 1000). -To increase events per second on this plugin, specify larger value than 512KiB. +512KiB(= 0x7ffff = 512 * 1024 * 1024) isn't equal to 512KB (= 512 * 1000 * 1000). To increase events per second on this plugin, specify larger value than 512KiB. -#### Query Languages for Event_Query Parameter +#### Query languages for `Event_Query` parameter The `Event_Query` parameter can be used to specify the XML query for filtering Windows EventLog during collection. -The supported query types are [XPath](https://developer.mozilla.org/en-US/docs/Web/XPath) and XML Query. -For further details, please refer to [the MSDN doc](https://learn.microsoft.com/en-us/windows/win32/wes/consuming-events). +The supported query types are [`XPath`](https://developer.mozilla.org/en-US/docs/Web/XPath) and XML Query. +For further details, refer to [Microsoft's documentation](https://learn.microsoft.com/en-us/windows/win32/wes/consuming-events). -### Command Line +### Command line -If you want to do a quick test, you can run this plugin from the command line. +If you want to do a test, you can run this plugin from the command line. ```bash -$ fluent-bit -i winevtlog -p 'channels=Setup' -p 'Read_Existing_Events=true' -o stdout +fluent-bit -i winevtlog -p 'channels=Setup' -p 'Read_Existing_Events=true' -o stdout ``` -Note that `winevtlog` plugin will tail channels on each startup. -If you want to confirm whether this plugin is working or not, you should specify `-p 'Read_Existing_Events=true'` parameter. +The `winevtlog` plugin will tail channels on each startup. +If you want to confirm whether this plugin is working or not, specify `-p 'Read_Existing_Events=true'` parameter. diff --git a/vale-styles/FluentBit/Acronyms.yml b/vale-styles/FluentBit/Acronyms.yml index d6eb84dcc..3fb8b0d54 100644 --- a/vale-styles/FluentBit/Acronyms.yml +++ b/vale-styles/FluentBit/Acronyms.yml @@ -9,6 +9,7 @@ second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' # ... with the exception of these: exceptions: - ACL + - ANSI - API - ARN - ASC From 4549f62aa22fa740716dba74df1e7be6bf05f73a Mon Sep 17 00:00:00 2001 From: Lynette Miles <6818907+esmerel@users.noreply.github.com> Date: Thu, 3 Jul 2025 10:34:59 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Craig Norris <112565517+cnorris-cs@users.noreply.github.com> Signed-off-by: Lynette Miles <6818907+esmerel@users.noreply.github.com> --- pipeline/inputs/windows-event-log-winevtlog.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pipeline/inputs/windows-event-log-winevtlog.md b/pipeline/inputs/windows-event-log-winevtlog.md index 7aea04394..d3ee34ecc 100644 --- a/pipeline/inputs/windows-event-log-winevtlog.md +++ b/pipeline/inputs/windows-event-log-winevtlog.md @@ -18,7 +18,7 @@ The plugin supports the following configuration parameters: | `Ignore_Missing_Channels` | Optional. Whether to ignore event channels not present in the event log, and continue running with subscribed channels. | `False` | | `Use_ANSI` | Optional. Use ANSI encoding on `eventlog` messages. If you have issues receiving blank strings with old Windows versions (Server 2012 R2), setting this to `True` might solve the problem. | `False` | | `Event_Query` | Specify XML query for filtering events. | `*` | -| `Read_Limit_Per_Cycle` | Specify read limit per cycle. | `512KiB` | +| `Read_Limit_Per_Cycle` | Specify read limit per cycle. | `512KiB` | | Threaded | Indicates whether to run this input in its own [thread](../../administration/multithreading.md#inputs). | `false` | | `Remote.Server` | Specify server name of remote access for Windows EventLog. | _none_ | | `Remote.Domain` | Specify domain name of remote access for Windows EventLog. | _none_ | @@ -80,11 +80,11 @@ For further details, refer to [Microsoft's documentation](https://learn.microsof ### Command line -If you want to do a test, you can run this plugin from the command line. +If you want to do a test, you can run this plugin from the command line: ```bash fluent-bit -i winevtlog -p 'channels=Setup' -p 'Read_Existing_Events=true' -o stdout ``` The `winevtlog` plugin will tail channels on each startup. -If you want to confirm whether this plugin is working or not, specify `-p 'Read_Existing_Events=true'` parameter. +If you want to confirm whether this plugin is working or not, specify the `-p 'Read_Existing_Events=true'` parameter.