Developer Documentation ReportedIP REST API und Ökosystem

API v2

Installationsbeispiele

Derselbe Installer auf den Hosts, die ihm üblicherweise begegnen: ein Rollout mit Ansible oder cloud-init, ein Golden Image, ein Server mit Control Panel, ein Mail- oder Datenbank-Host, ein LXC-Container und ein VPS hinter einer Cloud-Firewall. Jedes Beispiel nutzt die Flags und Variablen, die die Installationsseite dokumentiert, nichts hier ist ein zweiter Weg hinein.

Unbeaufsichtigt, auf vielen Hosts

Drei Dinge machen eine unbeaufsichtigte Installation möglich, und jedes Beispiel unten baut darauf auf. Die Nutzungsbedingungen werden vorab mit REPORTEDIP_ACCEPT_TERMS=1 akzeptiert, denn es ist niemand da, der yes tippt. Der Key reist in der Umgebung und nie als Argument, denn /proc/<pid>/cmdline kann jeder lokale Benutzer lesen, die Umgebung nicht. Und die Antworten auf die Fragen, die ein Terminal stellen würde, kommen als Variablen, damit kein Host auf eine Antwort wartet: REPORTEDIP_MODE, REPORTEDIP_BAN und REPORTEDIP_NOTIFY_EMAIL. Fehlt eine, gilt der Standard einer frischen Config, also drop, lokale Sperren an und keine Mail.

Der Lauf ist idempotent. Auf einem Host, der schon /etc/reportedip-agent/config.yaml hat, legt das Skript die Binärdatei ab und hört auf, die Konfiguration bleibt unangetastet. Upgrades brauchen den Rollout gar nicht: der Agent aktualisiert sich alle sechs Stunden selbst über ein signiertes Release. Das eine, was nach jeder Installation zu tun bleibt, ist die Whitelist: der Installer trägt die Adresse ein, aus der die Sitzung kam, und Ihr Management-Bereich steht erst darin, wenn Sie ihn hinzufügen.

Ansible

Eine Task-Liste, keine Rolle, denn es gibt nichts zu templaten: der Installer prüft den Host selbst. Der Key kommt aus dem Vault, der Task wird auf einem Host mit Config übersprungen, und der Whitelist-Task behandelt eine Adresse, die schon drin ist, als unverändert, denn genau so weist der Agent sie aus.

- name: Install the ReportedIP Agent
  ansible.builtin.shell: curl -fsSL https://reportedip.com/agent/install.sh | sh
  args:
    creates: /etc/reportedip-agent/config.yaml
  environment:
    REPORTEDIP_ACCEPT_TERMS: "1"
    REPORTEDIP_KEY: "{{ reportedip_api_key }}"
    REPORTEDIP_MODE: "drop"
    REPORTEDIP_BAN: "true"
    REPORTEDIP_NOTIFY_EMAIL: "ops@example.org"
  no_log: true

- name: Whitelist the management range
  ansible.builtin.command:
    argv: [reportedip-agent, whitelist, add, "{{ management_range }}", "management"]
  register: rip_whitelist
  changed_when: rip_whitelist.rc == 0
  failed_when: rip_whitelist.rc != 0 and "already in" not in (rip_whitelist.stderr ~ rip_whitelist.stdout)

- name: Confirm the host is healthy
  ansible.builtin.command: reportedip-agent status
  changed_when: false

no_log hält den Key aus der Ansible-Ausgabe und ihren Logs heraus; der Installer selbst hält ihn aus der Prozessliste heraus. Ein Jump-Host, von dem aus Sie nicht administrieren, braucht --admin-ip, und das gibt es nur als Argument: REPORTEDIP_ADMIN_IP existiert nicht, und install.sh reicht der Einrichtung keine Argumente durch. Lassen Sie das Skript mit REPORTEDIP_NO_SETUP=1 laufen und danach in einem zweiten Task reportedip-agent install --admin-ip 203.0.113.0/24, mit demselben Environment-Block.

cloud-init

Dieselbe Zeile in runcmd. Der Unterschied ist, wo der Key liegt: User Data kann aus der Instanz heraus jeder Prozess lesen, der den Metadatendienst erreicht, ein Key dort ist also ein Key, den jede Anwendung auf dem Host lesen kann. Wo das zählt, holen Sie ihn beim Booten aus einem Secret Store und reichen ihn in der Umgebung des einen Befehls weiter.

#cloud-config
runcmd:
  - [sh, -c, "curl -fsSL https://reportedip.com/agent/install.sh | REPORTEDIP_ACCEPT_TERMS=1 REPORTEDIP_KEY=YOUR_API_KEY REPORTEDIP_NOTIFY_EMAIL=ops@example.org sh"]
  - [reportedip-agent, whitelist, add, "203.0.113.0/24", "management"]
  - [reportedip-agent, sync]

