Bans et limites de debit

Un exemple

[sftp.ban]
max_failures = 5
window_secs = 300
ban_duration_secs = 600
whitelist_ips = ["10.0.0.0/8"]

[admin]
listen = "0.0.0.0:8080"

[admin.ban]
max_failures = 10
trusted_proxies = ["10.0.0.5"]   # le reverse proxy devant l'API

[api]
enabled = true

[api.ban]
max_failures = 5
trusted_proxies = ["10.0.0.5"]   # le meme : un seul ecouteur

Sans la section, la porte ne bannit rien.

Une liste par porte

Liste	Section	Portes
`sftp`	`[sftp.ban]`	SFTP
`api`	`[api.ban]`	API de fichiers, tickets de telechargement, explorateur
`admin`	`[admin.ban]`	API d’administration et console

Les trois listes sont independantes : une adresse bannie sur l’API de fichiers ouvre toujours la console, et inversement.

Les cles d’un ban

Les memes sous [sftp.ban], [api.ban] et [admin.ban], lues au demarrage.

Toutes les cles : Reference [sftp.ban], [api.ban], [admin.ban].

Ce qui compte comme un echec

Un echec est une credential presentee et jugee fausse, quel que soit le compte essaye.

Porte	Compte
SFTP	mot de passe faux ou nom inconnu ; jeton JWT juge faux ; signature d’une cle refusee ; une connexion finie sans s’authentifier apres des cles declinees (un echec par connexion, pas par cle)
API de fichiers	`Basic` faux ou mal forme ; `Bearer` vide ou jeton juge faux
Console et API d’administration	jeton statique faux ; `Bearer` vide, JWT ou jeton de session juge faux ; `POST /admin/login` : mot de passe faux, nom inconnu ou compte sans role admin

Ne comptent pas : une methode coupee, un jeton expire ou pas encore valide, un ticket de telechargement refuse, quel qu’il soit, un refus apres une credential acceptee (aucun role, limite de sessions), un refus du limiteur de debit, le refus d’une adresse deja bannie. Une connexion reussie ne remet pas le compteur a zero.

Avec [api] cors_origins = ["*"], toute page web peut faire envoyer par le navigateur d’un visiteur des credentials fausses, qui comptent pour le ban de son adresse : listez les origines de vos applications.

La vie d’un ban

Moment	Effet
`max_failures` echecs dans `window_secs`	l’adresse est bannie pour `ban_duration_secs` ; une ligne d’audit `ip_banned`
avec `[cluster]`	les echecs que les autres instances tiennent dans leur fenetre s’ajoutent au seuil, lus chaque seconde (≈ 1 s de retard) ; une instance injoignable ne compte plus apres 5 s (2 × `peer_timeout_ms` + 1 s si plus long)
sur SFTP, au verdict	les sessions SFTP ouvertes de l’adresse sont coupees, transferts compris
un echec de plus pendant le ban	l’echeance recule a `ban_duration_secs` apres lui
l’echeance	le ban finit, sans ligne
`DELETE /admin/bans/{protocol}/{ip}`	le ban est leve

Une adresse IPv4 mappee (::ffff:10.1.2.3) est la meme que 10.1.2.3, pour le ban, la liste blanche et les proxies.

Lever un ban

GET /admin/bans (onglet Bans de la console) les liste ; la levee demande la permission unban, {protocol} est sftp, api ou admin :

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/admin/bans/sftp/203.0.113.7

Une levee est une decision datee : elle annule les verdicts decides avant elle, jamais un verdict posterieur. Elle ne remet pas le compteur a zero.

Partager les bans entre instances

Backend	Cles	Partage
memoire	aucune	chaque instance a ses bans, perdus au redemarrage ; avec `[cluster]`, une levee est relayee a chaque instance, comme pour un fichier
fichier	`persist_file`	relu au demarrage, publie toutes les 30 s, relu sur un changement et toutes les `reread_interval_secs` ; ecrit de facon atomique, sur un volume partage (NFS, EFS) la relecture suffit
ConfigMap	`backend = "configmap"`, `ban_configmap_name`	suivi par l’API Kubernetes (feature `k8s`, un Role) : Kubernetes

Les trois listes peuvent partager un fichier ou un ConfigMap. La fusion garde, par adresse, le ban le plus long et le verdict le plus recent ; un ban appris d’un pair coupe les sessions SFTP de l’adresse, sans ligne ip_banned (celle de l’instance qui l’a decide suffit). A l’arret, chaque liste est publiee, 5 s au plus chacune.

L’adresse d’un client HTTP : `trusted_proxies`

Les portes HTTP prennent le pair TCP pour adresse. Quand ce pair est dans le trusted_proxies de leur liste ([api.ban] pour l’API de fichiers, [admin.ban] pour l’API d’administration), elles prennent l’adresse la plus a droite de X-Forwarded-For qui n’est pas un proxy de confiance, a defaut X-Real-IP. Le ban, le limiteur, la part de la file de hachage et l’audit utilisent cette adresse. La porte SFTP ne lit que le pair TCP.

Sans [admin] control_listen, l’API de fichiers et l’API d’administration partagent un ecouteur : [api.ban] et [admin.ban] portent alors les memes trusted_proxies.

Limites de debit

Un seau a jetons par adresse : burst connexions ou requetes d’affilee, puis le debit par minute. Sans la section, aucune limite.

[sftp.rate_limit]
connections_per_minute = 30
burst = 10

[api.rate_limit]
requests_per_minute = 600

Toutes les cles : Reference [sftp.rate_limit], [api.rate_limit].

L’API d’administration n’a pas de limite de debit. Un refus de debit ne compte pas pour le ban.

Ce que vous verrez

Quand	Ligne
un ban decide	audit `ip_banned` ; `INFO` `IP banned after auth failures`
sessions coupees par un ban	`INFO` `cut the sessions of a banned address` ; audit `session_end reason=banned`
un pair publie des bans	`INFO` `merged persisted bans from file`

Keyboard shortcuts

CraftFileGate