Path Parse

Parse Security

Synopsis

Splits a file path — Windows or Unix — into an object of its component parts.

Schema

- path_parse:
    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:

Field	Required	Default	Description
`field`	Y	-	Field containing the path to parse
`description`	N	-	Explanatory note
`if`	N	-	Condition to run
`ignore_failure`	N	`false`	See Handling Failures
`ignore_missing`	N	`false`	If `true`, quietly exit if field doesn't exist
`on_failure`	N	-	See Handling Failures
`on_success`	N	-	See Handling Success
`tag`	N	-	Identifier
`disabled`	N	`false`	When `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_field`	N	`field`	Field to store the component object. Defaults to `field`, replacing the path string

Details

The result is always an object with all seven keys present. A component that does not apply is an empty string rather than being absent, so a downstream reference never has to test for existence.

Key	Contents
`Scheme`	Anything before `://`, empty for a plain path
`RootPath`	The drive specifier, such as `C:`. Empty on a Unix path
`DirectoryPath`	Everything before the final separator
`DirectoryName`	The last segment of `DirectoryPath` alone
`Filename`	The final segment, without any alternate data stream
`Extension`	Text after the last dot in `Filename`, without the dot
`AlternateDataStreamName`	The NTFS alternate data stream name, if one is present

The separator is detected, not configured. Whichever of \ or / occurs more often in the path wins, so mixed-separator paths — common in logs that have passed through more than one system — parse the way a reader would expect rather than requiring the source platform to be known in advance.

AlternateDataStreamName is the reason to reach for this processor on Windows telemetry. A colon after the first character of the filename separates an NTFS alternate data stream, so notepad.exe:evil.ps1 yields Filename: notepad.exe and AlternateDataStreamName: evil.ps1. Splitting on the separator alone would leave both stuck together in one value. The colon of a drive specifier is not mistaken for this, because a stream separator has to appear beyond the first character.

A leading dot does not make an extension: .bashrc has an empty Extension and is a filename in full.

Examples

A Windows Path

Splitting a full Windows path...

{
  "file": {"path": "C:\\Windows\\System32\\drivers\\etc\\hosts"}
}

- path_parse:
    field: file.path
    target_field: file.parts

with every component present:

{
  "file": {
    "path": "C:\\Windows\\System32\\drivers\\etc\\hosts",
    "parts": {
      "Scheme": "",
      "RootPath": "C:",
      "DirectoryPath": "C:\\Windows\\System32\\drivers\\etc",
      "DirectoryName": "etc",
      "Filename": "hosts",
      "Extension": "",
      "AlternateDataStreamName": ""
    }
  }
}

An Alternate Data Stream

A colon past the first character separates an NTFS stream...

{
  "file": {"path": "C:\\Users\\jsmith\\notepad.exe:evil.ps1"}
}

- path_parse:
    field: file.path
    target_field: file.parts

so the hidden stream lands in its own field:

{
  "file": {
    "path": "C:\\Users\\jsmith\\notepad.exe:evil.ps1",
    "parts": {
      "Scheme": "",
      "RootPath": "C:",
      "DirectoryPath": "C:\\Users\\jsmith",
      "DirectoryName": "jsmith",
      "Filename": "notepad.exe",
      "Extension": "exe",
      "AlternateDataStreamName": "evil.ps1"
    }
  }
}

A Unix Path

The separator is detected from the path itself...

{
  "file": {"path": "/var/log/nginx/access.log"}
}

- path_parse:
    field: file.path
    target_field: file.parts

with RootPath empty, since there is no drive:

{
  "file": {
    "path": "/var/log/nginx/access.log",
    "parts": {
      "Scheme": "",
      "RootPath": "",
      "DirectoryPath": "/var/log/nginx",
      "DirectoryName": "nginx",
      "Filename": "access.log",
      "Extension": "log",
      "AlternateDataStreamName": ""
    }
  }
}

A Path With a Scheme

Anything before :// is lifted into Scheme...

{
  "file": {"path": "smb://fileserver/share/report.xlsx"}
}

- path_parse:
    field: file.path
    target_field: file.parts

and the rest is parsed as an ordinary path:

{
  "file": {
    "path": "smb://fileserver/share/report.xlsx",
    "parts": {
      "Scheme": "smb",
      "RootPath": "",
      "DirectoryPath": "fileserver/share",
      "DirectoryName": "share",
      "Filename": "report.xlsx",
      "Extension": "xlsx",
      "AlternateDataStreamName": ""
    }
  }
}

Synopsis​

Schema​

Configuration​

Details​

Examples​

A Windows Path​

An Alternate Data Stream​

A Unix Path​

A Path With a Scheme​