Skip to content
Veridian-ZenithPublic

About

Deterministic privilege policy enforcement runtime for Linux, built with C++26 and Clang

Resources

Code of conduct

Contributing

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Voix

Privilege Policy Enforcement Runtime

Tests CodeQL Release AUR version License

Voix is a user-space Privilege Policy Enforcement Runtime designed to evaluate authorization policies, construct controlled execution contexts, and enforce privilege and syscall-level boundaries during command execution on Unix-like systems.

It operates as a deterministic execution broker between user intent and privileged system operations. While it may provide compatibility with sudo-like workflows, it is architecturally distinct from traditional privilege escalation utilities and is not intended as a drop-in wrapper.


Table of Contents


1. System Model

Voix implements a staged execution pipeline for privileged command invocation:

flowchart TB
    A[CLI Parsing] --> B[Policy Evaluation<br/>first-match ACL]
    B --> C[Authentication<br/>PAM credential · persist ticket]
    C --> D[Account Validation<br/>pam_acct_mgmt for caller]
    D --> E[Privilege Transition<br/>setgroups / setgid / setuid]
    E --> F[Capability Reduction<br/>libcap]
    F --> G[Syscall Confinement<br/>NNP always · seccomp]
    G --> H[Environment Sanitization<br/>whitelist + umask 022]
    H --> I[Process Execution<br/>execve]
Loading

Each stage is strictly ordered and failure-atomic where applicable. Any violation of required invariants results in termination prior to execution.

Note

All identity resolution happens before fork(); the child performs no name-service lookups between fork() and execve().


2. Core Responsibilities

Voix is responsible for:

  • Evaluating structured authorization policies (YAML-based ACL model)
  • Determining whether an execution request is permitted
  • Constructing a constrained execution context for permitted operations
  • Applying privilege transitions and security hardening based on target execution tier
  • Delegating authentication to PAM where required
  • Enforcing syscall and capability restrictions for non-privileged execution targets
  • Executing the final binary within the prepared context

Voix does not interpret shell logic, provide a scripting environment, or manage long-lived sessions beyond optional authentication persistence mechanisms.


3. Execution Tiers

Voix defines two primary execution tiers, selected by the target identity and the matched rule's profile:.

Privileged target Non-privileged target
Selected for core.unconfined_targets, or an explicit profile: privileged Everything else
Capabilities Full Linux capabilities retained All capabilities dropped
No-new-privs Not applied PR_SET_NO_NEW_PRIVS enforced
Seccomp No filtering applied Syscall blacklist applied
Resource limits None imposed by Voix RLIMIT_* policies enforced
Environment Preserved verbatim for unconfined targets Sanitized to a restricted whitelist
Inherited FDs Not closed Closed except the pinned executable (fd 3)
Rationale Compatibility with system-level operations Least privilege

Note

The non-privileged environment is rebuilt from a whitelist unless the matched rule grants keepenv or the profile sets scrub_environment: false. keepenv preserves the caller's variables minus known loader/interpreter names.


4. Security Model

Voix follows a defense-in-depth model consisting of:

  • Policy-driven authorization (ACL evaluation)
  • System authentication delegation (PAM integration)
  • Privilege separation via the fork/exec transition
  • Capability reduction via libcap
  • Syscall filtering via libseccomp
  • Environment sanitization to eliminate injection vectors
  • Explicit denial of privilege-escalation paths after the transition

The security boundary is enforced at process creation time and is not dynamically adjusted after execution begins.


5. Configuration Model

Voix uses a structured YAML configuration file (/etc/voix.conf) to define execution policy. Configuration is divided into three sections:

Section Purpose
core Execution environment parameters (trusted paths, sanctuary, unconfined targets)
acl Authorization rules for users and groups
security Named profiles and the global blocklist

Policies are evaluated deterministically and matched against: user identity, group membership, the requested command path, and optional argument constraints.

Configuration example

For the full annotated example, see config/voix.conf — the canonical, installed copy.

# Voix configuration
core:
  sanctuary: /var/lib/voix
  paths:
    - /bin
    - /sbin
    - /usr/bin
    - /usr/sbin
  # Empty by default: unconfined targets bypass most confinement.
  unconfined_targets: []

# Empty by default: a fresh install permits nothing.
acl:
  user: {}
  group: {}

security:
  profiles:
    restricted:
      retain_full_capabilities: false
      enable_seccomp: true
      enable_resource_limits: true
      scrub_environment: true
    privileged:
      retain_full_capabilities: true
      enable_seccomp: false
      enable_resource_limits: false
      scrub_environment: false
  blocklist:
    - /bin/sh

Environment behavior is controlled by preserve_full_environment, the profile's scrub_environment, and the rule's keepenv.

Warning

The shipped sample is closed by default: no user or group is trusted, no target is unconfined, and the ACL contains no permits. Add only the rules you need, then validate the result with voix --check-config.


6. Authentication Model

