Skip to content

Commit

Permalink
Add remaining ECS attributes for file namespace (#914)
Browse files Browse the repository at this point in the history 
Co-authored-by: Joao Grassi <[email protected]>
  • Loading branch information
@trisch-me @joaopgrassi
trisch-me and joaopgrassi authored Sep 23, 2024
1 parent ee435c0 commit b780f48
Show file tree
Hide file tree
Showing 3 changed files with 157 additions and 9 deletions.
22 changes: 22 additions & 0 deletions .chloggen/file_leftovers.yaml
View file
Original file line number Diff line number Diff line change
@@ -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:
44 changes: 35 additions & 9 deletions docs/attributes-registry/file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
100 changes: 100 additions & 0 deletions model/file/registry.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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: >
Expand All @@ -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: >
Expand All @@ -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']

0 comments on commit b780f48

Please sign in to comment.