Inventarverwaltung

Das Inventar ist die zentrale Datenbank aller von IDIAL verwalteten Endpoints. Es speichert Verbindungsparameter, Zugangsdaten, Zertifikatsstatus und PKI-Zuweisung für jedes verwaltete Gerät. Das Inventar ist die primäre Datenquelle für Monitoring-Dashboards und Zertifikat-Lifecycle-Operationen.

hinweis

Das Inventar enthält zwischengespeicherte Informationen aus dem letzten Monitoring-Lauf — keine Live-Daten der Endpoints. Um die Daten zu aktualisieren, einen Monitoring-Lauf für die betreffenden Endpoints über POST /gds/monitor/crt auslösen.

Das Feld service identifiziert das Verbindungsprotokoll für jeden Eintrag:

gds-push-<identifier> — OPC UA GDS Push Protokoll. IDIAL unterstützt mehrere GDS-Push-Endpunkte verschiedener Hersteller und Firmware-Versionen. Da das OPC UA Informationsmodell stark variieren kann, pflegt IDIAL eine Liste getesteter Geräte und ihrer Firmware-Versionen. Der <identifier> ist dabei hersteller- und firmwarespezifisch.
ssh-<identifier> — SSH-basiertes Zertifikatsmanagement. Der <identifier> ist ein alphanumerischer Bezeichner, der den Endpunkttyp definiert. IDIAL kann mehrere SSH-verbundene Endpunkte unterstützen, wobei sich die SSH-Befehle je nach Endpunkttyp unterscheiden.
rest-<identifier> — REST API-basiertes Zertifikatsmanagement. Da jede REST API herstellerspezifisch ist, ist der <identifier> ein eindeutiger Bezeichner für eine bestimmte REST API, die für IDIAL entwickelt und getestet wurde.

GET /inventory

Gibt die vollständige Liste aller Inventareinträge über alle Service-Typen zurück (GDS, SSH, PKI usw.). Dieser Endpunkt ist der zentrale Monitoring- und Reporting-Endpunkt. Die zurückgegebenen Informationen können dazu verwendet werden, Monitoring-Dienste zu speisen, die in das operative Monitoring sowie in Incident-Management-Plattformen integriert sind.

IDIAL bewertet die Informationen nicht — es stellt sie lediglich bereit. Es obliegt dem REST-Client, die Informationen zu interpretieren und zu verarbeiten. Dadurch können Kunden die Monitoring-Informationen in ihre internen Asset-Management-, Change-Management- und Incident-Management-Prozesse integrieren.

Der Endpunkt hat keine Abhängigkeiten von anderen IDIAL-Diensten.

Authentifizierung: Erforderlich (X-API-Key)

Antwort 200

Array von Inventarobjekten:

[
  {
    "id": 1,
    "name": "Siemens PLC Line 1",
    "url": "opc.tcp://192.168.1.10:4840",
    "service": "gds-push-siemens",
    "server": "192.168.1.10",
    "port": 4840,
    "device_status": 1,
    "device_status_name": "Active",
    "pki_endpoint": "est-production",
    "username": "admin",
    "cert_subjectdn": "CN=plc-line1,O=ExampleCorp,C=DE",
    "cert_issuerdn": "CN=Issuing CA,O=ExampleCorp,C=DE",
    "cert_validfrom": "2025-01-01 00:00:00",
    "cert_validto": "2026-01-01 00:00:00",
    "cert_certb64": "MIIDxDCC...",
    "cert_expdays": 276,
    "cert_revoked": false
  }
]

Antwortfelder

