Permission Auditor CLI

Python CLI tool to audit file permissions for security reviews, compliance checks, or permission normalization.

Features

• Permission reports: List all files with octal mode (e.g., 644, 755)
• World-writable detection: Find files dangerous for team/shared directories
• Ownership checking: Report when file UID differs from real user
• Depth control: Scan shallow folders or entire tree
• Two modes: Summary mode counts permissions; verbose mode lists all files

Perfect for:

• Security audits before deployments
• Compliance with security policies (world-writable checks)
• Permission normalization after migrations
• Identifying shared-access scenarios in team environments

Usage

# Basic permission report (summary)
python perm-audit.py -d /path/to/dir [-l depth]

# Detailed listing of every file
python perm-audit.py -d /path/to/dir -v

# Security scan: world-writable only
python perm-audit.py -d /home/user/Downloads -w

Options

• -d, --dir: Directory to audit (required)
• -l, --depth: Maximum depth (default 2, 0=entire tree)
• -v, --verbose: List all files with permissions
• -w, --list-writable: Only world-writable files

Examples

Full Audit Report

python perm-audit.py -d /home/developer

Shows summary mode:

• Top 20 permission modes sorted by count
• Octal codes (644=owner rw+group r+others r, 755=all r+x)
• Quick count of unique permissions

Security Check for Shared Folder

python perm-audit.py -d /var/www/html -w

Scans web root for world-writable or group-writable files (common vulnerabilities):

[!] /var/www/html/uploads/: mode=644 owner_writable (uid != real-user)
       /var/www/html/static/css/theme.css: mode=0644 
         /var/www/html/config/database.yml: mode=0600

Verbose Listing

python perm-audit.py -d ~/projects -v

Detailed view of each file's permissions, path (truncated to first folder), with flags indicating readability/writability/executability.

Command Examples

Directory Tree Check Before Commit

Before committing a large repository:

python perm-audit.py -d /home/user/newproject -v -l 2

Identifies files with unusual permissions (like world-writable .py scripts in a web deployment):

• 664 config files → security risk if group isn't trusted
• 777 binaries anywhere → major vulnerability
• 0644 logs or caches → typically expected for log rotation scenarios

Web Server Audit

Check permissions of web root before serving:

python perm-audit.py -d /var/www/public -l 3 -v 2>/dev/null

Filters for common issues:

• 0600 config files in public directories (too restrictive)
• Missing execute bit on CGI/SID scripts
• Writable directories without sticky bits in /tmp

Security Policy Compliance Scan

Scan for world-writable files (violating principle-of-least-access):

python perm-audit.py -d /etc | grep -i "^0664\|^0777"

Or use built-in flag:

python perm-audit.py -d /home/user/shared -w

Common Findings to Address

Mode	Meaning	Typical Use Case	When Concerning?
0644	Owner rw+group r+others r	Data files	No (standard)
0755	Owner rwx+group rx+others rx	Executables, scripts	Rarely (expected)
0600	Owner-only rw	Secrets, keys	No in /etc/passwd, risky elsewhere
0664	Owner rw+group rw+x	Shared configs	Yes if group untrusted
0777	Full perms to all	Temp dirs only	Critical outside /tmp
1777	Sticky bit temp dir	/tmp, shared writable areas	No (expected)

Code Example

The scanner walks directories and collects permissions:

def iterate(path, depth=0):
    if depth == 0 or current < depth:
        try:
            stat_info = os.stat(path)
            mode = stat.S_IMODE(stat_info.st_mode) & 0o777  # Strip special bits
            # Report writable flags for security check
            is_world_writable = bool(mode & stat.S_IWOTH)
        except OSError:
            pass
    
    # Walk subdirs if depth allows traversal
    for name in os.listdir(path):
        iterate(os.path.join(path, name), current + 1)

Permission values use octal representation (0-7 digits). stat.S_IMODE() extracts the permission bits minus special bits like setuid/setgid.

World-writable check uses mode & stat.S_IWOTH (others-write bit). Owner-writable when UID doesn't match real user—indicates file created by elevated process and left accessible to group/other.

Use Cases

• Post-deployment audit: Verify permissions after migration or restore
• CI/CD security gates: Fail builds detecting mode 0777 files
• Team directory reviews: Check shared folders for proper group write access
• Regulatory compliance: Document permission state before external audits
• Bug isolation: Locate writable config in deployed code that causes crashes

Source Code

Public repo with examples and test cases. Readable, dependency-free, suitable as starting point for security automation scripts or policy enforcement tools.

🔗 Repo: https://github.com/Poolion/perm-audit-cli

If you find this useful, you can support development: https://www.buymeacoffee.com/poolion