> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgea.app/llms.txt
> Use this file to discover all available pages before exploring further.
# PolicyIQ
> Corgea über Richtlinien um geschäftlichen Kontext erweitern
**Voraussetzung:** Sie haben einen [Scan](scanning) abgeschlossen und PolicyIQ ist aktiviert. Wenden Sie sich zur Aktivierung an Ihren Ansprechpartner bei Corgea.
Corgea enthält vorkonfigurierte Richtlinien für gängige Sicherheitsmuster, Frameworks und Infrastrukturkonfigurationen, die sofort verwertbare Ergebnisse liefern.
Sie können diese Richtlinien anpassen und um Geschäfts-, Netzwerk- und Umgebungskontext erweitern. Dadurch verbessert sich die Genauigkeit bei der Schwachstellenerkennung, der Identifizierung von False Positives und der Generierung von Fixes. Der zusätzliche Kontext hilft Corgea, Ihre Sicherheitsanforderungen und Infrastruktur zu berücksichtigen.
## Wichtiges Verhalten von Richtlinien
Beachten Sie vor der Konfiguration folgende Verhaltensweisen:
1. **Anwendung der Richtlinie**: Neue Richtlinien treten nur für neue Scans in Kraft – sie wirken sich nicht rückwirkend auf bestehende Ergebnisse aus.
2. **Richtlinienvorrang**:
* Bei False-Positive-Erkennung und Fixes haben spezifische Richtlinien Vorrang vor allgemeinen Richtlinien
* Beispielsweise überschreibt eine SSRF-spezifische False-Positive-Richtlinie eine allgemeine False-Positive-Richtlinie
* Kundenspezifische Richtlinien haben immer Vorrang vor Corgeas integrierten Richtlinien
3. **Richtliniengruppierung**: Für Scan-Richtlinien wird empfohlen, verwandte Sicherheitsaspekte zusammenzufassen, anstatt einzelne Richtlinien zu erstellen. Zum Beispiel:
* Authentifizierung, Autorisierung und Berechtigungsverwaltung zusammenfassen
* Verwandte Datenvalidierungsprüfungen kombinieren
* Zusammengehörige Prüfungen von Sicherheitskontrollen bündeln
Dieser Ansatz liefert bessere Ergebnisse, da sich die betreffenden Sicherheitsaspekte häufig überschneiden.
## Richtlinienstruktur
Eine gut strukturierte Richtlinie sollte die folgenden Komponenten enthalten:
1. **Policy Type**: Wählen Sie BLAST zur Schwachstellenerkennung, False Positive zur Identifizierung von Fehlalarmen oder Fix für Code-Fixes.
2. **Business Context**: Beschreiben Sie:
* Geschäftsbereich und Anforderungen
* Netzwerkarchitektur und Sicherheitskontrollen
* Umgebungsspezifische Konfigurationen
* Anforderungen an Datenklassifizierung und -verarbeitung
* Compliance-Anforderungen (z. B. PCI, HIPAA, DSGVO)
3. **Description**: Geben Sie klare Anweisungen mit Ihrem Kontext an, darunter:
* Spezifische Schwachstellenmuster in Ihrer Umgebung
* Codebeispiele, die für Ihre Architektur relevant sind
* Den Umgang mit Issues unter Berücksichtigung Ihrer Infrastruktur
4. **Schwachstellentypen (CWEs)**: Wählen Sie aus, welche Arten von Sicherheitslücken diese Richtlinie behandeln soll, basierend auf Ihrem Risikoprofil.
5. **Projects**: Wählen Sie die Projekte aus, für die die Richtlinie gelten soll. Bei aktiviertem Project Access Control können Benutzer ohne Administratorrolle Richtlinien nur für Projekte erstellen und verwalten, auf die sie Zugriff haben. Dabei müssen sie mindestens ein zugängliches Projekt auswählen. Unternehmensadministratoren können weiterhin projektübergreifende Richtlinien erstellen.
6. **File Pattern (Glob)**: Beschränken Sie die Richtlinie optional auf passende Dateien, beispielsweise `src/**/*.py`. Ohne Wert gilt sie für alle Dateien.
7. **Guidance Notes (Optional)**: Ergänzen Sie statische Hinweise für Entwickler, etwa interne Behebungshinweise, Links zu Standards oder Implementierungstipps. Diese Hinweise erscheinen bei Issues, auf die die Richtlinie angewendet wurde.
8. **Instruction Type**: Legen Sie fest, wie Ihre Anweisungen mit Corgeas integrierten Richtlinien interagieren:
* **Append to Corgea Default Policy**: Ergänzt Corgeas integrierte Richtlinie um Ihre Anweisungen. Verwenden Sie diese Option für zusätzlichen Geschäftskontext, Sicherheitskontrollen oder Umgebungsdetails.
* **Replace Corgea Default Policy**: Ersetzt Corgeas Standardverhalten vollständig durch Ihre Anweisungen. Verwenden Sie diese Option, wenn Sie die Behandlung bestimmter Szenarien vollständig steuern möchten.
## Policy Playground
Policy Playground ist ein zweigeteilter Arbeitsbereich, in dem Sie Richtlinien erstellen, aktualisieren und testen, bevor diese Ihre Scans beeinflussen. Links bearbeiten Sie die Richtlinie, rechts testen Sie sie mit echtem Code.
* Der Arbeitsbereich besteht aus einem **Policy Editor** links und einem **Test Panel** rechts. Die Breite beider Bereiche lässt sich über den Trenner ändern.
* Mit **Back to Policies** in der oberen Toolbar kehren Sie zur Tabelle Policies zurück.
* Öffnen Sie eine bestehende **BLAST**- oder **False Positive**-Richtlinie direkt in Policy Playground aus der Richtlinientabelle.
* Durchsuchen Sie die Tabelle "Policies" nach **Policy ID**, Name, Typ oder Beschreibung, um eine Richtlinie schnell zu finden.
* Das Bearbeiten und Speichern im Policy Playground aktualisiert die Richtlinie, indem eine neue Version erstellt wird.
* **Instruction Type** im Editor wird als zwei klar erklärte Optionen angezeigt: **Replace Corgea Default Policy** oder **Append to Corgea Default Policy**.
* Lassen Sie **Projects**, **File Pattern (Glob)** oder **CWEs** leer, wenn diese Richtlinie global angewendet werden soll.
* Wenn die Projekt-Zugriffskontrolle aktiviert ist, können Benutzer mit eingeschränktem Zugriff Richtlinien sehen, die für sie sichtbar sind, aber nur Richtlinien bearbeiten oder löschen, die vollständig auf Projekte angewendet werden, auf die sie zugreifen können.
Im Policy Playground können Sie nur **BLAST**- und **False Positive**-Richtlinien testen. **Fix**-Richtlinien lassen sich weiterhin im Policy Center erstellen, erscheinen im Playground jedoch als **Fix (coming soon)**, da Fix-Tests noch nicht unterstützt werden.
### Testen einer Richtlinie
Wählen Sie zum Testen einer Richtlinie ein **Project** und eine **file** aus und klicken Sie auf **Test**. Während des Scans zeigt die Schaltfläche **Testing…** an und bleibt bis zum Abschluss deaktiviert. Fehlen Pflichtangaben, nennt ein Hinweis unter der Schaltfläche die fehlenden Werte: Projekt, Datei oder Richtlinienanweisungen.
Standardmäßig zeigt die Dateiauswahl nur Dateien mit erkannten Issues an. Um eine noch nicht vorhandene Datei zu testen, aktivieren Sie **New Test File**, wählen ein Projekt und geben einen Dateinamen ein. Das Projekt liefert den Sprach- und Framework-Kontext; den Testcode geben Sie anschließend im Editor ein.
### Ergebnisse überprüfen
Nach Abschluss des Scans erscheinen die Findings unter der Dateivorschau. Jede aufklappbare Zeile zeigt **severity**, **CWE** und **line number**. Klappen Sie ein Finding auf, um die Erklärung zu lesen, und wechseln Sie mit **Jump to line** zur betreffenden Zeile.
Findet der Scan keine Treffer, zeigt das Panel **No issues found for this policy** an und bestätigt damit die erfolgreiche Ausführung.
## PR-Scan- und Kommentarrichtlinien
PR Scan & Comment Rules steuern, wann Corgea Pull Requests scannt und Finding-Kommentare im Pull Request veröffentlicht.
* **Scan Only** scannt den Pull Request, veröffentlicht aber keine Finding-Kommentare.
* **Scan & Comment** scannt und kommentiert Findings, die der Regel entsprechen.
* **Severity** beschränkt die Regel auf ausgewählte Schweregrade. Ohne Auswahl gilt jeder Schweregrad.
* **Classification to comment** beschränkt Kommentare auf ausgewählte CWE-Typen. Ohne Auswahl werden alle passenden CWEs kommentiert.
* **Projects** und **Project Tags** bestimmen den Geltungsbereich. Eine Regel gilt, wenn das Projekt direkt ausgewählt ist oder eines der gewählten Tags besitzt. Sind beide Felder leer, gilt sie für alle Projekte.
* **Integrations** beschränkt die Regel zusätzlich auf Pull Requests ausgewählter GitHub-, GitLab- oder Azure-DevOps-Integrationen. Ohne Auswahl bestimmen nur Projekte und Projekt-Tags den Scope.
Mit dem Projekt-Tag-Filter auf der Seite für PR-Regeln finden Sie Scan-&-Comment-Regeln für Projekte mit einem bestimmten Tag. In der Tabelle zeigt die Spalte Projects ausgewählte Projekte und Tags als Chips. Regeln ohne Projekt- oder Tag-Scope zeigen **All Projects**; längere Listen werden hinter dem Tooltip **+N more** zusammengefasst.
## Best Practices für Richtlinien
Beim Schreiben von Richtlinien befolgen Sie diese bewährten Methoden, um einen effektiven Kontext zu bieten:
1. **Seien Sie spezifisch hinsichtlich Ihrer Umgebung**: Detaillieren Sie Ihre Infrastruktur, Sicherheitskontrollen und kompensierende Kontrollen.
2. **Geschäftslogik einbeziehen**: Erklären Sie geschäftsspezifische Validierungsregeln, Datenflüsse und Sicherheitsanforderungen.
3. **Sicherheitsarchitektur beschreiben**: Dokumentieren Sie Ihre Sicherheitsebenen, Vertrauensgrenzen und Schutzmechanismen.
4. **Datenkontext definieren**: Geben Sie an, wie verschiedene Datentypen in Ihrer Umgebung behandelt werden sollen.
5. **Ausnahmen dokumentieren**: Notieren Sie legitime Geschäftsfälle für scheinbare Sicherheitsprobleme.
## Beispiele
Beim Erstellen von Richtlinienbeispielen beachten Sie diese Tipps, um sie effektiver zu machen:
1. **Mehrere Beispiele verwenden**: Fügen Sie 3-5 verschiedene Beispiele für jeden Richtlinientyp hinzu, um:
* Verschiedene Anwendungsfälle und Szenarien zu zeigen
* Spezifische Randfälle Ihrer Umgebung abzudecken
* Unterschiedliche Komplexitätsstufen zu demonstrieren
* Veranschaulichen Sie verschiedene Sicherheitskontrollen und ausgleichende Maßnahmen
2. **Beispiele relevant machen**: Stellen Sie sicher, dass Ihre Beispiele:
* Ihre tatsächliche Infrastruktur und Architektur widerspiegeln
* Echte Sicherheitskontrollen enthalten, die Sie verwenden
* Auf Ihre spezifischen Tools und Frameworks verweisen
* Mit Ihren Entwicklungsmustern und -praktiken übereinstimmen
3. **Beispiele klar strukturieren**: Formatieren Sie Ihre Beispiele mit:
* Klare Abschnittsüberschriften und Bezeichnungen
* Konsistente Formatierung und Einrückung
* Detaillierte Kommentare, die Schlüsselpunkte erklären
* Tags zur Trennung verschiedener Komponenten
4. **Kontext einbeziehen**: Jedes Beispiel sollte bereitstellen:
* Das spezifische Geschäftsszenario
* Relevante Infrastrukturdaten
* Eingesetzte Sicherheitskontrollen
* Erwartetes Verhalten und Ergebnisse
Nachfolgend finden Sie Beispielrichtlinien, die diese Prinzipien demonstrieren:
### BLAST-Richtlinienbeispiel
**Richtlinientyp**: BLAST
```
Business Context: Our application processes healthcare data behind a secure API gateway that handles encryption. Internal services communicate over a private network with mutual TLS. All database access is through our custom ORM that implements row-level encryption.
Description: Review code considering our infrastructure. Flag potential PHI exposure but account for our API gateway encryption. Consider our network segregation when evaluating internal service communication. Verify proper use of our custom ORM for database access.
Use Cases:
- Detecting direct database access bypassing our ORM
- Identifying services accidentally exposed outside the API gateway
- Finding improper internal service authentication
- Detecting logging of pre-encryption PHI
- Identifying misuse of our security infrastructure
```
### False Positive-Richtlinienbeispiel
**Richtlinientyp**: False Positive
```
Business Context: Our test environments use sanitized data and mock services. All external services are replaced with stubs. The test network is isolated and all traffic is monitored. We use a custom test framework that simulates security controls.
Description: Consider our test infrastructure when evaluating security issues. Data that appears sensitive is actually sanitized. External service calls are mocked. Network isolation provides additional security layers.
Use Cases:
- Validating test data handling
- Confirming proper use of service mocks
- Verifying test environment isolation
- Checking sanitized data usage
- Validating test security controls
```
### Fix-Richtlinienbeispiel
Hier ist ein Beispiel für eine Fix-Richtlinie, die eine benutzerdefinierte Middleware verwendet, um vor XSS-Schwachstellen zu schützen:
**Richtlinientyp**: Fix
````
Business Context: We use a custom security middleware called "SecureMiddleware" that provides XSS protection, among other security features. All web applications must use this middleware for request handling. The middleware automatically sanitizes user input and encodes output to prevent XSS attacks.
Description: Generate fixes that integrate with our SecureMiddleware for XSS protection. Use the built-in sanitization and encoding functions provided by the middleware. Follow our secure coding guidelines for handling user input and rendering output.
Use Cases:
- Implementing XSS protection using SecureMiddleware
Example:
```javascript
// Import the SecureMiddleware
import SecureMiddleware from '../middleware/SecureMiddleware';
// Use the middleware for request handling
router.get('/profile', SecureMiddleware.sanitizeInput(), (req, res) => {
const username = req.query.username; // Username is now sanitized
// Render the profile page with encoded output
res.render('profile', {
username: SecureMiddleware.encodeOutput(username)
});
});
`` `
In this example, the `SecureMiddleware.sanitizeInput()` function is used to sanitize the `username` parameter from the query string, preventing XSS attacks through user input. The `SecureMiddleware.encodeOutput()` function is then used to encode the `username` value before rendering it in the template, preventing XSS attacks through output rendering.
- Integrating with our centralized security middleware
Example or description: [Add an content]
- Following secure coding practices for user input handling
Example or description: [Add an content]
- Implementing context-specific XSS protection measures
Example or description: [Add an content]
````
Mit diesem Kontext kann Corgea Fixes generieren, die Ihre eigene Security-Middleware korrekt integrieren und Ihre Secure-Coding-Vorgaben für den XSS-Schutz einhalten.
**Richtlinientyp**: Fix
```
Business Context: We use a custom security framework that provides encryption, authentication, and audit logging. All services must use our security middleware. We have specific requirements for key rotation and cipher selection.
Description: Generate fixes that integrate with our security framework. Use our standard middleware components. Follow our encryption standards and key management practices. Ensure proper audit logging through our centralized system.
Use Cases:
- Implementing framework-compliant security controls
Example or description: [Add an content]
- Integrating with our authentication services
Example or description: [Add an content]
- Setting up proper audit logging
Example or description: [Add an content]
- Configuring encryption using our standards
Example or description: [Add an content]
- Establishing service-to-service authentication
Example or description: [Add an content]
- Implementing environment-specific security measures
Example or description: [Add an content]
```
Ausführlicher Kontext zu Geschäftsumgebung, Sicherheitskontrollen und Infrastruktur ermöglicht Corgea präzisere, auf Ihre Anforderungen zugeschnittene Sicherheitsanalysen.
## Durch Prework generierte Richtlinien
Wenn Prework für Ihr Unternehmen aktiviert ist, kann Corgea bereits vor Abschluss des Hauptscans Richtlinien aus dem Projektkontext generieren.
* Generierte Richtlinien erscheinen in der Tabelle **Policies** mit dem Wert **Generated By Corgea Prework** unter `Source`.
* In den Scan-Details zeigt der Tab **Policies** alle auf den Scan angewendeten Richtlinien einschließlich älterer archivierter oder inaktiver Versionen. Von dort können Sie die Details öffnen.
* Ist unter **Policies > Settings** die Option **Policy Review** aktiviert, erstellt Corgea generierte Richtlinien als **Inactive**, damit Ihr Team sie prüfen und manuell aktivieren kann.
### Richtlinie generieren
Sie können die Richtliniengenerierung jederzeit auf der PolicyIQ-Seite manuell starten.
Klicken Sie auf der Seite **PolicyIQ** oben rechts auf **Generate Policy**.
Wählen Sie im Dialog ein **Pattern** (z. B. Authentication), ein **Project** und einen **Policy Type** aus. Starten Sie mit **Generate**.
Corgea analysiert Ihr Projekt im Hintergrund mit einem **Corgea-Prework**-Scan. Den Fortschritt können Sie unter **Scans** verfolgen.
Nach Abschluss erscheint die Richtlinie in der Tabelle **Policies**. Öffnen Sie sie, um die Details einschließlich der Beschreibung mit realen Codemustern aus Ihrem Projekt zu prüfen.
## Unterstützung für Corgea-Richtlinien in YAML
Mit einer `corgea.yaml`-Datei können Kunden Sicherheitsrichtlinien für ihre Projekte definieren, darunter:
* Bestimmte CWE-IDs
* Richtlinien für einzelne Unterverzeichnisse
* Tests neuer Richtlinien in einem separaten Branch
Die Funktion ist in den Tarifen `Scale` und `Enterprise` verfügbar und muss zusätzlich aktiviert werden. Weitere Informationen erhalten Sie unter [https://corgea.com/contact](https://corgea.com/contact).
Ein Beispiel finden Sie im [Example Repository](https://github.com/Corgea/mini-juice-shop).
Die [Main Policies](https://github.com/Corgea/mini-juice-shop/blob/main/corgea.yaml) enthalten allgemeine Richtlinien. Beispiele für unterverzeichnisspezifische Richtlinien:
* [Frontend Policies](https://github.com/Corgea/mini-juice-shop/blob/main/frontend/corgea.yaml)
* [Backend Policies](https://github.com/Corgea/mini-juice-shop/blob/main/backend/corgea.yaml)
Diese Konfigurationen berücksichtigen die Aufgabe des jeweiligen Verzeichnisses bei der Schwachstellenerkennung. Besonders in Monorepos können Entwickler dadurch den passenden Kontext festlegen.
### Workflow zum Aktualisieren von corgea.yaml
Erstellen Sie einen neuen Branch mit der Datei corgea.yaml und öffnen Sie einen Pull Request. Dadurch startet automatisch ein Scan des Branches. Alternativ können Sie den Scan auf der Projektseite manuell starten.
Öffnen Sie PolicyIQ und wechseln Sie zum Bereich `Policy File in Repos`.
Öffnen Sie den Bereich, um die aus corgea.yaml generierten Richtlinien zu prüfen.
Klicken Sie auf `Associated Issues`, um die durch diese Richtlinie ausgelösten Issues anzuzeigen.
Passen Sie die Konfiguration an, bis die Ergebnisse Ihren Erwartungen entsprechen. Mergen Sie anschließend den Pull Request, um corgea.yaml in den Main-Branch zu übernehmen.
### Grundkonfiguration für corgea.yaml
Eine grundlegende corgea.yaml sieht wie folgt aus:
```
# This is the corgea YAML file used for defining and managing security policies within applications.
# For more information, visit: https://docs.corgea.app/policies
version: 1 # Specifies the version of the corgea YAML standard being used. Update only if the standard changes.
policies:
- type: "scan"
description: >
This section ensures that all directories and files are thoroughly scanned to detect any security vulnerabilities in the backend code.
It is essential to identify and address potential issues such as SQL injection, exposure of sensitive data, and unauthorized access.
Comprehensive scanning helps maintain the security and integrity of the application.
```
* `type`: Richtlinientyp; mögliche Werte sind `scan`, `false_positive` und `fix`
* `description`: Inhalt der Richtlinie; zusätzlicher Kontext oder interne Sicherheitsvorgaben zur Anpassung der Schwachstellen-Findings
## Erweiterte Konfiguration für corgea.yaml
Optional können Sie folgende Felder ergänzen:
* `instruction_type`: Legt fest, wie Ihre Anweisungen mit Corgeas integrierten Richtlinien interagieren. `"append"` ergänzt die integrierten Richtlinien. `"overwrite"` ersetzt Corgeas Standardverhalten vollständig und ist der Standardwert.
* `guidance_text`: Optionale statische Hinweise, die Entwicklern bei Issues dieser Richtlinie angezeigt werden. Verwenden Sie das Feld für teamspezifische Anweisungen, interne Links oder Behebungskontext.
```
policies:
- type: "fix"
instruction_type: "append"
guidance_text: >
Use our secure logging utility and do not log raw request payloads.
description: >
Additionally, ensure all fixes integrate with our custom SecureMiddleware framework
and follow our internal security guidelines for key rotation.
cwes:
- "CWE-79" # XSS
```
* `cwes`: Gilt nur für `fix` und `false_positive` und beschränkt eine Richtlinie auf bestimmte CWEs. Beispiel:
```
cwes:
- "CWE-20" # CWE-20: Improper Input Validation
- "CWE-78" # CWE-78: Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')
- "CWE-209" # CWE-209: Information Exposure Through an Error Message
- "CWE-362"
- "CWE-79"
```
* `excludes`: Schließt Pfade mit Glob-Ausdrücken von einem bestimmten Richtlinien-Scan aus.
```
excludes:
- "config/*"
- "migrations/*"
```
* `ignore_paths`: Schließt Verzeichnisse global von allen Scans und der Erstellung neuer Issues aus.
(Hinweis: Diese Pfade werden global und nicht nur für eine bestimmte Richtlinie ignoriert. Muster wie `**/vendor/**` stimmen in jeder Verzeichnistiefe überein.)
```
ignore_paths:
- "test/*"
```
* `path`: Ermöglicht die zentrale Verwaltung, statt separate corgea.yaml-Dateien in Unterverzeichnissen anzulegen.
Für mini-juice-shop kann beispielsweise eine zentrale corgea.yaml wie in [diesem Beispiel](https://github.com/Corgea/mini-juice-shop/blob/central_corgea_yaml/corgea.yaml) verwendet werden:
```
# This is the corgea YAML file used for defining and managing security policies within applications.
# For more information, visit: https://docs.corgea.app/policies
version: 1 # Specifies the version of the corgea YAML standard being used. Update only if the standard changes.
policies:
- type: "scan"
path: 'backend'
description: >
...
- type: "scan"
path: 'frontend'
description: >
...
- type: "fix"
path: 'backend'
description: >
...
cwes:
- "CWE-22" # CWE-22: Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')
- type: "false_positive"
path: 'backend'
description: >
....
cwes:
- "CWE-20" # CWE-20: Improper Input Validation
- type: "false_positive"
path: "frontend"
description: >
...
cwes:
- "CWE-79" # CWE-79: Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')
```
Nachdem Sie einen Scan für einen Branch mit zentraler YAML-Konfiguration gestartet haben:
