Unix Permission

Parse Security

Synopsis

Extracts and decodes Unix file permission information.

Schema

- unix_permission:
    field: <ident>
    target_field: <string>
    format: <string>
    add_security_notes: <boolean>
    add_commands: <boolean>
    expand_special: <boolean>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Source field containing Unix permission data (string, int, or array of strings)
target_field	N	{field}_decoded	Target field to store decoded permission information
format	N	auto	Input format: auto, octal, symbolic, numeric
add_security_notes	N	false	Add security risk warnings for dangerous permissions
add_commands	N	false	Add chmod command examples to output
expand_special	N	false	Add detailed descriptions for special permission bits
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	Continue processing if decoding fails
ignore_missing	N	false	Skip processing if referenced 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

Details

Decodes Unix file permissions from various formats including octal notation (755), symbolic notation (rwxr-xr-x), and decimal values. The processor extracts owner, group, and other permissions along with special permission bits.

The processor supports automatic format detection through the format field set to auto, or explicit format specification using octal, symbolic, or numeric values. Auto-detection analyzes the input pattern to determine the appropriate format parser.

Unix permissions consist of three sets of three bits each: owner (user), group, and other. Each set contains read (r), write (w), and execute (x) permissions. Special bits include setuid, setgid, and sticky bit.

The decoded map always carries octal, decimal, symbolic, description, and a details map. The per-entity breakdowns live under details, not at the top level, and each of them carries five keys, not three:

{
  "octal": "755",
  "decimal": 493,
  "symbolic": "rwxr-xr-x",
  "description": "Owner full, others read/execute (standard for executables)",
  "details": {
    "owner": {"read": true, "write": true, "execute": true, "octal": 7, "symbolic": "rwx", "description": "owner can read, write, execute"},
    "group": {"read": true, "write": false, "execute": true, "octal": 5, "symbolic": "r-x", "description": "group can read, execute"},
    "other": {"read": true, "write": false, "execute": true, "octal": 5, "symbolic": "r-x", "description": "other can read, execute"}
  }
}

description is a lookup against a table of fifteen common modes; anything outside it gets a generated Custom permissions: Owner(...), Group(...), Other(...) string. The optional blocks add keys to the same map — special, security_risk, commands — rather than nesting under it.

When add_security_notes is enabled, the processor adds security_risk — a single string, not a list — together with the booleans world_readable, world_writable and world_executable. A setuid mode that is also world-writable additionally sets dangerous: true and danger_reason.

When add_commands is enabled, the processor adds a commands map with five fixed keys: set_numeric, set_symbolic, add_execute, remove_write and secure_private. All five use the literal filename file, and set_symbolic is built from the regular permission bits only — the special bits are not represented in it.

When expand_special is enabled, the special map gains setuid_desc, setgid_desc and sticky_desc alongside its three booleans. The special map itself is present whenever any special bit is set, with or without this option.

warning

If the input permission data is malformed or contains invalid permission values, the processor will fail unless ignore_failure is set to true.

Examples

Octal Permission Decoding

Decoding octal permission notation...

{ "file_mode": "755" } - unix_permission: field: file_mode target_field: permissions

extracts detailed permission breakdown:

{ "file_mode": "755", "permissions": { "octal": "755", "decimal": 493, "symbolic": "rwxr-xr-x", "description": "Owner full, others read/execute (standard for executables)", "details": { "owner": {"read": true, "write": true, "execute": true, "octal": 7, "symbolic": "rwx", "description": "owner can read, write, execute"}, "group": {"read": true, "write": false, "execute": true, "octal": 5, "symbolic": "r-x", "description": "group can read, execute"}, "other": {"read": true, "write": false, "execute": true, "octal": 5, "symbolic": "r-x", "description": "other can read, execute"} } } }

Symbolic Permission Input

Processing symbolic permission notation...

{ "file_perms": "rw-r--r--" } - unix_permission: field: file_perms format: symbolic target_field: perm_info

converts to detailed format:

{ "file_perms": "rw-r--r--", "perm_info": { "octal": "644", "decimal": 420, "symbolic": "rw-r--r--", "description": "Owner read/write, others read (standard for files)", "details": { "owner": {"read": true, "write": true, "execute": false, "octal": 6, "symbolic": "rw-", "description": "owner can read, write"}, "group": {"read": true, "write": false, "execute": false, "octal": 4, "symbolic": "r--", "description": "group can read"}, "other": {"read": true, "write": false, "execute": false, "octal": 4, "symbolic": "r--", "description": "other can read"} } } }

Special Permissions

Expanding special permission bits...

{ "exec_mode": "4755" } - unix_permission: field: exec_mode expand_special: true target_field: exec_perms

decodes setuid bit with descriptions:

{ "exec_mode": "4755", "exec_perms": { "octal": "4755", "decimal": 2541, "symbolic": "rwsr-xr-x", "description": "Setuid + standard executable permissions", "special": { "setuid": true, "setgid": false, "sticky": false, "setuid_desc": "Execute as file owner", "setgid_desc": "Execute with group privileges", "sticky_desc": "Only owner can delete in directory" }, "details": { "owner": {"read": true, "write": true, "execute": true, "octal": 7, "symbolic": "rwx", "description": "owner can read, write, execute"}, "group": {"read": true, "write": false, "execute": true, "octal": 5, "symbolic": "r-x", "description": "group can read, execute"}, "other": {"read": true, "write": false, "execute": true, "octal": 5, "symbolic": "r-x", "description": "other can read, execute"} } } }

Security Risk Analysis

Adding security warnings for dangerous permissions...

{ "file_mode": "777" } - unix_permission: field: file_mode add_security_notes: true target_field: perms

includes security risk warnings:

{ "file_mode": "777", "perms": { "octal": "777", "decimal": 511, "symbolic": "rwxrwxrwx", "description": "Full access for everyone (INSECURE!)", "security_risk": "CRITICAL: World-writable - anyone can modify/delete", "world_readable": true, "world_writable": true, "world_executable": true, "details": { "owner": {"read": true, "write": true, "execute": true, "octal": 7, "symbolic": "rwx", "description": "owner can read, write, execute"}, "group": {"read": true, "write": true, "execute": true, "octal": 7, "symbolic": "rwx", "description": "group can read, write, execute"}, "other": {"read": true, "write": true, "execute": true, "octal": 7, "symbolic": "rwx", "description": "other can read, write, execute"} } } }

Command Generation

Generating chmod commands...

{ "dir_mode": "2775" } - unix_permission: field: dir_mode add_commands: true target_field: dir_perms

includes ready-to-use chmod commands:

{ "dir_mode": "2775", "dir_perms": { "octal": "2775", "decimal": 1533, "symbolic": "rwxrwsr-x", "description": "Custom permissions: Owner(full), Group(full), Other(rx)", "special": {"setuid": false, "setgid": true, "sticky": false}, "details": { "owner": {"read": true, "write": true, "execute": true, "octal": 7, "symbolic": "rwx", "description": "owner can read, write, execute"}, "group": {"read": true, "write": true, "execute": true, "octal": 7, "symbolic": "rwx", "description": "group can read, write, execute"}, "other": {"read": true, "write": false, "execute": true, "octal": 5, "symbolic": "r-x", "description": "other can read, execute"} }, "commands": { "set_numeric": "chmod 2775 file", "set_symbolic": "chmod u=rwx,g=rwx,o=rx file", "add_execute": "chmod +x file", "remove_write": "chmod -w file", "secure_private": "chmod 600 file" } } }