Feld	Typ	Beschreibung
`id`	integer	Eindeutiger Bezeichner des Inventareintrags
`name`	string	Lesbarer Name des Endpoints
`url`	string	Vollständige Verbindungs-URL (z. B. `opc.tcp://host:port`). Wird von IDIAL intern aufgebaut und für Transparenz und Fehlersuche bei Verbindungsproblemen zurückgegeben.
`service`	string	Service-Typ-Bezeichner (siehe Service-Typen oben)
`server`	string	IP-Adresse oder DNS-FQDN des Endpoints. IDIAL verwendet diesen Wert zum Aufbau der Verbindungs-URL. Wenn ein DNS-FQDN angegeben wird, muss dieser von IDIAL auflösbar sein.
`port`	integer	Netzwerkport des Zertifikatsverwaltungsdienstes am Endpoint.
`device_status`	integer	`0` = Inaktiv, `1` = Aktiv (siehe Parameterreferenz). Bei `0` überwacht IDIAL den Endpoint, löst jedoch keine Zertifikats- oder Trust-List-Aktualisierungen aus.
`device_status_name`	string	Lesbarer Statusname
`pki_endpoint`	string	Konfigurierte Endpunkt-ID des Enrollment-Ziels für dieses Asset. Jeder EST-Endpunkt bietet Enrollment-Funktionen für eine bestimmte Zertifikatsvorlage. Die PKI-Konfiguration enthält die Endpunktinformationen.
`username`	string	Konfigurierter Benutzername für die Authentifizierung am Endpoint, sofern ein Benutzername definiert wurde.
`cert_subjectdn`	string	Subject DN des aktuell am Endpoint aktiven Zertifikats.
`cert_issuerdn`	string	Issuer DN des aktuell am Endpoint aktiven Zertifikats. Gibt an, von welcher CA das Zertifikat ausgestellt wurde.
`cert_validfrom`	string	Datum und Uhrzeit des Beginns der Zertifikatsgültigkeit des aktuell am Endpoint aktiven Zertifikats.
`cert_validto`	string	Datum und Uhrzeit des Endes der Zertifikatsgültigkeit des aktuell am Endpoint aktiven Zertifikats.
`cert_certb64`	string	Base64-kodiertes digitales Zertifikat, das von IDIAL am Endpoint identifiziert wurde.
`cert_expdays`	integer	Tage bis zum Ablauf des identifizierten Zertifikats. Dieser Wert wird von IDIAL auf Basis des `cert_validto`-Felds und der aktuellen IDIAL-Systemzeit berechnet.
`cert_revoked`	boolean	Gibt an, ob das Zertifikat widerrufen wurde.

hinweis

Das Inventar enthält keine Live-Daten, sondern die Informationen, die IDIAL beim letzten Monitoring-Lauf gegen den Endpoint aufgezeichnet hat. Um die aktuellsten Daten aller Endpoints zu erhalten, sollten Monitoring-Aufgaben für alle Endpoints ausgeführt werden — dabei ist jedoch darauf zu achten, dass die Last auf den Endpoints den laufenden Betrieb nicht beeinträchtigt.

Fehlerantwort

{"error": "string"}

POST /inventory

Erstellt einen neuen Inventareintrag oder aktualisiert einen bestehenden. IDIAL verwendet UPSERT-Logik: Die generierte Verbindungs-URL ist der eindeutige Schlüssel — existiert bereits ein Eintrag mit derselben URL, wird er aktualisiert; andernfalls wird ein neuer Eintrag angelegt.

Der Endpunkt validiert Eingabedaten auf mehreren Ebenen: Schema-Validierung, Business-Logic-Prüfungen und Datenbank-Integritätsprüfungen. Alle Passwörter werden vor der Speicherung automatisch mit dem Systemverschlüsselungsschlüssel verschlüsselt. Kritische Validierungen umfassen: Protokoll-Unterstützungsprüfung, Key-Value-Format-Parsing, URL-Eindeutigkeitsprüfung über alle Datenbanktabellen sowie PKI-Konfigurations-Validierung.

Authentifizierung: Erforderlich (X-API-Key)

Anfrage-Body

{
  "protocol": "GDS Push",
  "host": "192.168.1.10",
  "port": 4840,
  "userinfo_name": "admin",
  "userinfo_password": "secret",
  "device_status": 1,
  "pki": 1,
  "security_policy": 8,
  "security_mode": 2
}

Anfrage-Felder

