squidguard-gitlab/README.md

SquidGuard-Listen per GitLab self-managed (Shell-Runner)

Idee / Sicherheitsmodell

• Ein Repo pro Arbeitsgruppe (squidguard/ag01 .. squidguard/ag08). GitLab-Rechte am Projekt = wer die beiden Dateien AG<NN>domain / AG<NN>url aendern darf. Nur AG01-Mitglieder haben Developer im Repo ag01. Das ist die eigentliche Zugriffskontrolle.
• Ein zentrales Deploy-Repo (squidguard/deploy), nur Ops beschreibbar. Hier liegen Deploy-Skript und Secrets. Die AG-Repos enthalten KEINE Secrets -> auch wenn eine AG ihre .gitlab-ci.yml frei bearbeitet, kann sie damit nur die zentrale Pipeline anstossen, nichts ausspaehen.
• Dedizierter Shell-Runner nur fuer das Deploy-Repo (nicht mit den AG-Repos teilen!), Tag squidguard-shell.

Dateibaum

deploy-repo/            -> Inhalt des Repos squidguard/deploy
  .gitlab-ci.yml
  scripts/validate.sh
  scripts/deploy.sh
  config/proxies.env
ag-repo/                -> Vorlage fuer jedes Repo squidguard/agNN
  .gitlab-ci.yml        (optional, nur fuer Sofort-Deploy)
  AG01domain
  AG01url
proxy/                  -> auf BEIDE Squid-Proxies installieren
  usr-local-sbin-squidguard-rebuild.sh
  usr-local-sbin-squidguard-reload.sh
  sudoers.d-squidguard-deploy
  squidGuard.conf.snippet

Einrichtung Proxys (proxy1 + proxy2, je identisch)

# Deploy-User anlegen
useradd -m -s /bin/bash deploy
install -d -o deploy -g deploy /var/lib/squidguard/incoming
install -d -o proxy  -g proxy  /var/lib/squidguard/db
install -d -o proxy  -g proxy  /var/lib/squidguard/backup   # fuer Auto-Rollback

# Wrapper-Skripte installieren
install -o root -g root -m 0755 usr-local-sbin-squidguard-rebuild.sh /usr/local/sbin/squidguard-rebuild.sh
install -o root -g root -m 0755 usr-local-sbin-squidguard-reload.sh  /usr/local/sbin/squidguard-reload.sh

# sudoers (WICHTIG: 0440, vorher pruefen)
install -o root -g root -m 0440 sudoers.d-squidguard-deploy /etc/sudoers.d/squidguard-deploy
visudo -c

# SSH-Key des Runner-Users in ~deploy/.ssh/authorized_keys eintragen
# squidGuard.conf.snippet in /etc/squidguard/squidGuard.conf einbauen

Hinweis: PROXY_USER in squidguard-rebuild.sh ist unter Debian/Ubuntu proxy, unter RHEL/CentOS squid -> ggf. anpassen.

Einrichtung Shell-Runner (auf dem Runner-Host)

# Runner registrieren, an Projekt squidguard/deploy gebunden
gitlab-runner register \
  --url https://gitlab.intern/ \
  --token <PROJECT_RUNNER_TOKEN_des_deploy_repos> \
  --executor shell \
  --tag-list squidguard-shell

# Als Runner-User (meist gitlab-runner): SSH-Key + known_hosts anlegen
sudo -u gitlab-runner ssh-keygen -t ed25519 -N '' -f ~gitlab-runner/.ssh/id_ed25519
sudo -u gitlab-runner ssh-keyscan proxy1.intern proxy2.intern >> ~gitlab-runner/.ssh/known_hosts
# der oeffentliche Key gehoert in ~deploy/.ssh/authorized_keys beider Proxys

Einrichtung GitLab

1. Gruppe squidguard anlegen, darin Projekte ag01..ag08 und deploy.
2. Je AG-Repo: nur die AG-Mitglieder als Developer hinzufuegen. Optional main als Protected Branch (Maintainer merged).
3. Group-Deploy-Token mit Scope read_repository erstellen -> im Deploy-Repo als CI/CD-Variablen GIT_USER / GIT_TOKEN hinterlegen (protected + masked).
4. Deploy-Repo: Pipeline-Zeitplan (Schedule) z.B. alle 5 Minuten anlegen.
5. Optional Sofort-Deploy: im Deploy-Repo ein Trigger-Token erzeugen und in jedem AG-Repo als DEPLOY_TRIGGER_TOKEN + DEPLOY_PROJECT_ID hinterlegen, dann ag-repo/.gitlab-ci.yml verwenden.

Ablauf

Push in ag01/main -> (optional Trigger) -> zentrale Pipeline auf dem Shell-Runner -> deploy.sh: klont alle AG-Repos, validiert, rsynct auf beide Proxys, squidguard-rebuild.sh AG<NN> (DB je Gruppe neu), am Ende squidguard-reload.sh (squid -k reconfigure).

Eine ungueltige Zeile wird schon in der CI-Validierung abgefangen und gelangt gar nicht erst auf die Proxys.

Auto-Rollback auf dem Proxy

squidguard-rebuild.sh sichert vor jeder Uebernahme den letzten funktionierenden Stand einer Gruppe (Quelllisten + .db) nach /var/lib/squidguard/backup/AG<NN>/. Schlaegt der Rebuild fehl - erkannt an Exit-Code, Fehlermeldungen in der Ausgabe oder einer leeren .db -, wird dieser Stand automatisch zurueckgespielt. Die Gruppe laeuft damit unveraendert weiter, statt offline zu gehen.

deploy.sh behandelt das pro Gruppe isoliert: eine fehlgeschlagene Gruppe wird uebersprungen (und zurueckgerollt), alle anderen Gruppen gehen normal live, und Squid wird trotzdem neu geladen. Am Ende endet die Pipeline mit Exit-Code 1 und listet die betroffenen proxy/AG auf, damit der Fehler sichtbar bleibt.

Da die CI-Validierung Formatfehler bereits vorher abfaengt, ist der Rollback vor allem die zweite Sicherung gegen Proxy-seitige Probleme (z.B. squidGuard-Version, Rechte, kaputte Bestands-.db).