Security Assurance

token-privilege is a security-sensitive crate. This page documents the threat model, security properties, and the measures in place to maintain them.

• Threat Model
  • In Scope
  • Out of Scope
• Security Properties
  • Read-Only Access
  • Unsafe Code Isolation
  • No Panics, No Unwraps
  • Documented Unsafe Blocks
  • Non-Exhaustive Error Type
• Static Analysis
  • Clippy Configuration
  • Formatting
• Dependency Auditing
  • cargo-audit
  • cargo-deny
  • Minimal Dependencies
• Test Coverage
• CI Pipeline
• Reporting Security Issues

Threat Model

In Scope

• Incorrect privilege reporting. A bug that reports a privilege as enabled when it is not (or vice versa) could lead to incorrect authorization decisions by consuming applications.
• Resource leaks. Failing to close a token handle could leak kernel resources.
• Memory safety violations. Incorrect FFI usage could lead to buffer overflows, use-after-free, or other undefined behavior.
• Denial of service. Pathological inputs (e.g., extremely long privilege names) should not cause panics or unbounded allocations.

Out of Scope

• Privilege escalation. This crate is read-only; it never calls AdjustTokenPrivileges or any API that modifies the process token. It cannot elevate, enable, disable, or remove privileges.
• Malicious OS behavior. If the Windows kernel itself returns incorrect data, that is outside the crate’s control.
• Side-channel attacks. Timing differences between privilege checks are not considered a threat for this use case.

Security Properties

Read-Only Access

The crate opens process tokens with TOKEN_QUERY access only. No write operations are performed. The token state is never modified.

Unsafe Code Isolation

All unsafe blocks are confined to src/ffi.rs. The public API is entirely safe. Consumers can use #![forbid(unsafe_code)] in their own crates.

See the Safety Contract for a detailed audit of every unsafe block.

No Panics, No Unwraps

The following Clippy lints are set to deny in Cargo.toml:

• clippy::panic – no panic!(), todo!(), or unimplemented!() in non-test code.
• clippy::unwrap_used – no .unwrap() calls; all fallible operations use Result propagation.

This ensures the crate returns structured errors instead of aborting the process.

Documented Unsafe Blocks

The lint clippy::undocumented_unsafe_blocks = "deny" requires every unsafe block to have a // SAFETY: comment explaining why the operation is sound.

Non-Exhaustive Error Type

TokenPrivilegeError is #[non_exhaustive], allowing new error variants to be added in future releases without breaking downstream match arms. This prevents consumers from assuming they handle all possible errors.

Static Analysis

Clippy Configuration

The crate enables aggressive Clippy lint groups:

Additional security-focused lints include as_conversions, cast_ptr_alignment, indexing_slicing, and arithmetic_side_effects.

Formatting

rustfmt is configured for the 2024 edition and style. Formatting is checked in CI via just fmt-check.

Dependency Auditing

cargo-audit

cargo audit checks for known vulnerabilities in the dependency tree. Run locally with:

just audit

This is also enforced in CI via the audit.yml workflow.

cargo-deny

cargo deny check validates licenses, bans problematic crates, and checks for security advisories. Run locally with:

just deny

Minimal Dependencies

The crate has a single runtime dependency: thiserror for error derivation. The windows crate is only pulled in on Windows targets via [target.'cfg(windows)'.dependencies].

Dev dependencies (proptest, tempfile) are not included in production builds.

Test Coverage

The project targets 85% line coverage, enforced by:

just coverage-check

Coverage is generated with cargo-llvm-cov and reported to Codecov in CI. See the Testing page for details on the testing strategy.

CI Pipeline

Every push to main and every pull request runs through:

1. Quality gate – rustfmt check and Clippy with -D warnings.
2. Test suite – cargo nextest run on Ubuntu.
3. Cross-platform tests – Linux, macOS, and Windows runners.
4. Coverage – cargo-llvm-cov with Codecov upload.
5. Audit – cargo audit for known vulnerabilities.
6. Scorecard – OpenSSF Scorecard for supply chain security.
7. Security scanning – Additional security workflow checks.

Reporting Security Issues

If you discover a security vulnerability, please report it responsibly via GitHub’s private vulnerability reporting feature on the repository: https://github.com/EvilBit-Labs/token-privilege/security