Permission Guard Guide
Run enough sudo commands and root ends up owning files in your home directory, then you cannot edit your own work. permission-guard watches your directories and quietly hands ownership back. This guide is scenario-first: set up continuous protection, run one-off audits, and tune monitoring.
v9.8.4 (build 319) · 4 commands · 1.9 MB · inotify + periodic scan · auto-started by online-auth
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.
Binary Facts and Checksum
The full metadata table, raw signer JSON, and the current SHA-256 checksum live on the generated reference page so this guide never drifts out of date. Verify a downloaded binary in one click with the browser-side tool.
Where to confirm the binary
- permission-guard CLI reference, authoritative version, build, size, and SHA-256.
- File verification tool, drop the binary in and match it against the published hash, entirely in your browser.
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
Custom exclusion patterns, recursive depth, performance tuning, advanced daemon controls, audit-log management, and JSON field filtering, with every flag, are documented on the auto-generated permission-guard reference. This guide covers the everyday workflows; the reference is the exhaustive catalog.
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