testsAndMisc/linux_configuration/docs/security-hardening/DOCS-05-llm-readmes.md
Krzysztof kuhy Rudnicki f15f00f3fe Re-point paths for the ~ reorganisation (home-tidy)
Also bumps the 16 meta/requirements pins the freshness gate flagged
(anthropic 1.5.0, numpy 2.5.3, pytest-randomly 5, flake8-bugbear 26.9.9,
ruff 0.16.7, pyright 1.1.414, selenium 4.49.0, hypothesis 6.168.0, lxml
6.1.3, pipdeptree 4.2.5, the two types-* stubs) and Flutter 3.47.3 in
meta/.fvmrc. One test still expected the pre-move ~/mcp-servers path.

The pre-commit hook fed .zsh files to shfmt and shellcheck, neither of
which parses zsh (SC2148/SC1071), so no zsh file could be committed since
the hook was tightened on 2026-08-22; those now get `zsh -n` instead. The
hook's own shfmt pass also staged its reformat of 8 shell files.

CI_GREEN_SKIP because main is red on exactly the dependency-freshness
finding this commit fixes, which is the documented use of that flag.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AwtowrowDXx6ccmWVPkCaF
2026-09-11 20:50:19 +02:00

100 lines
2.2 KiB
Markdown

## Part 5: LLM README Files
These should be created in the respective directories:
### [hosts/guard/README_FOR_LLM.md](to be created)
```markdown
# Hosts Guard System - LLM Reference
## Purpose
Prevent tampering with /etc/hosts to maintain website blocking.
## Architecture
```
/etc/hosts (immutable) ←── canonical (/usr/local/share/locked-hosts)
↑
path watcher detects changes
↓
enforce-hosts.sh restores
````
## Critical Files
| File | Purpose | Protected By |
|------|---------|--------------|
| /etc/hosts | Actual hosts file | chattr +i, bind mount |
| /usr/local/share/locked-hosts | Canonical copy | chattr +i |
| /etc/hosts.custom-entries.state | Tracks blocked domains | chattr +i |
## Commands to Know
```bash
# Check protection status
lsattr /etc/hosts
systemctl status hosts-guard.path hosts-bind-mount.service
# Legitimate edit (with delay)
sudo /usr/local/sbin/unlock-hosts
# Reinstall/repair
sudo ~/src/hosts-blocker/install.sh
sudo ~/src/hosts-blocker/guard/setup_hosts_guard.sh
````
## DO NOT
- Edit /etc/nsswitch.conf (bypasses hosts entirely)
- Stop hosts-guard.path without understanding consequences
- Remove entries from install.sh without state file cleanup
````
### [periodic_background/digital_wellbeing/pacman/README_FOR_LLM.md](to be created)
```markdown
# Pacman Wrapper - LLM Reference
## Purpose
Intercept pacman to enforce package installation policies.
## Architecture
````
/usr/bin/pacman (symlink) → pacman_wrapper.sh
↓
/usr/bin/pacman.orig (real)
````
## Policy Files
| File | Purpose |
|------|---------|
| pacman_blocked_keywords.txt | Substring match = always blocked |
| pacman_whitelist.txt | Exact names that bypass blocking |
| pacman_greylist.txt | Requires challenge to install |
| words.txt | Word scramble challenge source |
## Hardcoded Checks (cannot bypass via files)
- VirtualBox → security challenge + hosts enforcement
- Steam → weekend-only + word scramble
## Integration Points
1. Hosts guard (pre/post hooks)
2. Periodic maintenance (auto-setup if missing)
3. VirtualBox hosts enforcement
## Adding Blocks
```bash
# Edit the blocked keywords file
echo "newpackage" >> pacman_blocked_keywords.txt
# Re-run installer to update checksums
sudo ./install_pacman_wrapper.sh
````
```
```