Registry-Konfiguration API

ENTWURF — Nur für interne Entwicklerteams

Diese API-Referenz ist für interne Entwicklerteams bestimmt.

Übersicht

Was es ist: Die Registry-Konfiguration-API ist der zentrale Konfigurationsspeicher für Hydden Discovery. Sie bietet CRUD-Operationen für drei Konfigurationsbereiche — Systemkonfiguration, Benutzerkonfiguration und Modulkonfiguration — jeweils mit eigenem Namensraum. Alle Konfigurationen verwenden ein versioniertes, repliziertes Speichermodell mit Soft-Delete (Tombstone) und Hard-Delete (Erase) Semantik.

Quelle: src/registry/rest/rest.go

Basispfad

/internal/v1/registry

Authentifizierung

Alle Endpunkte erfordern JWT-Cookie- oder API-Token-Authentifizierung.

Konfigurationsbereiche

Bereich	Pfadpräfix	Beschreibung
Config	/internal/v1/registry/config/:entity	Konfiguration auf Systemebene (Collectors, Workflows, Bedrohungsregeln usw.)
User Config	/internal/v1/registry/usrcfg/:entity	Konfiguration pro Benutzer (gespeicherte Suchen, Einstellungen, Spaltenlayouts)
Module Config	/internal/v1/registry/modcfg/:entity	Konfiguration pro Modul (modulspezifische Einstellungen und Status)

Der Pfadparameter :entity identifiziert den Konfigurationstyp (z. B. collector.aws, workflow, threat.rule, grid.user).

Endpunkte

Systemkonfiguration

Methode	Pfad	Beschreibung
POST	/internal/v1/registry/config/:entity	Einen Konfigurationseintrag erstellen oder aktualisieren
GET	/internal/v1/registry/config/:entity	Alle Konfigurationseinträge für einen Entitätstyp auflisten
GET	/internal/v1/registry/config/:entity/:id	Einen bestimmten Konfigurationseintrag abrufen
DELETE	/internal/v1/registry/config/:entity/:id	Einen Konfigurationseintrag soft-löschen (Tombstone)
DELETE	/internal/v1/registry/config/:entity/:id/erase	Einen Konfigurationseintrag hard-löschen (permanent)

Benutzerkonfiguration

Methode	Pfad	Beschreibung
POST	/internal/v1/registry/usrcfg/:entity	Einen Benutzerkonfigurationseintrag erstellen oder aktualisieren
GET	/internal/v1/registry/usrcfg/:entity	Benutzerkonfigurationseinträge auflisten
GET	/internal/v1/registry/usrcfg/:entity/:id	Einen bestimmten Benutzerkonfigurationseintrag abrufen
DELETE	/internal/v1/registry/usrcfg/:entity/:id	Einen Benutzerkonfigurationseintrag soft-löschen
DELETE	/internal/v1/registry/usrcfg/:entity/:id/erase	Einen Benutzerkonfigurationseintrag hard-löschen

Modulkonfiguration

Methode	Pfad	Beschreibung
POST	/internal/v1/registry/modcfg/:entity	Einen Modulkonfigurationseintrag erstellen oder aktualisieren
GET	/internal/v1/registry/modcfg/:entity	Modulkonfigurationseinträge auflisten
GET	/internal/v1/registry/modcfg/:entity/:id	Einen bestimmten Modulkonfigurationseintrag abrufen
DELETE	/internal/v1/registry/modcfg/:entity/:id	Einen Modulkonfigurationseintrag soft-löschen
DELETE	/internal/v1/registry/modcfg/:entity/:id/erase	Einen Modulkonfigurationseintrag hard-löschen

Zusätzliche Endpunkte

Methode	Pfad	Beschreibung
GET	/internal/v1/registry/collectorAttributes/:entity/:eid	Erweiterte Attribute für einen Collector abrufen
GET	/internal/v1/scheduler/job_status	Alle Scheduler-Jobstatus auflisten
GET	/internal/v1/scheduler/job_status/:jid	Einen bestimmten Jobstatus abrufen

---

