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 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]
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 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.
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: /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/shEnvironment 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.
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
persistticket exists for the caller/target UID pair and the matched rule carriespersist.
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.
- 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. 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.
| 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://git.gay/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. 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.
| 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.
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 |
"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.
Voix is distributed under the Open Software License v3.0 (OSL-3.0). See LICENSE for details.