Erkennungswerkzeug anbinden: Geräte aus dem Netz an knooing melden lassen

knooing sucht nicht selbst in Ihrem Netz. Das erledigt Ihr eigenes Erkennungswerkzeug, etwa ein Netzscanner, eine Netzwerkzugangskontrolle oder ein Monitoring. Liefert es seine Liste an knooing, prüft knooing jedes Gerät gegen den Bestand. Was dort fehlt, erscheint als Fund, den Ihr Team klärt. So fallen Geräte auf, die im Netz hängen, aber nirgends erfasst sind.

Julia Beispiel richtet in dieser Anleitung den Netzscanner der Beispiel GmbH ein. Sie legt in knooing einen Eintrag für das Werkzeug an (den Discovery-Sammler) und erzeugt ein Passwort dafür (das Anmelde-Token). Das Token gibt sie an Tobias Beispiel weiter, der den Scanner betreut. Am Ende stehen die ersten Funde in knooing. Wie Ihr Team sie klärt, steht im zweiten Teil: Unregistrierte Funde klären.

Die wichtigsten Begriffe

• Erkennungswerkzeug: ein Programm in Ihrem Netz, das Geräte findet, etwa ein Netzscanner.
• Discovery-Sammler: der Eintrag in knooing, der für ein Erkennungswerkzeug steht. Jede Lieferung gehört zu genau einem Sammler.
• Quelle (Quellsystem): der Eintrag im Quellregister, unter dem knooing die Lieferungen dieses Werkzeugs verbucht. An einem zugeordneten Objekt steht später diese Quelle.
• Anmelde-Token: das Passwort, mit dem sich das Werkzeug bei knooing ausweist. Ein API-Schlüssel, den Sie unter Einstellungen, Integrationen, Schnittstellen anlegen, funktioniert hier nicht.
• Zugangsdatum: ein gespeichertes Passwort oder ein Schlüssel, den ein Sammler für eigene Abfragen in Ihrem Netz nutzen kann; kein Kalenderdatum. Für das Melden von Funden braucht er keins. Sie können den Begriff hier übergehen.
• Basisadresse: die Adresse, unter der Fremdsysteme Ihr knooing erreichen. Die Weboberfläche, die Sie im Browser öffnen, hat eine andere Adresse.
• Lieferung: eine Liste von Geräten, die das Werkzeug an knooing schickt. In Fehlermeldungen heißt sie „Meldung“.
• Objekt: ein Eintrag im Bestand, etwa ein Server oder ein Notebook. Die App sagt dazu auch CI (Konfigurationselement). Die CI-Nummer ist seine Nummer im Bestand, etwa CI-1001.
• Mandant: Ihr Unternehmen in knooing. Das Wort steht in einigen Meldungen.
• FQDN: der vollständige Rechnername mit Domäne, etwa zeiterfassung.beispiel.local.
• Netzwerk-Kennung: ein Hostname, eine IP-Adresse oder ein Alias, den Sie am Objekt im Abschnitt Netzwerk-Kennungen hinterlegen. In manchen Hinweisen der App heißt sie Netzwerkidentität. Wie das geht, steht in Geräte für die Zuordnung vorbereiten.
• Gerätename aus dem Werkzeug: der Name, unter dem das Werkzeug ein Gerät meldet. In der Lieferung heißt er ref, in der Liste der Funde steht er in der Spalte Kennung/Endpunkt.
• Fund: ein gemeldetes Gerät, das keinem Objekt im Bestand entspricht.
• Nicht angenommen: ein geliefertes Gerät, das knooing nicht prüfen kann, weil alle Merkmale fehlen. Daraus wird kein Fund. „Abgewiesen“ heißt dagegen ein Fund, den Ihr Team bewusst aussortiert (zweiter Teil).

In den Bildern markieren Zahlen, wo Sie klicken. (i) markiert, wo Sie etwas ablesen.

Schritt 1: Den Reiter Zugangsdaten-Tresor öffnen

