docs(connectors): document the Google Cloud asset connector

docs/content/connectors/toolreference/google_cloud.de.md

@@ -0,0 +1,39 @@
+---
+title: "Google Cloud"
+description: "Einrichtung des Google Cloud Upstream-Connectors für DefectDojo"
+weight: 67
+audience: pro
+---
+Der Google-Cloud-Connector ist ein **Asset-Connector**: Er liest Ihre Google-Cloud-Ressourcenhierarchie und erstellt für jedes **Projekt** ein DefectDojo-Asset, gruppiert in Organisationen nach dem Ordner, in dem das Projekt liegt. Auch jeder Ordner wird zu einem Asset, sodass Ihre Organisation, Ordner und Projekte in DefectDojo als derselbe Baum erscheinen, den Sie in der Cloud-Console sehen. Es werden keine Befunde importiert.
+
+**Bitte beachten Sie:** Dieser Connector importiert nur Ihr Projekt-**Inventar**. Um Befunde aus dem Security Command Center zu importieren, verwenden Sie den separaten Connector [Google Cloud Security Command Center](/connectors/toolreference/google_cloud_scc/). Die beiden sind unabhängig voneinander und dafür ausgelegt, gemeinsam zu laufen: Ein von diesem Connector erstelltes Projekt ist dasselbe Asset, auf dem SCC-Befunde landen, sodass der gemeinsame Betrieb nichts dupliziert.
+
+#### Voraussetzungen
+
+Der Connector authentifiziert sich mit einem Google-**Service-Konto** und liest nur Hierarchie-Metadaten: Namen, IDs, Lifecycle-Status und Labels von Ordnern und Projekten. Er liest keine Ressourceninhalte und keine Befunde.
+
+1. Erstellen Sie in Google Cloud ein Service-Konto — ein dediziertes für DefectDojo wird empfohlen.
+2. Gewähren Sie ihm die Rolle **Browser** (`roles/browser`) auf der Organisation oder dem Ordner, den Sie importieren möchten. Für das Durchlaufen der Hierarchie werden `resourcemanager.folders.list` und `resourcemanager.projects.list` benötigt. Eine benutzerdefinierte Rolle muss zusätzlich `resourcemanager.folders.get` und `resourcemanager.organizations.get` enthalten, sonst wird das oberste Asset nach seiner Ressourcen-ID statt nach seinem Anzeigenamen benannt. Wenn Ihr Konto keine Organisation hat, gibt es keine übergeordnete Ressource, auf der die Rolle gewährt werden kann: Gewähren Sie `roles/browser` auf jedem Projekt, das Sie importieren möchten.
+3. Gewähren Sie die Rolle an der **obersten Stelle** des von Ihnen konfigurierten Geltungsbereichs. Der Connector durchläuft den gesamten Teilbaum, und ein Ordner, den er nicht lesen kann, lässt den Sync fehlschlagen, statt stillschweigend ein unvollständiges Inventar zu importieren.
+4. Erstellen Sie einen **JSON-Schlüssel** für das Service-Konto und laden Sie ihn herunter.
+5. Aktivieren Sie die **Cloud Resource Manager API** (`cloudresourcemanager.googleapis.com`) für das Projekt, dem das Service-Konto gehört.
+
+#### Connector-Zuordnungen
+
+1. Lassen Sie das Feld **Location** auf dem Standardwert `https://cloudresourcemanager.googleapis.com`, sofern Sie keinen nicht standardmäßigen Endpunkt verwenden.
+2. Geben Sie im Feld **Parent Resource** die Wurzel der zu importierenden Hierarchie ein: `organizations/{id}` oder `folders/{id}`. Ein einzelnes Projekt ist keine Hierarchie, daher wird `projects/{id}` hier nicht akzeptiert — verwenden Sie für einen einzelnen Projekt-Geltungsbereich den Google-Cloud-SCC-Connector. Wenn Ihr Konto keine Organisation hat, lassen Sie das Feld leer: Der Connector importiert dann jedes Projekt, das das Dienstkonto lesen kann, als flache Liste ohne Ordnerhierarchie.
+3. Fügen Sie den vollständigen Inhalt der **JSON-Schlüssel**-Datei des Service-Kontos in das Feld **Service Account Key** ein.
+
+Jeder `ACTIVE`-Ordner und jedes `ACTIVE`-Projekt unterhalb des übergeordneten Elements wird zu einem Eintrag. Der Eintrag jedes Projekts wird nach dessen **Projekt-ID** benannt, und seine Organisation in DefectDojo ist der Ordner, in dem es liegt (oder Ihre Google-Cloud-Organisation, wenn das Projekt direkt darunter liegt).
+
+Wird ein Projekt in Google Cloud gelöscht, wechselt es in den Status `DELETE_REQUESTED` und fällt aus dem Import heraus. Sein zugeordneter Eintrag wird daher beim nächsten Sync als `MISSING` markiert, statt entfernt zu werden — DefectDojo löscht niemals stillschweigend ein Asset. Dasselbe gilt für einen gelöschten Ordner.
+
+Sobald ein Eintrag zugeordnet ist, aktualisiert dieser Connector seine Metadaten nie. Wenn Sie in Google Cloud einen Ordner umbenennen oder ein Projekt in einen anderen Ordner verschieben, zeigt DefectDojo weiterhin den alten Namen oder den alten Ordner an.
+
+#### Zusammenspiel mit dem Google-Cloud-SCC-Connector
+
+Beide Connectors identifizieren ein Projekt auf dieselbe Weise und benennen sein Asset jeweils nach der Projekt-ID. Wenn Sie zuerst diesen Connector ausführen, landen SCC-Befunde auf den von ihm erstellten Assets; lief zuerst SCC, übernimmt dieser Connector diese Assets und ergänzt sie um die Ordnerhierarchie. Sie müssen nichts doppelt zuordnen.
+
+Für die Organisation gilt dieselbe Regel: Wenn dieser Connector das Asset erstellt, setzt er die Organisation auf den Ordner des Projekts. Erstellte der Google-Cloud-SCC-Connector das Asset zuerst, behält dieses Asset seine bestehende Organisation, und dieser Connector ergänzt es nur um die Ordnerhierarchie.
+
+Eine Ausnahme: SCC-Befunde, die zu keinem Projekt gehören, etwa Richtlinienbefunde auf Organisationsebene, landen auf einem separaten Asset. Der Google-Cloud-SCC-Connector erstellt dieses Asset für seine konfigurierte übergeordnete Ressource; es ist nicht das Organisations- oder Ordner-Asset, das dieser Connector erstellt. Wenn Sie beide Connectors ausführen, rechnen Sie mit einem zusätzlichen Asset für diese Befunde.

