Détection et règles

Ce que l'agent trouve dans les journaux qu'un serveur écrit déjà : les quatorze types de source et leurs seuils, comment s'ajoute une source que l'installateur n'a pas trouvée, ce qui quitte la machine et ce qui ne la quitte jamais, et les fichiers de règles dont chaque détecteur est fait, y compris ceux que vous écrivez vous-même.

Ce que l'agent trouve dans vos journaux

Chaque source a son propre détecteur et son propre seuil, car cinq connexions SSH échouées en dix minutes et cinquante requêtes web suspectes en deux heures sont la même affirmation sur un attaquant et pas le même nombre. La rotation, copytruncate et un journal qui disparaît un moment sont pris en charge, et un fichier illisible produit un avertissement et non un par lecture.

Les quatorze types de source

web-app n'est pas un type de source et ne peut pas être écrit dans sources. C'est un deuxième détecteur qui tourne sur les lignes qu'une source web lit déjà, et il possède son propre seuil, c'est pourquoi il figure sous son propre nom dans le tableau des seuils plus haut. Un agent dont la configuration le nomme refuse de démarrer : sources[0]: type "web-app" is not supported in this version.

Les scans de ports, depuis le journal du noyau

Toute autre source lit un journal qu'un service écrit. La source scan lit le noyau, et c'est la seule source qui modifie aussi le pare-feu : quand elle figure dans la configuration, la synchronisation ajoute derrière les listes une règle qui journalise un SYN vers un port sur lequel cet hôte n'écoute pas, avec le préfixe rip-scan: et au plus dix lignes par minute après une première salve de 20, pour qu'un scan des 65535 ports ne noie pas le journal. Avec le moteur ipset, c'est une chaîne à part, rip-blacklist-scan ; avec nftables, c'est une règle dans la chaîne. Les ports en écoute sont lus dans /proc à chaque synchronisation : un service que vous démarrez n'est plus une cible de scan après le passage suivant, et il n'y a rien à déclarer. Seule une socket que quelque chose venu de l'extérieur pourrait atteindre compte comme en écoute. Un port lié uniquement à 127.0.0.1 ou à ::1 reste dans la règle, car un paquet qui y arrive depuis le réseau est une sonde sur un port fermé et rien d'autre. La liste de la dernière synchronisation n'est pas le seul contrôle : la règle interroge aussi le noyau à l'arrivée du paquet, et un SYN vers un port sur lequel une socket écoute à cet instant est une connexion et n'est jamais journalisé. Cela couvre un service démarré depuis la dernière synchronisation et un démon qui ouvre un port pour un seul transfert. La plage passive d'un serveur FTP en cours d'exécution (pure-ftpd, proftpd, vsftpd) est lue dans sa configuration et exclue de la règle ; si le serveur tourne sans plage configurée, c'est la plage de ports éphémères du noyau qui est exclue. Un noyau sans la correspondance socket garde la règle sans ce contrôle.

La règle se trouve derrière la liste blanche et derrière les listes. Une adresse de votre liste blanche a quitté la chaîne avant elle et ne produit aucune ligne, et une adresse que les listes rejettent déjà ne l'atteint pas non plus. En mode: log et mode: off, elle fait ce que tout le reste fait dans ces modes.

La source lit le journal du noyau, journalctl -k, et se rabat sur /var/log/kern.log ou /var/log/messages là où il n'y a pas de journal ; un path que vous définissez l'emporte. La règle livrée scan compte dix sondes en dix minutes depuis une adresse, les signale sous la catégorie 14 (Port Scan) comme port probes et bannit l'adresse comme n'importe quelle autre détection. Un client qui réessaie un port fermé envoie au plus six paquets, d'où le seuil de dix. install écrit la source sur un hôte neuf comme dernière entrée de sources ; un hôte installé plus tôt garde sa configuration, et l'ajout tient en une ligne, suivie d'un redémarrage du service de surveillance et d'une synchronisation pour la règle.

# config.yaml: the source, next to the ones the installer wrote
sources:
  - type: sshd
  - type: scan