Konfigurations-CRUD-Operationen

Alle drei Bereiche (config, usrcfg, modcfg) teilen sich die gleiche Anfrage-/Antwortstruktur. Die folgenden Beispiele verwenden den Systemkonfigurationsbereich (/config/); ersetzen Sie /usrcfg/ oder /modcfg/ für andere Bereiche.

POST — Erstellen oder Aktualisieren

Einen Konfigurationseintrag erstellen oder aktualisieren. Der Anfragekörper umhüllt die eigentliche Konfiguration in einem versionierten Nachrichten-Envelope.

Anfrage:

POST /internal/v1/registry/config/:entity
Content-Type: application/json
Authorization: Bearer <token>

{
  "message": {
    "id": "collector-uuid",
    "name": "Corporate Active Directory",
    "host": "dc01.corp.local",
    "port": 636,
    "useSsl": true
  },
  "version": null,
  "tombstoned": false
}

Anfragefelder:

Feld	Typ	Beschreibung
message	object	Die Konfigurationsnutzlast (protobuf-abgeleitet, variiert je nach Entitätstyp)
version	bytes/null	Versionsvektor für optimistisches Concurrency (null für neue Einträge)
tombstoned	bool	Wird automatisch bei Erstellung/Aktualisierung auf false gesetzt

Antwort (200): Gibt die gespeicherte Nachricht mit einem aktualisierten version-Vektor zurück.

{
  "message": {
    "id": "collector-uuid",
    "name": "Corporate Active Directory"
  },
  "version": "dmVyc2lvbi12ZWN0b3I=",
  "tombstoned": false
}

Hinweis: Sensible Felder (Passwörter, Geheimnisse) werden in Antworten über das config.Sanitizer-Interface bereinigt.

GET — Auflisten

Alle Konfigurationseinträge für einen Entitätstyp auflisten.

Anfrage:

GET /internal/v1/registry/config/:entity
Authorization: Bearer <token>

Abfrageparameter:

Parameter	Typ	Beschreibung
tombstoned	string	Auf 1 setzen, um soft-gelöschte Einträge einzuschließen

Antwort (200): Array von Nachrichten-Envelopes, alphabetisch nach Name sortiert.

[
  {
    "message": { "id": "uuid-1", "name": "Alpha Collector" },
    "version": "...",
    "tombstoned": false
  },
  {
    "message": { "id": "uuid-2", "name": "Beta Collector" },
    "version": "...",
    "tombstoned": false
  }
]

GET — Nach ID abrufen

Einen bestimmten Konfigurationseintrag abrufen.

Anfrage:

GET /internal/v1/registry/config/:entity/:id
Authorization: Bearer <token>

Antwort (200): Einzelner Nachrichten-Envelope.

DELETE — Soft-Delete

Einen Konfigurationseintrag soft-löschen (Tombstone). Der Eintrag bleibt im Speicher, wird jedoch aus den Listenergebnissen ausgeschlossen, es sei denn ?tombstoned=1 ist angegeben.

Anfrage:

DELETE /internal/v1/registry/config/:entity/:id
Authorization: Bearer <token>

Antwort (200): Leere Antwort bei Erfolg.

Sicherung: Benutzer können ihren eigenen grid.user-Eintrag nicht löschen.

DELETE — Hard-Delete (Erase)

Einen Konfigurationseintrag dauerhaft entfernen. Diese Operation ist nicht rückgängig zu machen.

Anfrage:

DELETE /internal/v1/registry/config/:entity/:id/erase
Content-Type: application/json
Authorization: Bearer <token>

Der Anfragekörper enthält die vollständige Konfigurationsnachricht, die gelöscht werden soll.

Antwort (200): Leere Antwort bei Erfolg.

Warnung: Gelöschte Konfigurationen können nicht wiederhergestellt werden. Für generische Collectors führt das System zusätzlich CleanupGenericCollector() aus, um zugehörige Daten zu entfernen.

---

GET /internal/v1/registry/collectorAttributes/:entity/:eid

