Skip to content

Commit fca7366

Browse files
juliankoehnjuliankoehn
committed
feat: add GitHub and Microsoft 365 integration documentation and permissions details
1 parent 8f3cd38 commit fca7366

9 files changed

Lines changed: 267 additions & 2 deletions

File tree

‎content/docs/catalogs/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Kataloge
33
description: Übersicht der unterstützten Frameworks und Compliance-Kataloge in Kopexa
44
---
55

6-
# Frameworks & Kataloge
6+
## Frameworks & Kataloge
77

88
Kopexa unterstützt eine Vielzahl an **Compliance-, Sicherheits- und Datenschutz-Frameworks**.
99
Diese Kataloge liefern **Controls (Kontrollen)** und **Best Practices**, um regulatorische und normative Anforderungen strukturiert umzusetzen.

‎content/docs/integrations/github/index.mdx‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: GitHub Integration
3+
description: Synchronisation von Repositories, Organisationen und Security-Daten aus GitHub – plus Ausblick auf geplante Automatisierungen
4+
---
5+
6+
Mit der **GitHub-Integration** verbindet Kopexa dein GitHub-Organisation-Konto und synchronisiert automatisch relevante Informationen.
7+
Ziel: **Sichtbarkeit über alle Repositories und Projekte** herstellen und diese direkt mit **Assets, Risiken und Kontrollen** verknüpfen.
8+
9+
## Warum GitHub in Kopexa?
10+
11+
- **Zentrale Übersicht:** Alle Repos und Projekte als **Assets** im Inventory.
12+
- **Audit-Ready:** Überblick über Berechtigungen, Organisation, verwendete Technologien.
13+
- **Compliance-Verknüpfung:** Repos mit Risiken, Policies und Kontrollen verbinden.
14+
- **DSGVO/NIS2/ISO**: Nachvollziehbarkeit, wo Quellcode liegt, wer Zugriff hat, welche Sicherheitsmaßnahmen bestehen.
15+
16+
<Callout title="Gut zu wissen">
17+
Die GitHub-Integration ist aktuell **read-only**.
18+
Kopexa schreibt keine Änderungen an deine Repositories, Nutzer oder Organisationseinstellungen.
19+
</Callout>
20+
21+
## Welche Daten werden heute synchronisiert?
22+
23+
- **Organisation & Mitglieder:** GitHub-Organisation(en), User und Teams (optional).
24+
- **Repositories:** Name, Beschreibung, Sichtbarkeit (public/private), Owner.
25+
- **Repo-Assets:** Automatische Abbildung als **Assets** im Inventory.
26+
- **Metadaten:** Themen wie Default-Branch, letzte Commits, ob ein Repository archiviert ist.
27+
28+
Diese Daten sind die Basis für Risikoanalysen, z. B.: „Welche kritischen Assets liegen in public Repos? Wer hat Zugriff?“
29+
30+
## Roadmap & Zukunft: Security-Automatisierung
31+
32+
Wir arbeiten daran, **weit über reine Sichtbarkeit hinauszugehen**. Geplante Features (opt-in):
33+
34+
- **Branch Protection Checks:** Automatische Überprüfung, ob Branch Protection Rules aktiv sind (z. B. PR-Reviews, Status-Checks).
35+
- **Vulnerability Scanning:** Anbindung an GitHub Advanced Security und Dependabot-Daten, um bekannte Schwachstellen zu erfassen.
36+
- **Secret Scanning:** Erkennung von geleakten Secrets/Keys in Repositories.
37+
- **Best-Practice-Reports:** Abgleich mit OWASP DevSecOps und ISO 27001 Annex A Controls (z. B. „Secure SDLC“, „Code Integrity“).
38+
39+
Diese Daten können zukünftig **automatisiert als Evidenz** für Kontrollen dienen (z. B. „Alle kritischen Repos haben Branch Protection aktiv“).
40+
41+
<Callout title="Roadmap">
42+
Die Security-Automation befindet sich auf unserer **Produkt-Roadmap**.
43+
Wir starten mit **read-only Checks**, später folgen **optionale Remediation-Workflows** (z. B. automatisierte Branch-Protection-Policies).
44+
</Callout>
45+
46+
## Einrichtung & Berechtigungen
47+
48+
Aktuell erfolgt die Verbindung via **GitHub OAuth App / PAT (Personal Access Token)** mit Lesezugriff auf:
49+
50+
- `repo` (Leserechte für Organisation/Repos)
51+
- `read:org` (Leserechte für Organisations- und Team-Mitglieder)
52+
- `admin:repo_hook` (optional für Webhook-basierte Events, Roadmap-Feature)
53+
54+
55+
## Datenschutz & Sicherheit
56+
57+
- **Read-only Zugriff:** Keine Schreibaktionen an deinen Repos oder Organisationseinstellungen.
58+
- **Space-Isolation:** Jede Kopexa-Space ist mandantengetrennt.
59+
- **Widerruf jederzeit:** Zugriff über GitHub Settings entziehbar.
60+
61+
## Mapping in Kopexa
62+
63+
- **Repos → Assets:** Jedes Repo wird als Asset angelegt, kann mit Risiken und Kontrollen verknüpft werden.
64+
- **Owner → People:** GitHub-Nutzer können in Inventory „People“ gemappt werden.
65+
- **Policies:** Verknüpfe Kontrollen wie „Secure SDLC“ oder „Branch Protection aktiv“ direkt mit den Repos.
66+
67+
<Mermaid
68+
chart={`
69+
graph TD
70+
A[GitHub Org] --> B[Repos als Assets]
71+
B --> C[Risiken]
72+
B --> D[Kontrollen]
73+
D --> E["Evidenz (z.B. Branch Protection Check)"]
74+
style A fill:#e0f2fe,stroke:#3b82f6
75+
style B fill:#ecfdf5,stroke:#10b981
76+
style C fill:#fff7ed,stroke:#fb923c
77+
style D fill:#e5e7eb,stroke:#9ca3af
78+
style E fill:#fde68a,stroke:#f59e0b
79+
`}
80+
/>

