permission-guard

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

Version: 9.8.4 (build 319) | Size: 1.9MB | Author: Warith Al Maawali

License: Proprietary | Website: https://digi77.com

File Information

Property	Value
Binary Name	permission-guard
Version	9.8.4 (build 319)
Build Date	REDACTED-BUILD-TIME
Rust Version	unknown
File Size	1.9MB
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-06-28T11:16:39Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

86e60e6fc7494408e0b53fc3b2c0ed159d7f554c4f03f6e39289e040f39d06b8

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 timeout (default: 30)
`--retry <COUNT>`	Retry attempts (default: 3)
`-c, --config <FILE>`	Use custom configuration file
`--json-filter <FIELD1,FIELD2>`	Return only specified fields in JSON output
`--json-pretty`	Pretty-print JSON output with indentation
`--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

Usage:

permission-guard watch [OPTIONS] <DIRECTORIES>

Options:

--auto-fix: Enable automatic fixing
--no-auto-fix: Disable automatic fixing
--scan-interval <SECS>: Scan interval in seconds
--recursive: Enable recursive monitoring
--no-recursive: Disable recursive monitoring

Examples:

permission-guard watch /path/to/dir

permission-guard watch /dir1 /dir2 --scan-interval 60

permission-guard watch /path --json

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

`scan`

Perform one-time scan

Usage:

permission-guard scan [OPTIONS] <DIRECTORIES>

Options:

--fix: Fix permissions automatically
--dry-run: Preview changes without applying
--recursive: Enable recursive scanning
--no-recursive: Disable recursive scanning

Examples:

permission-guard scan /path/to/dir

permission-guard scan /path/to/dir --dry-run

permission-guard scan /path/to/dir --fix

permission-guard scan /path --fix --json

permission-guard scan /path --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: Basic Usage

Common operations

Step 1: Start monitoring with auto-fix

sudo permission-guard watch /path/to/hooks

Expected Output: Starts continuous monitoring of the directory

Step 2: One-time scan and fix

sudo permission-guard scan /path/to/dir --fix

Expected Output: Scans directory and fixes permission issues

Step 3: Preview changes without applying

sudo permission-guard scan /path/to/dir --dry-run

Expected Output: Shows what would be changed without making modifications

Step 4: Get status in JSON format

sudo permission-guard status --json

Expected Output: JSON response with current status

Step 5: Check current runtime status

sudo permission-guard status

Expected Output: Shows current daemon status and active configuration

Step 6: Default operation with JSON output

sudo permission-guard --json

Expected Output: JSON formatted help information

Scenario 2: Advanced Usage

Complex operations

Step 1: Custom scan interval

sudo permission-guard watch /hooks --scan-interval 30

Expected Output: Monitors directory with 30 second scan interval

Step 2: Monitor multiple directories with custom interval

sudo permission-guard watch /dir1 /dir2 --scan-interval 60

Expected Output: Monitors both directories, scanning every 60 seconds

Note

Useful for less frequently changing directories

Step 3: Scan multiple directories

sudo permission-guard scan /dir1 /dir2 --fix

Expected Output: Scans and fixes permissions in multiple directories

Step 4: Override target user

sudo permission-guard --user-override myuser scan /path --fix

Expected Output: Scans and fixes permissions for specific user

Step 5: Non-recursive scan

sudo permission-guard scan /path/to/dir --no-recursive

Expected Output: Scans only the specified directory, not subdirectories

Step 6: Watch without auto-fix

sudo permission-guard watch /path --no-auto-fix

Expected Output: Monitors directory but doesn't automatically fix permissions

Step 7: Run as background daemon

sudo permission-guard --daemon watch /hooks

Expected Output: Starts daemon process and returns

Note

Use --daemon-status to check if running

Scenario 3: Troubleshooting

Debug and error handling

Step 1: Preview changes with verbose output

sudo permission-guard --verbose scan /path --dry-run

Expected Output: Detailed scan results without making changes

Note

Use to understand what would be changed

Step 2: Check daemon status

sudo permission-guard --daemon-status

Expected Output: Shows if daemon is running and its PID

Step 3: Scan with extended timeout

sudo permission-guard --timeout 60 scan /large/dir --fix

Expected Output: Scans large directory with 60 second timeout

Note

Useful for large directory structures

Scenario 4: JSON Output Examples

Using JSON format for automation

Step 1: Runtime status in JSON format

sudo permission-guard --json status

Expected Output: JSON response with current runtime status and active configuration

Step 2: Embedded config template in JSON

sudo permission-guard --json config show

Expected Output: JSON formatted embedded configuration defaults and constraints

Note

Shows embedded defaults, not runtime configuration

Step 3: Scan results in JSON

sudo permission-guard --json scan /path --dry-run

Expected Output: JSON array of permission issues found

Note

Dry-run shows what would be changed

Step 4: Fix permissions with JSON output

sudo permission-guard --json scan /path --fix

Expected Output: JSON response with fix results

Step 5: Watch with JSON logging (no terminal output)

sudo permission-guard --json watch /path

Expected Output: JSON events written to stdout

Note

Useful for piping to log processors

Step 6: Detailed runtime status in JSON

sudo permission-guard --json status --detailed

Expected Output: Comprehensive JSON with runtime status, active config, and system info

Note

Shows actual runtime state, not embedded defaults

Step 7: Override user with JSON

sudo permission-guard --json --user-override myuser scan /path

Expected Output: JSON scan results with custom user

Note

Useful for multi-user systems

Step 8: Pretty JSON with field filtering

sudo permission-guard --json-pretty --fields scan_results,configuration scan /path --fix

Expected Output: Formatted JSON with only specified fields

Note

Use --fields to limit output to relevant data

Step 9: Filter JSON output fields

sudo permission-guard --json-filter files_scanned,files_corrected scan /path --fix

Expected Output: JSON with only files_scanned and files_corrected fields

Note

Reduces output size for automated processing

Step 10: Paginated JSON output

sudo permission-guard --json --limit 10 --offset 5 status

Expected Output: JSON response with pagination (skip 5, return 10)

Note

Useful for large result sets

Scenario 5: Configuration Management

Managing service configuration

Step 1: Display embedded configuration template

sudo permission-guard config show

Expected Output: Shows embedded configuration defaults and security constraints

Note

Use 'status --detailed' to see runtime configuration

Scenario 6: Daemon Operations

Running as background service

Step 1: Start as background daemon

sudo permission-guard --daemon watch /hooks

Expected Output: Starts daemon process and returns control

Note

Use --daemon-status to check if running

Step 2: Check if daemon is running

sudo permission-guard --daemon-status

Expected Output: Shows daemon status and PID if running

Step 3: Daemon status in JSON format

sudo permission-guard --daemon-status --json

Expected Output: JSON response with daemon status, PID, and PID file location

Note

Useful for automated monitoring scripts

Step 4: Stop running daemon

sudo permission-guard --stop-daemon

Expected Output: Stops the background daemon process

Step 5: Stop daemon with JSON response

sudo permission-guard --stop-daemon --json

Expected Output: JSON confirmation of daemon stop operation

Step 6: Custom PID file

sudo permission-guard --daemon --pid-file /custom/path.pid watch

Expected Output: Daemon with custom PID file location

Note

Useful for multiple instances

Step 7: Daemon mode for one-time scan

sudo permission-guard --daemon scan /path --fix

Expected Output: Runs scan in background and keeps daemon alive

Note

Daemon stays running after command completion

Step 8: Multiple daemon instances

sudo permission-guard --daemon --pid-file /var/run/pg-instance1.pid watch /path1

Expected Output: First daemon instance with unique PID file

Note

Run multiple instances by using different PID files

Step 9: Check specific daemon instance

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

Expected Output: Status of daemon using specified PID file

Step 10: Stop specific daemon instance

sudo permission-guard --stop-daemon --pid-file /var/run/pg-instance1.pid

Expected Output: Stops daemon using specified PID file

Scenario 7: Advanced Options and Validation

Using advanced CLI features and error handling

Step 1: Extended timeout with retry attempts

sudo permission-guard --timeout 120 --retry 5 scan /large/dir --fix

Expected Output: Scan with 120s timeout and up to 5 retry attempts

Note

Useful for unreliable environments or large directories

Step 2: Verbose output without colors

sudo permission-guard --verbose --no-color scan /path --dry-run

Expected Output: Detailed scan information in plain text

Note

Good for logging to files or piping to other tools

Step 3: Minimal output with JSON

sudo permission-guard --quiet --json status

Expected Output: JSON status without extra logging messages

Note

Reduces noise for automated processing

Step 4: Override with numeric UID

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

Expected Output: Scans and fixes permissions for user ID 1001

Note

Useful when username is not available

Step 5: Invalid user override handling

sudo permission-guard --user-override nonexistent scan /path

Expected Output: Error response: User 'nonexistent' not found

Note

Shows input validation in action

Step 6: Path validation example

sudo permission-guard watch /invalid/path/that/does/not/exist

Expected Output: Error response about invalid or unsafe path

Note

Demonstrates security path validation

Step 7: Explicit JSON output format

sudo permission-guard --output-format json status

Expected Output: Status in JSON format (same as --json)

Note

Alternative way to specify JSON output

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