Permission Guard
PROTECTION TOOL
Protect the local system and reduce accidental damage.
These guides focus on permission safety, local containment, and how to verify protection behavior.
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | permission-guard |
| Version | 9.0.1 |
| Build Date | REDACTED-BUILD-TIME |
| Rust Version | unknown |
| File Size | 1.9MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | File Permission Management |
| Description | A robust permission management service for Kodachi OS that monitors and corrects file ownership to p... |
| JSON Data | View Raw JSON |
SHA256 Checksum
Key Features
Permission Protection
| Feature | Description |
|---|---|
| Automatic Monitoring | Watches directories for permission problems |
| Instant Correction | Fixes root-owned files as they appear |
| Smart Exclusions | Ignores system files that should remain root-owned |
| Daemon Mode | Runs continuously in background |
Why Permission Guard is Essential
| Benefit | Description |
|---|---|
| Prevents Lockouts | No more "Permission denied" on your own files |
| Workflow Protection | Keeps your work uninterrupted by permission issues |
| Security Compliance | Maintains proper user/system separation |
| Automatic Recovery | Self-heals permission problems without intervention |
TL;DR - Essential Commands
# Start continuous monitoring (daemon mode - monitors current directory by default)
sudo permission-guard watch /home
# Start monitoring specific directory
sudo permission-guard watch /path/to/directory
# Scan and fix permissions once (scans current directory by default)
sudo permission-guard scan /home --fix
# Scan specific directory with fixes
sudo permission-guard scan /path/to/directory --fix
# Check current status
permission-guard status
# View configuration
permission-guard config show
Understanding Permission Issues
The Root-Owned File Problem
When you run commands with sudo, any files created become owned by root:
# Example problem:
sudo echo "config" > ~/myconfig.txt
ls -l ~/myconfig.txt
# -rw-r--r-- 1 root root 7 Jan 1 12:00 myconfig.txt
# Result: You can't edit your own file!
Permission Guard prevents this by automatically changing ownership back to you.
How Permission Guard Works
# Start monitoring your home directory
sudo permission-guard watch /home
# What it does:
# 1. Watches for new/modified files
# 2. Detects root ownership in user directories
# 3. Automatically changes ownership to correct user
# 4. Logs all corrections for audit
Scanning for Issues
One-time scan to find and fix existing problems:
# Scan and fix permissions (--fix required to apply changes)
sudo permission-guard scan /home --fix
# Scan only, report issues without fixing
sudo permission-guard scan /home
# Preview what would be fixed (dry run)
sudo permission-guard scan /home --dry-run
# Scan specific directory and fix
sudo permission-guard scan ~/documents --fix
Daemon Mode (Continuous Protection)
Run as a background service:
# Start daemon (daemon flag precedes the subcommand)
sudo permission-guard --daemon watch /path/to/directory
# Custom PID file location
sudo permission-guard --daemon --pid-file /var/run/pguard.pid watch /path/to/directory
# Check daemon status
permission-guard --daemon-status
# Stop daemon
sudo permission-guard --stop-daemon
Configuration Management
# View embedded configuration defaults
permission-guard config show
# View configuration in JSON format
permission-guard config show --json
Default Configuration:
| Setting | Value | Description |
|---|---|---|
| Monitor Scope | User home directories | Watches user-owned directories only |
| Exclusions | .cache, .tmp, system dirs |
Ignores temporary and system files |
| Fix Mode | Automatic | Immediately corrects ownership issues |
| Check Interval | 60 seconds | Time between permission scans |
| Auto-start | Enabled via online-auth | Starts during authentication |
Status Monitoring
# Check current status
permission-guard status
# Get JSON output for scripts
permission-guard status --json
# Verbose status with details
permission-guard status --verbose
Smart Exclusions
Permission Guard intelligently ignores:
| Type | Description |
|---|---|
| System directories | /etc, /var, /sys |
| Temporary files | .tmp, .cache |
| Root-required files | System configs |
| Symbolic links | Links to system files |
User Override
For multi-user systems:
# Monitor for specific user
sudo permission-guard watch --user-override alice
# Fix permissions for user by UID
sudo permission-guard scan --user-override 1001
Automatic Integration with Online-Auth
Permission Guard daemon starts automatically during online-auth authentication.
Manual Management Commands
| Action | Command |
|---|---|
| Check daemon | permission-guard --daemon-status |
| Stop daemon | sudo permission-guard --stop-daemon |
How It Works
When you authenticate:
sudo online-auth authenticate
# Permission-guard automatically:
# → Starts daemon in background
# → Monitors current directory
# → Fixes permission issues every 15 seconds
Default Configuration
| Setting | Value |
|---|---|
| Directory | Current working directory |
| Scan Interval | 60 seconds (default scan interval) |
| Mode | Continuous daemon |
| Auto-fix | Enabled |
Opting Out of Auto-Start
If you prefer manual control over permission-guard:
# Stop auto-started daemon
sudo permission-guard --stop-daemon
# Disable auto-start (modify online-auth behavior)
# Note: This requires configuration changes - contact support
Service lifecycle
# Verify overall system status including permission-guard
online-auth check-all-status
# Check if daemon is running
permission-guard status # Show daemon status
ps aux | grep permission-guard # Process check
# Start daemon manually (if auto-start disabled)
sudo permission-guard --daemon watch /path/to/directory
# Monitor daemon activity
tail -f <hooks-dir>/logs/permission-guard-log.log # Watch daemon logs
permission-guard status --verbose # Detailed status
# Stop daemon
sudo permission-guard --stop-daemon
Manual Control Scenarios
Manual control is needed for:
| Scenario | Description |
|---|---|
| Custom Directories | Monitor specific paths beyond working directory |
| Configuration Changes | Adjust scan intervals or exclusions |
| One-time Scans | Quick permission checks without daemon |
| Maintenance | Stop daemon for system work |
| Opt-out Usage | Users who prefer manual control |
Note
For normal usage, authentication starts protection automatically.
Advanced Commands
For advanced users who need access to all available commands and options, please refer to the auto-generated command reference which includes:
| Feature | Description |
|---|---|
| Exclusion Patterns | Custom exclusion patterns |
| Recursive Depth | Recursive depth settings |
| Performance Tuning | Performance tuning options |
| Daemon Controls | Advanced daemon controls |
| Audit Logs | Audit log management |
| JSON Filtering | JSON filtering options |
| CLI Reference | All command-line flags and parameters |
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Directory Scope | Only monitor user directories, not system directories |
| Log Review | Review logs regularly for unexpected changes |
| Sensitive Files | Use exclusion patterns for sensitive files |
| Minimal Privileges | Run with minimal privileges when possible |
| Config Security | Keep configuration files secure |
Performance
| Metric | Value |
|---|---|
| Scan Speed | ~1000 files/second |
| Memory Usage | ~15MB active, < 5MB idle |
| CPU Usage | < 2% during monitoring |
| Check Interval | 60 seconds default (30 seconds minimum) |
| Fix Time | < 100ms per file |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Setting Up Continuous Permission Monitoring (Daemon)
Start automated protection for your working directory after authentication.
# Step 1: Authenticate and auto-start permission-guard daemon
sudo online-auth authenticate
# Expected: permission-guard daemon starts automatically, monitoring current directory
# Step 2: Verify daemon is running
permission-guard --daemon-status
# Expected: Daemon is running with PID displayed
# Step 3: Check monitoring status
permission-guard status --detailed
# Expected: Current working directory being monitored, scan interval 60 seconds
# Step 4: Test the protection by creating a root-owned file
sudo touch test-file.txt
# Expected: permission-guard detects changes in real-time via inotify, with periodic scans every 10-60 seconds
# Step 5: Verify the fix happened
ls -l test-file.txt
# Expected: File owned by your username, not root
# Step 6: Monitor daemon activity in real-time
tail -f <hooks-dir>/logs/permission-guard-log.log
# Expected: Log entries showing automatic permission corrections
# Step 7: Stop daemon when maintenance needed
sudo permission-guard --stop-daemon
# Expected: Daemon stopped successfully
Cross-binary workflow: online-auth + permission-guard
When to run: After every authentication session to ensure continuous permission protection. Or Automate this with online-auth's built-in auto-start feature (enabled by default).
Scenario 2: One-Time Permission Audit and Fixing
Quick scan and fix for permission issues without running a daemon.
# Step 1: Preview permission issues (dry-run)
sudo permission-guard scan /home/kodachi/k900 --dry-run
# Expected: List of root-owned files found, no changes made
# Step 2: Save scan results to JSON for analysis
sudo permission-guard --json scan /home/kodachi/k900 --dry-run > scan-results.json
# Expected: JSON file created with detailed scan results
# Step 3: Fix all detected permission issues
sudo permission-guard scan /home/kodachi/k900 --fix
# Expected: All root-owned files changed to correct user ownership
# Step 4: Verify integrity of fixed files
sudo integrity-check check-all
# Expected: All files pass integrity checks with correct ownership
# Step 5: Get detailed fix statistics
sudo permission-guard --json scan /home/kodachi/k900 --fix --json-filter files_scanned,files_corrected
# Expected: JSON output showing files_scanned and files_corrected counts
# Step 6: Generate verbose report
sudo permission-guard --verbose scan /home/kodachi/k900 --fix
# Expected: Detailed output of each file processed and fixed
Cross-binary workflow: permission-guard + integrity-check
When to run: After running multiple sudo commands, before critical operations, or when experiencing "Permission denied" errors on your own files.
Scenario 3: Multi-Directory Monitoring with Custom Intervals
Monitor multiple directories with different scan frequencies based on activity level.
# Step 1: Start daemon monitoring multiple directories with custom interval
sudo permission-guard --daemon watch /home/kodachi/k900 /home/kodachi/Documents --scan-interval 60
# Expected: Daemon starts, monitoring both directories every 60 seconds
# Step 2: Verify daemon status with custom PID file
sudo permission-guard --daemon-status --pid-file /var/run/permission-guard.pid
# Expected: Daemon running, PID and PID file location displayed
# Step 3: Check detailed runtime configuration
permission-guard status --detailed --json
# Expected: JSON showing active directories and 60-second scan interval
# Step 4: View real-time logs with workflow-manager
sudo workflow-manager run protection-user-security
# Expected: User security hardening workflow executed, permission-guard integrated
# Step 5: Monitor daemon logs continuously
tail -f <hooks-dir>/logs/permission-guard-log.log
# Expected: Live log stream showing permission corrections across all monitored directories
# Step 6: Adjust scan interval for high-activity directory
sudo permission-guard --stop-daemon
sudo permission-guard --daemon watch /home/kodachi/k900 --scan-interval 30
# Expected: Daemon restarted with 30-second interval for faster response
# Step 7: Verify new configuration
permission-guard status --detailed
# Expected: Updated scan interval (30 seconds) displayed
Cross-binary workflow: permission-guard + workflow-manager + logs-hook
When to run: For production environments with multiple project directories requiring different monitoring sensitivity. Or Automate this with workflow-manager profiles for consistent environment setup.
Scenario 4: Non-Recursive Scan for Specific Directory
Quick surface-level scan without traversing subdirectories.
# Step 1: Scan only top-level directory (no subdirectories)
sudo permission-guard scan /home/kodachi/k900 --no-recursive
# Expected: Only files directly in /home/kodachi/k900 are scanned
# Step 2: Preview non-recursive scan results
sudo permission-guard scan /home/kodachi/k900 --no-recursive --dry-run
# Expected: List of root-owned files in top directory only
# Step 3: Fix top-level permissions only
sudo permission-guard scan /home/kodachi/k900 --no-recursive --fix
# Expected: Permission issues fixed in top directory, subdirectories untouched
# Step 4: Compare with recursive scan (don't fix, just preview)
sudo permission-guard scan /home/kodachi/k900 --dry-run
# Expected: Shows all root-owned files including subdirectories
# Step 5: Verify with integrity-check
sudo integrity-check check-all
# Expected: Integrity verification of all system files
# Step 6: Generate comparison report
sudo permission-guard --json scan /home/kodachi/k900 --no-recursive --dry-run > top-level.json
sudo permission-guard --json scan /home/kodachi/k900 --dry-run > full-scan.json
# Expected: Two JSON files for comparing scan scope differences
Cross-binary workflow: permission-guard + integrity-check
When to run: For large directory trees where you only care about top-level permission issues, or when subdirectories should intentionally have different ownership (like system-managed subdirs).
Scenario 5: User Override for Multi-User Systems
Fix permissions for specific users on shared systems.
# Step 1: Scan and fix permissions for specific user by username
sudo permission-guard --user-override alice scan /shared/projects --fix
# Expected: All root-owned files changed to alice:alice ownership
# Step 2: Verify user override with status check
sudo permission-guard --user-override alice status --detailed
# Expected: Configuration shows target user is 'alice'
# Step 3: Use numeric UID for user without username
sudo permission-guard --user-override 1001 scan /shared/data --fix
# Expected: Files changed to UID 1001 ownership
# Step 4: Generate user-specific report in JSON
sudo permission-guard --json --user-override alice scan /shared/projects --fix > alice-fix-report.json
# Expected: JSON report showing permission fixes for user alice
# Step 5: Monitor daemon for specific user
sudo permission-guard --daemon --user-override alice watch /shared/projects --scan-interval 30
# Expected: Daemon monitoring /shared/projects, fixing to alice ownership every 30 seconds
# Step 6: Verify multi-user security with health-control
sudo health-control user-security-enable
# Expected: User-level security hardening applied
# Step 7: Check overall system security score
sudo health-control security-score
# Expected: Security score displayed, showing user permission protection status
# Step 8: Stop user-specific daemon
sudo permission-guard --stop-daemon
# Expected: Daemon stopped
Cross-binary workflow: permission-guard + health-control
When to run: On shared development systems, CI/CD servers, or multi-tenant environments where files need specific user ownership. Or Automate this with user-specific systemd services or cron jobs.
Related Workflows
- System Health Monitoring — Overall security and system integrity
- File Integrity Verification — Verify file signatures and ownership
- Workflow Automation — Automate permission monitoring with profiles
- Centralized Logging — Monitor permission-guard activity logs
- Full CLI Reference: permission-guard commands