README.md und AGENTS.md um Netzwerk-Vertrauen-Feature ergänzen
Dokumentiert die neue Vertrauensprüfung vor dem nmap-Schritt: Konzept (Gateway-MAC als Netzwerk-Identifikator), die neuen CLI-Optionen --trusted-networks/--auto-trust-networks samt Config-Datei-Feld trusted_networks, sowie das Verhalten im interaktiven vs. --json-Modus. AGENTS.md um src/trust.rs in der Modulstruktur ergänzt. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnWfGGqHJGh2AhZ6uhotaD
This commit is contained in:
Claude Sonnet 5
@@ -12,6 +12,8 @@ Dieses Dokument dient als technischer Leitfaden und Kontextdokument für KI-Codi
|
||||
2. **`ip neigh`** (`src/network.rs`): moderner Ersatz für `arp`. Treffer nur bei Ping-Erreichbarkeit.
|
||||
3. **`nmap -sn`** (`src/network.rs`): ARP-/Ping-Scan der lokal angeschlossenen Subnetze. MAC-Adressen erscheinen in der nmap-Ausgabe nur mit Root-Rechten (Raw-Socket/libpcap), daher läuft dieser Schritt über `sudo nmap` (bzw. `nmap` direkt, falls schon root). Kein Treffer → Fehler ("nicht gefunden").
|
||||
|
||||
Vor Schritt 3 prüft `src/trust.rs`, ob das aktuelle Netzwerk (identifiziert über die MAC-Adresse seines Default-Gateways) für einen nmap-Scan vertrauenswürdig ist (statische Liste in `AppConfig::trusted_networks`, zuvor per interaktiver Rückfrage/`--auto-trust-networks` im Cache bestätigtes Netzwerk). Ist das Netzwerk unbekannt, wird im interaktiven Modus nachgefragt; im `--json`-Modus (keine Rückfrage möglich) wird der Scan abgelehnt.
|
||||
|
||||
Die Orchestrierung dieser drei Schritte liegt in `src/resolver.rs`; `src/main.rs` ist nur ein dünner Entry-Point (CLI-Parsing via `src/cli.rs`, Konfiguration via `src/config.rs` + `config-ctdra`, Logging via `src/log.rs` + `logger-ctdra`).
|
||||
|
||||
Zur Laufzeit werden folgende System-Tools benötigt: `ip` (iproute2), `ping` (iputils), `nmap`, `sudo` (nur für Schritt 3, falls nicht schon root). Diese sind in den Paketierungs-Metadaten (`Cargo.toml`, siehe §3.2) als Abhängigkeiten hinterlegt.
|
||||
@@ -60,6 +62,7 @@ Das Projekt basiert auf einem generischen **Rust-Projekt-Template** für Linux-A
|
||||
│ ├── mac.rs # MacAddress-Typ (Parsing/Kanonisierung)
|
||||
│ ├── cache.rs # Globaler Turso-Cache (MAC -> IP)
|
||||
│ ├── network.rs # ip neigh / ping / nmap: Exec- und Parse-Funktionen
|
||||
│ ├── trust.rs # Netzwerk-Vertrauensprüfung vor Schritt 3 (Gateway-MAC, Rückfrage, Cache)
|
||||
│ ├── resolver.rs # 3-Stufen-Algorithmus (Orchestrierung)
|
||||
│ └── output.rs # Human- und JSON-Ausgabe
|
||||
├── tests/ # Integrationstests (pure Parsing-/Logik-Funktionen, kein Netzwerk/root/nmap nötig)
|
||||
|
||||
@@ -6,7 +6,7 @@ Dazu wird ein 3-stufiger Algorithmus verwendet:
|
||||
|
||||
1. **Cache**: Ein globaler, systemweiter Cache (für alle Nutzer dieses Rechners) wird geprüft. Ein Treffer wird nur verwendet, wenn er noch nicht abgelaufen ist (TTL) **und** die IP per Ping erreichbar ist.
|
||||
2. **`ip neigh`**: Die Linux-Nachbartabelle (`ip neigh show`, der moderne Ersatz für den veralteten `arp`-Befehl) wird nach der MAC-Adresse durchsucht. Ein Treffer wird nur verwendet, wenn die IP per Ping erreichbar ist.
|
||||
3. **`nmap`**: Als letzter Schritt wird ein Ping-/ARP-Scan (`nmap -sn`) der lokal angeschlossenen Subnetze durchgeführt. Da MAC-Adressen in der nmap-Ausgabe nur mit Root-Rechten sichtbar sind (ARP-Scans benötigen Raw-Socket-/libpcap-Zugriff), läuft dieser Schritt über `sudo nmap` (bzw. direkt `nmap`, falls das Programm bereits als root läuft). Wird auch hier keine erreichbare IP gefunden, bricht das Programm mit einem Fehler ("nicht gefunden") ab.
|
||||
3. **`nmap`**: Als letzter Schritt wird ein Ping-/ARP-Scan (`nmap -sn`) der lokal angeschlossenen Subnetze durchgeführt. Da MAC-Adressen in der nmap-Ausgabe nur mit Root-Rechten sichtbar sind (ARP-Scans benötigen Raw-Socket-/libpcap-Zugriff), läuft dieser Schritt über `sudo nmap` (bzw. direkt `nmap`, falls das Programm bereits als root läuft). Da ein Subnetz-Scan auf fremden Netzwerken heikel sein kann, wird dieser Schritt nur in einem als vertrauenswürdig eingestuften Netzwerk ausgeführt (siehe [Netzwerk-Vertrauen](#netzwerk-vertrauen)). Wird auch hier keine erreichbare IP gefunden, bricht das Programm mit einem Fehler ("nicht gefunden") ab.
|
||||
|
||||
---
|
||||
|
||||
@@ -54,6 +54,8 @@ Bei Fehlern (`status: "error"`) ist `source` nicht enthalten, dafür ein `error`
|
||||
| `--cache-db-path <PATH>` | `MAC2IP_CACHE_DB_PATH` | `/var/lib/mac2ip/cache.db` | Pfad zur globalen Cache-Datenbankdatei. |
|
||||
| `--nmap-timeout-seconds <N>` | `MAC2IP_NMAP_TIMEOUT_SECONDS` | `120` | Timeout für einen einzelnen nmap-Subnetz-Scan. |
|
||||
| `--networks <CIDR,CIDR,...>` | `MAC2IP_NETWORKS` | Auto-Erkennung | Kommagetrennte Liste von Subnetzen für den nmap-Scan; überschreibt die automatische Erkennung über `ip route`. |
|
||||
| `--trusted-networks <MAC,MAC,...>` | `MAC2IP_TRUSTED_NETWORKS` | leer | Kommagetrennte Liste von Gateway-MAC-Adressen, deren Netzwerke ohne Rückfrage für nmap-Scans (Schritt 3) vertraut werden; überschreibt die Konfigurationsdatei vollständig. |
|
||||
| `--auto-trust-networks` | - | aus | Beantwortet die "Netzwerk vertrauen?"-Rückfrage vor Schritt 3 automatisch mit Ja (und merkt sich das Netzwerk dauerhaft im Cache), statt interaktiv nachzufragen bzw. im `--json`-Modus abzulehnen. |
|
||||
|
||||
Die Überschreibungs-Reihenfolge ist immer: **CLI-Flag > Umgebungsvariable > Konfigurationsdatei > Standardwert.**
|
||||
|
||||
@@ -75,6 +77,7 @@ cache_db_path = "/var/lib/mac2ip/cache.db"
|
||||
log_level = "info"
|
||||
nmap_timeout_seconds = 120
|
||||
networks = []
|
||||
trusted_networks = []
|
||||
```
|
||||
|
||||
Alle Felder sind optional (fehlende Felder verwenden den Standardwert) und können, wie oben beschrieben, zusätzlich per CLI-Flag oder Umgebungsvariable überschrieben werden.
|
||||
@@ -95,6 +98,24 @@ Kann das Cache-Verzeichnis beim Programmstart nicht angelegt/beschrieben werden
|
||||
|
||||
---
|
||||
|
||||
## Netzwerk-Vertrauen
|
||||
|
||||
Ein `nmap`-Subnetz-Scan (Schritt 3) ist auf Netzwerken, die man nicht selbst administriert (Firmen-/Gast-WLAN, Kundenstandort etc.), potenziell heikel — er kann IDS-Alarme auslösen oder gegen eine Nutzungsordnung verstoßen. mac2ip führt Schritt 3 deshalb nur in einem als vertrauenswürdig eingestuften Netzwerk aus.
|
||||
|
||||
Das aktuelle Netzwerk wird über die **MAC-Adresse seines Default-Gateways** identifiziert — sie bleibt stabil, solange derselbe Router im Einsatz ist, unabhängig von SSID oder wechselndem DHCP-Subnetz. Ein Netzwerk gilt als vertrauenswürdig, wenn eine der folgenden Bedingungen zutrifft:
|
||||
|
||||
1. Die Gateway-MAC steht in `trusted_networks` (Konfigurationsdatei oder `--trusted-networks`).
|
||||
2. Das Netzwerk wurde bereits einmal per Rückfrage bestätigt — das Ergebnis wird dauerhaft im globalen Cache gespeichert, sodass beim nächsten Besuch (auch nach Neustart) keine erneute Rückfrage nötig ist.
|
||||
3. `--auto-trust-networks` ist gesetzt: Die Rückfrage wird automatisch mit Ja beantwortet und das Ergebnis ebenfalls im Cache gemerkt.
|
||||
|
||||
Ist keine der Bedingungen erfüllt:
|
||||
- Im **interaktiven Modus** fragt mac2ip auf stderr nach, ob der Scan in diesem Netzwerk erlaubt werden soll.
|
||||
- Im **`--json`-Modus** ist keine Rückfrage möglich (die Ausgabe darf nicht durch einen Prompt verunreinigt werden) — der Scan wird sicherheitshalber abgelehnt und ein Fehler zurückgegeben. Für unbeaufsichtigte Läufe in bekannten Netzwerken also entweder `trusted_networks` vorkonfigurieren oder einmalig interaktiv (ohne `--json`) bestätigen.
|
||||
|
||||
Kann die Gateway-MAC nicht ermittelt werden (z. B. kein Default-Gateway vorhanden), wird der Scan ebenfalls abgelehnt, außer `--auto-trust-networks` ist gesetzt.
|
||||
|
||||
---
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
Neben Rust/Cargo zur Laufzeit benötigt werden folgende System-Tools:
|
||||
|
||||
Reference in New Issue
Block a user