‎content/docs/integrations/index.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Überblick
3+
description: Überblick über Kopexa-Integrationen – SSO, Datenquellen und Automatisierungen
4+
---
5+
6+
## Integrationen in Kopexa
7+
8+
Kopexa ist nicht nur eine isolierte Plattform, sondern lässt sich **nahtlos in deine bestehende IT-Landschaft einfügen**.
9+
Integrationen helfen dir, **Datenflüsse zu automatisieren**, **Aufgaben zu vereinfachen** und **Compliance-Nachweise direkt aus den genutzten Systemen** zu ziehen.
10+
11+
## Warum sind Integrationen wichtig?
12+
13+
- **Automatisierung statt Handarbeit:** Keine Excel-Listen oder manuelles Copy-Paste – Kopexa zieht Informationen direkt aus deinen Tools.
14+
- **Audit-Sicherheit:** Verknüpfe Nachweise (z. B. MFA-Status, Benutzerlisten) direkt aus angebundenen Systemen.
15+
- **Single Source of Truth:** Einheitliche Datenbasis für **Risiken, Kontrollen, Assets und Nachweise**, ohne Inkonsistenzen.
16+
- **Schnellere Onboardings:** Mit SSO und Directory-Integrationen sind Nutzer automatisch provisioniert und rollenbasiert berechtigt.
17+
18+
## Was findest du hier?
19+
20+
Dieser Bereich zeigt dir, wie du Kopexa mit wichtigen Systemen verbindest:
21+
22+
- **Identity & Access:**
23+
- **SSO & Directory** – z. B. Entra ID (Azure AD), Okta, Keycloak.
24+
Nutzer werden automatisch synchronisiert; SAML-Login für alle Pläne.
25+
- **Cloud & Infrastruktur:**
26+
- Anbindung von **Microsoft 365**, **GitHub**, **AWS/Azure/OVH** für Inventory- und Evidence-Daten.
27+
- **Security & Monitoring:**
28+
- Import von **Pen-Test-Berichten**, **Vulnerability-Scannern**, **SIEM/Logging-Systemen**.
29+
- **Vendor & Supply Chain:**
30+
- Automatisches Laden von **Zertifikaten**, **AVV**, **Fragebogendaten** über APIs.
31+
- **Ticketing & Collaboration:**
32+
- Sync mit **Jira**, **ServiceNow** oder **Slack/MS Teams** für Work-Items und Benachrichtigungen.
33+
34+
## Wie läuft eine Integration ab?
35+
36+
1. **Wähle die Integration** – z. B. SSO, Inventory oder Vendor-Sync.
37+
2. **Richte sie in Kopexa ein** – oft nur API-Key/SSO-Metadaten notwendig.
38+
3. **Mappe die Daten** – z. B. welches Feld im externen System welchem Asset/Control in Kopexa entspricht.
39+
4. **Nutze die Daten live** – z. B. MFA-Quoten aus Azure, Zertifikatsstatus aus Vendor-Portalen, Benutzerlisten aus M365.
40+
41+
<Callout title="Sicherheit & Datenschutz">
42+
Alle Integrationen sind **DSGVO-konform**, arbeiten mit **verschlüsselter Übertragung** und **rollenbasiertem Zugriff**.
43+
Wir speichern nur die für Compliance relevanten Daten. Du behältst jederzeit die Kontrolle, was angebunden wird.
44+
</Callout>

