whyno

whyno is a Linux permission debugger. It answers the question: "Why can't this user do this to this file?"

Given a subject (user, UID, PID, or service), an operation (read, write, execute, delete, create, stat), and a filesystem path, whyno checks every permission layer from mount options down to POSIX ACLs — then tells you exactly what's blocking and how to fix it with the least-privilege change.

Installation

whyno ships as a single static binary for four Linux architectures (x86_64, aarch64, armv7, riscv64). No runtime dependencies.

# Build from source (x86_64)
cargo build --release --target x86_64-unknown-linux-musl

# Build for aarch64 (requires cross)
cross build --release --target aarch64-unknown-linux-musl

# Optional: install CAP_DAC_READ_SEARCH for full coverage without sudo
sudo whyno caps install

Privilege tiers

In unprivileged mode, inaccessible checks are marked [SKIP] (never false-green). A one-time hint suggests elevated options.

Usage

whyno <subject> <operation> <path> [flags]
whyno <subject> chmod <path> [--new-mode MODE]
whyno <subject> chown-uid --new-uid UID <path>
whyno <subject> chown-gid --new-gid GID <path>
whyno <subject> setxattr --xattr-key KEY <path>
whyno caps <action>
whyno schema
whyno --help | --version

Subject formats

Operations

Flags

• --json — structured JSON output (versioned schema, CI-friendly)
• --explain — verbose resolution chain with per-component raw data
• --no-color — disable ANSI color (also respects NO_COLOR env var)
• --with-cap <CAP> — inject a capability for hypothetical queries; repeatable. Accepted names: CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_LINUX_IMMUTABLE
• --self-test — cross-check whyno's result against kernel faccessat2(AT_EACCESS); valid only when subject is the calling user and kernel >= 5.8; mismatches reported to stderr; runs automatically in debug builds
• --new-mode <MODE> — target mode bits for the chmod operation (octal, e.g. 644 or 0755)
• --new-uid <UID> — target UID for the chown-uid operation
• --new-gid <GID> — target GID for the chown-gid operation; owner-in-group check applies without CAP_CHOWN when caller owns the file
• --xattr-key <KEY> — extended attribute key for setxattr (e.g. user.custom, security.selinux); prefix determines required capability
• --json and --explain are mutually exclusive

Example Output

whyno nginx read /var/log/app/current.log

  Subject: uid=33, gid=33, groups=[33]
  Operation: read
  Target: /var/log/app/current.log

  [PASS] Mount options      — rw on /var (ext4)
  [PASS] Filesystem flags   — no immutable/append-only
  [FAIL] Path traversal     — /var/log/app: o-x (other has no execute)
         Fix: chmod o+x /var/log/app  [impact: 3/6]
  [FAIL] DAC permissions    — mode 0640 owner=root group=root, nginx is other
         Fix: setfacl -m u:nginx:r /var/log/app/current.log  [impact: 1/6]
  [SKIP] POSIX ACLs         — no ACL on target (would pass after DAC fix)
  [PASS] Metadata           — not a metadata operation
  [SKIP] SELinux            — SELinux state not gathered
  [SKIP] AppArmor           — AppArmor state not gathered

For pid:N and svc: subjects with readable capabilities, the subject line includes caps=0x... (e.g. caps=0x0000000000000000).

Permission Layers Checked (v0.4)

All layers run unconditionally — no short-circuiting. This ensures the fix engine sees the full picture.

Not checked in v0.4

systemd sandboxing directives, seccomp BPF filters, full user namespace UID/GID mapping, per-domain SELinux permissive state (system-wide only). AppArmor capability rule mediation (libapparmor; deferred to v0.5). MAC layers require --features selinux or --features apparmor at build time.

Fix Suggestions

Fixes are ranked by security impact score (1 = least privilege, 6 = highest risk):

Fixes with score ≥ 5 include a ⚠ warning. chmod 777 and o+rwx are never suggested.

When multiple layers block, an ordered fix plan is generated (outermost layer first). Cascade simulation re-runs checks after each hypothetical fix to prune redundant suggestions.

Exit Codes

Same codes apply to --json mode. Degraded layers (unprivileged mode) do not force a non-zero exit.

JSON Schema

whyno schema prints the auto-generated JSON Schema for --json output. Use to validate consumer tooling against the current schema contract.

Capability Management

sudo whyno caps install    # Set CAP_DAC_READ_SEARCH on the binary
sudo whyno caps uninstall  # Remove the capability
whyno caps check           # Verify current state

Uses raw setxattr() / getxattr() / removexattr() syscalls with VFS cap v2 format (20 bytes). No libcap or setcap dependency. Filesystem must support extended attributes (ext4, xfs, btrfs — yes; NFS, FAT — no).