Add comprehensive documentation for system information security configuration

Co-authored-by: mountaindude <1029262+mountaindude@users.noreply.github.com>
2025-12-19 17:58:18 -05:00 · 2025-07-24 20:20:10 +00:00
parent 657539452c
commit a05b3a68d9
6 changed files with 1106 additions and 633 deletions
--- a/docs/system-information-security.md
+++ b/docs/system-information-security.md
@@ -0,0 +1,140 @@
+# System Information and OS Command Execution
+
+## Overview
+
+Butler SOS collects system information for monitoring and diagnostic purposes. This information helps with troubleshooting, resource monitoring, and identifying system characteristics. However, on Windows systems, this may trigger security alerts in enterprise environments due to OS command execution.
+
+## Root Cause
+
+Butler SOS uses the [systeminformation](https://www.npmjs.com/package/systeminformation) npm package to gather detailed system information. On Windows, this package internally executes several OS commands to collect system details:
+
+- `cmd.exe /d /s /c \chcp` - Gets code page information
+- `netstat -r` - Gets routing table information  
+- `cmd.exe /d /s /c \echo %COMPUTERNAME%.%USERDNSDOMAIN%` - Gets computer name and domain
+
+These commands are **not executed directly by Butler SOS** but by the systeminformation package dependency. The commands are legitimate system information gathering commands, but they may trigger alerts in security monitoring tools.
+
+## Code Location
+
+The system information gathering occurs in the `initHostInfo()` function in `src/globals.js` (lines 1027-1085), which is called during Butler SOS startup from `src/butler-sos.js`.
+
+## Security Configuration
+
+Starting with version 11.1.0, Butler SOS provides a configuration option to disable detailed system information gathering for security-sensitive environments.
+
+### Configuration Option
+
+Add this section to your Butler SOS configuration file:
+
+```yaml
+Butler-SOS:
+  # System information gathering
+  # Butler SOS collects system information for monitoring and diagnostic purposes.
+  # On Windows, this may trigger security alerts as it executes OS commands like:
+  # - cmd.exe /d /s /c \chcp (to get code page info)
+  # - netstat -r (to get routing table)  
+  # - cmd.exe /d /s /c \echo %COMPUTERNAME%.%USERDNSDOMAIN% (to get computer/domain names)
+  # These commands are executed by the 'systeminformation' npm package, not directly by Butler SOS.
+  systemInfo:
+    enable: true    # Set to false in security-sensitive environments
+```
+
+### When to Disable System Information
+
+Consider setting `systemInfo.enable: false` if:
+
+- Your security monitoring tools flag the OS command execution as suspicious
+- Your organization has strict policies against any automated OS command execution
+- You don't need detailed system information in logs and monitoring outputs
+- Butler SOS runs in a highly secured environment
+
+### Impact of Disabling System Information
+
+When `systemInfo.enable` is set to `false`:
+
+**✅ Benefits:**
+- No OS commands are executed by the systeminformation package
+- Eliminates security alerts from monitoring tools
+- Butler SOS continues to function normally
+- Basic system information is still collected using Node.js built-in APIs
+
+**⚠️ Limitations:**
+- Reduced detail in system information logs
+- Some monitoring dashboards may show less detailed host information
+- Telemetry data will contain minimal system details
+
+**What's Still Collected:**
+- Node.js version and platform information
+- Basic OS platform, architecture, and version
+- Memory and CPU count from Node.js APIs
+- Application version and instance ID
+
+**What's Not Collected:**
+- Detailed CPU model and specifications
+- Detailed OS distribution information
+- Network interface details
+- Docker information
+- Detailed memory specifications
+
+## Example Configuration Files
+
+### High Security Environment
+```yaml
+Butler-SOS:
+  systemInfo:
+    enable: false  # Disable to prevent OS command execution
+  # ... rest of configuration
+```
+
+### Standard Environment
+```yaml
+Butler-SOS:
+  systemInfo:
+    enable: true   # Default - enables full system information gathering
+  # ... rest of configuration
+```
+
+## Testing the Configuration
+
+To test that the configuration is working correctly:
+
+1. Set `systemInfo.enable: false` in your config
+2. Start Butler SOS
+3. Check the logs for: `"SYSTEM INFO: Detailed system information gathering is disabled. Using minimal system info."`
+4. Verify that your security monitoring tools no longer flag the OS command execution
+
+## Troubleshooting
+
+### Configuration Validation Errors
+
+If you see configuration validation errors related to `systemInfo`:
+
+1. Ensure the `systemInfo` section is properly nested under `Butler-SOS`
+2. Verify that `enable` is set to a boolean value (`true` or `false`), not a string
+3. Check YAML indentation is correct
+
+### Missing System Information
+
+If you need some system information but want to minimize OS command execution:
+
+1. Consider using `systemInfo.enable: true` but monitor which specific commands trigger alerts
+2. Work with your security team to whitelist the specific systeminformation package commands
+3. Use Butler SOS logging to capture the minimal system information that's still collected
+
+## Security Best Practices
+
+1. **Principle of Least Privilege**: Only enable detailed system information gathering if you need it for your monitoring use case
+2. **Security Monitoring**: Work with your security team to understand which specific commands trigger alerts
+3. **Documentation**: Document your `systemInfo.enable` setting choice in your deployment documentation
+4. **Testing**: Test configuration changes in a development environment first
+5. **Monitoring**: Monitor Butler SOS logs to ensure it's working correctly with your chosen configuration
+
+## Related Issues
+
+- [Issue #1037](https://github.com/ptarmiganlabs/butler-sos/issues/1037) - Original investigation of OS command execution
+- [systeminformation package documentation](https://github.com/sebhildebrandt/systeminformation) - For understanding what information is collected
+
+## Version History
+
+- **11.1.0**: Added `systemInfo.enable` configuration option
+- **11.0.3**: Initial report of OS command execution alerts
--- a/src/globals.js
+++ b/src/globals.js
@@ -1057,7 +1057,9 @@ class Settings {
                siNetworkDefault = await si.networkInterfaceDefault();
            } else {
                // If detailed system info is disabled, use minimal fallback values
-                this.logger.info('SYSTEM INFO: Detailed system information gathering is disabled. Using minimal system info.');
+                this.logger.info(
+                    'SYSTEM INFO: Detailed system information gathering is disabled. Using minimal system info.'
+                );
                siSystem = { uuid: 'disabled' };
                siMem = { total: 0 };
                siOS = {
@@ -1065,19 +1067,21 @@ class Settings {
                    arch: os.arch(),
                    release: 'unknown',
                    distro: 'unknown',
-                    codename: 'unknown'
+                    codename: 'unknown',
                };
                siCPU = {
                    processors: 1,
                    physicalCores: 1,
                    cores: 1,
-                    hypervizor: 'unknown'
+                    hypervizor: 'unknown',
                };
-                siNetwork = [{
+                siNetwork = [
+                    {
                        iface: 'default',
                        mac: '00:00:00:00:00:00',
-                    ip4: '127.0.0.1'
-                }];
+                        ip4: '127.0.0.1',
+                    },
+                ];
                siNetworkDefault = 'default';
            }

@@ -1088,9 +1092,12 @@ class Settings {
            );

            // Ensure we have at least one network interface for ID generation
-            const netIface = networkInterface.length > 0 ? networkInterface[0] : siNetwork[0] || {
+            const netIface =
+                networkInterface.length > 0
+                    ? networkInterface[0]
+                    : siNetwork[0] || {
                          mac: '00:00:00:00:00:00',
-                ip4: '127.0.0.1'
+                          ip4: '127.0.0.1',
                      };

            const idSrc = netIface.mac + netIface.ip4 + siSystem.uuid;
--- a/src/lib/tests/system-info.test.js
+++ b/src/lib/tests/system-info.test.js
@@ -18,15 +18,15 @@ describe('System Information Configuration Schema', () => {
        const systemInfoSchema = {
            type: 'object',
            properties: {
-                systemInfo: confifgFileSchema.properties['Butler-SOS'].properties.systemInfo
+                systemInfo: confifgFileSchema.properties['Butler-SOS'].properties.systemInfo,
            },
-            required: ['systemInfo']
+            required: ['systemInfo'],
        };

        const config = {
            systemInfo: {
-                enable: false
-            }
+                enable: false,
+            },
        };

        const validate = ajv.compile(systemInfoSchema);
@@ -44,15 +44,15 @@ describe('System Information Configuration Schema', () => {
        const systemInfoSchema = {
            type: 'object',
            properties: {
-                systemInfo: confifgFileSchema.properties['Butler-SOS'].properties.systemInfo
+                systemInfo: confifgFileSchema.properties['Butler-SOS'].properties.systemInfo,
            },
-            required: ['systemInfo']
+            required: ['systemInfo'],
        };

        const config = {
            systemInfo: {
-                enable: true
-            }
+                enable: true,
+            },
        };

        const validate = ajv.compile(systemInfoSchema);
@@ -66,15 +66,15 @@ describe('System Information Configuration Schema', () => {
        const systemInfoSchema = {
            type: 'object',
            properties: {
-                systemInfo: confifgFileSchema.properties['Butler-SOS'].properties.systemInfo
+                systemInfo: confifgFileSchema.properties['Butler-SOS'].properties.systemInfo,
            },
-            required: ['systemInfo']
+            required: ['systemInfo'],
        };

        const config = {
            systemInfo: {
-                enable: 'not-a-boolean'
-            }
+                enable: 'not-a-boolean',
+            },
        };

        const validate = ajv.compile(systemInfoSchema);
@@ -83,8 +83,8 @@ describe('System Information Configuration Schema', () => {
        expect(isValid).toBe(false);
        expect(validate.errors).toContainEqual(
            expect.objectContaining({
-                instancePath: "/systemInfo/enable",
-                keyword: "type"
+                instancePath: '/systemInfo/enable',
+                keyword: 'type',
            })
        );
    });
@@ -94,13 +94,13 @@ describe('System Information Configuration Schema', () => {
        const systemInfoSchema = {
            type: 'object',
            properties: {
-                systemInfo: confifgFileSchema.properties['Butler-SOS'].properties.systemInfo
+                systemInfo: confifgFileSchema.properties['Butler-SOS'].properties.systemInfo,
            },
-            required: ['systemInfo']
+            required: ['systemInfo'],
        };

        const config = {
-            systemInfo: {}
+            systemInfo: {},
        };

        const validate = ajv.compile(systemInfoSchema);
@@ -109,8 +109,8 @@ describe('System Information Configuration Schema', () => {
        expect(isValid).toBe(false);
        expect(validate.errors).toContainEqual(
            expect.objectContaining({
-                instancePath: "/systemInfo",
-                keyword: "required"
+                instancePath: '/systemInfo',
+                keyword: 'required',
            })
        );
    });
--- a/static/configvis/jsontree.js
+++ b/static/configvis/jsontree.js
--- a/static/configvis/jsontree.js.css
+++ b/static/configvis/jsontree.js.css
@@ -5,45 +5,36 @@
 * Released under the MIT License
 */
 :root {
-  --json-tree-js-default-font: system-ui,
-                               -apple-system,
-                               "Segoe UI",
-                               Roboto,
-                               "Helvetica Neue",
-                               "Noto Sans",
-                               "Liberation Sans",
-                               Arial,
-                               sans-serif,
-                               "Apple Color Emoji",
-                               "Segoe UI Emoji",
-                               "Segoe UI Symbol",
-                               "Noto Color Emoji";
+    --json-tree-js-default-font:
+        system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', 'Noto Sans',
+        'Liberation Sans', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
+        'Segoe UI Symbol', 'Noto Color Emoji';
    --json-tree-js-text-bold-weight: 400;
    --json-tree-js-header-bold-weight: 900;
    --json-tree-js-title-bold-weight: var(--json-tree-js-header-bold-weight);
    --json-tree-js-text-bold-weight-active: var(--json-tree-js-header-bold-weight);
    --json-tree-js-color-dark-black: #1c2128;
    --json-tree-js-color-black: #3b3a3a;
-  --json-tree-js-color-white: #F5F5F5;
-  --json-tree-js-color-snow-white: #F5F5F5;
-  --json-tree-js-color-light-gray: #BBBBBB;
-  --json-tree-js-color-array: #F28C28;
-  --json-tree-js-color-object: #C0C0C0;
-  --json-tree-js-color-map: #BDB5D5;
-  --json-tree-js-color-set: #FFD700;
-  --json-tree-js-color-boolean: #FF0000;
+    --json-tree-js-color-white: #f5f5f5;
+    --json-tree-js-color-snow-white: #f5f5f5;
+    --json-tree-js-color-light-gray: #bbbbbb;
+    --json-tree-js-color-array: #f28c28;
+    --json-tree-js-color-object: #c0c0c0;
+    --json-tree-js-color-map: #bdb5d5;
+    --json-tree-js-color-set: #ffd700;
+    --json-tree-js-color-boolean: #ff0000;
    --json-tree-js-color-decimal: #e3c868;
    --json-tree-js-color-number: #666bf9;
-  --json-tree-js-color-bigint: #6495ED;
+    --json-tree-js-color-bigint: #6495ed;
    --json-tree-js-color-string: #78b13f;
    --json-tree-js-color-date: #a656f5;
    --json-tree-js-color-null: var(--json-tree-js-color-light-gray);
    --json-tree-js-color-undefined: var(--json-tree-js-color-null);
-  --json-tree-js-color-symbol: #DAA06D;
+    --json-tree-js-color-symbol: #daa06d;
    --json-tree-js-color-function: var(--json-tree-js-color-null);
    --json-tree-js-color-unknown: var(--json-tree-js-color-null);
    --json-tree-js-color-guid: #c45600;
-  --json-tree-js-color-regexp: #AA336A;
+    --json-tree-js-color-regexp: #aa336a;
    --json-tree-js-editable-text-color: var(--json-tree-js-color-snow-white);
    --json-tree-js-editable-background-color: #2d333b;
    --json-tree-js-editable-border-color: #454c56;
@@ -64,7 +55,7 @@
    --json-tree-js-border-size: 0.5px;
    --json-tree-js-spacing: 10px;
    --json-tree-js-spacing-font-size: 0.85rem;
-  --json-tree-js-transition: all .3s;
+    --json-tree-js-transition: all 0.3s;
    --json-tree-js-animation-length: 0.5s;
 }

@@ -109,7 +100,8 @@ div.json-tree-js * {
    box-sizing: border-box;
    line-height: normal;
 }
-div.json-tree-js *::before, div.json-tree-js *::after {
+div.json-tree-js *::before,
+div.json-tree-js *::after {
    box-sizing: border-box;
    line-height: normal;
 }
@@ -358,8 +350,14 @@ div.json-tree-js div.object-type-contents div.object-type-value span.main-title
    transition: var(--json-tree-js-transition);
    transition-property: opacity;
 }
-div.json-tree-js div.object-type-contents div.object-type-value span.value:not(.no-hover):not(.editable):hover,
-div.json-tree-js div.object-type-contents div.object-type-value span.main-title:not(.no-hover):not(.editable):hover {
+div.json-tree-js
+    div.object-type-contents
+    div.object-type-value
+    span.value:not(.no-hover):not(.editable):hover,
+div.json-tree-js
+    div.object-type-contents
+    div.object-type-value
+    span.main-title:not(.no-hover):not(.editable):hover {
    cursor: pointer;
    opacity: 0.7;
 }
--- a/static/configvis/prism.css
+++ b/static/configvis/prism.css
@@ -1,4 +1,174 @@
 /* PrismJS 1.30.0
 https://prismjs.com/download.html#themes=prism-twilight&languages=markup+yaml&plugins=line-numbers */
-code[class*=language-],pre[class*=language-]{color:#fff;background:0 0;font-family:Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace;font-size:1em;text-align:left;text-shadow:0 -.1em .2em #000;white-space:pre;word-spacing:normal;word-break:normal;word-wrap:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none}:not(pre)>code[class*=language-],pre[class*=language-]{background:#141414}pre[class*=language-]{border-radius:.5em;border:.3em solid #545454;box-shadow:1px 1px .5em #000 inset;margin:.5em 0;overflow:auto;padding:1em}pre[class*=language-]::-moz-selection{background:#27292a}pre[class*=language-]::selection{background:#27292a}code[class*=language-] ::-moz-selection,code[class*=language-]::-moz-selection,pre[class*=language-] ::-moz-selection,pre[class*=language-]::-moz-selection{text-shadow:none;background:hsla(0,0%,93%,.15)}code[class*=language-] ::selection,code[class*=language-]::selection,pre[class*=language-] ::selection,pre[class*=language-]::selection{text-shadow:none;background:hsla(0,0%,93%,.15)}:not(pre)>code[class*=language-]{border-radius:.3em;border:.13em solid #545454;box-shadow:1px 1px .3em -.1em #000 inset;padding:.15em .2em .05em;white-space:normal}.token.cdata,.token.comment,.token.doctype,.token.prolog{color:#777}.token.punctuation{opacity:.7}.token.namespace{opacity:.7}.token.boolean,.token.deleted,.token.number,.token.tag{color:#ce6849}.token.builtin,.token.constant,.token.keyword,.token.property,.token.selector,.token.symbol{color:#f9ed99}.language-css .token.string,.style .token.string,.token.attr-name,.token.attr-value,.token.char,.token.entity,.token.inserted,.token.operator,.token.string,.token.url,.token.variable{color:#909e6a}.token.atrule{color:#7385a5}.token.important,.token.regex{color:#e8c062}.token.bold,.token.important{font-weight:700}.token.italic{font-style:italic}.token.entity{cursor:help}.language-markup .token.attr-name,.language-markup .token.punctuation,.language-markup .token.tag{color:#ac885c}.token{position:relative;z-index:1}.line-highlight.line-highlight{background:hsla(0,0%,33%,.25);background:linear-gradient(to right,hsla(0,0%,33%,.1) 70%,hsla(0,0%,33%,0));border-bottom:1px dashed #545454;border-top:1px dashed #545454;margin-top:.75em;z-index:0}.line-highlight.line-highlight:before,.line-highlight.line-highlight[data-end]:after{background-color:#8693a6;color:#f4f1ef}
-pre[class*=language-].line-numbers{position:relative;padding-left:3.8em;counter-reset:linenumber}pre[class*=language-].line-numbers>code{position:relative;white-space:inherit}.line-numbers .line-numbers-rows{position:absolute;pointer-events:none;top:0;font-size:100%;left:-3.8em;width:3em;letter-spacing:-1px;border-right:1px solid #999;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.line-numbers-rows>span{display:block;counter-increment:linenumber}.line-numbers-rows>span:before{content:counter(linenumber);color:#999;display:block;padding-right:.8em;text-align:right}
+code[class*='language-'],
+pre[class*='language-'] {
+    color: #fff;
+    background: 0 0;
+    font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
+    font-size: 1em;
+    text-align: left;
+    text-shadow: 0 -0.1em 0.2em #000;
+    white-space: pre;
+    word-spacing: normal;
+    word-break: normal;
+    word-wrap: normal;
+    line-height: 1.5;
+    -moz-tab-size: 4;
+    -o-tab-size: 4;
+    tab-size: 4;
+    -webkit-hyphens: none;
+    -moz-hyphens: none;
+    -ms-hyphens: none;
+    hyphens: none;
+}
+:not(pre) > code[class*='language-'],
+pre[class*='language-'] {
+    background: #141414;
+}
+pre[class*='language-'] {
+    border-radius: 0.5em;
+    border: 0.3em solid #545454;
+    box-shadow: 1px 1px 0.5em #000 inset;
+    margin: 0.5em 0;
+    overflow: auto;
+    padding: 1em;
+}
+pre[class*='language-']::-moz-selection {
+    background: #27292a;
+}
+pre[class*='language-']::selection {
+    background: #27292a;
+}
+code[class*='language-'] ::-moz-selection,
+code[class*='language-']::-moz-selection,
+pre[class*='language-'] ::-moz-selection,
+pre[class*='language-']::-moz-selection {
+    text-shadow: none;
+    background: hsla(0, 0%, 93%, 0.15);
+}
+code[class*='language-'] ::selection,
+code[class*='language-']::selection,
+pre[class*='language-'] ::selection,
+pre[class*='language-']::selection {
+    text-shadow: none;
+    background: hsla(0, 0%, 93%, 0.15);
+}
+:not(pre) > code[class*='language-'] {
+    border-radius: 0.3em;
+    border: 0.13em solid #545454;
+    box-shadow: 1px 1px 0.3em -0.1em #000 inset;
+    padding: 0.15em 0.2em 0.05em;
+    white-space: normal;
+}
+.token.cdata,
+.token.comment,
+.token.doctype,
+.token.prolog {
+    color: #777;
+}
+.token.punctuation {
+    opacity: 0.7;
+}
+.token.namespace {
+    opacity: 0.7;
+}
+.token.boolean,
+.token.deleted,
+.token.number,
+.token.tag {
+    color: #ce6849;
+}
+.token.builtin,
+.token.constant,
+.token.keyword,
+.token.property,
+.token.selector,
+.token.symbol {
+    color: #f9ed99;
+}
+.language-css .token.string,
+.style .token.string,
+.token.attr-name,
+.token.attr-value,
+.token.char,
+.token.entity,
+.token.inserted,
+.token.operator,
+.token.string,
+.token.url,
+.token.variable {
+    color: #909e6a;
+}
+.token.atrule {
+    color: #7385a5;
+}
+.token.important,
+.token.regex {
+    color: #e8c062;
+}
+.token.bold,
+.token.important {
+    font-weight: 700;
+}
+.token.italic {
+    font-style: italic;
+}
+.token.entity {
+    cursor: help;
+}
+.language-markup .token.attr-name,
+.language-markup .token.punctuation,
+.language-markup .token.tag {
+    color: #ac885c;
+}
+.token {
+    position: relative;
+    z-index: 1;
+}
+.line-highlight.line-highlight {
+    background: hsla(0, 0%, 33%, 0.25);
+    background: linear-gradient(to right, hsla(0, 0%, 33%, 0.1) 70%, hsla(0, 0%, 33%, 0));
+    border-bottom: 1px dashed #545454;
+    border-top: 1px dashed #545454;
+    margin-top: 0.75em;
+    z-index: 0;
+}
+.line-highlight.line-highlight:before,
+.line-highlight.line-highlight[data-end]:after {
+    background-color: #8693a6;
+    color: #f4f1ef;
+}
+pre[class*='language-'].line-numbers {
+    position: relative;
+    padding-left: 3.8em;
+    counter-reset: linenumber;
+}
+pre[class*='language-'].line-numbers > code {
+    position: relative;
+    white-space: inherit;
+}
+.line-numbers .line-numbers-rows {
+    position: absolute;
+    pointer-events: none;
+    top: 0;
+    font-size: 100%;
+    left: -3.8em;
+    width: 3em;
+    letter-spacing: -1px;
+    border-right: 1px solid #999;
+    -webkit-user-select: none;
+    -moz-user-select: none;
+    -ms-user-select: none;
+    user-select: none;
+}
+.line-numbers-rows > span {
+    display: block;
+    counter-increment: linenumber;
+}
+.line-numbers-rows > span:before {
+    content: counter(linenumber);
+    color: #999;
+    display: block;
+    padding-right: 0.8em;
+    text-align: right;
+}