Ein Golden Image

Legen Sie die Binärdatei ins Image und sonst nichts. REPORTEDIP_NO_SETUP=1 lädt die Binärdatei herunter, prüft und installiert sie und hört dort auf: keine Config, keine Units, keine Registrierung. Das Setup läuft einmal beim ersten Boot, auf dem echten Host, denn zwei Dinge, die es schreibt, dürfen nicht geklont werden: die Install-ID, über die der Dienst einen Server vom anderen unterscheidet, und die Auto-Whitelist, die die Adresse der Sitzung trägt, die es ausgeführt hat. Ein Image mit Install-ID macht jeden Klon zum selben Server in der Registry, eine Lizenz wird dann einmal für alle gezählt und keinem von ihnen verlässlich zugeteilt.

# In the image build:
curl -fsSL https://reportedip.com/agent/install.sh | REPORTEDIP_ACCEPT_TERMS=1 REPORTEDIP_KEY=YOUR_API_KEY REPORTEDIP_NO_SETUP=1 sh

# At first boot of the clone, once:
REPORTEDIP_ACCEPT_TERMS=1 REPORTEDIP_KEY=YOUR_API_KEY reportedip-agent install --notify-email ops@example.org
reportedip-agent sync

Control Panels

reportedip-agent doctor nennt das Panel, das er unter /usr/local findet: ISPConfig, Plesk, cPanel oder DirectAdmin. Was der Installer über den Namen hinaus konfiguriert, hängt davon ab, ob das Log-Layout pro Site dieses Panels vermessen wurde. Heute ist das ISPConfig; bei den anderen wird das Panel genannt, die Standard-Logs werden gefunden, und die Logs pro Domain tragen Sie selbst nach. Er listet außerdem die konfigurierten Quellen mit den Dateien, zu denen sie auflösen, und reportedip-agent test <log> zeigt, was ein Log liefern würde, bevor es aufgenommen wird.

ISPConfig

Auf Produktionshosts gemessen. Der Installer findet die Logs pro Site unter /var/log/ispconfig/httpd/*/access.log und error.log als Glob, eine später angelegte Site ist also ohne Änderung abgedeckt, dazu das Login-Log des Panels /var/log/ispconfig/auth.log als Quelle panel, und das Mail-Log, pure-ftpd (das ISPConfig als pure-ftpd-mysql installiert) und fail2ban, wenn sie laufen. Auf einem Hosting-Host kamen so 196 Logdateien aus 62 Zeilen Konfiguration zusammen. Die Listen mail, web und ftp folgen den aktiven Diensten und den Ports, die nicht nur auf Loopback lauschen; ssh und edge sind immer an.

Plesk

Erkannt an /usr/local/psa. Das Standard-Mail-Log wird gefunden; die Web-Logs pro Domain werden nicht konfiguriert, denn ihr Layout wurde nicht vermessen. Sie liegen üblicherweise unter /var/www/vhosts/system/<domain>/logs/ als access_log, dazu proxy_access_log, wo nginx vor Apache sitzt. Prüfen Sie es mit ls, und tragen Sie dann eine Quelle web mit Glob und eine Quelle web-error für die Error-Logs nach. Eine Panel-Firewall, die die Tabellen beim Anwenden ihrer Regeln neu schreibt, entfernt den Agenten nicht dauerhaft: der nächste Sync-Lauf bemerkt, dass die Kette fehlt, und baut sie neu, und reportedip-agent sync tut das sofort.

sources:
  - type: sshd
  - type: postfix
    path: /var/log/maillog
  - type: dovecot
    path: /var/log/maillog
  - type: web
    glob: "/var/www/vhosts/system/*/logs/access_log"
  - type: web
    glob: "/var/www/vhosts/system/*/logs/proxy_access_log"
  - type: web-error
    glob: "/var/www/vhosts/system/*/logs/error_log"

cPanel

Erkannt an /usr/local/cpanel. Drei Dinge unterscheiden sich von einem einfachen Host. Die Logs pro Domain sind die domlogs, üblicherweise /var/log/apache2/domlogs/, auf das /usr/local/apache/domlogs zeigt; eine Quelle web mit Glob deckt sie ab. Der Mailserver ist Exim und sein Log ist /var/log/exim_mainlog, kein Pfad, nach dem der Installer sucht, die Quelle exim wird also von Hand nachgetragen. Und wo csf läuft, ist /var/log/lfd.log eine eigene Quelle, csf, und jede Sperre, die lfd setzt, wird darüber gemeldet; Imunify360 hat eine Polling-Quelle, als experimentell markiert. Lassen Sie test zuerst über jedes Log laufen: ein domlog mit eigenem Format liefert nichts, und das erfährt man besser im Terminal als eine Woche später an einem leeren Zähler.

