scripts/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 pacman_greylist.txt or pacman_blocked_keywords.txt 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 policy files had been modified.

Solutions Implemented

1. Policy File Integrity Checks

File: scripts/digital_wellbeing/pacman/install_pacman_wrapper.sh

The installer now:

• Generates SHA256 checksums of all policy files during installation
• Stores checksums in /var/lib/pacman-wrapper/policy.sha256
• Makes the integrity file immutable using chattr +i
• Makes policy files (pacman_blocked_keywords.txt, pacman_greylist.txt) immutable

File: scripts/digital_wellbeing/pacman/pacman_wrapper.sh

The wrapper now:

• Verifies policy file 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 policy files
• Tampering is immediately detected and blocked
• Must use chattr -i (requires root) to modify files, making bypass harder

2. Hardcoded VirtualBox Restrictions

File: scripts/digital_wellbeing/pacman/pacman_wrapper.sh

Added hardcoded VirtualBox detection that cannot be bypassed by editing policy files:

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 (harder than greylist's 6-letter words)
• 150 words to memorize (more than greylist's 120)
• 120-second timeout (longer than greylist's 90s)
• 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: scripts/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: scripts/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. Policy files 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 policy files
   • 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

Testing

Run the test suite:

bash tests/test_pacman_wrapper_security.sh

Tests verify:

• Script syntax validity
• Integrity check function exists and is called
• Hardcoded VirtualBox check exists
• VirtualBox challenge function exists
• Immutable file attributes are set
• VirtualBox enforcement integration

Usage

Installation

cd scripts/digital_wellbeing/pacman
sudo ./install_pacman_wrapper.sh

This will:

• Install the wrapper and policy files
• Generate integrity checksums
• Make policy files immutable
• Install VirtualBox enforcement script

Updating Policy Files

If you need to legitimately update policy files:

# Remove immutable attribute
sudo chattr -i /usr/local/bin/pacman_blocked_keywords.txt
sudo chattr -i /usr/local/bin/pacman_greylist.txt

# Edit files as needed
sudo nano /usr/local/bin/pacman_greylist.txt

# Reinstall wrapper to update checksums
cd scripts/digital_wellbeing/pacman
sudo ./install_pacman_wrapper.sh

# This will regenerate checksums and reapply immutable attributes

VirtualBox Enforcement

After installing VirtualBox, the wrapper will automatically apply enforcement. You can also manually run:

sudo /usr/local/share/digital_wellbeing/virtualbox/enforce_vbox_hosts.sh enforce

For VM guests, copy the generated script and add to startup:

# On host
sudo /usr/local/share/digital_wellbeing/virtualbox/enforce_vbox_hosts.sh generate-script /tmp/vbox_sync.sh

# Copy to VM and install
sudo cp /tmp/vbox_sync.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/vbox_sync.sh

# Add to crontab or systemd
@reboot /usr/local/bin/vbox_sync.sh

Design Philosophy

These enhancements follow the principle of defense in depth:

• Layer 1: Immutable policy files (prevents casual editing)
• Layer 2: Integrity checksums (detects tampering)
• Layer 3: Hardcoded restrictions (cannot bypass via files)
• Layer 4: VirtualBox enforcement (prevents VM bypass)
• Layer 5: Psychological friction (word challenges, delays)

Each layer adds difficulty, making circumvention progressively harder while maintaining usability for legitimate use.

Future Enhancements

Potential improvements:

1. Digital signatures: Sign the wrapper script itself to detect modifications
2. Remote policy updates: Fetch policy files from a trusted source
3. Logging: Log all wrapper invocations and challenges to detect patterns
4. Time-based restrictions: Different rules for different times/days
5. Multi-factor challenges: Combine word challenges with other verification methods