testsAndMisc/linux_configuration/scripts/digital_wellbeing/pacman/README_FOR_LLM.md

Pacman Wrapper Security System - LLM Reference Guide

For AI assistants: This document explains the pacman wrapper architecture so you can make correct modifications.

System Purpose

Intercept all pacman commands to:

1. Block installation of restricted packages (browsers, games, etc.)
2. Require challenges for greylisted packages
3. Enforce hosts file sharing on VirtualBox VMs
4. Auto-setup maintenance services if missing
5. Handle stale database locks gracefully

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         PACMAN WRAPPER                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  User runs: pacman -S firefox                                       │
│                    ↓                                                │
│  /usr/bin/pacman (symlink) → pacman_wrapper.sh                      │
│                    ↓                                                │
│  1. Verify policy file integrity (SHA256)                           │
│  2. Check if package matches blocked keywords                       │
│  3. Check if package requires challenge (greylist)                  │
│  4. Run hosts-guard pre-unlock hook                                 │
│  5. Execute real pacman: /usr/bin/pacman.orig                       │
│  6. Run hosts-guard post-relock hook                                │
│  7. Remove any blocked packages that slipped through                │
│  8. Enforce VirtualBox hosts if vbox detected                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

File Locations

File	Purpose
/usr/bin/pacman	Symlink to wrapper
/usr/bin/pacman.orig	Real pacman binary
pacman_wrapper.sh	Main wrapper script (823 lines)
install_pacman_wrapper.sh	Installer script
pacman_blocked_keywords.txt	Substrings that cause blocking
pacman_whitelist.txt	Exact names that bypass blocking
pacman_greylist.txt	Packages requiring challenge
words.txt	Word scramble challenge dictionary
/var/lib/pacman-wrapper/policy.sha256	Integrity checksums

Policy Files Explained

pacman_blocked_keywords.txt

# Lines starting with # are comments
# Any package containing these substrings is BLOCKED
firefox
brave
chromium
youtube
stremio

If user tries pacman -S firefox-developer-edition, it's blocked because it contains "firefox".

pacman_whitelist.txt

# Exact package names that bypass keyword blocking
minizip          # Contains nothing bad but might match a pattern
python-requests  # Safe despite containing blocked substrings

pacman_greylist.txt

# Packages requiring word scramble challenge
# Currently empty - add packages here for challenge requirement

Hardcoded Security Checks

These checks are in the script itself and cannot be bypassed by editing policy files:

VirtualBox Check

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

• Detects any package with "virtualbox" or "vbox" in name
• Requires word scramble challenge (7-letter words, 120s timeout)
• Auto-enforces hosts file sharing on all VMs after install

Steam Check

function is_steam_package() {
  [[ $1 == "steam" ]]
}

• Only exact match "steam" (not steam-native-runtime etc.)
• Weekend only - blocked Monday through Friday 4PM
• Requires word scramble challenge (5-letter words, 60s timeout)

Word Scramble Challenge

Used for Steam, VirtualBox, and greylisted packages:

Challenge: Words with 5 letters
Here are 160 random words. Remember them:
APPLE   BRAVE   CHAIR   DANCE   ...

One of those words has been scrambled to: ELPPA
Unscramble the word to proceed (you have 60 seconds):

Parameters vary by package type:

Package Type	Word Length	Words Shown	Timeout	Initial Delay
Steam	5	160	60s	0-20s
VirtualBox	7	150	120s	0-45s
Greylist	6	120	90s	0-30s

Integrity Verification

On every invocation, the wrapper verifies policy files haven't been tampered with:

verify_policy_integrity() {
  # Reads /var/lib/pacman-wrapper/policy.sha256
  # Compares SHA256 of each policy file
  # If mismatch: BLOCKS all operations
}

If tampering detected:

SECURITY WARNING: Policy file integrity check failed!
CRITICAL: Policy files have been tampered with!
Wrapper operation DENIED. Please reinstall using: sudo install_pacman_wrapper.sh

Hosts Integration

The wrapper integrates with the hosts guard system:

pre_unlock_hosts() {
  # Called before any transaction (-S, -U, -R)
  /usr/local/share/hosts-guard/pacman-pre-unlock-hosts.sh
}

post_relock_hosts() {
  # Called after transaction completes
  /usr/local/share/hosts-guard/pacman-post-relock-hosts.sh
}

This allows package installations to modify /etc/hosts temporarily (e.g., for network setup) while maintaining protection.

Common Tasks

Adding a Blocked Package

1. Edit pacman_blocked_keywords.txt:

echo "newkeyword" >> pacman_blocked_keywords.txt

2. Reinstall wrapper to update checksums:

sudo ./install_pacman_wrapper.sh

Whitelisting a Package

If a legitimate package is being blocked (e.g., python-firefox-sync blocked by "firefox" keyword):

1. Edit pacman_whitelist.txt:

echo "python-firefox-sync" >> pacman_whitelist.txt

2. Reinstall wrapper:

sudo ./install_pacman_wrapper.sh

Adding a Challenge Requirement

1. Edit pacman_greylist.txt:

echo "suspicious-package" >> pacman_greylist.txt

2. Reinstall wrapper.

Bypassing the Wrapper (Emergency)

If wrapper is broken and you need real pacman:

sudo /usr/bin/pacman.orig -S package

Warning: This bypasses all security checks.

Post-Transaction Cleanup

After every transaction, the wrapper:

1. Scans installed packages for blocked keywords
2. Removes any that match (shouldn't happen normally)
3. Scans for greylisted packages and removes them
4. Checks if VirtualBox is installed and enforces hosts

remove_installed_blocked_packages() {
  mapfile -t installed_names < <("$PACMAN_BIN" -Qq)
  for name in "${installed_names[@]}"; do
    if is_blocked_package_name "$name"; then
      pacman -Rns --noconfirm "$name"
    fi
  done
}

Stale Lock Handling

If /var/lib/pacman/db.lck exists but no pacman is running:

• Interactive: Prompts user to remove (15s timeout)
• Non-interactive (--noconfirm): Auto-removes if lock is >10 minutes old
• If another pacman is actually running: Blocks with error

Maintenance Auto-Setup

On first run, wrapper checks if periodic maintenance services exist:

ensure_periodic_maintenance() {
  # Checks: periodic-system-maintenance.timer
  #         periodic-system-startup.service
  #         hosts-file-monitor.service
  # If missing: runs setup_periodic_system.sh
}

Known Gaps (TODO)

1. ❌ google-chrome and google-chrome-stable not in blocked list
2. ❌ No automatic LeechBlock installation when browsers detected
3. ❌ User can download and install .deb/.tar.gz manually
4. ❌ AUR packages bypass wrapper (yay/paru call pacman internally)

Debugging

Check if wrapper is installed

ls -la /usr/bin/pacman
# Should show: /usr/bin/pacman -> /path/to/pacman_wrapper.sh

ls -la /usr/bin/pacman.orig
# Should exist and be the real binary

Test policy integrity

cat /var/lib/pacman-wrapper/policy.sha256
sha256sum /path/to/pacman_blocked_keywords.txt
# Hashes should match

Verbose mode

The wrapper outputs colored status messages to stderr. To see them:

pacman -S package 2>&1 | cat

DO NOT

1. ❌ Edit policy files without reinstalling wrapper (breaks integrity check)
2. ❌ Remove /usr/bin/pacman.orig (breaks all pacman operations)
3. ❌ Symlink pacman to something other than the wrapper
4. ❌ Clear /var/lib/pacman-wrapper/ without understanding consequences