Privilege Policy Enforcement Runtime
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.
- 1. System Model
- 2. Core Responsibilities
- 3. Execution Tiers
- 4. Security Model
- 5. Configuration Model
- 6. Authentication Model
- 7. Design Constraints
- 8. Compatibility Note
- 9. Build and Installation
- 10. Usage
- 11. CLI Reference
- 12. Documentation
- 13. Troubleshooting
- 14. License
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 · acct_mgmt always]
C --> D[Persisted Ticket Check<br/>persist option]
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]
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().
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.
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 (≥ 3) |
| Rationale | Compatibility with system-level operations | Least privilege |
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.
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: /tmp
paths:
- /bin
- /sbin
- /usr/bin
- /usr/sbin
acl:
group:
wheel:
- action: permit
options: [trust]
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/shAuthentication is delegated to the system PAM stack under the voix service context. Authentication is required unless explicitly bypassed via policy-level trust/nopass options or a fresh persist ticket. Voix does not implement its own credential storage or verification system.
Important
Account validation (pam_acct_mgmt) runs on every invocation, even for
trust/nopass rules — expired or disabled accounts are always denied.
- 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
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.
| 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) |
-
Clone the repository:
git clone https://github.com/Veridian-Zenith/Voix.git && cd Voix
-
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) -
Install (required for the setuid bit):
sudo cmake --install build
- Arch Linux: install from the AUR —
paru -S voixoryay -S voix. - Other distributions: see packaging/ for guidance.
After installation, ensure the PAM configuration at /etc/pam.d/voix is aligned with your security policy.
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.
| Flag | Long form | Description |
|---|---|---|
| -h | --help |
Show help |
| -v | --version |
Show version |
-C FILE |
--config |
Configuration file (default /etc/voix.conf) |
| -c | --check-config |
Validate the configuration file |
| -E | --preserve-env |
Preserve the environment (requires a keepenv grant) |
| -H | --home |
Set HOME to the target user's home directory |
| -i | --login |
Execute in a login shell environment |
| -k | Invalidate the persisted authentication timestamp | |
| -l | --list |
List permitted commands (deny-aware) |
| -n | Non-interactive mode | |
| -s | Execute the user's shell (ascend to shell) | |
-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 exit codes.
Consult the following technical guides:
| Document | Content |
|---|---|
| THREATS.md | Threat model, TCB metrics, system architecture, syscall filtering |
| 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 | Using Voix as a functional sudo alternative |
| packaging/README.md | Distribution and AUR packaging |
"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 (expired password, locked account) are also reported here — account
validation always 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.
Voix is distributed under the Open Software License v3.0 (OSL-3.0). See LICENSE for details.