Configuration

owLSM has a single config file which controls every aspect of its behavior.
See How to generate a config in the repo.

Full Configuration Structure 

{
    "features": {
        "file_monitoring": {
            "enabled": true,
            "events": {
                "chmod": true,
                "chown": true,
                "file_create": true,
                "unlink": true,
                "rename": true,
                "write": true,
                "read": false,  # Due to high volume of read syscalls, we advise to disable.
                "mkdir": true,
                "rmdir": true
            }
        },
        "shell_commands_monitoring": {
            "enabled": true
        },
        "network_monitoring": {
            "enabled": true
        },
        "anti_tampering": {
            "enabled": false,
            "events": {
                "signals": "EXCLUDE_EVENT",
                "ptrace": "EXCLUDE_EVENT"
            }
        }
    },
    "userspace": {
        "max_events_queue_size": 10000,
        "output_type": "JSON",
        "log_level": "LOG_LEVEL_INFO",
        "set_limits": true,
        "log_location": "/path/to/file.log" 
    },
    "kernel": {
        "log_level": "LOG_LEVEL_WARNING"
    },
    "rules": [ ... ]
}

Configuration Reference

features

Required: false

Default value: All monitoring features are enabled by default

Control what security features are enabled.

Features that are always enabled: exec monitoring, fork monitoring, and process exit monitoring.

features.file_monitoring

Required: false

Default value: All filesystem monitoring features are enabled by default

Controls file system monitoring. When enabled, owLSM hooks into file operations and can detect/prevent malicious file access.

features.file_monitoring.enabled

Required: false

Default value: true

Options: true, false

Master switch for file system monitoring.

features.file_monitoring.events.chmod

Required: false

Default value: true

Options: true, false

Monitor chmod syscall

features.file_monitoring.events.chown

Required: false

Default value: true

Options: true, false

Monitor chown syscall

features.file_monitoring.events.file_create

Required: false

Default value: true

Options: true, false

Monitor regular file creation

Required: false

Default value: true

Options: true, false

Monitor unlink syscall (file deletion)

features.file_monitoring.events.mkdir

Required: false

Default value: true

Options: true, false

Monitor mkdir syscall (directory creation)

features.file_monitoring.events.rmdir

Required: false

Default value: true

Options: true, false

Monitor rmdir syscall (directory deletion)

features.file_monitoring.events.rename

Required: false

Default value: true

Options: true, false

Monitor rename syscall

features.file_monitoring.events.write

Required: false

Default value: true

Options: true, false

Monitor write syscall. Only for regular files and symlinks.

features.file_monitoring.events.read

Required: false

Default value: true

Options: true, false

Monitor read syscall. Only for regular files and symlinks.
Due to high volume of read syscalls, we strongly advise to disable this feature.

features.shell_commands_monitoring

Required: false

Default value: shell commands monitoring is enabled

Monitor commands typed in interactive shell sessions (Bash, Zsh, Dash) and the commands to the process context. This allows you to write rules that match based on the shell command that initiated an operation.

features.shell_commands_monitoring.enabled

Required: false

Default value: true

Options: true, false

Enable shell command monitoring.
Supported shells: Bash, Zsh, Dash.

features.network_monitoring

Required: false

Default value: network monitoring is enabled

Controls network connection monitoring.
Currently, only TCP connections are supported.

features.network_monitoring.enabled

Required: false

Default value: true

Options: true, false

Enable network connection monitoring.
Currently, only TCP connections are supported.

features.anti_tampering

Required: false

Default value: disabled

Anti-tampering protects specified processes from being harmed by things like signals and ptrace.

Use the -p <pid> commandline flag to specify which processes are protected.
owLSM is automatically protected when the anti-tampering flags are enabled.
Protection is inherited by child processes — but only for children created after owLSM has started monitoring.

features.anti_tampering.enabled

Required: false

Default value: false

Options: true, false

Master switch for anti-tampering. When false, all the anti-tampering features are disabled, and their corresponding eBPF probes aren't attached.

features.anti_tampering.events.signals

Required: false

Default value: "EXCLUDE_EVENT"

Options: "ALLOW_EVENT", "BLOCK_EVENT", "BLOCK_KILL_PROCESS", "BLOCK_KILL_PROCESS_KILL_PARENT", "EXCLUDE_EVENT"

This feature defends protected processes from signals.
- Signals that are sent to non-protected processes are ignored by owLSM.
- Signals that are sent by the kernel, from pid 0/1, or from a protected process are ignored by owLSM.
- The rest of the signals that are sent to protected processes are handled and a SIGNAL event is sent (owLSM action depends on the option you specify).

Options represents the action taken when an unprotected process sends a signal to a protected process.

features.anti_tampering.events.ptrace

Required: false

Default value: "EXCLUDE_EVENT"

Options: "ALLOW_EVENT", "BLOCK_EVENT", "BLOCK_KILL_PROCESS", "BLOCK_KILL_PROCESS_KILL_PARENT", "EXCLUDE_EVENT"

This feature defends protected processes from ptrace attach (write access).
- ptrace attempts without the PTRACE_MODE_ATTACH are ignored.
- Ptrace attach attempts against non-protected processes are ignored.
- Ptrace attach attempts from the kernel, from pid 0/1, or from a protected process are ignored.
- Other ptrace attach attempts against protected processes are handled and a PTRACE event is emitted (action depends on the option you specify).

Options represents the action taken when an unprotected process tries to trace a protected process.

userspace

Required: false

The `userspace` section configures the userspace component of owLSM.

userspace.max_events_queue_size

Required: false

Default value: 10000

Options: Integer (1000 - 1000000)

Maximum events in the processing queue.
Controls the size of the event buffer. Larger values handle burst traffic better but use more memory.

userspace.output_type

Required: false

Default value: "JSON"

Options: "JSON", "FLATBUFFERS"

Output format for events and errors.
"JSON" — Newline-delimited JSON (one JSON object per line). Human-readable.
"FLATBUFFERS" — Size-prefixed FlatBuffers binary. See FlatBuffers output for stream format and schema details.

userspace.log_level

Required: false

Default value: "LOG_LEVEL_INFO"

Options: "LOG_LEVEL_DEBUG", "LOG_LEVEL_INFO", "LOG_LEVEL_WARNING", "LOG_LEVEL_ERROR"

Logging verbosity for userspace.

userspace.set_limits

Required: false

Default value: true

Options: true, false

Set climits. Should be enabled.

userspace.log_location

Required: false

Default value: Same directory as the owlsm binary (filename: owlsm.log)

Options: Any writable absolute file path

owLSM log file absolute path.

kernel

Required: false

Default value: { log_level: "LOG_LEVEL_WARNING" }

Options: Object containing kernel configuration

The `kernel` section configures the kernel component of owLSM.

kernel.log_level

Required: false

Default value: "LOG_LEVEL_WARNING"

Options: "LOG_LEVEL_DEBUG", "LOG_LEVEL_INFO", "LOG_LEVEL_WARNING", "LOG_LEVEL_ERROR"

Kernel-side logging verbosity. Keep at `LOG_LEVEL_WARNING` or higher in production for performance.

rules

Required: false

Default value: No rules

The `rules` array.
See How to generate a config with rules in the repo.
This site uses Just the Docs, a documentation theme for Jekyll.