Binary reference

permission-guard

A robust permission management service for Kodachi OS that monitors and corrects file ownership to prevent root-owned files in user directories

Version10.0.3Size2.0MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://digi77.com

File Information

Property	Value
Binary Name	permission-guard
Version	10.0.3
Build Date	Not disclosed
Rust Version	unknown
File Size	2.0MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	A robust permission management service for Kodachi OS that monitors and corrects file ownership to prevent root-owned fi...
Git Commit	unknown
Metadata Generated	2026-09-29T22:00:25Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

0d46a434ad5ff23d0904c425179058eca0cbc1c16bd1d19e11550c5db7de18d7

Features

#	Feature
1	Real-time file permission monitoring
2	Automatic permission correction
3	Configurable watch directories
4	Pattern-based exclusions
5	Daemon mode for background operation
6	JSON and text output formats
7	Field filtering and pagination
8	Comprehensive error handling

Security Features

Feature	Description
Authentication	Integrates with system user permissions
Encryption	Secure configuration storage
Input Validation	All paths and inputs are sanitized and validated
Rate Limiting	Configurable scan intervals prevent resource exhaustion

System Requirements

Requirement	Value
OS	Linux (Debian-based)
Privileges	root/sudo
Dependencies	systemd, inotify support

Global Options

Flag	Description
`-h, --help`	Print help information
`-v, --version`	Print version information
`-n, --info`	Display detailed information
`-e, --examples`	Show usage examples
`--json`	Output in JSON format
`-o, --output-format <text\|json>`	Force output format (default: text)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--timeout <SECS>`	Set operation timeout in seconds
`--json-filter <FIELD1,FIELD2>`	Return only specified fields in JSON output
`--json-pretty`	Pretty-print JSON output with indentation
`--json-human`	Enhanced human-friendly JSON output
`--fields <FIELD_LIST>`	Select specific fields to include in output
`--limit <NUMBER>`	Limit number of results returned
`--offset <NUMBER>`	Skip first N results (for pagination)
`--user-override <USER>`	Override target user (username or UID)
`-d, --daemon`	Run as daemon (background process)
`--pid-file <FILE>`	Custom PID file location
`--stop-daemon`	Stop running daemon
`--daemon-status`	Show daemon status

Commands

Monitoring Commands

`watch`

Start continuous monitoring with auto-fix (runs until interrupted)

Usage:

permission-guard watch [OPTIONS] [DIRECTORIES]...

Options:

[DIRECTORIES]...: Directories to monitor. Defaults to the binary's own execution folder. Rejected: /etc /bin /sbin /usr /lib /lib64 /boot /proc /sys /dev /var /run /root /srv /opt (only /opt/kodachi is allowed) and any path containing '..'
--auto-fix: Enable automatic fixing
--no-auto-fix: Disable automatic fixing
--scan-interval <SECS>: Re-scan interval in seconds for recently active paths. Falls back to the global --timeout value when omitted
--recursive: Enable recursive monitoring
--no-recursive: Disable recursive monitoring

Examples:

sudo permission-guard watch

sudo permission-guard watch /opt/kodachi/dashboard/hooks --scan-interval 60

permission-guard watch --no-auto-fix --json

sudo permission-guard --daemon watch

`scan`

Perform a one-time scan (report-only unless --fix is passed)

Usage:

permission-guard scan [OPTIONS] [DIRECTORIES]...

Options:

[DIRECTORIES]...: Directories to scan. Defaults to the binary's own execution folder. Rejected: /etc /bin /sbin /usr /lib /lib64 /boot /proc /sys /dev /var /run /root /srv /opt (only /opt/kodachi is allowed) and any path containing '..'
--fix: Correct ownership and modes (needs root; ignored when --dry-run is also passed)
--dry-run: Preview changes without applying
--recursive: Enable recursive scanning
--no-recursive: Disable recursive scanning

Examples:

permission-guard scan --dry-run

sudo permission-guard scan --fix

sudo permission-guard scan /opt/kodachi/dashboard/hooks --fix --json

permission-guard scan "$HOME/kodachi" --no-recursive

Management Commands

`status`

Show current status and configuration

Usage:

permission-guard status [OPTIONS]

Options:

--detailed: Show detailed information

Examples:

permission-guard status

permission-guard status --detailed

permission-guard status --json

permission-guard status --detailed --json

`config`

Manage configuration

Usage:

permission-guard config <SUBCOMMAND>

Options:

show: Display current embedded configuration

Examples:

permission-guard config show

permission-guard config show --json

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Quick Start

The first three commands on a fresh box. With no directory argument, scan and watch target the binary's own execution folder (on an installed system that is /opt/kodachi/dashboard/hooks).

Step 1: Report what is wrong in the hooks tree, change nothing

permission-guard scan --dry-run

Expected Output: Performing dry-run scan (no changes will be made) / Files scanned: N / Files needing correction: N

Step 2: Correct the ownership and modes that the dry run reported

sudo permission-guard scan --fix

Expected Output: Scan completed: Files corrected: N, Files failed to correct: 0

Note

Needs root: correcting ownership calls chown.

Step 3: Check whether the guard daemon is running and which directories it covers

permission-guard status

Expected Output: Daemon state, target user, watched directories and scan intervals currently in effect

Step 4: Print the compiled-in configuration defaults and security constraints

permission-guard config show

Expected Output: Embedded defaults: watch directories, exclude patterns, scan intervals, permission modes

Note

These are the embedded defaults, not the live values. Use 'status --detailed' for what is actually running.

Scenario 2: Choosing Directories

Which paths permission-guard accepts. Every directory you pass is checked against a denylist before any work starts, so most system paths are refused outright.

Step 1: Scan and fix the installed Kodachi hooks tree by explicit path

sudo permission-guard scan /opt/kodachi/dashboard/hooks --fix

Expected Output: Scan completed with per-directory counts for the hooks tree

Note

/opt/kodachi is the ONLY subtree under /opt the validator accepts; every other /opt path is refused. Needs root.

Step 2: Preview a scan of a Kodachi checkout in your home directory

permission-guard scan "$HOME/kodachi" --dry-run

Expected Output: Dry-run counts for the given directory, nothing modified

Note

Home paths are outside the denylist, and reporting on files you already own needs no root.

Step 3: Scan several directories in one run

sudo permission-guard scan /opt/kodachi/dashboard/hooks "$HOME/kodachi" --fix

Expected Output: Combined counts across both directories

Note

Every directory in the list must pass the denylist; one bad path aborts the whole run.

Step 4: What a refused path looks like, so you recognise it

permission-guard scan /etc

Expected Output: Error: Directory path is not in a safe location: /etc (exit code 2)

Note

Refused roots: /etc /bin /sbin /usr /lib /lib64 /boot /proc /sys /dev /var /run /root /srv /opt (except /opt/kodachi) and bare /. Any path containing '..' is refused as well.

Scenario 3: One-off Scans

Single-pass scans. Without --fix nothing is changed; --dry-run wins if both are passed.

Step 1: Report-only scan: count problems, change nothing, print the hint to use --fix

permission-guard scan

Expected Output: Performing scan without fixes (use --fix to enable corrections), then the file counts

Step 2: Preview every correction the guard would make, with per-file detail

permission-guard scan --dry-run --verbose

Expected Output: Verbose per-file listing plus the summary counts, nothing written

Step 3: Fix only the top level of the directory, do not descend into subdirectories

sudo permission-guard scan --fix --no-recursive

Expected Output: Scan completed covering the directory itself only

Note

--no-recursive conflicts with --recursive; pass only one. Needs root.

Step 4: Hand ownership to a specific user rather than the auto-detected one

sudo permission-guard --user-override "$USER" scan --fix

Expected Output: Scan completed with files chowned to the named user

Note

--user-override must come BEFORE the subcommand (it is not a global flag). UID 0 and numeric UIDs below 1000 are refused; pass a real username for a system account.

Step 5: Same, using a numeric UID when the username is not known

sudo permission-guard --user-override 1001 scan --fix

Expected Output: Scan completed with files chowned to UID 1001

Note

Numeric UIDs must be 1000 or above. Unknown users fail with "User not found".

Scenario 4: Continuous Monitoring

Keep the guard running and re-check permissions as files change. watch runs in the foreground until you interrupt it, unless you add --daemon.

Step 1: Monitor the hooks tree with auto-fix and recursion on (the defaults)

sudo permission-guard watch

Expected Output: Watcher starts and prints correction events as they happen; runs until Ctrl-C

Note

Needs root: auto-fix is on by default and chowns files. Blocks the terminal; use --daemon to background it.

Step 2: Re-check recently active paths every 60 seconds instead of the 30 second default

sudo permission-guard watch /opt/kodachi/dashboard/hooks --scan-interval 60

Expected Output: Watcher running with a 60 second rescan interval

Note

If --scan-interval is omitted, watch falls back to the global --timeout value. --timeout has no effect on any other command.

Step 3: Report-only monitoring: log what is wrong, never change it

permission-guard watch --no-auto-fix --scan-interval 120

Expected Output: Watcher logs permission violations without correcting them

Note

--no-auto-fix conflicts with --auto-fix; pass only one. Report-only monitoring needs no root.

Step 4: Watch one directory level only

sudo permission-guard watch "$HOME/kodachi" --no-recursive

Expected Output: Watcher covering the named directory, ignoring its subdirectories

Step 5: Stream watch events as JSON so a log processor can consume them

permission-guard watch --no-auto-fix --json

Expected Output: JSON event objects on stdout instead of human text

Note

Good for piping. Drop --no-auto-fix and add sudo if you also want corrections applied.

Scenario 5: Status and Configuration

Inspect the live configuration and the compiled-in defaults. Neither command changes anything, and neither needs root.

Step 1: Full runtime view: target user, watched and excluded directories, every interval

permission-guard status --detailed

Expected Output: Expanded text report of the active runtime configuration and daemon state

Step 2: The same detailed view as a single JSON object for a script

permission-guard status --detailed --json

Expected Output: JSON envelope whose data block holds the runtime status and active configuration

Step 3: Read the embedded configuration template as JSON

permission-guard config show --json

Expected Output: JSON with the embedded defaults and the security constraints they must satisfy

Note

Embedded defaults only. 'status --detailed --json' is the one that reflects the running configuration.

Scenario 6: Background Daemon

Run the guard detached. --daemon, --pid-file, --stop-daemon and --daemon-status are root-level flags: they must appear BEFORE the subcommand. The default PID file is <execution folder>/tmp/permission-guard.pid.

Step 1: Start monitoring the hooks tree in the background and return to the shell

sudo permission-guard --daemon watch

Expected Output: Daemon started with PID <N>, then the terminal is free

Note

Needs root (auto-fix chowns files). Check it afterwards with --daemon-status.

Step 2: Ask whether a guard daemon is running and under which PID

permission-guard --daemon-status

Expected Output: Running with PID <N>, or a message that no daemon is running

Step 3: Same check, machine readable, for a monitoring script

permission-guard --daemon-status --json

Expected Output: JSON with the running flag, the PID and the PID file path

Step 4: Stop the daemon recorded in the default PID file

sudo permission-guard --stop-daemon

Expected Output: Confirmation that the daemon was signalled and stopped

Note

Stopping the guard means permissions stop being corrected until you start it again.

Step 5: Run a second, independently addressable daemon instance

sudo permission-guard --daemon --pid-file /opt/kodachi/dashboard/hooks/tmp/pg-instance1.pid watch /opt/kodachi/dashboard/hooks

Expected Output: Daemon started with its own PID file and lock file

Note

The PID path goes through the SAME denylist as directories: /var/run and /run are refused with "PID file path is not in a safe location". Keep instance PID files under /opt/kodachi or in your home directory.

Step 6: Check that one named instance specifically

permission-guard --daemon-status --pid-file /opt/kodachi/dashboard/hooks/tmp/pg-instance1.pid

Expected Output: Running state and PID for the daemon recorded in that PID file

Step 7: Stop that one named instance and leave the others running

sudo permission-guard --stop-daemon --pid-file /opt/kodachi/dashboard/hooks/tmp/pg-instance1.pid

Expected Output: Confirmation that the named instance was stopped

Step 8: Run a one-time fix in the background

sudo permission-guard --daemon scan --fix

Expected Output: Scan runs, then the process prints a heartbeat every 60 seconds

Note

The daemon deliberately STAYS ALIVE after the scan finishes; end it with --stop-daemon.

Scenario 7: JSON for Automation

Machine-readable output. Field paths are resolved against the JSON envelope, so a bare name such as scan_results is looked up inside the data block automatically. --limit and --offset only reshape list-shaped payloads and have no useful effect on permission-guard, whose scan and status payloads are single objects.

Step 1: Runtime status as a compact JSON envelope

permission-guard --json status

Expected Output: {"status":"success","command":"status","data":{...}}

Note

--json is global: 'status --json' parses identically. This corpus puts it before the subcommand throughout.

Step 2: Dry-run results as JSON for a pre-flight check in a script

permission-guard --json scan --dry-run

Expected Output: JSON with scan_results (files_scanned, files_needing_correction, success_rate) and the configuration used

Step 3: Apply fixes and capture the outcome as JSON

sudo permission-guard --json scan --fix

Expected Output: JSON with files_corrected, files_failed and any per-file errors

Note

Needs root.

Step 4: Indented JSON reduced to just the scan results and the configuration used

permission-guard --json-pretty --fields scan_results,configuration scan --dry-run

Expected Output: Pretty-printed JSON containing only the scan_results and configuration blocks

Note

Bare field names are resolved inside the data block. Use dotted paths for anything deeper.

Step 5: Cut the JSON down to the two counters a deployment script cares about

sudo permission-guard --json-filter scan_results.files_corrected,scan_results.files_failed scan --fix

Expected Output: {"scan_results":{"files_corrected":N,"files_failed":0}}

Note

Nested values need the dotted path. A bare 'files_corrected' does NOT resolve, because it lives under scan_results.

Step 6: JSON only, with warnings and progress chatter suppressed

permission-guard --quiet --json status

Expected Output: The JSON envelope on stdout and nothing else

Step 7: Select JSON with the explicit format flag instead of --json

permission-guard --output-format json config show

Expected Output: The same output as 'permission-guard --json config show'

Scenario 8: Troubleshooting

What to run when the guard is not doing what you expect, and what its refusals look like.

Step 1: See exactly which files the guard considers wrong, before touching anything

permission-guard --verbose scan --dry-run

Expected Output: Per-file expected versus actual owner and mode, plus the summary

Step 2: The same detail as plain text, safe to redirect into a log file

permission-guard --verbose --no-color scan --dry-run

Expected Output: Verbose scan output with no ANSI escape codes

Step 3: What an unknown target user looks like

permission-guard --user-override nonexistent scan

Expected Output: Error: User 'nonexistent' not found (exit code 2)

Step 4: What a refused PID path looks like, so you do not lose time on it

permission-guard --pid-file /var/run/pg.pid --daemon-status

Expected Output: Error: PID file path is not in a safe location (exit code 2)

Note

/var and /run are on the denylist. Put instance PID files under /opt/kodachi or in your home directory.

Environment Variables

Variable	Description	Default	Values
`RUST_LOG`	Set logging level	info	error\|warn\|info\|debug\|trace
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)
`HTTP_PROXY`	HTTP proxy for network requests	unset	http://proxy:port
`HTTPS_PROXY`	HTTPS proxy for secure requests	unset	https://proxy:port
`PERMISSION_GUARD_CONFIG`	Path to configuration file	~/.config/permission-guard/config.json	/path/to/config.json

Exit Codes

Code	Description
0	Success
1	General error
10	Command error
2	Invalid arguments
3	Permission denied
4	Network error
5	File not found
6	Timeout
7	Authentication error
8	Internal error
9	Validation error