docs/content/connectors/toolreference/google_cloud.es.md

@@ -0,0 +1,39 @@
+---
+title: "Google Cloud"
+description: "Cómo configurar el Conector Upstream de Google Cloud para DefectDojo"
+weight: 67
+audience: pro
+---
+El conector de Google Cloud es un **Asset Connector**: lee la jerarquía de recursos de su Google Cloud y crea un Activo de DefectDojo para cada **proyecto**, agrupados en Organizaciones según la carpeta en la que se encuentra el proyecto. Cada carpeta también se convierte en un Activo, de modo que su organización, sus carpetas y sus proyectos aparecen en DefectDojo como el mismo árbol que ve en la consola de Cloud. No se importa ningún hallazgo.
+
+**Tenga en cuenta:** este conector importa únicamente el **inventario** de sus proyectos. Para importar los hallazgos de Security Command Center, utilice el conector independiente [Google Cloud Security Command Center](/connectors/toolreference/google_cloud_scc/). Ambos son independientes y están diseñados para ejecutarse juntos: un proyecto que crea este conector es el mismo Activo sobre el que aterrizan los hallazgos de SCC, por lo que ejecutar ambos no duplica nada.
+
+#### Requisitos previos
+
+El conector se autentica con una **cuenta de servicio** de Google y solo lee metadatos de la jerarquía: nombres, ids, estado del ciclo de vida y etiquetas de carpetas y proyectos. No lee el contenido de los recursos ni hallazgos.
+
+1. En Google Cloud, cree una cuenta de servicio; se recomienda una dedicada para DefectDojo.
+2. Otórguele el rol **Browser** (`roles/browser`) en la organización o carpeta que desea importar. El recorrido de la jerarquía necesita `resourcemanager.folders.list` y `resourcemanager.projects.list`. Un rol personalizado debe incluir además `resourcemanager.folders.get` y `resourcemanager.organizations.get`; de lo contrario, el Asset de nivel superior recibe el nombre de su ID de recurso en lugar de su nombre visible. Si su cuenta no tiene organización, no hay un recurso principal en el que otorgar el rol: otorgue `roles/browser` en cada proyecto que desee importar.
+3. Otorgue el rol en la parte **superior** del alcance que configure. El conector recorre todo el subárbol, y una carpeta que no pueda leer hace que la sincronización falle en lugar de importar silenciosamente un inventario parcial.
+4. Cree una **clave JSON** para la cuenta de servicio y descárguela.
+5. Habilite la **Cloud Resource Manager API** (`cloudresourcemanager.googleapis.com`) en el proyecto propietario de la cuenta de servicio.
+
+#### Asignaciones del conector
+
+1. Deje el campo **Location** con el valor predeterminado `https://cloudresourcemanager.googleapis.com`, salvo que utilice un endpoint no estándar.
+2. En el campo **Parent Resource**, introduzca la raíz de la jerarquía que desea importar: `organizations/{id}` o `folders/{id}`. Un solo proyecto no es una jerarquía, por lo que `projects/{id}` no se acepta aquí — use el conector Google Cloud SCC para un alcance de un solo proyecto. Si su cuenta no tiene organización, deje el campo en blanco: el conector importa entonces todos los proyectos que la cuenta de servicio puede leer, como una lista plana sin jerarquía de carpetas.
+3. Pegue el contenido completo del archivo de **clave JSON** de la cuenta de servicio en el campo **Service Account Key**.
+
+Cada carpeta `ACTIVE` y cada proyecto `ACTIVE` bajo el elemento padre se convierte en un Record. El Record de cada proyecto se nombra según su **ID de proyecto**, y su Organización en DefectDojo es la carpeta en la que se encuentra (o su organización de Google Cloud, si el proyecto se encuentra directamente debajo de ella).
+
+Un proyecto que elimina en Google Cloud pasa al estado `DELETE_REQUESTED` y deja de importarse, por lo que su Record asignado se marca como `MISSING` en la siguiente sincronización en lugar de eliminarse: DefectDojo nunca elimina un Activo de forma silenciosa. Lo mismo ocurre con una carpeta que elimina.
+
+Una vez asignado un Record, este conector nunca actualiza sus metadatos. Si cambia el nombre de una carpeta o mueve un proyecto a otra carpeta en Google Cloud, DefectDojo sigue mostrando el nombre antiguo o la carpeta antigua.
+
+#### Uso conjunto con el conector de Google Cloud SCC
+
+Ambos conectores identifican un proyecto de la misma manera, y ambos nombran su Activo según el ID del proyecto. Por eso, si ejecuta primero este conector, los hallazgos de SCC aterrizan en los Activos que creó; si SCC se ejecutó primero, este conector adopta esos Activos y añade la jerarquía de carpetas a su alrededor. No necesita mapear nada dos veces.
+
+La Organización sigue la misma regla: cuando este conector crea el Activo, establece su Organización como la carpeta del proyecto. Cuando el conector de Google Cloud SCC crea el Activo primero, ese Activo conserva su Organización existente, y este conector solo añade la jerarquía de carpetas a su alrededor.
+
+Una excepción: los hallazgos de SCC que no pertenecen a ningún proyecto, como los hallazgos de políticas a nivel de organización, aterrizan en un Activo separado. El conector de Google Cloud SCC crea ese Activo para su recurso principal configurado, y no es el Activo de organización o carpeta que crea este conector. Si ejecuta ambos conectores, espere un Activo adicional para esos hallazgos.

