Skip to content

Permission Guard

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 2025-01-28T00:00:00Z
Rust Version unknown
File Size 1.6MB
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

82f339798d23beeba12d3555de0249babf1b271a2fffc7adc2d72e815eb89e7d

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 with automatic fixing
sudo permission-guard scan /home

# Preview what would be fixed (dry run)
sudo permission-guard scan /home --dry-run

# Scan specific directory
sudo permission-guard scan ~/documents

Daemon Mode (Continuous Protection)

Run as a background service:

# Start daemon
sudo permission-guard watch -d

# Custom PID file location
sudo permission-guard watch -d --pid-file /var/run/pguard.pid

# Check daemon status
permission-guard --daemon-status

# Stop daemon
sudo permission-guard --stop-daemon

Configuration Management

# View current configuration
permission-guard config

# View configuration (detailed)
permission-guard config show

# Use custom config file
permission-guard scan -c /path/to/config.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 watch -d

# 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.