testsAndMisc/linux_configuration/docs/DOCS-pacman-wrapper-security.md

Pacman Wrapper Security Enhancements

Overview

This document describes the security enhancements made to the pacman wrapper to prevent circumvention, particularly for VirtualBox installations.

Problem Statement

The original pacman wrapper had the following vulnerabilities:

1. Easy Policy Bypass: Users could edit the wrapper's helper libs (pacman_lock_lib.sh, pw_*.sh) to remove restrictions, then reinstall the wrapper.
2. VirtualBox Hosts Bypass: VirtualBox VMs do not inherit the host machine's /etc/hosts file, allowing users to bypass content filtering within VMs.
3. No Tamper Detection: The wrapper had no mechanism to detect if wrapper libs had been modified.

Solutions Implemented

1. Wrapper Lib Integrity Checks

File: periodic_background/digital_wellbeing/pacman/install_pacman_wrapper.sh

The installer now:

• Generates SHA256 checksums of all wrapper libs during installation
• Stores checksums in /var/lib/pacman-wrapper/policy.sha256
• Makes the integrity file immutable using chattr +i
• Makes the lock lib (pacman_lock_lib.sh) immutable

File: periodic_background/digital_wellbeing/pacman/pacman_wrapper.sh

The wrapper now:

• Verifies wrapper lib integrity on every invocation
• Compares current file checksums against stored checksums
• Blocks all operations if tampering is detected
• Displays security warnings and instructs user to reinstall

Benefits:

• Cannot bypass restrictions by editing wrapper libs
• Tampering is immediately detected and blocked
• Must use chattr -i (requires root) to modify files, making bypass harder

2. Hardcoded VirtualBox Restrictions

File: periodic_background/digital_wellbeing/pacman/pacman_wrapper.sh

Added hardcoded VirtualBox detection that cannot be bypassed by editing wrapper libs:

function is_virtualbox_package() {
  local pkg_lower="${1,,}"
  [[ $pkg_lower == *"virtualbox"* || $pkg_lower == *"vbox"* ]]
}

This function:

• Is compiled into the wrapper code itself
• Cannot be disabled by editing text files
• Catches all VirtualBox-related packages

Enhanced Challenge:

• 7-letter words
• 150 words to memorize
• 120-second timeout
• 45-second initial delay (psychological friction)
• 30-50 second post-challenge delay

Warning Messages:

• Explicit warning about /etc/hosts bypass potential
• Lists security measures that will be applied
• Emphasizes that restrictions are hardcoded

3. VirtualBox Hosts Enforcement

File: periodic_background/digital_wellbeing/virtualbox/enforce_vbox_hosts.sh

A new enforcement script that:

For Host Configuration:

• Configures all VMs to use host's DNS resolution (--natdnshostresolver1 on)
• Enables NAT DNS proxy (--natdnsproxy1 on)
• Adds /etc as a read-only shared folder to all VMs
• Tracks enforcement status with marker file

For Guest Configuration:

• Generates a startup script for VMs
• Mounts the shared /etc folder inside the VM
• Syncs host's /etc/hosts to VM's /etc/hosts
• Makes the hosts file read-only in the VM

Commands:

# Apply enforcement to all VMs
sudo enforce_vbox_hosts.sh enforce

# Check enforcement status
sudo enforce_vbox_hosts.sh status

# Generate script for VM guests
sudo enforce_vbox_hosts.sh generate-script

Auto-Integration: The pacman wrapper automatically:

• Detects VirtualBox installation after any install operation
• Locates and runs the enforcement script
• Applies enforcement to all existing VMs
• Creates enforcement marker to avoid repeated runs

4. Installation Integration

File: periodic_background/digital_wellbeing/pacman/install_pacman_wrapper.sh

The installer now:

• Installs VirtualBox enforcement script to /usr/local/share/digital_wellbeing/virtualbox/
• Makes the enforcement script executable
• Reports installation status to user

Security Guarantees

What's Protected

1. Wrapper libs cannot be easily modified:

   • Immutable attribute prevents casual editing
   • Requires chattr -i which requires root and knowledge
   • Changes are detected on next wrapper invocation

2. VirtualBox restrictions are hardcoded:

   • Cannot remove by editing wrapper libs
   • Would require modifying the wrapper code itself
   • Integrity checks would detect wrapper modification

3. VMs inherit host's content filtering:

   • DNS queries use host's resolution
   • /etc/hosts is synced from host to guest
   • Read-only mounting prevents VM modification

What's Still Vulnerable

1. Root access can bypass everything:

   • Root can chattr -i and modify files
   • Root can edit the wrapper script itself
   • Root can disable enforcement entirely
   • Mitigation: Not the goal; this is about self-discipline, not security against root

2. Wrapper replacement:

   • Could replace /usr/bin/pacman with direct link to /usr/bin/pacman.orig
   • Mitigation: Periodic maintenance services can detect and alert
   • Reinstallation would fail integrity check if files are modified

3. VM Guest Additions bypass:

   • If guest doesn't install VBox Guest Additions, shared folders won't work
   • Mitigation: DNS proxy still enforces host's DNS resolution
   • Manual hosts file sync would be needed

More detail

Split out to stay under the 250-line cap.

• Testing, usage and design philosophy