added readmes (#1)

Co-authored-by: DerLinkman <derlinkman@gmail.com> Reviewed-on: #1
2026-07-18 19:36:54 +00:00
parent 8d64bf5982
commit cab59c1658
7 changed files with 782 additions and 0 deletions
@@ -0,0 +1,104 @@
+# Rolle `manage-ssh-keys`
+
+Hardening-Rolle zur Verwaltung autorisierter SSH-Schlüssel. Sie fügt
+erwünschte ("Good") Keys hinzu und entfernt unerwünschte ("Bad") Keys aus der
+`authorized_keys`-Datei des Zielbenutzers.
+
+> Siehe auch das Playbook `playbooks/hardening/manage-ssh-keys.yml` sowie die
+> [Repo-README](../../README.md).
+
+## Voraussetzungen
+
+- Debian-Ziel-Host
+- SSH-Zugang als Zielbenutzer (Default: `admin`)
+- `lineinfile`-/`blockinfile`-Module (Bordmittel)
+
+## Einbindung
+
+```yaml
+- hosts: all
+  user: admin
+  roles:
+    - role: manage-ssh-keys
+```
+
+```bash
+ansible-playbook -i inventory/dmc12.yml playbooks/hardening/manage-ssh-keys.yml
+```
+
+Good/Bad-Keys können per Inventory überschrieben oder über Umgebungsvariablen
+übergeben werden (siehe auskommentiertes Beispiel im Playbook):
+
+```yaml
+# vars:
+#   good_keys: "{{ lookup('env', 'good_keys') | from_json }}"
+#   bad_keys: "{{ lookup('env', 'bad_keys') | from_json }}"
+```
+
+## Funktionsweise
+
+`tasks/main.yml` steuert den modularen Ablauf:
+
+1. **`validate-authorized-keys.yml`** – stellt das `.ssh`-Verzeichnis des
+   eingeloggten Users sicher (Mode `0700`).
+2. **`add-goodkeys.yml`** – fügt jeden Key aus `good_keys` per `lineinfile`
+   zur `authorized_keys` hinzu (idempotent). Benachrichtigt Handler
+   `Cleanup Comments` und `Add Comment`.
+3. **`remove-badkeys.yml`** – entfernt jeden Key aus `bad_keys` per
+   `lineinfile` (state: absent). Benachrichtigt ebenfalls die Handler.
+
+Die Handler bereinigen alle Kommentarzeilen (`^#.*$`) und fügen einen
+eindeutigen "Modified by Ansible"-Block mit Datum/Uhrzeit ein.
+
+## Variablen
+
+| Variable              | Typ     | Default        | Beschreibung                                         |
+|-----------------------|---------|----------------|------------------------------------------------------|
+| `ssh_user`            | string  | `admin`        | (Referenz) Zielbenutzer – Aktionen laufen als dieser User |
+| `good_keys`           | list    | siehe `defaults/` | Liste erwünschter SSH-Keys (vollständige Key-Zeilen) |
+| `bad_keys`            | list    | siehe `defaults/` | Liste unerwünschter SSH-Keys (vollständige Key-Zeilen) |
+
+### Steuer-Variablen (keine Defaults)
+
+| Variable              | Typ    | Beschreibung                                              |
+|-----------------------|--------|-----------------------------------------------------------|
+| `authorized_keys_file`| string | Pfad zur `authorized_keys`-Datei (muss gesetzt sein)     |
+
+> `authorized_keys_file` wird im Playbook bzw. Inventory gesetzt und muss
+> auf die Datei des Zielusers verweisen (z. B.
+> `/home/admin/.ssh/authorized_keys`).
+
+Default `good_keys` enthält die Admin-Keys (Niklas, Dennis, Generic Ansible).
+Default `bad_keys` enthält einen veralteten RSA-Key als Beispiel.
+
+## Templates
+
+Keine Templates.
+
+## Handler
+
+| Handler           | Auslöser                                  | Beschreibung                                              |
+|-------------------|-------------------------------------------|----------------------------------------------------------|
+| `Cleanup Comments`| Good/Bad-Key-Änderung                     | Entfernt alle Kommentarzeilen (`^#.*$`) aus der Datei   |
+| `Add Comment`     | Good/Bad-Key-Änderung                     | Fügt "Modified by Ansible on <Datum> at <Uhrzeit>" ein   |
+
+## Tags
+
+Die Rolle vergibt keine eigenen Tags.
+
+## Abhängigkeiten
+
+- Keine weiteren Rollen.
+- Collections: `ansible.builtin` (Bordmittel).
+
+## Hinweise
+
+- Die Rolle ist **idempotent**: mehrfaches Ausführen führt zu keinem
+  geänderten Zustand, wenn Keys bereits vorhanden/abwesend sind.
+- Good/Bad-Keys sind **vollständige Key-Zeilen** inkl. Typ, Key und
+  Kommentar (z. B. `ssh-ed25519 AAAA... user@host`). Der Vergleich erfolgt
+  zeilenbasiert.
+- Handler laufen erst am Ende des Playbook-Laufs – bei mehreren Key-Änderungen
+  wird die Datei nur einmal bereinigt.
+- Vorsicht bei der Definition von `bad_keys`: zu weit gefasste Patterns
+  könnten legitime Keys entfernen. Immer die exakte Key-Zeile angeben.