Skip to content

Latest commit

 

History

History
101 lines (72 loc) · 5.04 KB

SECURITY.md

File metadata and controls

101 lines (72 loc) · 5.04 KB

Security Overview

Security does not depend on enabling features. The core API is secure-by-default; the optional anchored feature is a convenience for virtual roots.

Always-on protections:

  • Lexical ./.. handling with floors (root/share/device) — never pops above floor
  • Symlink resolution with bounded depth (MAX_SYMLINK_DEPTH) and cycle detection
  • Windows ADS validation (placement rules, token checks, control/whitespace, length)
  • UNC/device namespace semantics; extended-length normalization on Windows
  • NUL byte rejection; Unicode preserved as text (no unintended normalization)
  • Percent encodings are not decoded (treated as text)

Anchored convenience (optional):

  • Reinterprets absolute inputs and clamps both relative and absolute symlink targets to the anchor (virtual filesystem semantics)
  • Shares the same hardened core; enabling it never weakens validation

Local CI exercises all modes: no features; --features anchored; and --features anchored,dunce. The dunce feature is presentation-only and never changes validation outcomes; unsafe cases remain UNC.

Threat Classes and Mitigations

  • Path Traversal / "Zip Slip"-like bypasses

    • Mitigation: Lexical .. processing with clamping. No decoding of percent encodings.
    • Tests: src/tests/platform_specific.rs, tests/anchored_blackbox_security.rs.

  • TOCTOU / Symlink Races

    • Mitigation: Deterministic resolver; no panics/hangs. Use race-resistant open flags for final writes (e.g., O_NOFOLLOW / CreateFileW policies).
    • Tests: tests/blackbox_toctou_attacks.rs, src/tests/anchored_security/windows_symlink.rs (swap to UNC/device).

  • Symlink Cycles / Depth Exhaustion

    • Mitigation: MAX_SYMLINK_DEPTH and cycle detection.
    • Tests: src/tests/symlink_depth.rs.

  • Windows NTFS ADS (Alternate Data Streams)

    • Mitigation: Early + late ADS validation; legitimate ADS (final component) accepted.
    • Tests: tests/windows_ads_traversal.rs, tests/ads_advanced_exploits.rs, tests/ads_comprehensive_security.rs, tests/ads_security_verification.rs.

  • Windows UNC Floors and Device Namespaces

    • Mitigation: Respect UNC floors; treat device namespaces lexically; preserve trailing spaces/dots under verbatim paths.
    • Tests: src/tests/platform_specific.rs, tests/blackbox_unc_attacks.rs, tests/blackbox_unc_corner_cases.rs.

  • Windows 8.3 Short Names

    • Mitigation: No expansion for non-existing suffixes; existing components probe normally.
    • Tests: src/tests/short_filename_detection.rs, Windows symlink + 8.3 suites.

  • NUL-Byte / Unicode / Control Characters

    • Mitigation: Reject embedded NUL; preserve Unicode as text; validate ADS tokens strictly.
    • Tests: src/tests/platform_specific.rs, tests/ads_*, tests/unicode_advanced_attacks.rs.

CVE-Class Mapping and Applicability

These CVE families are mitigated when using soft_canonicalize with a simple prefix policy — or anchored_canonicalize for a virtual root. Use race-resistant open flags to prevent TOCTOU during writes.

  • GNU tar path escape (e.g., CVE-2025-45582)

    • Mitigation: let base = soft_canonicalize(base_dir)?; let out = soft_canonicalize(base.join(member))?; reject if !out.starts_with(&base).
    • Tests: traversal/clamp suites listed above.

  • Archive symlink handling (e.g., CVE-2024-0406, CVE-2025-55188)

    • Mitigation: Clamp symlink targets; absolute targets are reinterpreted under anchor; cycles bounded; prefix policy for core.
    • Tests: anchored symlink suites; TOCTOU swaps.

  • Python tarfile traversal (e.g., CVE-2024-12718)

    • Mitigation: Clamp .. lexically; no percent-decoding.
    • Tests: anchored black-box traversal; core platform traversal tests.

  • Container volume symlink traversal (e.g., CVE-2025-9566)

    • Mitigation: virtual root semantics (anchored) or core + prefix policy; UNC/device quirks covered.
    • Tests: anchored symlink + UNC/device namespaces tests.

  • Windows ADS traversal (WinRAR-style)

    • Mitigation: strict ADS placement/token validation; legit final-component ADS accepted (local and UNC).
    • Tests: ADS suites listed above.

If you have details for CVE-2025-61882, please share; existing suites already cover the common traversal/symlink/ADS classes.

Secure Usage Pattern (no features required)

Archive extraction or "stay under base" policy:

let base = soft_canonicalize(base_dir)?; // absolute, normalized
let dest = soft_canonicalize(base.join(member_path))?; // resolve member under base
if !dest.starts_with(&base) {
    anyhow::bail!("escape attempt: {dest:?}");
}
// Open/write with race-resistant flags (O_NOFOLLOW / CreateFileW policies)

CI / Local

  • Run tests without features, with --features anchored, and with --features anchored,dunce.
  • Local helpers: bash ci-local.sh, ./ci-local.ps1.

References

  • Apache HTTP Server traversal normalization defects: CVE-2021-41773, CVE-2021-42013
  • NIST NVD references for cited CVEs

Notes:

  • Core and anchored flows are deterministic and panic-free.
  • Do not decode URL-encoded or other encodings before validation unless you explicitly allow them; if you do, validate containment after decoding.