docs/content/connectors/toolreference/google_cloud.fr.md

@@ -0,0 +1,39 @@
+---
+title: "Google Cloud"
+description: "Comment configurer le Connecteur Upstream Google Cloud pour DefectDojo"
+weight: 67
+audience: pro
+---
+Le connecteur Google Cloud est un **connecteur d'actifs (Asset Connector)** : il lit la hiérarchie de ressources de votre Google Cloud et crée un actif DefectDojo pour chaque **projet**, regroupés en organisations par le dossier dans lequel se trouve le projet. Chaque dossier devient également un actif, si bien que votre organisation, vos dossiers et vos projets apparaissent dans DefectDojo comme la même arborescence que celle que vous voyez dans la console Cloud. Aucune constatation n'est importée.
+
+**Remarque :** ce connecteur importe uniquement l'**inventaire** de vos projets. Pour importer les constatations de Security Command Center, utilisez le connecteur distinct [Google Cloud Security Command Center](/connectors/toolreference/google_cloud_scc/). Les deux sont indépendants et conçus pour fonctionner ensemble : un projet créé par ce connecteur est le même actif sur lequel atterrissent les constatations SCC, donc exécuter les deux ne duplique rien.
+
+#### Prérequis
+
+Le connecteur s'authentifie avec un **compte de service** Google et ne lit que les métadonnées de la hiérarchie : noms, ids, état du cycle de vie et labels des dossiers et projets. Il ne lit ni le contenu des ressources, ni les constatations.
+
+1. Dans Google Cloud, créez un compte de service — un compte dédié pour DefectDojo est recommandé.
+2. Accordez-lui le rôle **Browser** (`roles/browser`) au niveau de l'organisation ou du dossier que vous souhaitez importer. Le parcours de la hiérarchie nécessite `resourcemanager.folders.list` et `resourcemanager.projects.list`. Un rôle personnalisé doit aussi inclure `resourcemanager.folders.get` et `resourcemanager.organizations.get`, sinon l'Asset de premier niveau est nommé d'après son identifiant de ressource plutôt que son nom d'affichage. Si votre compte n'a pas d'organisation, il n'y a aucune ressource parente sur laquelle accorder le rôle : accordez `roles/browser` sur chaque projet à importer.
+3. Accordez le rôle au **sommet** du périmètre que vous configurez. Le connecteur parcourt tout le sous-arbre, et un dossier qu'il ne peut pas lire fait échouer la synchronisation au lieu d'importer silencieusement un inventaire partiel.
+4. Créez une **clé JSON** pour le compte de service et téléchargez-la.
+5. Activez l'**API Cloud Resource Manager** (`cloudresourcemanager.googleapis.com`) sur le projet propriétaire du compte de service.
+
+#### Mappages du connecteur
+
+1. Laissez le champ **Location** à sa valeur par défaut `https://cloudresourcemanager.googleapis.com`, sauf si vous utilisez un point de terminaison non standard.
+2. Dans le champ **Parent Resource**, saisissez la racine de la hiérarchie à importer : `organizations/{id}` ou `folders/{id}`. Un seul projet n'est pas une hiérarchie, donc `projects/{id}` n'est pas accepté ici — utilisez le connecteur Google Cloud SCC pour un périmètre limité à un seul projet. Si votre compte n'a pas d'organisation, laissez le champ vide : le connecteur importe alors chaque projet que le compte de service peut lire, sous forme de liste plate sans hiérarchie de dossiers.
+3. Collez le contenu complet du fichier de **clé JSON** du compte de service dans le champ **Service Account Key**.
+
+Chaque dossier `ACTIVE` et chaque projet `ACTIVE` sous le parent devient un Record. Le Record de chaque projet est nommé d'après son **ID de projet**, et son organisation dans DefectDojo est le dossier dans lequel il se trouve (ou votre organisation Google Cloud, pour un projet situé directement en dessous).
+
+Un projet que vous supprimez dans Google Cloud passe à l'état `DELETE_REQUESTED` et sort de l'import ; son Record mappé est donc marqué `MISSING` lors de la prochaine synchronisation plutôt que supprimé — DefectDojo ne supprime jamais silencieusement un actif. Il en va de même pour un dossier que vous supprimez.
+
+Une fois qu'un Record est mappé, ce connecteur ne met jamais à jour ses métadonnées. Si vous renommez un dossier ou déplacez un projet vers un autre dossier dans Google Cloud, DefectDojo continue d'afficher l'ancien nom ou l'ancien dossier.
+
+#### Fonctionnement avec le connecteur Google Cloud SCC
+
+Les deux connecteurs identifient un projet de la même manière, et tous deux nomment son actif d'après l'ID du projet. Ainsi, si vous exécutez ce connecteur en premier, les constatations SCC atterrissent sur les actifs qu'il a créés ; si SCC s'est exécuté en premier, ce connecteur adopte ces actifs et ajoute la hiérarchie de dossiers autour d'eux. Vous n'avez pas besoin de mapper quoi que ce soit deux fois.
+
+L'organisation suit la même règle : quand ce connecteur crée l'actif, il définit son organisation comme le dossier du projet. Quand le connecteur Google Cloud SCC crée l'actif en premier, cet actif conserve son organisation existante, et ce connecteur ajoute seulement la hiérarchie de dossiers autour de lui.
+
+Une exception : les constatations SCC qui n'appartiennent à aucun projet, comme les constatations de stratégie au niveau de l'organisation, atterrissent sur un actif distinct. Le connecteur Google Cloud SCC crée cet actif pour sa ressource parente configurée ; ce n'est pas l'actif d'organisation ou de dossier que crée ce connecteur. Si vous exécutez les deux connecteurs, attendez-vous à un actif supplémentaire pour ces constatations.