> ## 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
> Enrichissez Corgea avec votre contexte métier grâce aux politiques
**Prérequis** Vous avez effectué un [scan](scanning) et PolicyIQ est activé. Demandez son activation à votre interlocuteur Corgea.
Corgea est préconfiguré avec un ensemble complet de politiques destinées à apporter une valeur immédiate et à optimiser vos analyses de sécurité. Ces politiques intégrées couvrent les patterns de sécurité, les frameworks et les configurations d’infrastructure courants.
Vous pouvez personnaliser et étendre ces politiques afin d’enrichir la plateforme avec votre contexte métier, réseau et environnemental. Vous améliorez ainsi la précision de la détection des vulnérabilités et des faux positifs, ainsi que la génération des correctifs. Les politiques aident Corgea à mieux comprendre vos exigences de sécurité et votre infrastructure.
## Comportements importants des politiques
Avant d’examiner la structure des politiques, retenez les comportements suivants :
1. **Application de la politique** : les nouvelles politiques ne prennent effet que lors des nouveaux scans ; elles ne modifient pas rétroactivement les résultats existants.
2. **Priorité des politiques** :
* Les politiques plus spécifiques priment sur les politiques générales pour la détection des faux positifs et la génération de correctifs
* Par exemple, une politique de faux positifs propre aux SSRF remplace une politique générale de faux positifs
* Les politiques définies par le client supplantent toujours les politiques natives de Corgea
3. **Regroupement des politiques** : pour les politiques de scan, il est recommandé de regrouper les problématiques de sécurité connexes plutôt que de créer une politique par problème. Par exemple :
* Regroupez l’authentification, l’autorisation et la gestion des permissions
* Combinez les vérifications de validation des données associées
* Regroupez les vérifications de contrôles de sécurité associées
Cette approche donne de meilleurs résultats car ces préoccupations de sécurité se chevauchent et interagissent souvent.
## Structure de la politique
Une politique bien structurée doit inclure les éléments suivants :
1. **Type de politique** : indiquez le type de politique créé, par exemple BLAST (détection des vulnérabilités), Faux positif (identification des faux positifs) ou Correctif (suggestion de correctifs du code).
2. **Contexte métier** : fournissez des informations détaillées sur les éléments suivants :
* Domaine métier et exigences
* Architecture réseau et contrôles de sécurité
* Configurations spécifiques à l’environnement
* Exigences de classification et de traitement des données
* Exigences de conformité (par exemple, PCI, HIPAA, GDPR)
3. **Description** : instructions claires intégrant votre contexte, notamment :
* Schémas de vulnérabilité spécifiques dans votre environnement
* Exemples de code pertinents pour votre architecture
* Comment gérer les problèmes compte tenu de votre infrastructure
4. **Types de vulnérabilités (CWE)** : choisissez les types de vulnérabilités que cette politique doit gérer en fonction de votre profil de risque.
5. **Projets** : sélectionnez les projets auxquels appliquer cette politique afin de définir des politiques propres à chaque environnement. Lorsque le contrôle d’accès aux projets est activé, les utilisateurs non administrateurs ne peuvent créer ou gérer que des politiques portant sur des projets auxquels ils ont accès et doivent sélectionner au moins un projet accessible. Les administrateurs de l’entreprise peuvent toujours créer des politiques applicables à tous les projets.
6. **Motif de fichier (glob)** : limitez éventuellement une politique aux fichiers correspondants (par exemple, `src/**/*.py`). Laissez ce champ vide pour l’appliquer à tous les fichiers.
7. **Notes d’orientation (facultatives)** : ajoutez des consignes statiques destinées aux développeurs, telles que des notes internes de remédiation, des liens vers des normes internes ou des conseils d’implémentation. Elles s’affichent lors de la consultation des problèmes auxquels la politique s’est appliquée.
8. **Type d’instruction** : choisissez comment les instructions de votre politique interagissent avec les politiques intégrées de Corgea :
* **Ajouter à la politique par défaut de Corgea** : ajoute les instructions de votre politique aux politiques intégrées de Corgea, en conservant les deux ensembles de règles. Utilisez cette option pour enrichir les politiques par défaut avec votre contexte métier, vos contrôles de sécurité ou les caractéristiques de votre environnement.
* **Remplacer la politique par défaut de Corgea** : les instructions de votre politique remplacent entièrement le comportement par défaut de Corgea. Utilisez cette option pour contrôler totalement le traitement de scénarios précis.
## Policy Playground
Policy Playground est un espace de travail côte à côte pour créer, mettre à jour et tester des politiques avant qu’elles n’affectent vos scans. Vous écrivez la politique à gauche et la testez avec du code réel à droite, afin de pouvoir itérer rapidement sans quitter la page.
* L’espace de travail comprend un **éditeur de politique** (à gauche) et un **panneau de test** (à droite), séparés par une barre déplaçable qui permet de redimensionner les panneaux.
* Utilisez **Retour aux politiques** dans la barre d’outils supérieure pour revenir à tout moment au tableau Politiques.
* Ouvrez une politique **BLAST** ou **Faux positif** existante directement dans Policy Playground depuis le tableau Politiques.
* Recherchez une politique dans le tableau Politiques par **ID de politique**, nom, type ou description.
* L’édition et la sauvegarde dans Policy Playground mettent à jour la politique en créant une nouvelle version.
* Dans l’éditeur, le **Type d’instruction** propose deux options clairement expliquées : **Remplacer la politique par défaut de Corgea** ou **Ajouter à la politique par défaut de Corgea**.
* Laissez **Projets**, **Motif de fichier (Glob)** ou **CWE** vide pour appliquer la politique globalement.
* Lorsque le contrôle d’accès aux projets est activé, les utilisateurs disposant d’un périmètre restreint peuvent consulter les politiques qui leur sont visibles, mais uniquement modifier ou supprimer celles qui s’appliquent exclusivement à des projets auxquels ils ont accès.
Seules les politiques **BLAST** et **Faux positif** peuvent être testées dans Policy Playground. Les politiques de **correctif** peuvent toujours être créées dans le Policy Center, mais apparaissent sous la mention **Fix (à venir)** dans Policy Playground, car leur test n’est pas encore pris en charge.
### Tester une politique
Pour tester une politique, sélectionnez un **Projet** et un **fichier**, puis cliquez sur **Tester**. Le bouton affiche l’indicateur **Test en cours…** pendant le scan et reste désactivé jusqu’à la fin. Si une information obligatoire manque, un message sous le bouton précise quoi ajouter : projet, fichier ou instructions de la politique.
Par défaut, le sélecteur ne répertorie que les fichiers dans lesquels des problèmes ont déjà été détectés. Pour effectuer un test sur un fichier qui n’existe pas encore, activez **Nouveau fichier de test**, sélectionnez un projet et saisissez un nom de fichier. Le projet fournit au scan le contexte du langage et du framework ; vous pouvez ensuite écrire votre propre code dans l’éditeur pour tester la politique.
### Examiner les résultats
Une fois le scan terminé, les résultats s’affichent sous l’aperçu du fichier. Chaque résultat est présenté sur une ligne extensible indiquant sa **sévérité**, son **CWE** et son **numéro de ligne**. Développez le résultat pour lire son explication et utilisez **Aller à la ligne** pour accéder à la ligne concernée dans l’aperçu.
Si le scan ne trouve aucune correspondance, le panneau affiche **Aucun problème trouvé pour cette politique**, ce qui confirme que le test a bien été exécuté.
## Règles de scan et de commentaires sur les pull requests
Ces règles déterminent quand Corgea scanne les pull requests et quand il y publie des commentaires sur les résultats.
* **Scanner uniquement** exécute le scan de la pull request sans publier de commentaires sur les résultats.
* **Scanner et commenter** exécute le scan et commente les résultats qui correspondent à la règle.
* **Sévérité** limite les correspondances aux niveaux sélectionnés. Laissez ce champ vide pour accepter toutes les sévérités.
* **Classification à commenter** limite les commentaires aux types de CWE sélectionnés. Laissez ce champ vide pour commenter toutes les CWE correspondantes.
* **Projets** et **Tags de projet** définissent le périmètre de la règle. Une règle s’applique lorsqu’un projet est sélectionné directement ou porte l’un des tags sélectionnés. Si les deux champs sont vides, elle s’applique à tous les projets.
* **Intégrations** peut restreindre davantage la règle aux pull requests provenant des intégrations GitHub, GitLab ou Azure DevOps sélectionnées. Laissez ce champ vide pour utiliser uniquement le périmètre des projets et de leurs tags.
Utilisez le filtre de tags de projet de la page des règles de pull request pour trouver les règles Scanner et commenter qui s’appliquent aux projets portant un tag donné. Dans le tableau des règles, la colonne Projets affiche les projets et tags sélectionnés sous forme de badges. Les règles sans périmètre de projet ou de tag indiquent **Tous les projets** ; les longues listes sont regroupées derrière une infobulle **+N autres**.
## Bonnes pratiques relatives aux politiques
Lors de la rédaction de politiques, suivez ces meilleures pratiques pour fournir un contexte efficace :
1. **Décrivez précisément votre environnement** : détaillez votre infrastructure, vos contrôles de sécurité et vos mesures compensatoires.
2. **Incluez la logique métier** : expliquez les règles de validation propres à l’entreprise, les flux de données et les exigences de sécurité.
3. **Décrivez l’architecture de sécurité** : documentez vos couches de sécurité, vos frontières de confiance et vos mécanismes de protection.
4. **Définissez le contexte des données** : précisez comment les différents types de données doivent être traités dans votre environnement.
5. **Documentez les exceptions** : indiquez les cas métier légitimes qui peuvent expliquer des problèmes de sécurité apparents.
## Exemples
Lors de la création d’exemples de politiques, suivez ces conseils pour les rendre plus efficaces :
1. **Utilisez plusieurs exemples** : incluez 3 à 5 exemples variés pour chaque type de politique afin de :
* Montrer différents cas d’usage et scénarios
* Couvrir les cas particuliers propres à votre environnement
* Présenter différents niveaux de complexité
* Illustrer différents contrôles de sécurité et mesures compensatoires
2. **Rendez les exemples pertinents** : assurez-vous que vos exemples :
* Reflètent votre infrastructure et votre architecture réelles
* Incluez de véritables contrôles de sécurité que vous utilisez
* Font référence à vos outils et frameworks
* Correspondent à vos conventions et pratiques de développement
3. **Structurez clairement les exemples** : utilisez :
* Des titres de section et libellés explicites
* Une mise en forme et une indentation cohérentes
* Des commentaires détaillés expliquant les points clés
* Des tags pour séparer les différents composants
4. **Incluez le contexte** : chaque exemple doit préciser :
* Le scénario métier concerné
* Les détails pertinents de l’infrastructure
* Les contrôles de sécurité en place
* Le comportement et les résultats attendus
Voici des exemples de politiques illustrant ces principes :
### Exemple de politique BLAST
**Type de politique** : 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
```
### Exemple de politique de faux positif
**Type de politique** : Faux positif
```
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
```
### Exemple de politique de correction
Voici un exemple de politique de correctif qui utilise un middleware personnalisé pour se protéger contre les vulnérabilités XSS :
**Type de politique** : Correctif
````
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]
````
By providing this context, Corgea can generate fixes that properly integrate with your custom security middleware and follow your secure coding guidelines for XSS protection.
**Policy Type**: 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]
```
Providing rich context about your business environment, security controls, and infrastructure helps Corgea deliver more accurate and relevant security analysis tailored to your specific needs.
## Prework-generated policies
When prework is enabled for your company, Corgea can generate policies from your project context before the main scan completes.
* Generated policies appear in the **Policies** table with `Source` set to **Generated By Corgea Prework**.
* In scan details, the **Policies** tab shows all policies applied to that specific scan, including older archived or inactive versions, and lets you open the policy for more details.
* If **Policy Review** is enabled from **Policies > Settings**, generated policies are created as **Inactive** so your team can review and activate them manually.
### Generating a Policy
You can manually trigger policy generation directly from the PolicyIQ page at any time.
On the **PolicyIQ** page, click the **Generate Policy** button in the top-right area.
In the dialog, select a **Pattern** (e.g., Authentication), choose a **Project**, and select a **Policy Type**. Click **Generate** to start.
Corgea runs a **Corgea-Prework** scan in the background to analyze your project. You can monitor its progress from the **Scans** page.
Once complete, the generated policy appears in the **Policies** table. Click on it to review the policy details, including the description populated with real code patterns found in your project.
## Corgea Policy YAML Configuration Support
Customers can now define security policies for their projects using a `corgea.yaml` file. This configuration file enables the specification of detailed security policies, such as:
* Specific CWE identifiers
* Policies tailored to sub-folders
* Testing new policies on a separate branch
This feature is available with the `Scale` or `Enterprise` plan and requires additional enablement. Please contact us at [https://corgea.com/contact](https://corgea.com/contact) for more information.
For reference, you can view an example repository here: [Example Repository](https://github.com/Corgea/mini-juice-shop).
You can have - [Main Policies](https://github.com/Corgea/mini-juice-shop/blob/main/corgea.yaml) for general policy.
Examples of sub-folder specific policies can be found in sub-folders like:
* [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)
These configurations help identify vulnerabilities by considering the context of each folder's responsibilities. This is particularly useful for monorepos, allowing developers to configure the right context.
### Workflow for Updating corgea.yaml
Create a new branch with the corgea.yaml file and open a pull request. This will automatically trigger a scan on the branch. Alternatively, you can manually trigger a scan from the project page.
Go to the PoliciesIQ page, where you will find a section labeled `Policy File in Repos`.
Click on the section to review the specific policies generated by the corgea.yaml file.
Click on the `Associated Issues` column to see issues triggered from this policy.
Make further modifications until the results meet your expectations, then merge your pull request to include the corgea.yaml file in the main branch.
### Basic configuration for corgea.yaml
Basic configuration of corgea.yaml looks like this :
```
# 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` : type of policy. This can be one of “scan”, “false\_positive”, “fix”
* `description` contents of policy. Explain additional context or internal security guidelines to tailor security vulnerabilities findings.
## Advanced configuration for corgea.yaml
Optionally, you can add these fields
* `instruction_type` : Determines how your policy instructions interact with Corgea's built-in policies. Can be set to `"append"` or `"overwrite"`. When set to `"append"`, your policy instructions are added to Corgea's built-in policies, preserving both sets of rules. When set to `"overwrite"` (default), your policy instructions completely replace Corgea's default behavior.
* `guidance_text` : Optional static guidance shown to developers when viewing issues associated with the policy. Use this for team-specific instructions, internal links, or remediation context.
```
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` : Only applicable to "fix", or "false\_positive". It can apply specific policy to specific cwes.
As an example,
```
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` : If you want to exclude some paths for a specific policy scan, you can list those files using a glob expression.
```
excludes:
- "config/*"
- "migrations/*"
```
* `ignore_paths` : If you want to exclude folders globally from all scans and new issue creation, you can specify them here.
(Note: these file paths are ignored globally, not just for a specific policy. Patterns such as `**/vendor/**` match at any directory depth.)
```
ignore_paths:
- "test/*"
```
* `path` : Instead of having separate corgea.yaml files under sub-folders, you can manage everything centrally by setting path.
As an example of mini-juice-shop, you can have one corgea.yaml like [this](https://github.com/Corgea/mini-juice-shop/blob/central_corgea_yaml/corgea.yaml)
```
# 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')
```
Après avoir déclenché un scan sur une branche contenant le fichier YAML central :