Authentication is delegated to the system PAM stack under the voix service context. A credential check is required unless one of the following applies:

  • the matched rule carries trust/nopass;
  • the invoking user is root;
  • a fresh persist ticket exists for the caller/target UID pair and the matched rule carries persist.

Tickets are consulted before -n rejects an invocation, so a non-interactive run can reuse an existing ticket but can never prompt. Only a successful pam_authenticate() mints or refreshes a ticket; trust/nopass/root skips and reused tickets never do.

Voix does not implement its own credential storage or verification system; persist stores only a timestamp.

Important

pam_acct_mgmt runs for the invoking user on every invocation, including trust/nopass paths, so an expired or disabled caller is denied. The target account is validated separately with its own PAM handle. That target account check is not credential verification and is never treated as proof that the target's password was checked. See Known Limitations.


7. Design Constraints

  • Implemented in C++26
  • Built exclusively with the LLVM/Clang toolchain
  • Minimal external dependency surface
  • Deterministic policy evaluation
  • No dynamic plugin execution model
  • No embedded shell interpreter

8. Compatibility Note

Voix may be used in workflows similar to sudo or doas for operational familiarity. However, this is a compatibility layer of usage, not a reflection of its internal architecture or design intent. Voix does not implement the full sudo/doas command-line surface; the provides/conflicts entries in the AUR packages exist for dependency resolution, not as a claim of CLI equivalence.


9. Build and Installation

Prerequisites

Requirement Notes
LLVM/Clang Clang 22+; GCC is not supported
CMake v3.30+ (C++26 standard features)
Ninja Build generator
yaml-cpp, pam Required runtime/development dependencies
libcap, libseccomp Optional (default ON)

Build Instructions

  1. Clone the repository:

    git clone https://git.gay/Veridian-Zenith/Voix.git && cd Voix
  2. Configure and build:

    cmake -B build -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release
    ninja -C build -j$(nproc)
  3. Install (required for the setuid bit):

    sudo cmake --install build

Distribution Specifics

  • Arch Linux: install from the AUR — paru -S voix or yay -S voix.
  • Other distributions: see packaging/ for guidance.

10. Usage

After installation, ensure the PAM configuration at /etc/pam.d/voix is aligned with your security policy. The shipped /etc/voix.conf is closed by default — no ACL permits and no unconfined targets — so add only the rules you need and validate with voix --check-config.

voix <command> [args...]

The most common flags are -u, -n, -k, -C, and -l; the full table is in CLI Reference, and voix --help prints the built-in summary.


11. CLI Reference

Flag Long form Description
-h --help Show help
-v --version Show version
-C FILE --config Configuration file (default /etc/voix.conf); must be a regular root-owned file with no group/world write bits
-c --check-config Validate the configuration file
-E --preserve-env Accepted for compatibility; has no effect. Environment preservation is enabled by a keepenv rule or a profile with scrub_environment: false
-H --home Set HOME to the target user's home directory. Without it, HOME is not set to the target's home
-i --login Run via the target's login shell. Forces HOME and SHELL to the target's values, even with keepenv or an unconfined target
-k Invalidate all persisted authentication tickets for the invoking user
-l --list List permit rules for the current user with runtime first-match deny-awareness (fully covered permits omitted, partial coverage marked)
-n Non-interactive mode; reuse a valid persisted ticket if one exists, otherwise fail rather than prompt
-s Execute the target account's passwd shell (fallback /bin/sh); the invoking user's $SHELL is ignored
-u USER Execute as a specific target user (default: root)
--run-tests Run the built-in test suite (testing builds only)

See docs/CLI.md for the full reference, including stable exit codes and logging behavior.


12. Documentation

Consult the following technical guides:

Document Content
THREATS.md Threat model, TCB metrics, system architecture, syscall filtering, known limitations
CONTRIBUTING.md Build, lint, and test workflow; roadmap and design decisions
docs/CLI.md Command-line interface and flag specifications
docs/CONFIG.md Detailed guidance on /etc/voix.conf
docs/SUDO.md sudo/doas compatibility guide and caveats
packaging/README.md Distribution and AUR packaging

13. Troubleshooting

"PAM authentication failed"

Verify that the PAM configuration at /etc/pam.d/voix matches your system's authentication stack (most distributions can include system-auth). Account-level failures for the invoking user (expired password, locked account) are also reported here — pam_acct_mgmt runs even for trust rules.

"Permission denied"

Check the user/group authorization rules in /etc/voix.conf. Remember that rules without a target: field only apply to the default target (root); switching users requires an explicit target: USER rule. Validate your policy with voix -c.

"Insufficient privileges" at startup

The binary must be setuid root (mode 4755) or carry equivalent file capabilities. Reinstall with sudo cmake --install build.


14. License

Voix is distributed under the Open Software License v3.0 (OSL-3.0). See LICENSE for details.

About

Deterministic privilege policy enforcement runtime for Linux, built with C++26 and Clang

Resources

Code of conduct

Contributing

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages