Ga naar inhoud

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.

ssh user@192.168.50.12

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:

sudo -u schoolicap jq -r '.server.dashboard_token' /etc/school-icap-guard/config.json

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:

  1. Log in op https://netbird.secure1e.org/.
  2. Ga naar Team → Service Users → Create Service User.
  3. Naam: school-icap-sync — rol: minimale leesrechten op users/peers/groups.
  4. Open de aangemaakte gebruiker → Tokens → Create Token.
  5. Naam: school-icap-sync-token — stel een vervaldatum in (bijv. 365 dagen).
  6. 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)

nc -vz 192.168.50.12 13440

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

icap://192.168.50.12:13440/reqmod

Response Modification URL

icap://192.168.50.12:13440/respmod

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.

  1. Schakel SSL Inspection in.
  2. Importeer je interne CA (of genereer een nieuwe via OPNsense).
  3. 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:

sudo bash /tmp/school-icap-guard/fix_permissions.sh

Het script herstelt eigenaarschap en modus voor:

  • /opt/school-icap-guard/ — schoolicap:schoolicap, dirs 750, bestanden 640, scripts 755
  • /etc/school-icap-guard/ — schoolicap:schoolicap, dirs 750, bestanden 640
  • /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

sudo journalctl -u school-icap-guard -n 100 --no-pager
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_TOKEN is fout, verlopen of ingetrokken.
  • Je gebruikt een setup key in plaats van een service user access token.
  • De header moet Authorization: Token <token> zijn, niet Bearer.
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:

{ "clamav": { "enabled": false } }

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_TOKEN is niet opgenomen in git-commits of andere publieke opslagplaatsen
  • dashboard_token is veilig opgeslagen en geroteerd bij twijfel
  • fail_open: false in 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.sh uitvoeren na elke handmatige bestandsbewerking