‎content/docs/integrations/meta.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"title": "Integrationen",
3+
"root": true,
4+
"pages": [
5+
"index",
6+
"---Identity & Access---",
7+
"microsoft-365",
8+
"---Developer & Code---",
9+
"github"
10+
]
11+
}

‎content/docs/integrations/microsoft-365/images/permissions.png‎

125 KB
Loading

‎content/docs/integrations/microsoft-365/index.mdx‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: Microsoft 365 / Entra ID Integration
3+
description: Automatisierte Synchronisation von Benutzern, Apps, Policies und Security-Daten aus Entra ID (Microsoft 365) für ISMS, DSMS und Audits
4+
---
5+
6+
Mit der **Microsoft 365 / Entra ID Integration** holt Kopexa automatisch alle relevanten Compliance-Daten aus deiner Entra-ID-Umgebung.
7+
Das spart manuelle Arbeit und schafft **auditfeste Evidenzen** für ISO 27001, NIS2, DSGVO, TISAX® und andere Frameworks.
8+
9+
---
10+
11+
## Warum diese Integration?
12+
13+
- **Automatisierte Evidenz:** Keine Screenshots, keine Excel-Listen – Kopexa ruft per API relevante Daten ab.
14+
- **ISMS & DSMS verbinden:** Benutzerverwaltung, MFA, Policies und Subprozessoren als **Controls/TOMs** mappen.
15+
- **Supply-Chain-Risiken managen:** Übersicht über Enterprise Apps, Consent Policies und Drittanbieter-Zugriffe.
16+
- **Audit-Ready:** Zugriff auf Audit Logs & Security Events als Nachweis für Kontrollen.
17+
18+
<Callout title="Gut zu wissen">
19+
Alle Daten werden **read-only** abgerufen und verschlüsselt gespeichert.
20+
Kopexa schreibt **keine Änderungen** in deine Microsoft-Umgebung und du kannst den Zugriff jederzeit entziehen.
21+
</Callout>
22+
23+
## Welche Daten werden synchronisiert?
24+
25+
Nach Einrichtung zieht Kopexa automatisiert u. a.:
26+
27+
- **Accounts & Personen:** Benutzer, Gruppen, Rollen inkl. MFA-Status
28+
- **Apps & Service Principals:** registrierte Enterprise Apps, Berechtigungen & Consents
29+
- **Security-Policies:** Conditional Access, Identity Provider Einstellungen, Intune Policies
30+
- **Audit-Logs & Security Events:** Anmeldeprotokolle, Sicherheitsvorfälle (als Incident-Evidenz)
31+
- **Consent & Grant Policies:** Welche Apps haben welche Rechte?
32+
- **Optional:** SharePoint/OneDrive Site Collections (Metadaten für Datenlokation/DSGVO)
33+
34+
Diese Informationen fließen in **Inventory (People/Apps)**, **Risiken**, **Kontrollen** und **Incidents** ein.
35+
36+
## Berechtigungen & Scopes
37+
38+
Bei der Einrichtung musst du als Entra-ID-Administrator einmalig Berechtigungen (Admin Consent) erteilen.
39+
Die Liste der Scopes erscheint in Microsoft wie auf diesem Screenshot:
40+
41+
![Permissions Dialog](./images/permissions.png)
42+
43+
Eine ausführliche Übersicht, welche Scopes warum benötigt werden, findest du hier:
44+
[**Berechtigungen (Permissions)**](./permissions.mdx)
45+
46+
## Setup und Einrichtung
47+
48+
1. **Integration starten:** In Kopexa unter *Integrationen → Microsoft 365* auswählen.
49+
2. **Admin Consent:** Mit einem Entra-ID-Admin einloggen, Berechtigungen akzeptieren (siehe Screenshot).
50+
3. **Sync:** Kopexa ruft die Daten read-only ab; keine manuelle Konfiguration erforderlich.
51+
4. **Mapping:** Nutzer, Apps und Policies werden automatisch in Kopexa-Module übernommen.
52+
53+
54+
## Datenschutz & Sicherheit
55+
56+
- **Read-only:** Kein Schreibzugriff in Entra oder M365.
57+
- **Space-Isolation:** Daten pro Kopexa-Space getrennt.
58+
- **Verschlüsselung:** Alle Daten werden verschlüsselt gespeichert.
59+
- **Widerruf:** Zugriff jederzeit in Entra ID entziehbar.
60+
61+
<Callout title="Transparenz">
62+
Kopexa nutzt die [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/permissions-reference).
63+
Die vollständige Liste der genutzten Endpunkte findest du in [Permissions](./permissions.mdx).
64+
</Callout>
65+
66+
---
67+
68+
## Weiterführende Inhalte
69+
70+
- [Berechtigungen & Scopes](./permissions.mdx) – welche Daten und warum
71+
- [Integrations-Übersicht](../index.mdx) – weitere Integrationen (z. B. GitHub)
72+

