Skip to main content

Command Line

Parse Security

Synopsis​

Splits a command line string into its argument array, using the Windows quoting rules that CommandLineToArgvW applies.

Schema​

- command_line:
    field: <ident>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>
    target_field: <ident>

Configuration​

The following fields are used to define the processor:

FieldRequiredDefaultDescription
fieldY-Field containing the command line string
descriptionN-Explanatory note
ifN-Condition to run
ignore_failureNfalseSee Handling Failures
ignore_missingNfalseIf true, quietly exit if field doesn't exist
on_failureN-See Handling Failures
on_successN-See Handling Success
tagN-Identifier
disabledNfalseWhen true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration
target_fieldNfieldField to store the argument array. Defaults to field, replacing the command line string

Details​

These are the Windows rules, not shell rules, and the difference matters when reading process-creation telemetry. A backslash is only an escape character when it precedes a quote; elsewhere it is an ordinary character, which is why a Windows path such as C:\Windows\System32 survives unescaped. Two backslashes before a quote produce one literal backslash and leave the quote as a delimiter.

Splitting on whitespace with a regular expression gets this wrong on exactly the arguments an analyst cares about — quoted paths containing spaces, and arguments whose values are themselves quoted.

The result is an array of strings, with the executable as element 0, so an argument can be referenced by position downstream.

The field must hold a string. Anything else is an error.

note

target_field defaults to field, which replaces the command line string with the array. Set it explicitly to keep the original text, which is usually what a detection rule matches on.

Examples​

Quoted Paths​

Splitting a command line whose path contains spaces...

{
  "process": {
    "command_line": "\"C:\\Program Files\\App\\app.exe\" --config \"C:\\ProgramData\\app\\cfg.yml\" --verbose"
  }
}
- command_line:
    field: process.command_line
    target_field: process.args

keeping each quoted path as one argument:

{
  "process": {
    "command_line": "\"C:\\Program Files\\App\\app.exe\" --config \"C:\\ProgramData\\app\\cfg.yml\" --verbose",
    "args": [
      "C:\\Program Files\\App\\app.exe",
      "--config",
      "C:\\ProgramData\\app\\cfg.yml",
      "--verbose"
    ]
  }
}

Extracting the Executable​

The executable is always element 0...

{
  "process": {
    "command_line": "powershell.exe -EncodedCommand SQBFAFgA"
  }
}
- command_line:
    field: process.command_line
    target_field: process.args
- set:
    field: process.executable
    copy_from: process.args.0

so it can be lifted into its own field:

{
  "process": {
    "command_line": "powershell.exe -EncodedCommand SQBFAFgA",
    "args": ["powershell.exe", "-EncodedCommand", "SQBFAFgA"],
    "executable": "powershell.exe"
  }
}

Backslashes Before Quotes​

A backslash escapes only a quote, so paths stay readable...

{
  "cmd": "tool.exe --path \"C:\\data\\\\\" --flag"
}
- command_line:
    field: cmd
    target_field: cmd_args

with the doubled backslash collapsing to one and the quote closing the argument:

{
  "cmd": "tool.exe --path \"C:\\data\\\\\" --flag",
  "cmd_args": ["tool.exe", "--path", "C:\\data\\", "--flag"]
}