From b780f480e73ffc2d1da117689475b7b9c8af610b Mon Sep 17 00:00:00 2001 From: Alexandra Konrad Date: Mon, 23 Sep 2024 17:13:35 +0200 Subject: [PATCH] Add remaining ECS attributes for file namespace (#914) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/file_leftovers.yaml | 22 +++++++ docs/attributes-registry/file.md | 44 +++++++++++--- model/file/registry.yaml | 100 +++++++++++++++++++++++++++++++ 3 files changed, 157 insertions(+), 9 deletions(-) create mode 100755 .chloggen/file_leftovers.yaml diff --git a/.chloggen/file_leftovers.yaml b/.chloggen/file_leftovers.yaml new file mode 100755 index 0000000000..099d6d9e3c --- /dev/null +++ b/.chloggen/file_leftovers.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: file + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add additional attributes from ECS to the `file` namespace. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [914] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/file.md b/docs/attributes-registry/file.md index eb9a4140dc..b8cfc67b22 100644 --- a/docs/attributes-registry/file.md +++ b/docs/attributes-registry/file.md @@ -10,12 +10,38 @@ Describes file attributes. -| Attribute | Type | Description | Examples | Stability | -| ---------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- | -| `file.directory` | string | Directory where the file is located. It should include the drive letter, when appropriate. | `/home/user`; `C:\Program Files\MyApp` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `file.extension` | string | File extension, excluding the leading dot. [1] | `png`; `gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `file.name` | string | Name of the file including the extension, without the directory. | `example.png` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `file.path` | string | Full path to the file, including the file name. It should include the drive letter, when appropriate. | `/home/alice/example.png`; `C:\Program Files\MyApp\myapp.exe` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `file.size` | int | File size in bytes. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). +| Attribute | Type | Description | Examples | Stability | +| -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- | +| `file.accessed` | string | Time when the file was last accessed, in ISO 8601 format. [1] | `2021-01-01T12:00:00Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.attributes` | string[] | Array of file attributes. [2] | `["readonly", "hidden"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.changed` | string | Time when the file attributes or metadata was last changed, in ISO 8601 format. [3] | `2021-01-01T12:00:00Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.created` | string | Time when the file was created, in ISO 8601 format. [4] | `2021-01-01T12:00:00Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.directory` | string | Directory where the file is located. It should include the drive letter, when appropriate. | `/home/user`; `C:\Program Files\MyApp` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.extension` | string | File extension, excluding the leading dot. [5] | `png`; `gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.fork_name` | string | Name of the fork. A fork is additional data associated with a filesystem object. [6] | `Zone.Identifer` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.group.id` | string | Primary Group ID (GID) of the file. | `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.group.name` | string | Primary group name of the file. | `users` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.inode` | string | Inode representing the file in the filesystem. | `256383` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.mode` | string | Mode of the file in octal representation. | `0640` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.modified` | string | Time when the file content was last modified, in ISO 8601 format. | `2021-01-01T12:00:00Z` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.name` | string | Name of the file including the extension, without the directory. | `example.png` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.owner.id` | string | The user ID (UID) or security identifier (SID) of the file owner. | `1000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.owner.name` | string | Username of the file owner. | `root` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.path` | string | Full path to the file, including the file name. It should include the drive letter, when appropriate. | `/home/alice/example.png`; `C:\Program Files\MyApp\myapp.exe` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.size` | int | File size in bytes. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `file.symbolic_link.target_path` | string | Path to the target of a symbolic link. [7] | `/usr/bin/python3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc. + +**[2]:** Attributes names depend on the OS or file system. Here’s a non-exhaustive list of values expected for this attribute: `archive`, `compressed`, `directory`, `encrypted`, `execute`, `hidden`, `immutable`, `journaled`, `read`, `readonly`, `symbolic link`, `system`, `temporary`, `write`. + +**[3]:** `file.changed` captures the time when any of the file's properties or attributes (including the content) are changed, while `file.modified` captures the timestamp when the file content is modified. + +**[4]:** This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc. + +**[5]:** When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). + +**[6]:** On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at least one fork for the data portion, and additional forks may exist. +On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet. An ADS is typically of the form: C:\path\to\filename.extension:some_fork_name, and some_fork_name is the value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension` should populate `file.extension`. The full path, `file.path`, will include the fork name. + +**[7]:** This attribute is only applicable to symbolic links. diff --git a/model/file/registry.yaml b/model/file/registry.yaml index 742f95afee..49049cdd6c 100644 --- a/model/file/registry.yaml +++ b/model/file/registry.yaml @@ -4,6 +4,41 @@ groups: display_name: File Attributes brief: "Describes file attributes." attributes: + - id: file.accessed + type: string + brief: > + Time when the file was last accessed, in ISO 8601 format. + note: > + This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc. + stability: experimental + examples: ['2021-01-01T12:00:00Z'] + - id: file.attributes + type: string[] + brief: > + Array of file attributes. + note: > + Attributes names depend on the OS or file system. Here’s a non-exhaustive list of values expected for this + attribute: `archive`, `compressed`, `directory`, `encrypted`, `execute`, `hidden`, `immutable`, `journaled`, `read`, `readonly`, `symbolic link`, `system`, `temporary`, `write`. + stability: experimental + examples: ['readonly', 'hidden'] + - id: file.created + type: string + brief: > + Time when the file was created, in ISO 8601 format. + note: > + This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc. + stability: experimental + examples: ['2021-01-01T12:00:00Z'] + - id: file.changed + type: string + brief: > + Time when the file attributes or metadata was last changed, in ISO 8601 format. + note: > + `file.changed` captures the time when any of the file's properties or attributes + (including the content) are changed, while `file.modified` captures the timestamp + when the file content is modified. + stability: experimental + examples: ['2021-01-01T12:00:00Z'] - id: file.directory type: string brief: > @@ -19,12 +54,69 @@ groups: note: > When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz"). + - id: file.fork_name + type: string + brief: > + Name of the fork. A fork is additional data associated with a filesystem object. + note: > + On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at + least one fork for the data portion, and additional forks may exist. + + On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is + just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet. + An ADS is typically of the form: C:\path\to\filename.extension:some_fork_name, and some_fork_name is the + value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension` + should populate `file.extension`. The full path, `file.path`, will include the fork name. + stability: experimental + examples: ['Zone.Identifer'] + - id: file.group.id + type: string + brief: > + Primary Group ID (GID) of the file. + stability: experimental + examples: ["1000"] + - id: file.group.name + type: string + brief: > + Primary group name of the file. + stability: experimental + examples: ['users'] + - id: file.inode + type: string + brief: > + Inode representing the file in the filesystem. + stability: experimental + examples: ['256383'] + - id: file.mode + type: string + brief: > + Mode of the file in octal representation. + stability: experimental + examples: ['0640'] + - id: file.modified + type: string + brief: > + Time when the file content was last modified, in ISO 8601 format. + stability: experimental + examples: ['2021-01-01T12:00:00Z'] - id: file.name type: string brief: > Name of the file including the extension, without the directory. stability: experimental examples: ['example.png'] + - id: file.owner.id + type: string + brief: > + The user ID (UID) or security identifier (SID) of the file owner. + stability: experimental + examples: ["1000"] + - id: file.owner.name + type: string + brief: > + Username of the file owner. + stability: experimental + examples: ['root'] - id: file.path type: string brief: > @@ -36,3 +128,11 @@ groups: brief: > File size in bytes. stability: experimental + - id: file.symbolic_link.target_path + type: string + brief: > + Path to the target of a symbolic link. + note: > + This attribute is only applicable to symbolic links. + stability: experimental + examples: ['/usr/bin/python3']