‎content/docs/integrations/microsoft-365/permissions.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Berechtigungen
3+
description: Welche Entra ID Graph-API-Berechtigungen benötigt Kopexa und wofür werden sie genutzt?
4+
---
5+
6+
## Berechtigungen & Scopes – Microsoft 365 / Entra ID
7+
8+
Beim Einrichten der Microsoft 365 / Entra ID Integration siehst du eine Liste von Berechtigungen, die Kopexa anfordert.
9+
Diese Berechtigungen sind **ausschließlich lesend (read-only)** und dienen dem **automatisierten Abruf von Compliance-relevanten Daten**.
10+
11+
Kopexa führt **keine Änderungen** in deinem Entra ID-Tenant durch, schreibt keine Werte zurück und hat **keine administrativen Schreibrechte**.
12+
13+
## Angefragte Scopes und deren Zweck
14+
15+
Folgende Graph-API-Scopes werden abgefragt, um typische Compliance-Nachweise abzubilden.
16+
Hier einige Beispiele:
17+
18+
- **`Read all audit log data`** – Abruf von Audit Logs (z. B. Anmelde- und Admin-Protokolle) als Evidenz für Kontrollen wie „Zugriffe werden protokolliert und überwacht“.
19+
- **`Read Microsoft Intune device configuration and policies`** – Übersicht über Gerätekonfiguration und Mobile-Device-Policies (für Mobile Security / BYOD-Nachweise).
20+
- **`Read directory data` & `Read identity providers`** – Auslesen von Benutzern, Gruppen, Domänen und Identity-Provider-Konfiguration (z. B. um MFA-Abdeckung und Rollenmodelle zu belegen).
21+
- **`Read your organization's policies` & `Read conditional access policies`** – Abruf von Richtlinien und Conditional-Access-Regeln (z. B. MFA-Pflicht, Zugriffssteuerung).
22+
- **`Read consent and permission grant policies`** – Überblick, welche Apps/Integrationen Berechtigungen haben (Supply-Chain-Risiko & Drittanbieterbewertung).
23+
- **`Read your organization's security actions` & `Read security events`** – Security-Alerts und Reaktionen abrufen (für Incident-Management und Lessons Learned).
24+
- **`Have full control of all site collections`** *(optional)* – Metadaten zu SharePoint/OneDrive-Sites auslesen, z. B. Datenlokationen und Verantwortliche (keine Datei-Inhalte!).
25+
- **`Sign in and read user profile`** – Technischer Basis-Scope für den Graph-Zugriff und User-Identifizierung.
26+
27+
<Callout title="Warum werden diese Berechtigungen benötigt?">
28+
Frameworks wie **NIS2**, **ISO 27001** oder **TISAX®** verlangen Nachweise über Benutzerverwaltung, MFA, Zugriffskontrollen, Subprozessoren und Security Events.
29+
Durch diese Scopes kann Kopexa relevante Daten automatisiert abrufen und in deinem ISMS/DSMS bereitstellen – ohne manuelle Screenshots oder Excel-Listen.
30+
</Callout>
31+
32+
## Datennutzung & Datenschutz
33+
34+
- Alle abgerufenen Daten werden **verschlüsselt gespeichert** und **Space-isoliert verarbeitet**.
35+
- Kopexa nutzt die Daten ausschließlich **read-only** für Compliance-Zwecke (z. B. zur Erstellung von Reports, Evidenzen und Risikoanalysen).
36+
- **Kein Export an Dritte** ohne dein Zutun: Du behältst jederzeit die Kontrolle, wann und mit wem Daten geteilt werden.
37+
- **Widerruf jederzeit möglich**: Du kannst die erteilten Berechtigungen in Entra ID/Microsoft 365 jederzeit entziehen oder die Integration in Kopexa deaktivieren.
38+
39+
## Transparenz & Dokumentation
40+
41+
Kopexa verwendet die **Microsoft Graph API**.
42+
Eine vollständige Liste aller genutzten Endpunkte inkl. offizieller Microsoft-Dokumentation findest du hier:
43+
44+
- [Microsoft Graph Permissions Reference](https://learn.microsoft.com/en-us/graph/permissions-reference)
45+
46+
<Callout title="Hinweis">
47+
Für Audits kannst du jederzeit exportieren, **welche Scopes freigegeben wurden**, wann der Zugriff eingerichtet wurde und wie die Daten innerhalb Kopexa verwendet werden.
48+
</Callout>
49+
50+
## Sicherheit & Audit-Fit
51+
52+
- **Least Privilege**: Es werden nur die Scopes angefragt, die für die vereinbarten Compliance-Nachweise notwendig sind.
53+
- **Nachvollziehbarkeit**: Alle Datenflüsse sind im Audit-Trail dokumentiert (wer hat wann welchen Import angestoßen).
54+
- **Kein Vendor Lock-in**: Du behältst die Hoheit über deine Entra-ID-Daten; die Integration ist optional und kann jederzeit widerrufen werden.
55+
56+
Mit diesen Berechtigungen wird eine saubere Brücke zwischen deiner Microsoft-365-Umgebung und Kopexa geschaffen – für automatisierte, prüfbare und **audit-sichere Compliance-Nachweise** ohne manuellen Aufwand.

‎content/docs/meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"pages": [
33
"platform",
4-
"catalogs"
4+
"catalogs",
5+
"integrations"
56
]
67
}

‎source.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ export const docs = defineDocs({
1818
});
1919

2020
export default defineConfig({
21+
lastModifiedTime: "git",
2122
mdxOptions: {
2223
rehypePlugins: (v) => [rehypeCode, ...v],
2324
},

0 commit comments

Comments
 (0)
⚡