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.0.1 | Size: 1.4MB | Author: Warith Al Maawali

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

File Information

Property	Value
Binary Name	permission-guard
Version	9.0.1
Build Date	2025-01-28T00:00:00Z
Rust Version	unknown
File Size	1.4MB
JSON Data	View Raw JSON

SHA256 Checksum

dc8e325925898f25ec3829c54be013f7e5dc8557567924cbae82819bb852ae8b

Features

Feature	Description
Feature	Real-time file permission monitoring
Feature	Automatic permission correction
Feature	Configurable watch directories
Feature	Pattern-based exclusions
Feature	Daemon mode for background operation
Feature	JSON and text output formats
Feature	Field filtering and pagination
Feature	Comprehensive error handling

Security Features

Feature	Description
Authentication	Integrates with system user permissions
Encryption	Secure configuration storage
Inputvalidation	All paths and inputs are sanitized and validated
Ratelimiting	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 - init: Show initialization info (config is embedded) - set <KEY> <VALUE>: Set configuration value (read-only, use CLI args) - add-watch <PATH>: Add directory to watch list (read-only, use CLI args) - remove-watch <PATH>: Remove directory from watch list (read-only, use CLI args) - add-exclude <PATH>: Add directory to exclude list (read-only, use CLI args) - remove-exclude <PATH>: Remove directory from exclude list (read-only, use CLI args) - add-pattern <PATTERN>: Add exclude pattern (read-only, built-in patterns optimized) - remove-pattern <PATTERN>: Remove exclude pattern (read-only, built-in patterns optimized)

Examples:

permission-guard config show

permission-guard config show --json

permission-guard config init

permission-guard config set scan_interval 60

permission-guard config add-watch /new/path

permission-guard config remove-watch /old/path

permission-guard config add-exclude /tmp

permission-guard config remove-exclude /tmp

permission-guard config add-pattern '*.log'

permission-guard config remove-pattern '*.bak'

Examples

Basic Usage

Common operations

Start monitoring with auto-fix

sudo permission-guard watch /path/to/hooks

Expected Output: Starts continuous monitoring of the directory

One-time scan and fix

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

Expected Output: Scans directory and fixes permission issues

Preview changes without applying

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

Expected Output: Shows what would be changed without making modifications

Get status in JSON format

sudo permission-guard status --json

Expected Output: JSON response with current status

Check current runtime status

sudo permission-guard status

Expected Output: Shows current daemon status and active configuration

Default operation with JSON output

sudo permission-guard --json

Expected Output: JSON formatted help information

Advanced Usage

Complex operations

Custom scan interval

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

Expected Output: Monitors directory with 30 second scan interval

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

Scan multiple directories

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

Expected Output: Scans and fixes permissions in multiple directories

Override target user

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

Expected Output: Scans and fixes permissions for specific user

Non-recursive scan

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

Expected Output: Scans only the specified directory, not subdirectories

Watch without auto-fix

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

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

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

Troubleshooting

Debug and error handling

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

Check daemon status

sudo permission-guard --daemon-status

Expected Output: Shows if daemon is running and its PID

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

JSON Output Examples

Using JSON format for automation

Runtime status in JSON format

sudo permission-guard --json status

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

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

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

Fix permissions with JSON output

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

Expected Output: JSON response with fix results

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

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

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

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

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

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

Configuration Management

Managing service configuration

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

Daemon Operations

Running as background service

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

Check if daemon is running

sudo permission-guard --daemon-status

Expected Output: Shows daemon status and PID if running

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

Stop running daemon

sudo permission-guard --stop-daemon

Expected Output: Stops the background daemon process

Stop daemon with JSON response

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

Expected Output: JSON confirmation of daemon stop operation

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

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

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

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

Stop specific daemon instance

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

Expected Output: Stops daemon using specified PID file

Advanced Options and Validation

Using advanced CLI features and error handling

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

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

Minimal output with JSON

sudo permission-guard --quiet --json status

Expected Output: JSON status without extra logging messages

Note

Reduces noise for automated processing

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

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

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

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

Debug logging via environment variable

RUST_LOG=debug ./permission-guard scan /path --fix

Expected Output: Scan with detailed debug information

Note

Set RUST_LOG for different verbosity levels

Disable colors via environment

NO_COLOR=1 ./permission-guard status

Expected Output: Status output without ANSI color codes

Note

Useful for terminals that don't support colors

Environment Variables

Variable	Description	Default	Values
`RUST_LOG`	Set logging level	info	error
`NO_COLOR`	Disable all colored output when set	unset	1
`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