acl module (Windows)

use acl reads, compares and sets the owner and the DACL (the access control list) of Windows files, directories and registry keys, without starting PowerShell for Get-Acl or Set-Acl. The module is registered on every platform, so a playbook compiles and validates identically everywhere; on Linux and macOS every call returns a runtime error. It does not handle POSIX ACLs. Guard a call with a step condition on os.family or with sys::family() from the sys module. Every function returns Result[…, string]. A check script calls diff and an apply script calls set with the same spec. diff makes exactly the comparison set converges, so set followed by diff returns an empty list. lookup resolves an account name or SID string the way set does, without touching any object.

read

acl::read(path: string, opts: Value) -> Result[Value, string]

Reads the owner and the DACL of path. It returns a map with these keys.

Each entry map has these keys.

A NULL DACL, which grants everyone full access, reads as an empty entries list with null_dacl set to true. An empty DACL, which grants nobody anything, also has no entries but reads null_dacl: false. Check null_dacl before treating no entries as locked down. diff reports a NULL DACL as a difference.

set

acl::set(path: string, spec: Value, opts: Value) -> Result[unit, string]

Writes spec to path. The spec is a map with these keys.

Each entry is a map with these keys.

set replaces every explicit entry on the object with entries. It writes them in the Windows canonical order, deny entries before allow entries, each group in spec order, and drops exact duplicates. It never writes inherited entries: while inheritance is enabled, Windows recomputes them from the parent, and a directory or key passes its own inheritable entries on to its children. protected: true disables inheritance and drops the inherited entries. It does not copy them in as explicit entries, unlike the Explorer dialog; list every entry the object needs. protected: false enables inheritance again, and Windows restores the inherited entries from the parent. Changing the owner needs SeRestorePrivilege and SeTakeOwnershipPrivilege. set enables both on a thread-local copy of the process token for the call only, which works when config-weave runs as SYSTEM or as an administrator. When they cannot be enabled and the owner differs from the spec, set returns an Err naming the privileges and changes nothing. Inherit flags mean something only on a container. Windows strips them from the entries of a plain file, so an entry with inherit flags on a file is an Err from set and diff, rather than a change that never converges.

diff

acl::diff(path: string, spec: Value, opts: Value) -> Result[List[string], string]

Returns the differences between the object's descriptor and spec, one human-readable line each. An empty list means converged. The comparison is exactly the one set makes converge: - The owner is compared by SID, when the spec gives one. - The protected flag is compared when the spec gives it. - Explicit entries are compared as a set. Each entry is keyed by its SID, its kind, its mask with generic bits mapped, and its inherit flags. Order and duplicates do not count. A missing entry and an entry the spec does not list are each one line, so a changed right shows as both. - Inherited entries are ignored, unless the spec has protected: true and the DACL is already protected; then each inherited entry left over is a difference. diff takes the same spec and options as set and fails on the same errors.

lookup

acl::lookup(principal: string) -> Result[Value, string]

Resolves principal and returns a map {sid, name}, the shape of read's owner. principal is a SID string or an account name, resolved exactly as set resolves a spec principal (see Principals below), so the SID lookup returns is the SID set writes. sid is the SID string in canonical form. name is the account name in DOMAIN\name form, such as BUILTIN\Administrators for both Administrators and S-1-5-32-544, or a bare name for a well-known SID with no domain, such as Everyone. A SID string is not checked against the account database: a SID that does not resolve, such as one for a deleted account, returns its sid with name set to Value::Null. An account name that does not resolve is an Err with the same message set gives for it.

use acl
use value

// The SID of an account, to compare against acl::read's entries.
fn sid_of(name: string) -> Result[string, string] {
    let found = acl::lookup(name)?
    if let Some(v) = found.get("sid") {
        if let Some(s) = v.as_string() {
            return Ok(s)
        }
    }
    Err("acl::lookup returned no sid for '" + name + "'")
}

Options

opts is Value::Null or a map. target selects what path names: "file" (the default) for a file or directory, or "registry" for a registry key. view selects the registry view, as in the registry module: "native" (the default), "wow64_32" or "wow64_64". view is valid only with target: "registry". An unknown key or value is an Err. A registry path uses the registry module's syntax, HKLM\Software\Vendor\App. A file path is passed to Windows as written. acl does not follow a final symlink or junction: it opens the path with FILE_FLAG_OPEN_REPARSE_POINT, refuses any reparse point with an Err, and reads and writes the descriptor through that one handle, so the object cannot be swapped between the check and the write. Name the link's target instead. A missing file or key is an Err naming it.

Principals

A principal in a spec is a SID string (S-1-5-32-544) or an account name: BUILTIN\Administrators, Administrators, NT AUTHORITY\SYSTEM, DOMAIN\user, or .\user for an account on this computer. Account names are resolved with LookupAccountNameW. A principal that does not resolve is an Err naming it. Every comparison is by SID, so a spec may name an account either way. lookup resolves a principal the same way without touching any object.

Rights

Rights are lists of names, because wscript has no bitwise operators. The names are the .NET FileSystemRights and RegistryRights names in snake_case. A right name that is not valid for the target is an Err listing the valid names.

read turns a mask into names in two passes. First it takes each composite name, largest first (files: full_control, modify, read_and_execute, read, write; registry keys: full_control, read_key, write_key), when all of its bits are in the mask and it covers at least one bit no earlier name did. Then it adds the single-bit name of each bit still not covered, in bit order. So 0x1F01FF reads as ["full_control"] and 0x1200A9 as ["read_and_execute", "synchronize"]. Aliases are accepted in a spec but never reported. A bit with no name, such as ACCESS_SYSTEM_SECURITY, appears only in mask. Windows writes the generic bits (GENERIC_READ, GENERIC_WRITE, GENERIC_EXECUTE, GENERIC_ALL) into some entries, typically the inherit-only CREATOR OWNER entry. read maps them to the rights they grant on the target before reporting rights and mask: GENERIC_ALL on a file reads as full_control with mask 0x1F01FF, where Get-Acl shows 268435456. diff compares mapped masks too, and set writes a spec's generic bits already mapped. set writes the mask the spec gives and adds nothing. Explorer and .NET add synchronize to every file allow entry, and a process needs it to open a file for synchronous IO, so a file allow entry normally lists synchronize alongside its other rights.

A resource whose path parameter names the object and whose acl parameter holds the spec map checks with diff and applies with set.

use acl
use log
use value

fn target(params: Value) -> Result[string, string] {
    if let Some(v) = params.get("path") {
        if let Some(s) = v.as_string() {
            return Ok(s)
        }
    }
    Err("missing 'path' parameter")
}

fn want(params: Value) -> Result[Value, string] {
    match params.get("acl") {
        Some(v) => Ok(v),
        None => Err("missing 'acl' parameter"),
    }
}

fn check(params: Value) -> Result[CheckResult, string] {
    let changes = acl::diff(target(params)?, want(params)?, Value::Null)?
    for line in changes {
        log::info(line)
    }
    if changes.len() == 0 {
        Ok(CheckResult::AlreadyConfigured)
    } else {
        Ok(CheckResult::NotConfigured)
    }
}

fn apply(params: Value) -> Result[ApplyResult, string] {
    acl::set(target(params)?, want(params)?, Value::Null)?
    Ok(ApplyResult::Success)
}