Klicken Sie unten in der Seitenleiste auf Einstellungen, links auf Integrationen und in der Spalte daneben auf Föderierung & Speichermodus. Klicken Sie oben auf den Reiter Zugangsdaten-Tresor (1).

1

Danach sehen Sie zwei Bereiche: oben Tresor-Anbindungen, darunter Discovery-Sammler und ihre Zugangsdaten. Für die Funde brauchen Sie nur den unteren. Den Kasten mit dem Hinweis zu Tresor-Verweisen können Sie übergehen. Steht unten „Noch kein Discovery-Sammler angelegt.“, machen Sie mit Schritt 2 weiter.

Steht Ihr Werkzeug schon in der Tabelle und liefert es, sind Sie fertig: weiter mit Schritt 5. Ein neues Token stellen Sie nur aus, wenn das alte verloren ist. Das alte gilt dann sofort nicht mehr.

Warum hier? Hier verwaltet knooing an einer Stelle alle Anmeldedaten der Erkennungswerkzeuge.

Beispiel: Julia Beispiel öffnet den Reiter, um den Netzscanner anzubinden.

Schritt 2: Einen Sammler anlegen

Unter Sammler anlegen stehen die Felder untereinander. Füllen Sie aus:

• Name (1), das erste Feld: ein Name für das Werkzeug, im Beispiel „Netzscanner Zentrale“.
• Quellsystem (2), die Auswahl darunter: die Quelle aus „Das brauchen Sie“, im Beispiel Netzscanner.
• Netzwerkzone (optional) (3), das dritte Feld: ein frei wählbarer Text für den Netzbereich, im Beispiel „Verwaltungsnetz“. knooing zeigt ihn nur in der Tabelle an; für den Abgleich zählt er nicht.

Die letzte Auswahl lassen Sie auf „später setzen“. Den erklärenden Text des Bereichs und den Hinweis „Wählen Sie GENAU EINEN Weg …“ können Sie übergehen, denn für Funde braucht der Sammler kein Zugangsdatum. Klicken Sie auf Sammler anlegen (4).

1234

Danach meldet knooing „Sammler angelegt.“ In der Tabelle darüber steht jetzt der Sammler. Unter Aktiv steht „aktiv“, unter Zugangsdatum „nicht gesetzt“. Das ist richtig so.

Warum ein Sammler je Werkzeug? Jeder Fund zeigt später, welcher Sammler ihn geliefert hat. So wissen Sie, wen Sie bei Fragen ansprechen.

Beispiel: Der Netzscanner sucht im Verwaltungsnetz der Beispiel GmbH.

Schritt 3: Das Anmelde-Token ausstellen

Klicken Sie in der Zeile des Sammlers auf Anmelde-Token (1). Die anderen Aktionen der Zeile brauchen Sie für Funde nicht.

1

Es öffnet sich der Dialog Anmelde-Token für das Erkennungswerkzeug: Netzscanner Zentrale. Er weist darauf hin: Stellen Sie ein neues Token aus, gilt das bisherige nicht mehr. Klicken Sie auf Token ausstellen (2).

2

Danach meldet knooing kurz „Das Token wurde ausgestellt.“ Im Feld steht das Token (i), darunter der gelbe Hinweis, dass es nur jetzt angezeigt wird. Klicken Sie auf Token kopieren (3); knooing meldet „Token kopiert.“ Legen Sie das Token sofort im Passwortmanager Ihres Unternehmens ab, nicht im Feld Zugangsdatum und nicht in einem Ticket. Klicken Sie erst dann auf Schließen.

i3

Geben Sie der Person, die das Werkzeug betreut, drei Dinge. Das Token geben Sie über den Passwortmanager weiter, nie per E-Mail oder Chat. Dazu kommen die Basisadresse und der Link auf diese Anleitung mit dem Hinweis auf Schritt 4.

Das Token läuft nicht ab. Es gilt, bis Sie ein neues ausstellen oder den Sammler deaktivieren.

Warum sofort sichern? knooing speichert das Token nicht im Klartext und zeigt es nie wieder. Geht es verloren, stellen Sie ein neues aus.