# /etc/reportedip-agent/rules.d/50-scan.yaml: ban a scanner on this
# host, but leave the report to hosts that see more of it. Every field
# not named here stays as shipped.
format: 1
rules:
  - id: scan
    action: {ban: true, report: false}

# The same file with enabled: false switches the rule off; the firewall
# rule and its log lines stay. A threshold of your own goes into
# config.yaml and wins over the file:
thresholds:
  scan: {hits: 20, window_minutes: 10}

Ajouter une source que l'installateur n'a pas trouvée

Une source que l'installateur n'a pas trouvée est simplement absente de la configuration, et l'ajouter est une entrée avec un chemin ou un motif. Comme un fichier avec une clé sources remplace entièrement la liste par défaut, votre entrée va à côté des entrées existantes et non dans un second bloc.

sources:
  - type: sshd
  - type: web
    path: /var/log/nginx/access.log

  # A second web server on a different path
  - type: web
    path: /var/log/caddy/access.log

  # Every site of a panel host, rescanned every ten minutes.
  # At most five wildcard segments.
  - type: web
    glob: /var/www/clients/*/web*/log/access.log
    exclude:
      # This site reports to the API on its own, through Hive or a
      # honeypot. Without the exclude the host sends every address
      # twice and pays twice out of the daily quota.
      - /var/log/ispconfig/httpd/honeypot.example.com/*

  # Exim on a host the installer saw as a Postfix machine
  - type: exim
    path: /var/log/exim4/mainlog

Deux chemins qui pointent sur le même fichier ne posent pas de problème et n'ont pas besoin d'exclude : ISPConfig publie chaque journal d'accès deux fois, sous /var/www et sous /var/log/ispconfig, et l'agent lit un tel fichier une seule fois. Avant de faire confiance à une nouvelle entrée, pointez reportedip-agent test sur le fichier, redémarrez ensuite le service de surveillance, puis regardez status : la section sources montre les occurrences par source. doctor affiche un compte files= par source, et une source avec un compte à zéro ne pointe vers rien du tout.

Ce qui quitte la machine

Un signalement contient l'adresse, les identifiants des Threat Categories et une phrase générée. Aucune ligne de journal, aucun corps de requête, aucun User-Agent, aucune URL et aucun nom d'utilisateur n'est jamais transmis : un signalement ne peut donc pas divulguer vos clients, vos chemins ou vos identifiants, même par accident.

Une précision, car une promesse absolue serait fausse ici. Deux sources placent un nom issu du journal dans cette phrase générée : avec fail2ban le nom de la jail qui a banni, avec imunify360 le nom de la règle qui s'est déclenchée. Les deux sont filtrés sur les lettres, les chiffres, le point, le tiret et le tiret bas, et coupés à 32 caractères avant de quitter la machine, car un nom de jail provient d'une ligne de journal et constitue donc une entrée proche de l'attaquant. Aucune autre source n'envoie quoi que ce soit issu d'une ligne de journal.

Le nom d'hôte est envoyé, et pour une seule raison : que vous reconnaissiez votre propre machine dans la liste des serveurs au lieu de comparer des identifiants aléatoires. Il est filtré côté client sur A-Za-z0-9._-, tout le reste étant supprimé et non remplacé, coupé à 191 caractères, et il ne part jamais sans l'identifiant d'installation à côté.

L'identité reste l'identifiant d'installation. Le nom d'hôte est une étiquette et rien de plus : renommer la machine ne change rien à la licence, rien à l'hôte qui la détient et rien à ce que le serveur décide. Vous pouvez en plus donner à un hôte une étiquette à vous dans votre compte ; elle est affichée avant le nom d'hôte et n'est jamais déduite de la machine.

Quatre choses ne sont jamais signalées et jamais bloquées, et c'est une frontière dans le code plutôt qu'un réglage : les plages privées et réservées, la boucle locale, chaque adresse des interfaces de ce serveur et sa passerelle par défaut, et tout ce qui figure dans votre liste blanche. L'adresse du client SSH relevée à l'installation se trouve dans la liste blanche automatique et appartient donc au dernier groupe.

Règles

Une règle dit quelles lignes d'une source sont des correspondances, où se trouve l'adresse dans une telle ligne, comment s'appelle une correspondance, et combien d'entre elles en combien de minutes deviennent un bannissement ou un signalement. Chaque détecteur de l'agent est une règle, et chaque règle est un fichier. Trois couches sont lues et fusionnées par identifiant de règle :

Le paquet l'emporte sur le binaire, vos fichiers l'emportent sur le paquet. Une surcharge nomme une règle par son id et seulement les champs à changer ; chaque champ qu'elle ne nomme pas garde la valeur de la couche du dessous. match et examples sont remplacés en bloc, action champ par champ. enabled: false désactive une règle. Le nom du fichier ne joue aucun rôle : un fichier appelé 10-sshd.yaml sous rules.d ne masque pas le fichier livré de ce nom, il est lu comme n'importe quel autre et fusionné par les identifiants qu'il contient, si bien qu'une version qui renomme un fichier livré ne peut pas transformer votre surcharge en doublon.

Le format de fichier

Un fichier contient autant de règles qu'on veut. En voici une complète, tirée de la suite de tests de l'agent lui-même :

format: 1
rules:
  - id: my-sshd
    source: sshd
    match:
      regex: '(Failed password|Invalid user) .* from '
      anchors: ["Failed password", "Invalid user", "Accepted "]
      reset: 'Accepted (password|publickey) for .* from '
    addr: {after: " from ", occurrence: last}
    categories: [22, 18]
    noun: failed logins
    threshold: {hits: 5, window_minutes: 10}
    examples:
      match:
        - {line: "Sep 24 14:47:38 host sshd[1]: Failed password for root from 45.33.32.156 port 51422 ssh2", addr: 45.33.32.156}
      inject:
        - {line: "Sep 24 14:47:38 host sshd[1]: Invalid user x from 8.8.8.8 port 22 from 45.33.32.156 port 51422", addr: 45.33.32.156}
      nomatch:
        - "Sep 24 14:47:38 host sshd[1]: Connection closed by 45.33.32.156 port 1"

Pourquoi l'adresse n'est pas un groupe de capture

fail2ban a connu cela deux fois, CVE-2013-2178 et CVE-2009-0362, et les deux fois c'était la même erreur : l'adresse sortait du motif, et un attaquant avait mis une adresse de son choix dans un champ que le motif atteignait. RE2 trouve la correspondance la plus à gauche, donc dans Invalid user x from 8.8.8.8 port 22 from 45.33.32.156 port 51422 un groupe derrière le premier from bannirait 8.8.8.8, qui est le nom d'utilisateur que l'attaquant a tapé. addr: {after: " from ", occurrence: last} prend le dernier, celui que sshd a écrit lui-même. C'est pour cela qu'une règle nomme une position et non un groupe, et que chaque règle porte une ligne inject qui le prouve.

Ce qui vous protège de votre propre règle

Les exemples tournent à chaque chargement de la règle, donc un motif qui ne correspond plus à ses propres lignes ne se charge pas. Une règle à motif que votre couche ajoute ou surcharge bannit et ne signale pas pendant les premières 24 heures de son contenu (une règle avec match.builtin jamais) : une entrée noyau erronée expire et apparaît dans ban list, un signalement erroné ne se reprend pas. rules status marque une telle règle comme young. Un redémarrage du démon fait recommencer la journée.

Deux garde-fous surveillent une règle pendant qu'elle tourne. Quand trois adresses de votre liste blanche atteignent son seuil en dix minutes, la règle lit le mauvais champ, car les vrais attaquants ne sont jamais sur la liste blanche ; elle cesse de signaler jusqu'à ce que son fichier change, et continue de bannir, ce que la liste blanche couvre. Quand une règle jeune pousse plus de 50 adresses distinctes au-dessus de son seuil en une minute, elle correspond à chaque visiteur et elle est suspendue en entier, bannissements et signalements, jusqu'à ce que son contenu change. Une règle établie n'est jamais suspendue pour une rafale : une force brute distribuée avec des centaines de sources par minute est exactement ce pour quoi une règle sshd existe. Une règle du paquet est surveillée par le garde-fou de rafale comme une règle jeune, parce qu'un paquet atteint tous les hôtes en même temps.

Une entrée sous thresholds dans config.yaml continue de l'emporter sur le fichier, donc un hôte que vous avez réglé ne perd rien. Un fichier qui n'est pas du YAML valide, ou qui nomme un format plus récent, est ignoré seul et les autres se chargent. Une règle qui échoue à l'une des vérifications ci-dessus coûte toute votre couche : les règles livrées et le paquet continuent, status et doctor le disent, et rules check nomme le fichier, la ligne et l'identifiant.

Les commandes rules

reportedip-agent rules list                 # every rule: id, source, event, kind, state, threshold, action
reportedip-agent rules show sshd            # one rule as merged, and whether it is overridden
reportedip-agent rules check                # load rules.d the way the daemon does, and say what is wrong
reportedip-agent rules check /root/my.yaml  # try a file before it is put in place
reportedip-agent rules export sshd          # print the shipped file of a rule, as the template
reportedip-agent rules status               # state, hits since the daemon started, young and suspended rules
reportedip-agent rules disable sshd         # write enabled: false for one id; enable takes it back
reportedip-agent test --rule my-sshd /var/log/auth.log   # run one rule alone over a real log

list, show, check, export et status lisent et affichent. check sans fichier charge votre répertoire exactement comme le démon le ferait ; avec des fichiers, il charge ceux-là par-dessus le jeu livré, si bien qu'un fichier peut être essayé avant d'être dans rules.d. export affiche le fichier livré dans lequel une règle se trouve, commentaires compris, comme point de départ d'une surcharge. enable et disable sont les deux qui écrivent : un seul fichier généré, 90-agent-toggles.yaml, root seulement, réécrit à chaque appel. test --rule fait tourner cette seule règle et aucun détecteur compilé à côté, prend le type de source dans la règle, et ne signale ni ne bannit rien, comme le fait toujours test.

Écrire une règle à soi

1. Partir d'un fichier livré. reportedip-agent rules export sshd > /root/60-sshd.yaml affiche le fichier dans lequel la règle se trouve, commentaires et exemples compris.
2. Le réduire, ou lui donner un nouvel identifiant. Pour une surcharge, gardez l'id et seulement les champs à changer ; le fichier ci-dessous est complet. Pour une règle à vous, donnez-lui un nouvel id avec source, match, addr, categories et examples, comme my-sshd plus haut. Un nouvel identifiant est une nouvelle source d'événement, et la règle livrée continue de tourner à côté.
3. Le vérifier. reportedip-agent rules check /root/60-sshd.yaml charge le fichier par-dessus le jeu livré exactement comme le démon le ferait et affiche chaque problème avec fichier, ligne et identifiant, ou une ligne qui dit ok.
4. Le mettre en place. install -m 644 -o root -g root /root/60-sshd.yaml /etc/reportedip-agent/rules.d/. Le répertoire et chaque fichier qu'il contient doivent appartenir à root et n'être inscriptibles par personne d'autre, et un lien symbolique qui pointe hors du répertoire est refusé ; sinon toute la couche n'est pas utilisée.
5. Attendre une minute. Le démon prend le changement de lui-même, sans redémarrage, et les compteurs repartent de zéro. reportedip-agent rules status montre la règle, marquée young pendant son premier jour. reportedip-agent test --rule my-sshd /var/log/auth.log montre entre-temps ce qu'elle aurait attrapé.

# /etc/reportedip-agent/rules.d/60-sshd.yaml: the shipped sshd rule,
# stricter on this host. Everything not named here stays as shipped.
format: 1
rules:
  - id: sshd
    threshold: {hits: 3, window_minutes: 10}

Dernière mise à jour: 30. septembre 2026 · Maintenu par l’équipe ReportedIP