Événements ssh-guard (JSON)¶

Référence stable du flux d'événements émis par la couche ssh-guard du serveur SSH gitrust. Ce format est garanti stable pour les consommateurs externes (fail2ban, Loki, Vector, SIEM). Tout changement incompatible passe par un nouveau nom d'événement.

Où trouver ces événements : selon SSH_GUARD_LOG_TARGET, dans le journald du service (stderr), dans /var/log/gitrust-ssh-guard.json (file), ou les deux (both). Voir Variables d'environnement — SSH_GUARD_*.

1. Forme générale¶

Tous les événements partagent trois champs :

Champs additionnels selon le type d'événement (voir tables ci-dessous).

2. Catalogue des événements¶

3. Référence par événement¶

3.1 connection_accepted¶

Une connexion TCP a passé tous les contrôles ssh-guard. Le russh handshake va démarrer.

{"event":"connection_accepted","ts":"2026-04-19T14:32:11.482Z","session_id":"a4c2b8e1-9f3d-4d7e-8c11-0a5d9b6f4e22","ip":"203.0.113.42"}

3.2 connection_dropped¶

ssh-guard a refusé la connexion avant le handshake SSH.

Valeurs de reason :

{"event":"connection_dropped","ts":"2026-04-19T14:33:02.117Z","ip":"203.0.113.42","reason":"banned"}

3.3 auth_failed¶

Tentative d'authentification SSH refusée. Source principale pour fail2ban.

{"event":"auth_failed","ts":"2026-04-19T14:32:13.221Z","session_id":"a4c2b8e1-9f3d-4d7e-8c11-0a5d9b6f4e22","ip":"203.0.113.42","user":"root","method":"public_key","fingerprint":"SHA256:k1Qp9xJ8r6Z3HfV2Bn7tT5Cw"}

3.4 auth_succeeded¶

Tentative d'authentification SSH validée. Audit des accès légitimes.

{"event":"auth_succeeded","ts":"2026-04-19T14:32:14.005Z","session_id":"a4c2b8e1-9f3d-4d7e-8c11-0a5d9b6f4e22","ip":"203.0.113.42","user":"alice","fingerprint":"SHA256:p3Lm7nB6xQz9fK1WyT8c"}

3.5 brute_force_detected¶

Le seuil SSH_GUARD_BRUTE_FORCE_THRESHOLD a été atteint. Un événement ip_banned suit immédiatement.

{"event":"brute_force_detected","ts":"2026-04-19T14:36:42.998Z","ip":"203.0.113.42","count":5,"window_secs":300}

3.6 user_enumeration_detected¶

Le seuil SSH_GUARD_USER_ENUM_THRESHOLD (nombre d'usernames distincts essayés depuis la même IP) a été atteint.

{"event":"user_enumeration_detected","ts":"2026-04-19T14:38:15.402Z","ip":"203.0.113.42","distinct_users":10,"window_secs":300}

3.7 key_scanning_detected¶

Le seuil SSH_GUARD_KEY_SCAN_THRESHOLD (nombre de fingerprints distincts essayés depuis la même IP) a été atteint.

{"event":"key_scanning_detected","ts":"2026-04-19T14:39:08.117Z","ip":"203.0.113.42","distinct_keys":10,"window_secs":300}

3.8 connection_flood_detected¶

Le cap SSH_GUARD_CONN_FLOOD_PER_SEC a été dépassé pour cette IP. Un connection_dropped avec reason="flood_limit" suit dans le même millième de seconde.

{"event":"connection_flood_detected","ts":"2026-04-19T14:40:01.555Z","ip":"203.0.113.42","rate_per_sec":10}

3.9 ip_banned¶

Un ban a été appliqué (auto par un détecteur, manuel par un admin, ou simulé en dry_run).

Valeurs de reason :

{"event":"ip_banned","ts":"2026-04-19T14:36:42.999Z","ip":"203.0.113.42","reason":"brute_force","expires_at":"2026-04-19T15:36:42.999Z"}

Mode dry_run : un ip_banned est émis pour signal externe (fail2ban) sans que ssh-guard inscrive le ban dans son store. Utile pour observer un nouveau seuil sans risque.

3.10 ip_unbanned¶

Un ban a été levé (TTL expiré ou action admin).

{"event":"ip_unbanned","ts":"2026-04-19T15:36:43.001Z","ip":"203.0.113.42","manual":false}

4. Filtrage côté outils externes¶

4.1 Fail2ban (filtre par regex sur le fichier JSON)¶

[Definition]
# Brute-force détecté → ban dur côté firewall
failregex = ^.*"event":"auth_failed".*"ip":"<HOST>".*$
ignoreregex =

Voir le template clé en main : template/security/fail2ban-gitrust-ssh-guard.conf et le how-to Durcir avec Fail2ban.

4.2 Loki (LogQL)¶

# Toutes les détections fortes (signal pour alerting Grafana)
{job="gitrust-ssh-guard"}
  | json
  | event=~"brute_force_detected|user_enumeration_detected|key_scanning_detected|connection_flood_detected"

4.3 jq (extraction shell)¶

# 10 IP les plus actives en échec d'auth sur la dernière heure
sudo journalctl -u gitrust --since "1 hour ago" --no-pager \
  | jq -r 'select(.event=="auth_failed") | .ip' \
  | sort | uniq -c | sort -rn | head -10

5. Pour aller plus loin¶

• Variables d'environnement — SSH_GUARD_*
• Configurer ssh-guard
• ssh-guard : détection d'attaques SSH
• Durcir avec Fail2ban
• Crate gitrust-ssh-guard (pour les contributeurs)