School ICAP Guard — Configuratie & Installatie¶
Project: SASE Proof of Concept
Datum: 31-05-2026
Component: School ICAP Guard v0.2.0
Repository: github.com/Bnl06/School-icap-guard
Verantwoordelijke: Youness
School ICAP Guard is een ICAP-service (geen externe Python-dependencies) die draait als REQMOD- en RESPMOD-endpoint voor Squid/OPNsense. Hij koppelt NetBird-gebruikers automatisch aan per-groep policies, scant met ClamAV, handhaaft DLP-regels en blokkeert URL-categorieën uit de UT-1 blacklist.
Architectuuroverzicht¶
NetBird Dashboard / API
│ NETBIRD_TOKEN + NETBIRD_API
▼
sync_netbird_users.py (systemd timer, elke 60 s)
│ schrijft users.json + optioneel policies in config.json
▼
/etc/school-icap-guard/
│
▼
School ICAP Guard ←── ICAP ──→ Squid / OPNsense ←── Browser
(poort 13440) icap_send_client_ip on
│
├── ClamAV (poort 3310 of Unix socket)
├── DLP-regels (regex + validators op request/response body)
├── UT-1 URL-blacklist (70+ categorieën, lokaal gecached)
└── Dashboard http://127.0.0.1:8088
De sync leest /api/users, /api/peers en /api/groups van NetBird en schrijft users.json met een mapping van NetBird-IP → gebruiker → groepen. Squid stuurt het client-IP mee via icap_send_client_ip on zodat de ICAP-service de juiste per-groep policy kan toepassen.
Features¶
| Feature | Details |
|---|---|
| ICAP REQMOD + RESPMOD | Drop-in voor Squid / OPNsense |
| Per-groep policies | student, teacher, common, plus elke NetBird-groep |
| User identity | NetBird peer-IP → User identity |
| ClamAV antivirus | TCP of Unix-socket verbinding met clamd |
| DLP-regels | Regex + validators op request- en response-bodies |
| Weighted phrase lists (Beta) | E2Guardian-stijl scoring per contentcategorie |
| URL-blacklists | UT-1 (70+ categorieën), lokaal gecached |
| Dashboard | Web UI op 127.0.0.1:8088 voor live config-beheer |
| Hot-reload | User-mapping herladen zonder actieve verbindingen te verbreken |
| Geen dependencies | Alleen Python 3.9+ standaardbibliotheek |
VM-specificaties¶
De ICAP-service draait op een aparte Linux-VM in het SASE-netwerk. Hieronder de minimale en aanbevolen specificaties voor de PoC-opstelling.
| Resource | Minimum | Aanbevolen (PoC) | Opmerking |
|---|---|---|---|
| CPU | 1 vCPU | 2 vCPU | ClamAV scanning is CPU-intensief bij veel gelijktijdig verkeer |
| RAM | 1 GB | 2 GB | ClamAV laadt de volledige virusdatabase in geheugen (~800 MB) |
| Schijf | 10 GB | 20 GB | UT-1 blacklist + ClamAV signaturen + logs |
| Netwerk | 1 NIC | 1 NIC | LAN-IP bereikbaar voor OPNsense/Squid op poort 13440 |
| OS | Debian 11 / Ubuntu 22.04+ | Ubuntu 22.04 LTS | systemd vereist voor timer en service |
| Python | 3.9+ | 3.11+ | Geen pip-pakketten nodig |
IP-adressen in deze PoC:
| Component | IP-adres | Poort |
|---|---|---|
| ICAP Guard (deze VM) | 192.168.50.12 |
13440 (ICAP), 8088 (dashboard) |
| OPNsense / Squid | 192.168.50.1 |
3128 (proxy) |
| ClamAV (clamd) | 127.0.0.1 |
3310 |
Benodigdheden¶
| Vereiste | Toelichting |
|---|---|
| Linux met systemd (Debian 11 / Ubuntu 22.04+) | systemd vereist voor timer en service |
| Python 3.9 of nieuwer | Geen pip-pakketten nodig |
| ClamAV + clamd | apt install clamav-daemon clamav-freshclam |
| Squid via OPNsense of standalone | ICAP-ondersteuning + SSL inspection voor HTTPS-inhoudsinspectie |
| NetBird (cloud of self-hosted) | Voor user/groep-sync |
| Root/sudo op de ICAP-server | Installer en systemd-units vereisen root |
| Git | Repository klonen op de server |
| curl, jq, iproute2 | Hulpprogramma's voor installatie en troubleshooting |
Repository-indeling¶
school-icap-guard/
├── README.md
├── school_icap_guard.py # De ICAP-service — single file, geen deps
├── fix_permissions.sh # Zet eigenaarschap en modus correct
└── netbird_pkg/
├── install.sh # Installer voor NetBird-sync (systemd timer + service)
├── uninstall.sh # Verwijdert de sync timer en service
├── sync_netbird_users.py # Sync-script — door de timer aangeroepen
└── opnsense_custom_options.conf # Legacy configuratiebestand (optioneel)
Installatie¶
Alle commando's worden uitgevoerd op de ICAP-server via SSH.
Stap 1 — Basispakketten installeren¶
sudo apt update
sudo apt install -y python3 curl jq git iproute2 ca-certificates openssl
# ClamAV (malware scanning):
sudo apt install -y clamav-daemon clamav-freshclam
sudo systemctl enable --now clamav-daemon
# Wacht tot ClamAV de signaturen heeft gedownload:
sudo systemctl status clamav-daemon --no-pager
ClamAV heeft bij eerste start tijd nodig om de virusdatabase te downloaden via
freshclam. Dit kan enkele minuten duren afhankelijk van de verbinding.
Stap 2 — Servicegebruiker aanmaken¶
sudo useradd \
--system \
--shell /usr/sbin/nologin \
--home /opt/school-icap-guard \
schoolicap
sudo mkdir -p /opt/school-icap-guard /etc/school-icap-guard
sudo chown -R schoolicap:schoolicap /opt/school-icap-guard /etc/school-icap-guard
Stap 3 — Repository klonen¶
git clone https://github.com/Bnl06/School-icap-guard.git /tmp/school-icap-guard
cd /tmp/school-icap-guard
Stap 4 — ICAP-service installeren¶
4a — Script installeren en syntax controleren¶
sudo install -o schoolicap -g schoolicap -m 0755 \
school_icap_guard.py \
/opt/school-icap-guard/school_icap_guard.py
# Syntax controleren:
python3 -m py_compile /opt/school-icap-guard/school_icap_guard.py && echo "OK"
4b — systemd service aanmaken¶
sudo tee /etc/systemd/system/school-icap-guard.service > /dev/null <<'EOF'
[Unit]
Description=School ICAP Guard
After=network-online.target clamav-daemon.service
Wants=network-online.target clamav-daemon.service
[Service]
Type=simple
User=schoolicap
Group=schoolicap
WorkingDirectory=/opt/school-icap-guard
Environment=PYTHONUNBUFFERED=1
ExecStart=/usr/bin/python3 /opt/school-icap-guard/school_icap_guard.py \
--config-dir /etc/school-icap-guard
Restart=always
RestartSec=5
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now school-icap-guard
sudo systemctl status school-icap-guard --no-pager
4c — Dashboard-token ophalen¶
Bij de eerste start wordt config.json automatisch aangemaakt met een willekeurig dashboard_token. Lees het token uit en bewaar het veilig:
Het dashboard is bereikbaar via een SSH-tunnel:
# Op je lokale machine:
ssh -L 8088:127.0.0.1:8088 user@192.168.50.12
# Daarna in de browser: http://127.0.0.1:8088
Het dashboard luistert alleen op
127.0.0.1:8088. Stel het nooit bloot aan het netwerk zonder TLS en firewallregel.
Stap 5 — NetBird Service User Access Token aanmaken¶
De sync gebruikt een Service User access token — geen setup key. De token heeft leesrechten nodig op /api/users, /api/peers en /api/groups.
| Token-type | Waarvoor | Gebruikt door dit project |
|---|---|---|
| Service User access token | API-toegang users/peers/groups | Ja — dit is NETBIRD_TOKEN |
| Setup key | Nieuwe peers automatisch verbinden | Niet voor de sync |
Aanmaken in NetBird Cloud:
- Log in op https://netbird.secure1e.org/.
- Ga naar Team → Service Users → Create Service User.
- Naam:
school-icap-sync— rol: minimale leesrechten op users/peers/groups. - Open de aangemaakte gebruiker → Tokens → Create Token.
- Naam:
school-icap-sync-token— stel een vervaldatum in (bijv. 365 dagen). - Kopieer de token direct — hij wordt één keer getoond.
Token verifiëren voor deployment:
export NETBIRD_API="https://netbird.secure1e.org"
export NETBIRD_TOKEN="nbp_YOURTOKEN"
curl -fsS "${NETBIRD_API}/api/users" -H "Authorization: Token ${NETBIRD_TOKEN}" | jq '.[0] // .'
curl -fsS "${NETBIRD_API}/api/peers" -H "Authorization: Token ${NETBIRD_TOKEN}" | jq '.[0] // .'
curl -fsS "${NETBIRD_API}/api/groups" -H "Authorization: Token ${NETBIRD_TOKEN}" | jq '.[0] // .'
Alle drie calls moeten JSON teruggeven. 401 = token fout of verlopen. 403 = te weinig rechten.
Stap 6 — NetBird-sync installeren¶
De installer kopieert sync_netbird_users.py, schrijft de env-file, maakt een systemd timer aan (elke 60 s) en voert direct de eerste sync uit.
cd /tmp/school-icap-guard
# NetBird Cloud:
sudo NETBIRD_API="https://netbird.secure1e.org" \
NETBIRD_TOKEN="nbp_YOURTOKEN" \
bash netbird_pkg/install.sh
Installatie controleren:
# Timer actief?
sudo systemctl status netbird-users-sync.timer --no-pager
# Eerste sync geslaagd?
sudo journalctl -u netbird-users-sync.service -n 50 --no-pager
# Hoeveel users gesynchroniseerd?
sudo -u schoolicap jq '.ip_map | length' /etc/school-icap-guard/users.json
# Aanwezige policies?
sudo -u schoolicap jq '.policies | keys' /etc/school-icap-guard/config.json
Policies en NetBird-groepen:
NetBird-groepsnamen worden genormaliseerd naar lowercase policy keys:
| NetBird-groep | ICAP policy key |
|---|---|
Students |
students |
Leerjaar 1 |
leerjaar_1 |
Teachers |
teachers |
Met ICAP_AUTO_CREATE_POLICIES=1 (standaard aan) maakt de sync ontbrekende policies automatisch aan door de policy ICAP_POLICY_TEMPLATE (standaard student) te kopiëren.
Stap 7 — OPNsense / Squid koppelen¶
7a — Bereikbaarheid testen (vanuit OPNsense)¶
7b — ICAP toevoegen in OPNsense¶
Ga naar Services → Web Proxy → Administration → Forward Proxy → ICAP Settings.
Vink de volgende opties aan:
- Enable ICAP
- Enable Preview
- Send Client IP
- Send Client Username
Vul vervolgens in:
- Preview Size:
4096
Configureer daarna de ICAP-servers:
Request Modification URL¶
Response Modification URL¶
Klik vervolgens op Apply om de configuratie op te slaan.
7c — SSL Inspection inschakelen (vereist voor HTTPS-inhoudsinspectie)¶
Zonder SSL Inspection ziet de proxy alleen de HTTPS CONNECT-tunnel en niet de versleutelde inhoud. Daardoor kunnen ICAP-gebaseerde malware scans, DLP-regels en content filtering niet worden toegepast op HTTPS-downloads, uploads en webpagina's.
In OPNsense: Services → Web Proxy → Forward Proxy → SSL Inspection.
- Schakel SSL Inspection in.
- Importeer je interne CA (of genereer een nieuwe via OPNsense).
- Distribueer het CA-certificaat naar clients.
Configuratiebestanden¶
Bestandslocaties¶
| Bestand | Pad | Eigenaar | Modus | Inhoud |
|---|---|---|---|---|
| ICAP-service | /opt/school-icap-guard/school_icap_guard.py |
schoolicap |
0755 |
Hoofdservice |
| NetBird-sync | /opt/school-icap-guard/sync_netbird_users.py |
root |
0755 |
Sync-script |
| Configuratie | /etc/school-icap-guard/config.json |
schoolicap |
0640 |
ICAP-instellingen + policies |
| User-mapping | /etc/school-icap-guard/users.json |
schoolicap |
0640 |
IP → user → groepen |
| Env-file | /etc/school-icap-guard-netbird.env |
root:schoolicap |
0640 |
NetBird token + variabelen |
| Reload-script | /usr/local/bin/icap-users-reload.sh |
root |
0755 |
Hot-reload helper |
config.json — overzicht sleutels¶
Automatisch aangemaakt bij de eerste start. Bewerk via het dashboard of rechtstreeks; na directe bestandswijzigingen: sudo systemctl restart school-icap-guard.
{
"server": {
"icap_host": "0.0.0.0", // ICAP bind-adres
"icap_port": 13440, // Moet overeenkomen met de OPNsense
"dashboard_host": "127.0.0.1", // Alleen localhost — niet publiek blootstellen
"dashboard_port": 8088,
"dashboard_token": "<auto>", // Behandel als secret — roteer bij twijfel
"max_body_bytes": 26214400 // 25 MB body-limiet
},
"settings": {
"webfilter_enabled": true,
"domain_blocking_enabled": true,
"weighted_phrases_enabled": false, // Standaard uit — expliciet aanzetten
"dlp_enabled": true,
"antivirus_enabled": true,
"logging_enabled": true,
"netbird_sync_enabled": true
},
"clamav": {
"enabled": true,
"host": "127.0.0.1",
"port": 3310,
"unix_socket": "", // Alternatief: "/var/run/clamav/clamd.ctl"
"timeout_seconds": 30,
"fail_open": false // false = blokkeer verkeer als ClamAV niet bereikbaar is
}
}
users.json — structuur¶
Wordt automatisch geschreven door de NetBird-sync. Nooit handmatig bewerken; de volgende sync overschrijft het.
{
"meta": {
"generated_at": "2026-05-31T10:00:00Z",
"netbird_api": "https://netbird.secure1e.org",
"total_peers": 5,
"mapped_peers": 4
},
"ip_map": {
"100.64.0.5": {
"user_id": "abc123",
"email": "lana.verbeeck@school.be",
"name": "Lana Verbeeck",
"groups": ["student-1e", "All"]
}
}
}
Variabelenreferentie (env-file)¶
Opgeslagen in /etc/school-icap-guard-netbird.env.
| Variabele | Verplicht | Standaard | Omschrijving |
|---|---|---|---|
NETBIRD_TOKEN |
Ja | — | Service User access token. Begint met nbp_. Nooit publiek committen. |
NETBIRD_API |
Nee | https://netbird.secure1e.org |
Base URL van de NetBird API. Geen trailing slash, geen /api. |
ICAP_CONFIG_DIR |
Nee | /etc/school-icap-guard |
Map met users.json en config.json. |
ICAP_SERVICE |
Nee | school-icap-guard.service |
systemd-unit die herstart wordt als hot-reload faalt. |
ICAP_AUTO_CREATE_POLICIES |
Nee | 1 |
1 = nieuwe NetBird-groepen krijgen automatisch een policy. |
ICAP_POLICY_TEMPLATE |
Nee | student |
Policy in config.json die als template wordt gekopieerd. |
SYNC_INTERVAL_SECONDS |
Nee | 60 |
Interval van de systemd timer in seconden. |
INSTALL_DIR |
Nee | /opt/school-icap-guard |
Installatiemap voor de Python-scripts. |
SYNC_USER / SYNC_GROUP |
Nee | schoolicap |
Linux user/group waarmee de sync draait. |
systemd-units¶
school-icap-guard.service¶
| Parameter | Waarde |
|---|---|
| Type | simple |
| User / Group | schoolicap |
| ExecStart | /usr/bin/python3 /opt/school-icap-guard/school_icap_guard.py --config-dir /etc/school-icap-guard |
| Restart | always (RestartSec=5) |
| NoNewPrivileges | true |
| After | network-online.target clamav-daemon.service |
netbird-users-sync.timer + .service¶
| Parameter | Waarde |
|---|---|
| Type | oneshot |
| OnBootSec | 30 s |
| OnUnitActiveSec | 60 s (configureerbaar via SYNC_INTERVAL_SECONDS) |
| ExecStart | /usr/bin/python3 /opt/school-icap-guard/sync_netbird_users.py |
| ExecStartPost | Rechten herstellen + hot-reload aanroepen |
Controle na deployment¶
# 1. ICAP-service actief?
sudo systemctl status school-icap-guard --no-pager
# 2. ICAP luistert op poort 13440?
sudo ss -lntp | grep 13440
# 3. Timer actief?
sudo systemctl status netbird-users-sync.timer --no-pager
# 4. Laatste sync geslaagd?
sudo journalctl -u netbird-users-sync.service -n 50 --no-pager
# 5. users.json heeft entries?
sudo -u schoolicap jq '.ip_map | length' /etc/school-icap-guard/users.json
# 6. NetBird API bereikbaar vanaf de server?
set -a; . /etc/school-icap-guard-netbird.env; set +a
curl -fsS "${NETBIRD_API}/api/peers" \
-H "Authorization: Token ${NETBIRD_TOKEN}" | jq 'length'
# 7. Dashboard reageert?
TOKEN=$(sudo -u schoolicap jq -r '.server.dashboard_token' /etc/school-icap-guard/config.json)
curl -sf -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8088/api/status | jq .
Beheer¶
Hot-reload vs. volledige herstart¶
| Situatie | Actie |
|---|---|
| Nieuwe NetBird users/peers/groepen | Automatisch — timer roept POST /api/reload/users aan elke 60 s |
| Handmatige user-reload (zero downtime) | icap-users-reload.sh of curl naar dashboard-API |
config.json gewijzigd (policies, DLP, drempelwaarden) |
sudo systemctl restart school-icap-guard |
Updates uitvoeren¶
cd /tmp/school-icap-guard
git pull
# ICAP-service updaten:
sudo install -o schoolicap -g schoolicap -m 0755 \
school_icap_guard.py \
/opt/school-icap-guard/school_icap_guard.py
python3 -m py_compile /opt/school-icap-guard/school_icap_guard.py && echo "OK"
sudo systemctl restart school-icap-guard
# NetBird-sync updaten:
sudo install -o root -g root -m 0755 \
netbird_pkg/sync_netbird_users.py \
/opt/school-icap-guard/sync_netbird_users.py
sudo systemctl start netbird-users-sync.service
Rechten herstellen¶
Na handmatige bestandsbewerkingen:
Het script herstelt eigenaarschap en modus voor:
/opt/school-icap-guard/—schoolicap:schoolicap, dirs750, bestanden640, scripts755/etc/school-icap-guard/—schoolicap:schoolicap, dirs750, bestanden640/etc/school-icap-guard-netbird.env—root:schoolicap,640/usr/local/bin/icap-users-reload.sh—root:root,755
Uninstall¶
Alleen NetBird-sync verwijderen¶
sudo bash /tmp/school-icap-guard/netbird_pkg/uninstall.sh
# Volledig (incl. env-file en sync-script):
sudo rm -f /etc/school-icap-guard-netbird.env
sudo rm -f /opt/school-icap-guard/sync_netbird_users.py
sudo rm -f /usr/local/bin/icap-users-reload.sh
ICAP-service volledig verwijderen¶
sudo systemctl disable --now school-icap-guard
sudo rm -f /etc/systemd/system/school-icap-guard.service
sudo systemctl daemon-reload
# Data verwijderen (pas op — configuratie gaat verloren):
sudo rm -rf /opt/school-icap-guard
sudo rm -rf /etc/school-icap-guard
sudo rm -f /etc/school-icap-guard-netbird.env
Troubleshooting¶
Service start niet¶
| Symptoom | Mogelijke oorzaak | Oplossing |
|---|---|---|
json.JSONDecodeError |
Syntax error in config.json |
python3 -c "import json; json.load(open('/etc/school-icap-guard/config.json'))" |
OSError: [Errno 98] Address already in use |
Poort 13440 al in gebruik | sudo ss -lntp \| grep 13440 |
PermissionError |
Verkeerde bestandsrechten | sudo bash fix_permissions.sh |
NetBird-sync geeft 401 Unauthorized¶
NETBIRD_TOKENis fout, verlopen of ingetrokken.- Je gebruikt een setup key in plaats van een service user access token.
- De header moet
Authorization: Token <token>zijn, nietBearer.
set -a; . /etc/school-icap-guard-netbird.env; set +a
curl -v "${NETBIRD_API}/api/users" \
-H "Authorization: Token ${NETBIRD_TOKEN}"
# Token vervangen:
sudo sed -i 's|^NETBIRD_TOKEN=.*|NETBIRD_TOKEN=nbp_NIEUWTOKEN|' \
/etc/school-icap-guard-netbird.env
sudo systemctl start netbird-users-sync.service
NetBird-sync geeft 403 Forbidden¶
De service user heeft te weinig rechten. Verhoog tijdelijk de rol in het NetBird-dashboard, test de drie endpoints, beperk daarna terug.
users.json blijft leeg na sync¶
Mogelijke oorzaken:
- NetBird peers zijn verbonden via setup key, niet via user-login — zij hebben geen
user_id. - De service user ziet niet alle peers/users.
sudo journalctl -u netbird-users-sync.service -n 100 --no-pager | grep -E "WARN|ERROR|skip"
sudo -u schoolicap jq '.meta' /etc/school-icap-guard/users.json
DLP- en malware-inspectie werken niet op HTTPS¶
Zonder SSL Inspection ziet ICAP alleen de HTTPS CONNECT-tunnel en niet de versleutelde inhoud. Hierdoor kunnen DLP-regels, malware scans en andere inhoudsinspecties niet worden toegepast op HTTPS-verkeer.
Schakel SSL Inspection in via OPNsense (Services → Web Proxy → Forward Proxy → SSL Inspection) en distribueer het CA-certificaat naar alle clients.
ClamAV niet bereikbaar¶
sudo systemctl status clamav-daemon --no-pager
sudo ss -lntp | grep 3310
# Als clamd nog bezig is met laden (database download):
sudo journalctl -u clamav-daemon -n 50 --no-pager
Als ClamAV definitief niet beschikbaar is en je wil toch verder testen, zet in config.json:
En herstart de service: sudo systemctl restart school-icap-guard.
Security checklist¶
- Dashboard (
8088) is niet bereikbaar van het netwerk — alleen via SSH-tunnel NETBIRD_TOKENis niet opgenomen in git-commits of andere publieke opslagplaatsendashboard_tokenis veilig opgeslagen en geroteerd bij twijfelfail_open: falsein ClamAV-config — blokkeert verkeer als clamd niet bereikbaar is- SSL Inspection CA-certificaat is gedistribueerd naar alle clients
- Identity headers (
X-NetBird-User,X-Client-IP) worden gestript aan de rand van de proxy - NetBird service user heeft minimale rechten (alleen lezen op users/peers/groups)
fix_permissions.shuitvoeren na elke handmatige bestandsbewerking