Beispiel: Julia Beispiel legt das Token im Passwortmanager ab und gibt Tobias Beispiel Bescheid.

Schritt 4: Das Werkzeug liefern lassen

Diesen Schritt richtet die Person ein, die das Erkennungswerkzeug betreut. Das Werkzeug schickt seine Geräteliste per POST als JSON an die Basisadresse, direkt gefolgt von /api/cmdb/discovery-findings. Das Token steht in der Kopfzeile Authorization nach dem Wort Bearer. In den Beispielen steht https://knooing-api.beispiel-gmbh.test für die Basisadresse und $TOKEN für das Anmelde-Token.

curl -X POST 'https://knooing-api.beispiel-gmbh.test/api/cmdb/discovery-findings' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d @lieferung.json

Die Datei lieferung.json enthält eine Liste devices:

{
  "devices": [
    { "ref": "srv-lagerverwaltung", "hostname": "srv-lagerverwaltung", "ipAddresses": ["10.20.1.21"] },
    { "ref": "nb-lager-07", "hostname": "nb-lager-07", "ipAddresses": ["10.20.30.47"],
      "macAddress": "3C:52:82:1A:4F:07", "serialNumber": "SN-NB-0142",
      "vendor": "Lenovo", "model": "ThinkPad T14" },
    { "ref": "zeiterfassung.beispiel.local", "fqdn": "zeiterfassung.beispiel.local",
      "ipAddresses": ["10.20.5.40"] },
    { "ref": "drucker-og2-07", "hostname": "drucker-og2-07", "ipAddresses": ["10.20.40.17"],
      "vendor": "Kyocera", "model": "ECOSYS M3655" },
    { "ref": "scan-0815" }
  ]
}

Die Angaben je Gerät:

• ref, Pflicht: der Name des Geräts im Werkzeug. Wählen Sie einen lesbaren Namen, etwa den Hostnamen, denn in der Liste der Funde steht nur er. An ref erkennt knooing dasselbe Gerät bei der nächsten Lieferung wieder.
• hostname, fqdn, ipAddresses (eine Liste, bis zu 20) und inventoryNumber: die Merkmale für den Abgleich. Mindestens eines davon braucht jedes Gerät.
• macAddress, serialNumber, vendor und model, optional: knooing speichert sie am Fund. Sie fließen in die Vorschläge beim Zuordnen ein, zählen aber nicht für den Abgleich. Angezeigt werden sie derzeit nicht.
• lastSeenAt, optional: wann das Werkzeug das Gerät gesehen hat, als Zeitpunkt nach ISO 8601, etwa 2026-10-15T02:00:00Z. Fehlt er, gilt der Zeitpunkt der Lieferung.

Neben devices darf die Lieferung sentAt enthalten, den Zeitpunkt des Versands im selben Format. Er darf höchstens 15 Minuten von der Serverzeit abweichen.

Bei Erfolg antwortet knooing mit dem Status 200. Die Antwort nennt, wie viele Geräte bekannt, neu oder nicht angenommen sind, und das Ergebnis je Gerät:

{
  "ok": true, "registered": 1, "created": 3, "updated": 0, "unchanged": 0, "rejected": 1,
  "results": [
    { "ref": "srv-lagerverwaltung", "result": "registered", "matchedBy": "name" },
    { "ref": "nb-lager-07", "result": "finding_created" },
    { "ref": "zeiterfassung.beispiel.local", "result": "finding_created" },
    { "ref": "drucker-og2-07", "result": "finding_created" },
    { "ref": "scan-0815", "result": "rejected",
      "reason": "Für den Abgleich ist mindestens Hostname, FQDN, IP-Adresse oder Inventarnummer nötig." }
  ]
}

So vergleicht knooing, in dieser Reihenfolge:

