{ "report_info": { "version": "9.0.1", "generated_at": "2026-05-19T08:52:42Z", "binary_name": "permission-guard" }, "binary": { "name": "permission-guard", "path": "/home/kodachi/k900/dashboard/hooks/permission-guard", "timestamp": "2026-05-19T08:52:42Z", "file_info": { "size": 1721696, "sha256": "4ddaaa8055f3b554be0c15332638a4b1524ed0e52c732381c60d9b9b76497997" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Linux Kodachi", "description": "A robust permission management service for Kodachi OS that monitors and corrects file ownership to prevent root-owned files in user directories", "features": [ "Real-time file permission monitoring", "Automatic permission correction", "Configurable watch directories", "Pattern-based exclusions", "Daemon mode for background operation", "JSON and text output formats", "Field filtering and pagination", "Comprehensive error handling" ], "license": "Proprietary", "name": "permission-guard", "securityFeatures": { "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" }, "systemRequirements": { "dependencies": [ "systemd", "inotify support" ], "os": "Linux (Debian-based)", "privileges": "root/sudo" }, "version": "9.0.1", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-27inch", "user": "kodachi" }, "status": "success", "timestamp": "2026-05-19T08:52:42.463103246Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "2025-01-28T00:00:00Z", "gitCommit": "unknown", "name": "permission-guard", "rustVersion": "unknown", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-27inch", "user": "kodachi" }, "status": "success", "timestamp": "2026-05-19T08:52:42.496949340Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Monitoring Commands", "commands": [ { "description": "Start continuous monitoring with auto-fix", "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" ], "name": "watch", "options": [ { "default": "true", "description": "Enable automatic fixing", "flag": "--auto-fix" }, { "description": "Disable automatic fixing", "flag": "--no-auto-fix" }, { "default": "30", "description": "Scan interval in seconds", "flag": "--scan-interval " }, { "default": "true", "description": "Enable recursive monitoring", "flag": "--recursive" }, { "description": "Disable recursive monitoring", "flag": "--no-recursive" } ], "requires_sudo": true, "usage": "permission-guard watch [OPTIONS] " }, { "description": "Perform one-time scan", "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" ], "name": "scan", "options": [ { "description": "Fix permissions automatically", "flag": "--fix" }, { "description": "Preview changes without applying", "flag": "--dry-run" }, { "default": "true", "description": "Enable recursive scanning", "flag": "--recursive" }, { "description": "Disable recursive scanning", "flag": "--no-recursive" } ], "requires_sudo": true, "usage": "permission-guard scan [OPTIONS] " } ] }, { "category": "Management Commands", "commands": [ { "description": "Show current status and configuration", "examples": [ "permission-guard status", "permission-guard status --detailed", "permission-guard status --json", "permission-guard status --detailed --json" ], "name": "status", "options": [ { "description": "Show detailed information", "flag": "--detailed" } ], "requires_sudo": false, "usage": "permission-guard status [OPTIONS]" }, { "description": "Manage configuration", "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'" ], "name": "config", "options": [ { "description": "Display current embedded configuration", "flag": "show" }, { "description": "Show initialization info (config is embedded)", "flag": "init" }, { "description": "Set configuration value (read-only, use CLI args)", "flag": "set " }, { "description": "Add directory to watch list (read-only, use CLI args)", "flag": "add-watch " }, { "description": "Remove directory from watch list (read-only, use CLI args)", "flag": "remove-watch " }, { "description": "Add directory to exclude list (read-only, use CLI args)", "flag": "add-exclude " }, { "description": "Remove directory from exclude list (read-only, use CLI args)", "flag": "remove-exclude " }, { "description": "Add exclude pattern (read-only, built-in patterns optimized)", "flag": "add-pattern " }, { "description": "Remove exclude pattern (read-only, built-in patterns optimized)", "flag": "remove-pattern " } ], "requires_sudo": false, "usage": "permission-guard config " } ] } ], "description": "A robust permission management service for Kodachi OS", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "unset", "description": "HTTP proxy for network requests", "name": "HTTP_PROXY", "values": "http://proxy:port" }, { "default": "unset", "description": "HTTPS proxy for secure requests", "name": "HTTPS_PROXY", "values": "https://proxy:port" }, { "default": "~/.config/permission-guard/config.json", "description": "Path to configuration file", "name": "PERMISSION_GUARD_CONFIG", "values": "/path/to/config.json" } ], "exitCodes": { "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" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (default: text)", "flag": "-o, --output-format " }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Set timeout (default: 30)", "flag": "--timeout " }, { "description": "Retry attempts (default: 3)", "flag": "--retry " }, { "description": "Use custom configuration file", "flag": "-c, --config " }, { "description": "Return only specified fields in JSON output", "flag": "--json-filter " }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Select specific fields to include in output", "flag": "--fields " }, { "description": "Limit number of results returned", "flag": "--limit " }, { "description": "Skip first N results (for pagination)", "flag": "--offset " }, { "description": "Override target user (username or UID)", "flag": "--user-override " }, { "description": "Run as daemon (background process)", "flag": "-d, --daemon" }, { "description": "Custom PID file location", "flag": "--pid-file " }, { "description": "Stop running daemon", "flag": "--stop-daemon" }, { "description": "Show daemon status", "flag": "--daemon-status" } ], "name": "permission-guard", "usage": "permission-guard [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-27inch", "user": "kodachi" }, "status": "success", "timestamp": "2026-05-19T08:52:42.532264476Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Common operations", "examples": [ { "command": "sudo permission-guard watch /path/to/hooks", "description": "Start monitoring with auto-fix", "expectedOutput": "Starts continuous monitoring of the directory" }, { "command": "sudo permission-guard scan /path/to/dir --fix", "description": "One-time scan and fix", "expectedOutput": "Scans directory and fixes permission issues" }, { "command": "sudo permission-guard scan /path/to/dir --dry-run", "description": "Preview changes without applying", "expectedOutput": "Shows what would be changed without making modifications" }, { "command": "sudo permission-guard status --json", "description": "Get status in JSON format", "expectedOutput": "JSON response with current status" }, { "command": "sudo permission-guard status", "description": "Check current runtime status", "expectedOutput": "Shows current daemon status and active configuration" }, { "command": "sudo permission-guard --json", "description": "Default operation with JSON output", "expectedOutput": "JSON formatted help information" } ], "id": "1_basic_usage", "title": "Basic Usage" }, { "description": "Complex operations", "examples": [ { "command": "sudo permission-guard watch /hooks --scan-interval 30", "description": "Custom scan interval", "expectedOutput": "Monitors directory with 30 second scan interval" }, { "command": "sudo permission-guard watch /dir1 /dir2 --scan-interval 60", "description": "Monitor multiple directories with custom interval", "expectedOutput": "Monitors both directories, scanning every 60 seconds", "notes": "Useful for less frequently changing directories" }, { "command": "sudo permission-guard scan /dir1 /dir2 --fix", "description": "Scan multiple directories", "expectedOutput": "Scans and fixes permissions in multiple directories" }, { "command": "sudo permission-guard --user-override myuser scan /path --fix", "description": "Override target user", "expectedOutput": "Scans and fixes permissions for specific user" }, { "command": "sudo permission-guard scan /path/to/dir --no-recursive", "description": "Non-recursive scan", "expectedOutput": "Scans only the specified directory, not subdirectories" }, { "command": "sudo permission-guard watch /path --no-auto-fix", "description": "Watch without auto-fix", "expectedOutput": "Monitors directory but doesn't automatically fix permissions" }, { "command": "sudo permission-guard --daemon watch /hooks", "description": "Run as background daemon", "expectedOutput": "Starts daemon process and returns", "notes": "Use --daemon-status to check if running" } ], "id": "2_advanced_usage", "title": "Advanced Usage" }, { "description": "Debug and error handling", "examples": [ { "command": "sudo permission-guard --verbose scan /path --dry-run", "description": "Preview changes with verbose output", "expectedOutput": "Detailed scan results without making changes", "notes": "Use to understand what would be changed" }, { "command": "sudo permission-guard --daemon-status", "description": "Check daemon status", "expectedOutput": "Shows if daemon is running and its PID" }, { "command": "sudo permission-guard --timeout 60 scan /large/dir --fix", "description": "Scan with extended timeout", "expectedOutput": "Scans large directory with 60 second timeout", "notes": "Useful for large directory structures" } ], "id": "3_troubleshooting", "title": "Troubleshooting" }, { "description": "Using JSON format for automation", "examples": [ { "command": "sudo permission-guard --json status", "description": "Runtime status in JSON format", "expectedOutput": "JSON response with current runtime status and active configuration" }, { "command": "sudo permission-guard --json config show", "description": "Embedded config template in JSON", "expectedOutput": "JSON formatted embedded configuration defaults and constraints", "notes": "Shows embedded defaults, not runtime configuration" }, { "command": "sudo permission-guard --json scan /path --dry-run", "description": "Scan results in JSON", "expectedOutput": "JSON array of permission issues found", "notes": "Dry-run shows what would be changed" }, { "command": "sudo permission-guard --json scan /path --fix", "description": "Fix permissions with JSON output", "expectedOutput": "JSON response with fix results" }, { "command": "sudo permission-guard --json watch /path", "description": "Watch with JSON logging (no terminal output)", "expectedOutput": "JSON events written to stdout", "notes": "Useful for piping to log processors" }, { "command": "sudo permission-guard --json status --detailed", "description": "Detailed runtime status in JSON", "expectedOutput": "Comprehensive JSON with runtime status, active config, and system info", "notes": "Shows actual runtime state, not embedded defaults" }, { "command": "sudo permission-guard --json --user-override myuser scan /path", "description": "Override user with JSON", "expectedOutput": "JSON scan results with custom user", "notes": "Useful for multi-user systems" }, { "command": "sudo permission-guard --json-pretty --fields scan_results,configuration scan /path --fix", "description": "Pretty JSON with field filtering", "expectedOutput": "Formatted JSON with only specified fields", "notes": "Use --fields to limit output to relevant data" }, { "command": "sudo permission-guard --json-filter files_scanned,files_corrected scan /path --fix", "description": "Filter JSON output fields", "expectedOutput": "JSON with only files_scanned and files_corrected fields", "notes": "Reduces output size for automated processing" }, { "command": "sudo permission-guard --json --limit 10 --offset 5 status", "description": "Paginated JSON output", "expectedOutput": "JSON response with pagination (skip 5, return 10)", "notes": "Useful for large result sets" } ], "id": "4_json_output", "title": "JSON Output Examples" }, { "description": "Managing service configuration", "examples": [ { "command": "sudo permission-guard config show", "description": "Display embedded configuration template", "expectedOutput": "Shows embedded configuration defaults and security constraints", "notes": "Use 'status --detailed' to see runtime configuration" } ], "id": "5_configuration_management", "title": "Configuration Management" }, { "description": "Running as background service", "examples": [ { "command": "sudo permission-guard --daemon watch /hooks", "description": "Start as background daemon", "expectedOutput": "Starts daemon process and returns control", "notes": "Use --daemon-status to check if running" }, { "command": "sudo permission-guard --daemon-status", "description": "Check if daemon is running", "expectedOutput": "Shows daemon status and PID if running" }, { "command": "sudo permission-guard --daemon-status --json", "description": "Daemon status in JSON format", "expectedOutput": "JSON response with daemon status, PID, and PID file location", "notes": "Useful for automated monitoring scripts" }, { "command": "sudo permission-guard --stop-daemon", "description": "Stop running daemon", "expectedOutput": "Stops the background daemon process" }, { "command": "sudo permission-guard --stop-daemon --json", "description": "Stop daemon with JSON response", "expectedOutput": "JSON confirmation of daemon stop operation" }, { "command": "sudo permission-guard --daemon --pid-file /custom/path.pid watch", "description": "Custom PID file", "expectedOutput": "Daemon with custom PID file location", "notes": "Useful for multiple instances" }, { "command": "sudo permission-guard --daemon scan /path --fix", "description": "Daemon mode for one-time scan", "expectedOutput": "Runs scan in background and keeps daemon alive", "notes": "Daemon stays running after command completion" }, { "command": "sudo permission-guard --daemon --pid-file /var/run/pg-instance1.pid watch /path1", "description": "Multiple daemon instances", "expectedOutput": "First daemon instance with unique PID file", "notes": "Run multiple instances by using different PID files" }, { "command": "sudo permission-guard --daemon-status --pid-file /var/run/pg-instance1.pid", "description": "Check specific daemon instance", "expectedOutput": "Status of daemon using specified PID file" }, { "command": "sudo permission-guard --stop-daemon --pid-file /var/run/pg-instance1.pid", "description": "Stop specific daemon instance", "expectedOutput": "Stops daemon using specified PID file" } ], "id": "6_daemon_operations", "title": "Daemon Operations" }, { "description": "Using advanced CLI features and error handling", "examples": [ { "command": "sudo permission-guard --timeout 120 --retry 5 scan /large/dir --fix", "description": "Extended timeout with retry attempts", "expectedOutput": "Scan with 120s timeout and up to 5 retry attempts", "notes": "Useful for unreliable environments or large directories" }, { "command": "sudo permission-guard --verbose --no-color scan /path --dry-run", "description": "Verbose output without colors", "expectedOutput": "Detailed scan information in plain text", "notes": "Good for logging to files or piping to other tools" }, { "command": "sudo permission-guard --quiet --json status", "description": "Minimal output with JSON", "expectedOutput": "JSON status without extra logging messages", "notes": "Reduces noise for automated processing" }, { "command": "sudo permission-guard --user-override 1001 scan /path --fix", "description": "Override with numeric UID", "expectedOutput": "Scans and fixes permissions for user ID 1001", "notes": "Useful when username is not available" }, { "command": "sudo permission-guard --user-override nonexistent scan /path", "description": "Invalid user override handling", "expectedOutput": "Error response: User 'nonexistent' not found", "notes": "Shows input validation in action" }, { "command": "sudo permission-guard watch /invalid/path/that/does/not/exist", "description": "Path validation example", "expectedOutput": "Error response about invalid or unsafe path", "notes": "Demonstrates security path validation" }, { "command": "sudo permission-guard --output-format json status", "description": "Explicit JSON output format", "expectedOutput": "Status in JSON format (same as --json)", "notes": "Alternative way to specify JSON output" } ], "id": "7_advanced_options", "title": "Advanced Options and Validation" } ], "description": "Usage examples for permission-guard", "name": "permission-guard", "quickReference": [ "sudo permission-guard --help", "sudo permission-guard --version", "sudo permission-guard --info --json", "sudo permission-guard --examples --json", "sudo permission-guard watch /path", "sudo permission-guard scan /path --fix", "sudo permission-guard status", "sudo permission-guard config show", "sudo permission-guard --daemon-status", "sudo permission-guard --stop-daemon" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "iMac-27inch", "user": "kodachi" }, "status": "success", "timestamp": "2026-05-19T08:52:42.608557376Z", "version": "9.0.1", "warnings": [] } } }