Robert Rapp
082ecc579a
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>
151 lines
4.2 KiB
Markdown
151 lines
4.2 KiB
Markdown
# 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
|
|
```
|
|
|
|
1. Die Client-IP wird ermittelt
|
|
2. Die zugehörige ASN wird lokal nachgeschlagen
|
|
3. Die ASN wird mit einer NREN-ASN-Liste verglichen
|
|
4. 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):
|
|
```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):
|
|
```json
|
|
{
|
|
"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.
|