• Netzwerk-Kennung (matchedBy: network_identity): Hostname, FQDN oder eine IP-Adresse stimmt mit einer Netzwerk-Kennung eines Objekts überein.
• Name (name): Hostname oder FQDN stimmt genau mit dem Namen eines Objekts überein. Ein Kurzname wie srv-lagerverwaltung passt nicht zu einem Objekt namens srv-lagerverwaltung.beispiel.local.
• CI-Nummer (inventory_number): inventoryNumber stimmt mit der CI-Nummer eines Objekts überein. Verglichen wird nur die CI-Nummer, keine Anlagen- oder Seriennummer.

Groß- und Kleinschreibung zählt dabei nicht. Was die Ergebnisse bedeuten:

• registered: Das Gerät steht schon im Bestand, im Beispiel der Server srv-lagerverwaltung. Sie müssen nichts tun.
• finding_created: Nichts passt. knooing legt einen Fund an, den Ihr Team klärt.
• finding_updated: Zu diesem Gerät gibt es schon einen offenen Fund. knooing übernimmt die neuen Angaben und den Zeitpunkt.
• finding_unchanged: Ihr Team hat den Fund schon zugeordnet oder abgewiesen (siehe zweiter Teil). Er bleibt so.
• rejected: Das Gerät wurde nicht angenommen, weil alle Merkmale fehlen. Der Grund steht bei reason. rejected heißt hier „nicht angenommen“, nicht „abgewiesen“.

Legen Sie ein Objekt später an, erkennt knooing das Gerät bei der nächsten Lieferung. Die Antwort meldet dann registered, und der offene Fund steht auf Zugeordnet. Fehlt ein Gerät in einer Lieferung, ändert sich an seinem Fund nichts. Klappt eine Lieferung als Ganzes nicht, antwortet knooing mit einem Fehlercode und einer Meldung bei error, siehe unten.

Jede Lieferung steht außerdem als Lauf im Bericht unter Konfigurationsverwaltung, Datenflüsse, Reiter Berichte, mit der Zahl der Geräte und der nicht angenommenen. So sehen Sie auch ohne neue Funde, ob die Lieferungen ankommen. Wie Sie den Bericht lesen, steht in Fehlerbericht lesen.

Warum regelmäßig liefern? Nur dann fallen neue Geräte zeitnah auf. Eine Lieferung darf bis zu 1000 Geräte enthalten; je Unternehmen sind 20 Lieferungen in der Minute möglich.

Beispiel: Tobias Beispiel lässt den Netzscanner jede Nacht liefern. Die erste Lieferung meldet 5 Geräte: 1 bekannt, 3 neue Funde und 1 Gerät ohne jedes Merkmal, das nicht angenommen wurde.

Schritt 5: Die Funde prüfen

Öffnen Sie in der Seitenleiste Konfigurationsverwaltung, Klärfälle und den Reiter Unregistrierte Funde. Dort stehen die neuen Funde (i). In der Spalte Status steht jeweils Offen, bei Discovery-Sammler steht Netzscanner Zentrale.

i

knooing meldet neue Funde nicht per Glocke oder E-Mail. Schauen Sie deshalb regelmäßig auf die Zahl am Reiter Unregistrierte Funde; sie nennt die offenen Funde und stimmt nach dem Neuladen der Seite.

Warum prüfen? So sehen Sie, dass Token und Lieferung funktionieren, bevor das Team mit dem Klären beginnt.

Beispiel: Julia Beispiel sieht die drei Funde. Sie klärt sie selbst, wie im zweiten Teil beschrieben.

Wenn etwas nicht klappt