Feld	Typ	Erforderlich	Standard	Beschreibung
`protocol`	string	Ja	`"GDS Push"`	Kommunikationsprotokoll für die Geräteintegration. Aktuell wird ausschließlich `"GDS Push"` unterstützt. Groß-/Kleinschreibung wird ignoriert: `"gds push"`, `"GDS Push"` und `"GDS PUSH"` sind gleichwertig.
`host`	string	Ja	`"localhost"`	FQDN oder IP-Adresse des Zielgeräts. Wird verwendet, um die Verbindung zum Zielendpunkt aufzubauen.
`port`	integer	Nein	`4840`	Port, auf dem der Zielendpunkt lauscht. Standard: `4840` (Standard-OPC-UA-Port).
`userinfo_name`	string	Nein	—	Benutzername für die OPC UA Authentifizierung. Kann ein leerer String sein.
`userinfo_password`	string	Nein	—	Passwort für die OPC UA Authentifizierung. Wird vor der Speicherung verschlüsselt. Es wird keine Passwort-Stärke-Validierung durchgeführt.
`device_status`	integer	Nein	`1`	Statuskennzeichen des Zielgeräts. `0` = Inaktiv, `1` = Aktiv. Wenn auf `0` (Inaktiv) gesetzt, überwacht IDIAL das Zertifikat des Endpoints, löst jedoch keine Zertifikats- oder Trust-List-Aktualisierungen aus.
`pki`	integer	Nein	—	PKI-Konfigurations-ID. Die PKI-Endpunktkonfiguration wird über einen Bezeichner referenziert. Die verfügbaren IDs können über `GET /pki/est` abgerufen werden.
`security_policy`	integer	Nein	`31`	OPC UA Security Policy Bitmask (siehe Parameterreferenz)
`security_mode`	integer	Nein	`0`	OPC UA Security Mode (siehe Parameterreferenz)

Antwort 200

{"success": true, "execution": "...", "error": "", "result": {...}}

Fehlercodes

Code	Fehlertyp	Beschreibung
400	Ungültiges Datenformat	Der Anfrage-Body enthält ungültige Datentypen oder eine fehlerhafte Struktur. Die Eingabedaten konnten aufgrund von Formatierungsfehlern nicht verarbeitet werden.
500	Inventardienst nicht verfügbar	Das Inventarsystem ist vorübergehend nicht erreichbar oder hat Probleme.
500	Gerätekonfigurationskonflikt	Die Gerätekonfiguration steht im Widerspruch zu vorhandenen Inventareinträgen.
500	Ungültige PKI-Konfiguration	Die angegebene PKI-Konfiguration existiert nicht oder ist ungültig.
500	Geräteregistrierung fehlgeschlagen	Das Gerät konnte nicht zum Inventarsystem hinzugefügt oder dort aktualisiert werden.
500	Ungültige Service-Antwort	Der Inventardienst hat ein unerwartetes Antwortformat zurückgegeben.
501	Nicht unterstütztes Protokoll	Das gesendete Protokoll wird von IDIAL in dieser Version nicht unterstützt. Bitte ausschließlich unterstützte Zertifikatsverwaltungsprotokolle verwenden.

PATCH /inventory

Aktualisiert einen bestehenden Inventareintrag. Verwendet dasselbe Schema wie POST /inventory. Es werden nur die übermittelten Felder aktualisiert.

Authentifizierung: Erforderlich (X-API-Key)

GET /gds/inventory

Gibt alle GDS Push Inventareinträge zurück.

Authentifizierung: Erforderlich (X-API-Key)

Antwort 200

Array von Inventarobjekten (gleiches Schema wie GET /inventory, gefiltert auf GDS-Einträge).

POST /gds/inventory

Erstellt einen neuen GDS Push Inventareintrag.

Authentifizierung: Erforderlich (X-API-Key)

Anfrage-Body

{
  "server": "192.168.1.10",
  "port": 4840,
  "name": "PLC Line 1",
  "userinfo_name": "admin",
  "userinfo_password": "secret",
  "device_status": 1,
  "pki": 1,
  "security_policy": 8,
  "security_mode": 2,
  "renewal_days": 30
}

Anfrage-Felder

