Files

Robert Rapp 082ecc579a feat: enrich /lookup with university domain list check

Add a second detection path alongside ASN lookup: a self-maintained
list of university domains (uni_domains.txt) loaded at startup.

- New /lookup params: email= (extracts domain from address), domain= unchanged
- Suffix matching: insti.uni-stuttgart.de matches list entry uni-stuttgart.de
  without false-positives (evil-uni-stuttgart.de does not match)
- New response fields: asn_match, domain_match, matched_domain (omitempty)
- nren remains true if either asn_match OR domain_match is true (backwards compat)
- /healthz now returns JSON body: {"asn_count":N,"domain_count":N}
- asn-updater: new update_uni_domains() merges hs-kompass.de TSV + Hipo JSON
  (configurable via UNI_DOMAIN_COUNTRIES / HS_KOMPASS_URL env vars)
- 7 new tests; all existing tests pass unchanged

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-17 15:10:49 +01:00

4.3 KiB

Raw Blame History

education-flagger

Forschung und Bildung sind die wichtigste Investition in die Zukunft, und der Zugang zu ihren Netzwerken verdient besondere Unterstützung.

Dieses Repo stellt einen minimalen Microservice bereit, um Hochschul- und Forschungsnetzwerke (NRENs) anhand der Autonomous System Number (ASN) zu erkennen. Ziel ist es, Zugriff oder bevorzugte Behandlung für Nutzer aus Research- und Education-Netzen zu ermöglichen, ohne personenbezogene Daten zu verarbeiten.

Das System dient ausschließlich der Netzwerk-Klassifikation und ersetzt keine Authentifizierung.

Ziel

Erkennen, ob eine Anfrage aus einem Hochschul- oder Forschungsnetz stammt
Bereitstellung eines Header-Hinweises für nachgelagerte Services
Grundlage für Entscheidungen wie:
- kostenfreie Research-Features
- angepasste UI-Hinweise
- alternative Rate-Limits

Funktionsweise (Kurzfassung)

Client
  -> Traefik
    -> ForwardAuth
      -> ASN Detection Service
        -> Header wird ergänzt

Die Client-IP wird ermittelt
Die zugehörige ASN wird lokal nachgeschlagen
Die ASN wird mit einer NREN-ASN-Liste verglichen
Das Ergebnis wird als HTTP-Header zurückgegeben

Datenquellen

GeoLite2 ASN (MaxMind)
- kostenlos
- lokal
- monatliche Aktualisierung
NREN-ASN-Liste
- abgeleitet aus PeeringDB
- Kategorie: Research and Education
- monatliche Aktualisierung
Hochschul-Domainliste (uni_domains.txt)
- zusammengeführt aus hs-kompass.de TSV und Hipo university-domains-list JSON
- Länderfilter konfigurierbar via UNI_DOMAIN_COUNTRIES (Standard: DE,AT)
- nach Update: uni_domains_meta.json mit Zählern je Quelle

Bereitgestellte Header

Header	Beschreibung
`X-ASN`	ASN der Client-IP
`X-ASN-ORG`	Organisation (optional)
`X-NREN`	`1` wenn ASN zu einem Hochschul-/Forschungsnetz gehört, sonst `0`

Integration

Der Service wird als Traefik ForwardAuth Middleware eingebunden.
Die Header werden über authResponseHeaders an die eigentliche Anwendung weitergereicht.

Der Service ist nicht öffentlich exponiert und kommuniziert ausschließlich über das interne Docker-Netzwerk.

Die dafür vorgesehenen Labels sind:

  # Middleware Definition (ForwardAuth -> asn-header)
  - "traefik.http.middlewares.asn-enrich.forwardauth.address=http://asn-header:8080/auth"
  - "traefik.http.middlewares.asn-enrich.forwardauth.trustForwardHeader=true"
  - "traefik.http.middlewares.asn-enrich.forwardauth.authResponseHeaders=X-ASN,X-ASN-ORG,X-NREN"

  # Middleware am Router aktivieren
  - "traefik.http.routers.web.middlewares=asn-enrich@docker"

Bitte füge diese zu dem Service hinzu, bei welchem man die gewünschten Header möchte.

Run/Deploy (kurz)

example.env kopieren und als .env befüllen (mindestens MAXMIND_LICENSE_KEY).
Den Updater-Container starten und OUT_DIR als Volume mounten (z. B. /data).
Den ASN-Detection-Service so starten, dass er denselben OUT_DIR liest.
Traefik ForwardAuth aktivieren und authResponseHeaders durchreichen.
Nach dem ersten Update sollten GeoLite2-ASN.mmdb und nren_asns.txt im OUT_DIR liegen.

example.env (kurz erklärt)

MAXMIND_LICENSE_KEY: notwendig für den GeoLite2 Download.
PDB_API_KEY: optional, reduziert PeeringDB Rate-Limits.
OUT_DIR: gemeinsamer Datenpfad zwischen Updater und Detection-Service.
PDB_BASE, PDB_INFO_TYPE, PDB_LIMIT: PeeringDB Filter.
HTTP_TIMEOUT: Timeout pro HTTP-Request.
INTERVAL_SECONDS: Update-Intervall (Standard 30 Tage).
UNI_DOMAIN_COUNTRIES: ISO-Ländercodes für Hipo-Filter (Standard: DE,AT).
HS_KOMPASS_URL: URL der hs-kompass.de TSV-Datei (überschreibbar ohne Image-Rebuild).

Update-Strategie

monatliche Aktualisierung der ASN-Daten
keine externen Requests während der Anfrageverarbeitung

Einschränkungen

Die Erkennung ist heuristisch
Es gibt keine Garantie, dass jede Anfrage aus einem Hochschulnetz erkannt wird
Die Information darf nicht als Authentifizierungsmerkmal verwendet werden

Zusammenfassung

Dieses Projekt ermöglicht eine performante, datenschutzfreundliche Erkennung von Hochschulnetzen, um Research-Angebote kontextabhängig bereitzustellen, ohne Nutzer zu identifizieren oder externe Dienste zur Laufzeit zu kontaktieren.

4.3 KiB Raw Blame History