Exploiter l'agent Linux
Les commandes et leurs codes de sortie, ce que font les trois unités systemd, comment status et doctor s'intègrent dans la supervision, test à la place de fail2ban-regex, et le tableau de dépannage : symptôme, cause, commande.
Commandes
| Commande | Effet | Sortie |
|---|---|---|
REPORTEDIP_KEY=K install [--accept-terms] [--admin-ip IP|CIDR] [--ssh-port N] [--mode log|drop] [--ban|--no-ban] [--notify-email A] [--log-level L] [--expert] | Détecte les services, écrit la configuration, la liste blanche automatique et l'identifiant d'installation, installe et active les unités et vérifie la clé. La clé vient de l'environnement ; --key fonctionne toujours et avertit que sa valeur se trouve dans la liste des processus. N'écrase jamais une configuration existante. En root uniquement. --expert demande en plus l'échelle de bannissement, les seuils, les limites et un serveur SMTP. | 0, 2 si la clé est refusée avant toute écriture ou en cas de problème de configuration, 1 si la vérification de la clé après l'installation échoue |
sync | Un passage du flux : reconstruire l'ensemble de liste blanche, récupérer chaque liste de façon conditionnelle, basculer ce qui a passé la vérification de taille, reconstruire la chaîne, restaurer les bannissements locaux manquants, faire le ménage, chercher une mise à jour toutes les six heures. C'est ce que lance la minuterie, et c'est ce qui tourne au démarrage. | 0, 1 dégradé, également 0 si une autre synchronisation détient le verrou |
watch | Le démon. Suit chaque source, compte, signale et bannit si c'est activé. Se termine sur SIGTERM. | 1 si le verrou de file est encore détenu après une minute ou si le démon s'arrête sur une erreur, 2 en cas de problème de configuration |
report-queue | Envoie une fois les signalements en attente. Utile après une panne de l'API, ou sur un hôte où le démon ne tourne pas. | 0, 1 dégradé |
status | Version, moteur, mode, outils, nombre et dernier succès par liste, liste blanche, contrôle de la chaîne, positions de lecture et occurrences par source, file et expéditeur, compte et licence, le groupe de cette clé, la réputation de l'adresse depuis laquelle cet hôte signale, disque, bannissements locaux, états ouverts. | 0 sain, 1 dégradé, 2 configuration |
doctor | Ce que l'hôte offre et ce qui manque, y compris un journal que cet hôte écrit et qu'aucune source ne lit. Ne change rien, fonctionne sans configuration. | 0, 1 avec limites, 2 impossible |
test <file>... [--type T] [--rule ID] [--lines] | Fait passer les détecteurs sur de vrais fichiers de journaux. Ne signale rien, ne bannit rien, n'écrit rien. --rule fait tourner une seule règle d'un fichier de règles. | 0, 2 en cas de problème de fichier ou de type |
ban list | add <ip> [minutes] | rm <ip> | Montre les bannissements locaux face à ce que le noyau détient réellement, en pose un à la main, en lève un. | 0, 1 en cas d'échec du noyau, 2 si un argument est faux ou tant qu'une synchronisation détient le verrou ; add aussi pour une adresse en liste blanche ou sans backend de pare-feu |
unban <ip> | La même chose que ban rm, sous le mot qu'un opérateur tape quand ça brûle. | comme ci-dessus |
whitelist add <ip|cidr> [comment] | list | rm <ip|cidr> [--auto] | Gère la liste « jamais bloquer, jamais signaler ». add écrit le fichier et l'ensemble du noyau d'un coup. list affiche votre fichier, la liste blanche automatique et la liste blanche de votre groupe, cette dernière sur des lignes marquées group: avec leurs notes. --auto retire une entrée écrite par l'installateur. | 0, 1 si le fichier a changé et pas l'ensemble, 2 si l'adresse est fausse ou tant qu'une synchronisation détient le verrou |
update [--check] | Vérifie le point de distribution, remplace ce binaire puis redémarre le service de surveillance. --check ne fait que rapporter. C'est la seule commande qui lit la configuration de façon souple : elle fonctionne donc aussi sur un hôte dont la configuration est plus récente que le binaire. | 0, 1 si la vérification ou l'installation a échoué, 2 si la configuration est illisible ou si le répertoire d'état ne peut pas être créé |
housekeeping | Retire les propres restes de l'agent et affiche les chiffres. La synchronisation fait la même chose en silence. | 0, 2 en cas de problème de configuration ou d'état |
rules list | show <id> | check [file...] | export <id> | status | enable <id> | disable <id> | Les règles de détection : celles livrées et les fichiers sous /etc/reportedip-agent/rules.d qui les remplacent ou les complètent. check teste un fichier avant sa mise en service, export affiche une règle comme point de départ, status ajoute les occurrences et les règles encore jeunes, enable et disable activent ou coupent une règle. | 0, 1 si un fichier a été ignoré ou si les règles de l'exploitant ne sont pas utilisées, 2 si un argument est faux ou si check trouve un problème |
version | Affiche la version et rien d'autre. | 0 |
help | La liste des commandes, avec les chemins de configuration et d'état. | 0 |
test, au lieu de fail2ban-regex
test fait passer la chaîne de détecteurs sur un fichier de journal que vous avez déjà,
avec les seuils et la liste blanche de cet hôte, et affiche quelles adresses auraient dépassé un seuil
et à quel endroit du fichier. Il ne signale rien, ne bloque rien et n'écrit rien : il est donc sans
danger sur un hôte de production et c'est la réponse honnête à la question de savoir si cela aurait
attrapé l'attaque de la semaine dernière.
# A configured source: the type is taken from the config
reportedip-agent test /var/log/auth.log
# Any other file: name the type yourself
reportedip-agent test --type postfix /var/log/mail.log.1
# A rotated log and its successor as one stream, in this order,
# so a window that spans the rotation counts like the daemon saw it.
# A .gz is read inflated.
reportedip-agent test /var/log/mail.log.2.gz /var/log/mail.log.1 /var/log/mail.log
# Every single hit, with line number, address and timestamp
reportedip-agent test --lines /var/log/auth.logLa ligne de résumé indique les lignes lues, combien ont correspondu, combien ne portaient pas d'horodatage utilisable et combien ont été ignorées comme trop longues. Suit une ligne par adresse avec ses occurrences, ses remises à zéro, si elle aurait été bannie et combien de fois, l'heure de la première occurrence et le seuil appliqué. Une adresse figurant dans votre liste blanche est affichée avec la couche qui a répondu et marquée comme jamais bannie et jamais signalée, ce qui fait de cette commande le moyen le plus rapide de prouver qu'une entrée de liste blanche fonctionne vraiment.
Deux choses que test ne fait pas. Il ne devine aucun format : sans --type, le
fichier doit être l'un des chemins de source configurés, sinon il le dit et énumère les types valides.
Et il n'applique pas la pondération issue de l'historique de bannissements : le démon a donc besoin de
moins d'occurrences pour une adresse déjà bannie que ne le suggère cette relecture.
Exploitation
Trois unités systemd, écrites et activées par install et remises au niveau de la version
en cours par chaque synchronisation. Mettez vos propres modifications dans un drop-in sous
/etc/systemd/system/<unit>.d/, où elles survivent à une mise à jour. Une unité que
vous avez éditée directement est remplacée, la version précédente reste à côté sous
<unit>.bak, et le journal nomme les deux.
| Unité | Quand elle tourne | Détails |
|---|---|---|
reportedip-agent-sync.timer | Toutes les 15 minutes, plus un décalage aléatoire fixe allant jusqu'à 2 minutes | Il doit se déclencher au rythme le plus rapide qu'une licence puisse demander, car il est la seule chose qui lance une synchronisation. Combien de ces exécutions récupèrent vraiment est décidé par la licence, et une exécution trop précoce pour son offre ne récupère rien. |
reportedip-agent-sync.service | Au démarrage et à chaque tic du minuteur | Activé pour multi-user.target, après network-online.target et après chaque service de pare-feu, sans délai aléatoire. Une passe de synchronisation : l'ensemble de la liste blanche, les six listes, la chaîne, la restauration des bannissements locaux manquants, l'entretien, et une vérification de mise à jour toutes les six heures. |
reportedip-agent.service | En continu | Le démon de surveillance. Il redémarre après un échec au bout de dix secondes, au plus cinq fois en cinq minutes, et jamais sur le code 2 : un hôte mal configuré s'arrête donc avec une raison lisible au lieu d'être relancé sans fin. |
Les deux services tournent avec NoNewPrivileges, ProtectHome,
PrivateTmp, une personnalité verrouillée et un jeu restreint de familles d'adresses.
| Ce qui tourne tout seul | À quelle fréquence | Ce que cela fait |
|---|---|---|
| Rotation du journal | À chaque écriture | L'agent effectue la rotation de log_file à log_max_mb et garde log_keep générations. Il ne dépend pas de logrotate. Chaque ligne part aussi sur stderr, donc dans le journal de l'unité. |
housekeeping | À chaque synchronisation | Anciens fichiers de file, entrées de déduplication périmées, positions de lecture obsolètes, fichiers temporaires et de verrou restants, enregistrements de bannissement périmés, générations en trop du propre journal de l'agent, fichiers du miroir des règles livrées que le binaire ne contient plus, et le binaire précédent une fois vieux d'un mois. Lancé à la main, il montre les chiffres. |
| Mise à jour automatique | Toutes les six heures | Une nouvelle version est vérifiée contre une signature Ed25519 avec la clé publique compilée dans le binaire avant d'être installée : un téléchargement altéré échoue donc sur votre machine au lieu d'être cru parce qu'il est arrivé en HTTPS. Si le remplacement échoue, le binaire en cours d'exécution est remis en place : une mise à jour défectueuse laisse donc l'hôte sur la version qu'il avait. |
| Courrier d'état | Par condition, avec notify.cooldown_hours | Un courrier quand quelque chose ne va pas, un quand c'est réglé. À partir de Professional, il peut sortir par le relais de reportedip.com. |
| Le plancher de disque | À chaque écriture dans la file | Sous disk_min_mb, l'agent ne met plus de nouveaux signalements en file et le dit, tandis que la détection et le blocage continuent. |
systemctl list-timers reportedip-agent-sync.timer
systemctl status reportedip-agent.service --no-pager
journalctl -u reportedip-agent.service -n 50 --no-pager
journalctl -u reportedip-agent-sync.service -n 50 --no-pager
tail -n 100 /var/log/reportedip-agent.logCodes de sortie
| Code | Signification | Que faire |
|---|---|---|
0 | Sain | Rien. |
1 | Dégradé, mais une nouvelle tentative suivra | Lire la sortie. Une nouvelle tentative peut très bien régler la chose. Un état d'erreur ouvert dans le registre de santé se répercute sur le code de sortie même si l'exécution elle-même est passée, car un code 0 à côté d'une erreur consignée n'est pas un signal pour une supervision. Pour status, un démon watch arrêté est l'une de ces raisons. |
2 | Ne se résout pas sans intervention humaine | La configuration, les droits de fichier, un outil manquant, un verrou détenu par un autre processus. Lancer doctor. systemd ne relance pas le service de surveillance sur un 2. |
reportedip-agent status est ainsi utilisable directement comme sonde de supervision, sans
script d'encapsulation et sans analyse de sortie. status --json donne le même résultat
sous forme de document JSON ; la mise en place pour Zabbix, Nagios, Icinga, Checkmk et Prometheus se
trouve sous Supervision.
La réputation de l'adresse de cet hôte
Au moins une fois par jour, et à chaque synchronisation tant que la condition décrite ci-dessous est ouverte, l'agent demande au serveur ce qu'il pense de l'adresse depuis laquelle cet
hôte signale. Si cette adresse est elle-même listée dans la base communautaire,
status avertit et se termine avec le code 1. À partir d'une confiance de 75, la condition de santé reputation est en plus ouverte, avec la confiance, le nombre de signalements
et le lien vers la page de retrait dans son texte. C'est un avertissement et non
une erreur, parce qu'une adresse listée dit quelque chose du réseau où se trouve l'hôte et pas
forcément de l'hôte : une adresse partagée, un NAT d'opérateur ou un voisin derrière le même proxy
peuvent l'y mettre. Cela mérite tout de même un regard, car un hôte qui signale depuis une adresse
listée ressemble, vu de l'extérieur, à un hôte compromis. Vérifiez ce qui quitte la machine,
demandez le retrait une fois qu'elle est propre, et la condition disparaît à la synchronisation suivant le
retrait ; il n'y a rien à réinitialiser sur l'hôte. En dessous de 75, aucune condition de santé n'est ouverte : quelques
vieux signalements sont une donnée honnête et non quelque chose sur quoi un exploitant peut agir, et
aucun flux ne sert une adresse à ce score.
Dépannage
Un symptôme, une cause probable, une commande. reportedip-agent doctor et
reportedip-agent status répondent ensemble à la plupart de ces cas, et ce sont les deux
choses que le support demande en premier.
| Symptôme | Cause | Commande |
|---|---|---|
| Ne démarre pas et nomme son fichier de configuration | Le fichier est lisible par le groupe ou par les autres, et il contient votre clé API. | chmod 0600 /etc/reportedip-agent/config.yaml && chown root:root /etc/reportedip-agent/config.yaml |
| Code 2 avec « field ... not found in type » | Une clé inconnue dans la configuration. L'analyseur est strict volontairement. | Retirer ou corriger la clé nommée. La liste des clés valides figure plus haut. |
| Chaque commande se termine par un code 2 après un retour arrière | Le binaire est plus ancien que la configuration et ne peut pas lire un bloc plus récent. | reportedip-agent update, la seule commande qui lit le fichier de façon souple et nomme les clés inconnues. |
Un binaire plus ancien se termine avec le code 2 sur une configuration qui porte notify.relay | Cette clé est plus récente que le binaire. La même classe de piège que la ligne au-dessus, et elle a déjà laissé des hôtes sans protection deux fois. | Retirer la ligne relay: du bloc notify, ou avancer au lieu de reculer : reportedip-agent update. |
| Les ensembles existent mais sont vides | Soit le flux a été refusé, soit la liste a échoué à la vérification de taille. | reportedip-agent status dit lequel des deux, et la ligne de la liste porte la dernière erreur. |
status indique unlicensed | Le compte n'a aucune licence libre pour cet hôte. | En ajouter une sous Agent Servers. La liste dans le noyau continue de travailler pendant ce temps. |
| Rien n'est jamais signalé | La source qui aurait réagi n'a jamais été détectée, ou son seuil n'est pas atteint. | reportedip-agent test /path/to/log, puis reportedip-agent status et lire la section sources. |
| Rien n'est jamais bloqué, bien que des signalements partent | ban.enabled a été mis à false, ou mode à log (par défaut, les deux bloquent). Deux interrupteurs. | reportedip-agent ban list dit lequel des deux dans ses dernières lignes. |
| Aucun état de source du tout | Le démon de surveillance n'a jamais tourné. | systemctl enable --now reportedip-agent.service |
Une source affiche files=0 | Le chemin ou le motif ne pointe vers rien sur cet hôte. | reportedip-agent doctor nomme la source et le motif essayé. |
| Un service installé après l'agent ne signale rien | La détection a lieu une seule fois, à l'installation, et c'est voulu : un service arrêté pour une maintenance ne doit jamais désactiver une source. Dans l'autre sens, rien ne se produit tout seul non plus, un serveur de messagerie ajouté sur un hôte qui n'en avait pas n'est donc pas repris. | reportedip-agent doctor nomme le journal que ce service écrit, dit qu'aucune source ne le lit et se termine avec le code 1. Ajoutez la source dans config.yaml et redémarrez le service de surveillance. |
| Une source de journal est signalée illisible | Le fichier n'est pas lisible même pour root. Souvent un panneau de contrôle qui met le mode 000 à la rotation. | ls -l sur le chemin, et corriger la rotation qui a produit cela. |
| Une source a des occurrences mais ne signale jamais | Ses horodatages sont à plus d'une minute de l'horloge système, la fenêtre de comptage ne se remplit donc jamais. | reportedip-agent doctor, les lignes de dérive sous sources. Corriger le fuseau horaire de ce journal. |
| Votre propre adresse a été bannie | Elle n'était pas en liste blanche. | reportedip-agent whitelist add <address>. Effet immédiat, car la règle de liste blanche est avant la règle de blocage. |
Un bannissement est dans bans.json mais pas dans le noyau | Un redémarrage sans synchronisation, ou un rechargement de pare-feu qui a emporté l'ensemble. | reportedip-agent sync le restaure avec le temps restant. |
Une entrée du noyau avec l'enregistrement none | Quelqu'un a banni à la main avec ipset ou nft, ou le registre a été perdu. Elle expire, mais aucun redémarrage ne la ramène. | reportedip-agent ban list |
| Un ensemble existe avec un mauvais type ou sans délai d'expiration | Un reste du script shell documenté ou d'un autre outil. | ipset destroy <set> puis reportedip-agent sync, qui le recrée correctement. |
Les deux chaînes d'outils ont des objets rip- | Le moteur a été changé sans migration. | reportedip-agent sync --migrate-backend, et status affiche les commandes exactes de suppression pour l'autre côté. |
| Le pare-feu a disparu après un redémarrage | Un jeu de règles enregistré référence un ensemble rip-, et iptables-restore abandonne tout le fichier sur un ensemble inconnu. | grep -n rip- /etc/iptables/rules.v4 /etc/iptables/rules.v6 et retirer ces lignes. L'agent n'a besoin de rien d'enregistré. |
| Une source retirée continue d'être lue | Un systemctl restart ne suffit pas pour une source retirée. | systemctl stop reportedip-agent.service && systemctl start reportedip-agent.service |
| Les signalements s'arrêtent, la détection continue | La limite de disque a été atteinte. | Libérer de l'espace, puis reportedip-agent housekeeping. |
| HTTP 429 sur les signalements | La limite quotidienne de signalements de votre forfait. | Les limites figurent sous Authentification. |
| La file d'attente ne cesse de grandir | L'expéditeur est en pause après une erreur, avec un délai progressif. | reportedip-agent status montre la pause et la raison ; si le démon tourne, il envoie lui-même, et reportedip-agent report-queue n'envoie que lorsque le démon est arrêté. |
| Chaque occurrence web est la même poignée d'adresses | nginx voit un proxy ou Cloudflare et non le visiteur. | Configurer set_real_ip_from. reportedip-agent install avertit précisément de ce cas. |
| « more addresses than the counter tracks at once » | Un balayage plus large que le compteur par source. Pas un défaut. | Rien. Un balayage aussi large est un cas pour la liste communautaire et non pour des bannissements locaux. |
status dit que l'hôte est en retard de version | La mise à jour automatique ne passe pas, ou auto_update est désactivée. | reportedip-agent update --check, puis reportedip-agent update. |
status indique group=none | La clé de cet hôte n'est dans aucun groupe. Pas un défaut : l'ensemble rip-group reste vide. | Créez un groupe sous Groups dans votre compte et mettez-y les clés des hôtes ; la synchronisation suivante remplit l'ensemble. |
status avertit sur la réputation de l'adresse de cet hôte | L'adresse depuis laquelle cet hôte signale est listée dans la base communautaire. | Vérifiez ce qui quitte la machine, puis demandez le retrait. L'état disparaît à la synchronisation suivante. |
Aucune ligne rip-scan: dans le journal du noyau | Pas de source scan dans la configuration, ou la synchronisation qui construit la règle n'a pas tourné depuis l'ajout. | Ajoutez - type: scan sous sources, redémarrez le service de surveillance, puis reportedip-agent sync. Les adresses en liste blanche et celles déjà rejetées ne produisent jamais de ligne. |
Dernière mise à jour: · Maintenu par l’équipe ReportedIP