Feld	Typ	Erforderlich	Standard	Beschreibung
`server`	string	Ja	—	IP-Adresse oder FQDN
`port`	integer	Nein	`4840`	OPC UA Port
`name`	string	Nein	—	Lesbarer Name des Endpoints
`userinfo_name`	string	Nein	—	OPC UA Benutzername
`userinfo_password`	string	Nein	—	OPC UA Passwort (wird verschlüsselt gespeichert)
`device_status`	integer	Nein	`1`	`0` = Inaktiv, `1` = Aktiv
`pki`	integer	Nein	—	PKI-Konfigurations-ID
`security_policy`	integer	Nein	`31`	Security Policy Bitmask
`security_mode`	integer	Nein	`0`	Security Mode
`renewal_days`	integer	Nein	—	Tage vor Ablauf, ab denen die automatische Erneuerung ausgelöst wird

Antwort 200

Angelegtes oder aktualisiertes Inventarobjekt.

PATCH /gds/inventory

Aktualisiert einen bestehenden GDS-Inventareintrag. Verwendet dasselbe Schema wie POST /gds/inventory. Es werden nur die übermittelten Felder aktualisiert.

Authentifizierung: Erforderlich (X-API-Key)

GET /gds/inventory/{host_or_url}

Gibt einen bestimmten GDS-Inventareintrag anhand des Server-Hostnamens, der IP-Adresse oder der vollständigen OPC UA URL zurück.

Authentifizierung: Erforderlich (X-API-Key)

Pfadparameter

Parameter	Beschreibung
`host_or_url`	Server-Hostname, IP-Adresse oder vollständige OPC UA URL (bei Bedarf URL-kodiert)

Antwort 200

Einzelnes Inventarobjekt.

Antwort 404

Eintrag nicht gefunden.

Beispiel

curl -X GET "http://localhost:5000/gds/inventory/192.168.1.10" \
  -H "X-API-Key: your-api-key"

GET /ssh/inventory

Gibt alle SSH-basierten Inventareinträge zurück. SSH-Verbindungen werden für das Zertifikatsmanagement auf Geräten verwendet, die OPC UA GDS nicht unterstützen.

Authentifizierung: Erforderlich (X-API-Key)

Antwort 200

Array von Inventarobjekten, gefiltert auf SSH-Einträge (gleiches Schema wie GET /inventory).

Beispiele

# Alle Inventareinträge abrufen
curl -X GET http://localhost:5000/inventory \
  -H "X-API-Key: your-api-key"

# Neues GDS-Gerät hinzufügen
curl -X POST http://localhost:5000/gds/inventory \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840,
    "name": "PLC Line 1",
    "userinfo_name": "admin",
    "userinfo_password": "secret",
    "device_status": 1,
    "security_policy": 8,
    "security_mode": 2
  }'

# Bestimmten Eintrag abrufen
curl -X GET "http://localhost:5000/gds/inventory/192.168.1.10" \
  -H "X-API-Key: your-api-key"

GET /inventory​

Antwort 200​

Antwortfelder​

Fehlerantwort​

POST /inventory​

Anfrage-Body​

Anfrage-Felder​

Antwort 200​

Fehlercodes​

PATCH /inventory​

GET /gds/inventory​

Antwort 200​

POST /gds/inventory​

Anfrage-Body​

Anfrage-Felder​

Antwort 200​

PATCH /gds/inventory​

GET /gds/inventory/{host_or_url}​

Pfadparameter​

Antwort 200​

Antwort 404​

Beispiel​

GET /ssh/inventory​

Antwort 200​

Beispiele​

GET /inventory

Antwort 200

Antwortfelder

Fehlerantwort

POST /inventory

Anfrage-Body

Anfrage-Felder

Antwort 200

Fehlercodes

PATCH /inventory

GET /gds/inventory

Antwort 200

POST /gds/inventory

Anfrage-Body

Anfrage-Felder

Antwort 200

PATCH /gds/inventory

GET /gds/inventory/{host_or_url}

Pfadparameter

Antwort 200

Antwort 404

Beispiel

GET /ssh/inventory

Antwort 200

Beispiele