Erweiterte Zuordnungsattribute für eine generische Collector-Konfiguration abrufen.

Anfrage:

GET /internal/v1/registry/collectorAttributes/:entity/:eid
Authorization: Bearer <token>

Pfadparameter:

Parameter	Beschreibung
entity	Entitätstyp (muss ein collector.generic*-Typ sein)
eid	Entitäts-/Collector-ID

Antwort (200):

["customAttribute1", "customAttribute2", "department", "location"]

Gibt ein Array von erweiterten Attributnamen aus den Principal-Zuordnungen des Collectors zurück.

---

GET /internal/v1/scheduler/job_status

Alle Scheduler-Jobstatus auflisten. Jobs repräsentieren geplante Aufgaben wie Datenerfassungsläufe, Zuordnungszyklen und Bedrohungsbewertungen.

Anfrage:

GET /internal/v1/scheduler/job_status
Authorization: Bearer <token>

Antwort (200):

[
  {
    "message": {
      "id": "collection-corporate-ad",
      "owner": "collector-uuid",
      "starttime": 1707700800000,
      "finishtime": 1707701100000,
      "metadata": {
        "type": "collection",
        "platform": "Active Directory"
      },
      "next": 1707787200000,
      "runNow": false,
      "locked": false,
      "logs": ["Started collection", "Processed 4521 accounts", "Completed"]
    }
  }
]

Jobstatus-Felder:

Feld	Typ	Beschreibung
id	string	Job-Identifikator
owner	string	ID des Moduls/Collectors, dem dieser Job gehört
starttime	int64	Startzeit der letzten Ausführung (ms)
finishtime	int64	Endzeit der letzten Ausführung (ms)
metadata	map	Schlüssel-Wert-Metadaten (Typ, Plattform usw.)
next	int64	Nächste geplante Ausführungszeit (ms)
runNow	bool	Ob der Job zur sofortigen Ausführung in der Warteschlange steht
locked	bool	Ob der Job derzeit von einem laufenden Prozess gesperrt ist
logs	string[]	Lognachrichten der letzten Ausführung

---

GET /internal/v1/scheduler/job_status/:jid

Den Status eines bestimmten Scheduler-Jobs abrufen.

Anfrage:

GET /internal/v1/scheduler/job_status/:jid
Authorization: Bearer <token>

Antwort (200): Einzelner Jobstatus-Envelope. Gibt ein leeres Statusobjekt zurück, wenn die Job-ID nicht gefunden wird.

---

Gängige Entitätstypen

Der Parameter :entity akzeptiert die folgenden gängigen Werte:

Entitätstyp	Beschreibung
collector.ad	Active Directory Collector-Konfiguration
collector.aws	AWS Collector-Konfiguration
collector.azure	Azure AD Collector-Konfiguration
collector.okta	Okta Collector-Konfiguration
collector.generic*	Universal Connector-Konfigurationen
credential.*	Anmeldeinformationsspeicher-Konfigurationen
workflow	Automatisierungs-Workflow-Konfigurationen
action.*	Aktionsanbieter-Konfigurationen
threat.rule	Bedrohungserkennungsregel-Konfigurationen
grid.user	Plattformbenutzer-Konfigurationen
mapping.rule	Identitätszuordnungsregel-Konfigurationen
classification.rule	Kontokassifikationsregel-Konfigurationen
savedsearch	Gespeicherte Suche-Konfigurationen
notification	Benachrichtigungs-Konfigurationen

---

Fehlerantworten

Status	Beschreibung
400	Ungültiger Anfragekörper oder unbekannter Entitätstyp
403	Authentifizierung fehlgeschlagen oder Versuch der Selbstlöschung
404	Konfigurationseintrag nicht gefunden
409	Versionskonflikt (Fehler bei optimistischem Concurrency)
500	Interner Serverfehler

Verwandte Themen

• Registry API — Knoteninformationen, Beitrittscodes, Gateway-Adressen
• Backup & Wiederherstellung API — Registry- und Datenspeicher-Backup-Operationen
• Collectors API — Collector-Verwaltung auf höherer Ebene