sources:
  - type: sshd
  - type: web
    glob: "/var/log/apache2/domlogs/*"
    exclude: ["*-ssl_log", "*.bkup*"]
  - type: exim
    path: /var/log/exim_mainlog
  - type: csf
    path: /var/log/lfd.log

DirectAdmin

Erkannt an /usr/local/directadmin. Die Logs pro Domain liegen üblicherweise unter /var/log/httpd/domains/, je eine <domain>.log und eine <domain>.error.log, und Exim schreibt /var/log/exim/mainlog, wieder kein Pfad, den der Installer probiert. Zwei Globs und ein Pfad decken den Host ab.

Ein Mailserver, ein Datenbankserver

Mail

Bei einem Host mit Postfix und Dovecot muss nichts nachgetragen werden. Der Installer sieht die Dienste oder die lauschenden Ports und konfiguriert beide Quellen auf dem einen Mail-Log, und die Mail-Liste landet auf den festen Mail-Ports 25, 465, 587, 110, 995, 143 und 993. Die Schwellwerte gelten pro Ereignisquelle und sind mit Absicht niedrig, denn ein Mailserver sieht wenige legitime Fehlschläge: drei SASL-Fehlschläge in einer Stunde, fünf abgelehnte Empfänger, drei amavis-Ablehnungen, zehn Dovecot-Fehlschläge. Ein Host mit Exim statt Postfix bekommt die Quelle exim, wenn das Log an einem der Debian- oder Red-Hat-Pfade liegt. Was die Maschine verlässt, ist dasselbe wie überall: die Adresse, die Kategorie-IDs, ein generierter Satz, und keine Zeile des Logs.

Datenbank

Ein Datenbank-Host, der auf nichts als SSH und dem Datenbank-Port lauscht, bekommt eine Quelle, sshd, und zwei Listen, die zählen: ssh auf dem SSH-Port und edge, die auf jeden Port passt und damit auch auf den Datenbank-Port. Der Agent liest kein Datenbank-Log, einen Brute-Force-Angriff auf die Datenbank selbst sieht er also nicht; die Antwort darauf steht nicht auf dieser Seite, sie ist eine Firewall-Regel, die den Port vom Internet fernhält. Was der Agent hinzufügt: eine Adresse, die das Netzwerk schon als Angreifer kennt, wird vor ihrem ersten Verbindungsversuch verworfen, auf jedem Port.

LXC-Container und Cloud-Firewalls

Proxmox LXC

Der Agent braucht zwei Dinge von einem Container: systemd, das ein LXC-Container mit einer systemd-Distribution hat, und ein Firewall-Backend, das er nutzen kann, und das ist die offene Frage. Ob nft oder ipset im Container ein Set anlegen kann, hängt davon ab, wie der Container privilegiert ist, und in einem unprivilegierten Container geht es meist nicht. Der Installer rät nicht: der Block mit den Voraussetzungen nennt das Backend, das er gefunden hat, und eine Installation ohne Backend läuft als reine Melde-Installation durch, und doctor sagt das ausdrücklich. Lassen Sie nach der Installation einen sync laufen und lesen Sie status: eine Kette, die da ist, ist die Antwort. Wo sie fehlt, gehört das Blocken auf den Proxmox-Host, und der Container erkennt und meldet weiter.

Ein VPS hinter einer Cloud-Firewall

Eine Provider-Firewall filtert, bevor das Paket den Host erreicht. Was sie verwirft, taucht in keinem Log auf, die Zähler und Sets des Agenten sehen also nur, was der Provider durchgelassen hat; das ist kein Fehler, das ist die Reihenfolge der Schichten. Zwei Dinge lohnen sich auf einem VPS. Tragen Sie den Bereich, aus dem Sie administrieren, gleich nach der Installation in die Whitelist ein, denn die Auto-Whitelist enthält nur die Adresse, aus der die Sitzung kam. Und kennen Sie den Weg zurück, bevor Sie ihn brauchen: die Konsole des Providers ist Out-of-Band, sie läuft nicht durch die Kernel-Sets, eine gesperrte Admin-Adresse ist von der Konsole aus also ein reportedip-agent unban <address> entfernt, und jede lokale Sperre läuft ohnehin von selbst ab.

Zuletzt aktualisiert: 30. September 2026 · Betreut vom ReportedIP-Team

Security Focused

DSGVO-konform

Made in Germany

Zurück zur Doku