# 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
```

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

## 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)

1. `example.env` kopieren und als `.env` befüllen (mindestens `MAXMIND_LICENSE_KEY`).
2. Den Updater-Container starten und `OUT_DIR` als Volume mounten (z. B. `/data`).
3. Den ASN-Detection-Service so starten, dass er **denselben** `OUT_DIR` liest.
4. Traefik ForwardAuth aktivieren und `authResponseHeaders` durchreichen.
5. 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).

## 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.