• Der Punkt Föderierung & Speichermodus fehlt. Ihrer Rolle fehlt die Stufe Bearbeiten in der Zeile CMDB-Verwaltung. Bitten Sie Ihre Administration darum.
• Einen Sammler löschen. Das geht nicht. Klicken Sie stattdessen auf Deaktivieren; das Werkzeug kann dann nicht mehr liefern.
• Die Auswahl Quellsystem ist leer. Es gibt noch keine aktive Quelle. Tragen Sie sie ein, wie in Quellen eintragen und Rangfolge einstellen beschrieben.
• „Dieser Eintrag existiert bereits.“ Es gibt schon einen Sammler mit diesem Namen. Wählen Sie einen anderen.
• Das Token ist verloren, oder der Dialog wurde vor dem Kopieren geschlossen. knooing zeigt ein Token nur einmal. Stellen Sie in Schritt 3 ein neues aus; das alte gilt dann nicht mehr.
• Das Werkzeug erreicht knooing nicht (Zeitüberschreitung, Zertifikatsfehler, Proxy). Firewall oder Proxy lassen die Verbindung nicht durch. Klären Sie mit Ihrem Netzwerkteam die Freigabe zur Basisadresse.
• Die Antwort ist 404 oder eine HTML-Seite. Die Adresse stimmt nicht, etwa die Adresse der Weboberfläche statt der Basisadresse. Prüfen Sie die Basisadresse und hängen Sie /api/cmdb/discovery-findings direkt an.
• 401 „Nicht authentisiert - ein gültiges Anmelde-Token des Erkennungswerkzeugs ist erforderlich.“ Das Token fehlt, ist falsch, wurde durch ein neues ersetzt, oder der Sammler ist deaktiviert. Prüfen Sie den Sammler und stellen Sie bei Bedarf ein neues Token aus.
• 400 „Der Anfragekörper braucht eine Liste "devices".“ oder „Die Liste "devices" ist leer.“ Der Inhalt der Lieferung hat das falsche Format. Lassen Sie sie nach dem Beispiel oben aufbauen.
• 413 „Pro Meldung sind höchstens 1000 Geräte erlaubt.“ Teilen Sie die Lieferung auf.
• 429 „Zu viele Meldungen für diesen Mandanten - bitte kurz warten.“ Für Ihr Unternehmen kamen mehr als 20 Lieferungen in einer Minute. Lassen Sie seltener liefern.
• 400 „sentAt muss innerhalb von 15 Minuten der Serverzeit liegen.“ Das Werkzeug schickt sentAt mit einer falschen Uhrzeit. Lassen Sie die Uhr des Werkzeugs prüfen, oder schicken Sie sentAt nicht mit.
• Ein Gerät steht bei rejected mit „Für den Abgleich ist mindestens Hostname, FQDN, IP-Adresse oder Inventarnummer nötig.“ Dem Gerät fehlen alle Merkmale für den Abgleich. Lassen Sie das Werkzeug mindestens eines mitschicken. Nicht angenommene Geräte stehen auch im Fehlerbericht.
• Die Lieferung klappt, aber in der Liste steht kein Fund. Alle Geräte waren schon im Bestand, oder die Filter passen nicht. Fragen Sie die Person am Werkzeug nach der Antwort; steht dort nur registered, sind alle Geräte bekannt. Stellen Sie Status auf Offen und die Art auf Alle Arten.
• Der Punkt Konfigurationsverwaltung fehlt. Ihrer Rolle fehlt die Stufe Lesen in der Zeile CMDB. Bitten Sie Ihre Administration darum.
• Ein Gerät gilt als bekannt, obwohl es neu ist. Ein Objekt heißt zufällig genauso wie der Hostname, oder eine Netzwerk-Kennung passt. Prüfen Sie im Bestand das Objekt mit diesem Namen und korrigieren Sie Name oder Netzwerk-Kennung.
• Ein bekanntes Gerät erscheint trotzdem als Fund. Hostname, FQDN, IP-Adresse und CI-Nummer passen zu keinem Objekt. Ordnen Sie den Fund zu, wie in Unregistrierte Funde klären beschrieben. Die Zuordnung gilt für diesen Gerätenamen. Meldet ein anderes Werkzeug dasselbe Gerät unter anderem Namen, hilft eine Netzwerk-Kennung am Objekt.
• Das Werkzeug soll vorübergehend nicht liefern. Klicken Sie in der Zeile des Sammlers auf Deaktivieren. Das Werkzeug bekommt dann den Fehler 401. Mit Aktivieren in derselben Zeile schalten Sie den Sammler wieder ein.