whyno-core 0.3.0

Permission check pipeline, fix engine, and state types for Linux filesystem permissions.

whyno-core is the pure-logic engine behind the whyno permission debugger. It takes a pre-gathered snapshot of filesystem state and deterministically evaluates whether an operation is allowed — with zero I/O at check time. When a check fails, it generates least-privilege fix suggestions ranked by impact.

Overview

whyno-core answers one question: "Why can't this user do this to that file?"

Given a SystemState (subject identity, path walk, mount table, MAC state, and the requested operation), the check pipeline evaluates seven layers of Linux permission enforcement:

1. Mount — read-only, noexec, nosuid filesystem options
2. FsFlags — inode flags (immutable, append-only)
3. Traversal — +x on every ancestor directory
4. DAC — discretionary access control (uid/gid/mode bits + capability overrides)
5. ACL — POSIX.1e access control lists with mask evaluation
6. SELinux — mandatory access control (feature-gated)
7. AppArmor — mandatory access control (feature-gated)

Each layer returns Pass, Fail, or Degraded (state unavailable). The fix engine then generates repair suggestions for every failed layer, simulates their cascading effects, and prunes redundant fixes.

Features

• Pure logic, zero I/O — all filesystem state is gathered externally and passed in via SystemState
• Seven-layer check pipeline — mount options, fs flags, traversal, DAC, ACL, SELinux, AppArmor
• Capability-aware DAC — models CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, and more
• POSIX.1e ACL evaluation — full mask interaction, named user/group entries, effective permission computation
• Fix engine — generates chmod, chown, setfacl, mount -o remount, and chattr suggestions
• Impact scoring — fixes ranked 1 (least privilege) to 6 (broadest impact)
• Cascade simulation — applies fixes to cloned state, prunes cross-layer redundancies
• Serializable — all types derive Serialize for JSON output
• JSON Schema — all public types derive JsonSchema via schemars

Installation

[dependencies]
whyno-core = "0.3"

Quick Start

Build a SystemState

The check pipeline operates on a SystemState struct built from gathered OS data. The pipeline performs no I/O.

use whyno_core::state::{
    SystemState, Probe,
    subject::ResolvedSubject,
    path::{PathComponent, StatResult, FileType},
    mount::{MountTable, MountEntry, MountOptions},
    mac::MacState,
};
use whyno_core::operation::Operation;

let subject = ResolvedSubject {
    uid: 1000,
    gid: 1000,
    groups: vec![33, 44],
    capabilities: Probe::Unknown,
};

let walk = vec![
    PathComponent {
        path: "/".into(),
        stat: Probe::Known(StatResult {
            mode: 0o755, uid: 0, gid: 0,
            dev: 1, nlink: 2, file_type: FileType::Directory,
        }),
        acl: Probe::Unknown,
        flags: Probe::Unknown,
        mount: Some(0),
    },
    PathComponent {
        path: "/var/log/app.log".into(),
        stat: Probe::Known(StatResult {
            mode: 0o640, uid: 0, gid: 44,
            dev: 1, nlink: 1, file_type: FileType::Regular,
        }),
        acl: Probe::Unknown,
        flags: Probe::Unknown,
        mount: Some(0),
    },
];

let mounts = MountTable(vec![MountEntry {
    mount_id: 1,
    device: 1,
    mountpoint: "/".into(),
    fs_type: "ext4".into(),
    options: MountOptions { read_only: false, noexec: false, nosuid: false },
}]);

let state = SystemState {
    subject,
    walk,
    mounts,
    operation: Operation::Read,
    mac_state: MacState::default(),
};

Run Checks

use whyno_core::checks::run_checks;

let report = run_checks(&state);

if report.is_allowed() {
    println!("Access allowed");
} else {
    for layer in report.failed_layers() {
        println!("Blocked by: {layer:?}");
    }
}

Generate Fixes

use whyno_core::fix::generate_fixes;

let plan = generate_fixes(&report, &state);

for fix in &plan.fixes {
    println!("[impact {}] {:?} — {}", fix.impact, fix.action, fix.description);
}

for warning in &plan.warnings {
    println!("⚠ {warning}");
}

Key Types

State Types

Check Types

Fix Types

Check Pipeline

run_checks() evaluates layers in a fixed order. All layers always run — no short-circuiting.

Feature Flags

Dependencies

• serde + serde_json — serialization for all public types
• schemars — JsonSchema derive for schema generation
• thiserror — structured error types
• enum-map — fixed-size enum-keyed maps for layer results

Minimum Supported Rust Version

Rust 1.78. Pure Rust, no platform-specific code — compiles on any target rustc supports.