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.2 KiB

Raw Blame History

NREN / ASN Detection Service

Dieses Projekt stellt einen minimalen Microservice bereit, um Hochschul- und Forschungsnetzwerke (NRENs) anhand der Autonomous System Number (ASN) zu erkennen.

Der Zweck ist es, Anfragen aus Hochschulnetzen (z. B. eduroam) zu identifizieren, um Research-bezogene Services kostenlos oder bevorzugt bereitzustellen.

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 (DE) und Hipo university-domains-list (DE+AT, konfigurierbar)
- fängt Hochschulen ab, die externe Mail-Provider nutzen und daher kein eigenes NREN-AS haben
- monatliche Aktualisierung durch den Updater-Sidecar

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`

Domain-Lookup (optional)

Für die Validierung von Institutions-Domains kann ein Lookup genutzt werden. Der Service prüft sowohl die ASN-Datenbank als auch eine gepflegte Liste von Hochschuldomains (uni_domains.txt).

Abfrage per Domain:

GET /lookup?domain=uni-stuttgart.de
GET /lookup?domain=insti.uni-stuttgart.de

Abfrage per E-Mail-Adresse (Domain wird automatisch extrahiert):

GET /lookup?email=student@uni-stuttgart.de

Antwort (JSON):

{
  "domain": "uni-stuttgart.de",
  "nren": true,
  "asn_match": true,
  "domain_match": false,
  "asn": 12345,
  "asn_org": "Universitaet Stuttgart",
  "ips": ["129.69.1.1"],
  "matched_ip": "129.69.1.1"
}

Antwort bei Treffer über die Domain-Liste (z. B. für Hochschulen mit externem Mail-Provider):

{
  "domain": "hdm-stuttgart.de",
  "nren": true,
  "asn_match": false,
  "domain_match": true,
  "matched_domain": "hdm-stuttgart.de",
  "ips": ["..."]
}

nren: true wenn asn_match ODER domain_match zutrifft
asn_match: ASN-Treffer in PeeringDB-Daten
domain_match: Treffer in uni_domains.txt (inkl. Subdomain-Matching)
matched_domain: der gematchte Eintrag in der Liste (nur bei domain_match: true)

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.

Update-Strategie

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

Healthcheck

GET /healthz liefert 200 wenn mindestens MIN_ASN_COUNT ASNs geladen sind, sonst 503
Antwort ist immer JSON: {"asn_count": N, "domain_count": N}
Standard: MIN_ASN_COUNT=10 (konfigurierbar via Env)

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.2 KiB Raw Blame History