> ## 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
> Enriquece Corgea con contexto empresarial mediante políticas
**Requisito previo** Has completado un [escaneo](/es/quickstart), y tienes activado PolicyIQ. Contacta con tu contacto de Corgea para habilitar PolicyIQ.
Corgea incluye un conjunto completo de políticas preconfiguradas que aportan valor desde el primer momento y mejoran el análisis de seguridad. Estas políticas integradas abarcan patrones de seguridad habituales, frameworks y configuraciones de infraestructura.
Puedes personalizarlas y ampliarlas para aportar contexto adicional sobre el negocio, la red y el entorno. Esto mejora la precisión de la detección de vulnerabilidades, la identificación de falsos positivos y la generación de correcciones, ya que permite que Corgea comprenda mejor tus requisitos de seguridad y tu infraestructura.
## Comportamientos importantes en las políticas
Antes de examinar la estructura de las políticas, conviene conocer algunos comportamientos importantes:
1. **Aplicación de la política**: Las nuevas políticas solo entran en vigor en nuevos escaneos, no afectarán retroactivamente a los resultados existentes.
2. **Precedencia de política**:
* Las políticas más específicas tienen prioridad sobre las políticas generales para detección de falsos positivos y correcciones
* Por ejemplo, una política de falsos positivos específica para SSRF prevalecería sobre una política general de falsos positivos
* Las políticas definidas por el cliente siempre anulan las políticas nativas de Corgea
3. **Agrupación de políticas**: En las políticas de escaneo, se recomienda agrupar los aspectos de seguridad relacionados en lugar de crear una política para cada uno. Por ejemplo:
* Agrupar la autenticación, autorización y gestión de permisos
* Combinar comprobaciones de validación de datos relacionadas
* Agrupar verificaciones de control de seguridad asociadas
Este enfoque da mejores resultados, ya que estas preocupaciones de seguridad suelen solaparse e interactuar.
## Estructura de la política
Una política bien estructurada debe incluir los siguientes componentes:
1. **Tipo de política**: Especifica el tipo de política que estás creando, como BLAST (detección de vulnerabilidades), Falso Positivo (identificación de falsos positivos) o Corrección (sugiriendo correcciones en código).
2. **Contexto empresarial**: Proporciona información detallada sobre tu:
* Dominio empresarial y requisitos
* Arquitectura de red y controles de seguridad
* Configuraciones específicas del entorno
* Requisitos de clasificación y tratamiento de datos
* Requisitos de cumplimiento (por ejemplo, PCI, HIPAA, RGPR)
3. **Descripción**: Instrucciones claras que incorporan tu contexto, incluyendo:
* Patrones específicos de vulnerabilidad en tu entorno
* Ejemplos de código relevantes para tu arquitectura
* Cómo deben gestionarse los hallazgos según tu infraestructura
4. **Tipos de vulnerabilidades (CWEs)**: Elige qué tipos de vulnerabilidades de seguridad debe gestionar esta política, en función de tu perfil de riesgo.
5. **Proyectos**: Selecciona los proyectos a los que se aplicará la política para adaptar las políticas a cada entorno. Cuando el control de acceso a proyectos está habilitado, los usuarios que no sean administradores solo pueden crear o gestionar políticas para proyectos a los que tengan acceso y deben seleccionar al menos uno. Los administradores de la empresa pueden seguir creando políticas que se apliquen a todos los proyectos.
6. **File Pattern (Glob)**: Opcionalmente limitar una política a archivos coincidentes (por ejemplo, `src/**/*.py`). Deja vacío para aplicar a todos los archivos.
7. **Notas de orientación (opcional)**: Añade directrices estáticas para los desarrolladores, como notas internas de remediación, enlaces a estándares internos o recomendaciones de implementación. Estas indicaciones se muestran al consultar los hallazgos afectados por la política.
8. **Tipo de instrucción**: Elige cómo interactúan tus instrucciones de política con las políticas integradas de Corgea:
* **Añadir a la política predeterminada de Corgea**: Añade tus instrucciones a las políticas integradas de Corgea y conserva ambos conjuntos de reglas. Utiliza esta opción para complementar las políticas predeterminadas con contexto empresarial, controles de seguridad o detalles del entorno.
* **Reemplazar la política predeterminada de Corgea**: Tus instrucciones de política anulan completamente el comportamiento predeterminado de Corgea. Úsalo cuando quieras tener control total sobre cómo se manejan escenarios específicos.
## Policy Playground
Policy Playground es un espacio de trabajo en paralelo donde puedes crear, actualizar y probar políticas antes de que afecten a los escaneos. Escribe la política a la izquierda y pruébala con código real a la derecha para iterar con rapidez sin salir de la página.
* El espacio de trabajo se divide en un **editor de políticas** (izquierda) y un **panel de prueba** (derecha), con un divisor arrastrable para que puedas redimensionar los paneles a tu gusto.
* Utiliza **Volver a Políticas** en la barra de herramientas superior para volver a la tabla de Políticas en cualquier momento.
* Abre una política existente de **BLAST** o **Falso Positivo** directamente en Policy Playground desde la tabla de Políticas.
* Busca en la tabla de Políticas por **ID de Política**, nombre, tipo o descripción para encontrar rápidamente una política.
* Editar y guardar en Policy Playground actualiza la política creando una nueva versión.
* El **tipo de instrucción** aparece en el editor con dos opciones: **Reemplazar la política predeterminada de Corgea** o **Añadir a la política predeterminada de Corgea**.
* Deja **Proyectos**, **Patrón de Archivo (Glob)** o **CWEs** vacíos cuando quieras que esa política se aplique globalmente.
* Cuando el Control de Acceso a Proyectos está habilitado, los usuarios con alcance pueden ver las políticas visibles para ellos, pero solo pueden editar o eliminar políticas que se apliquen íntegramente a proyectos a los que puedan acceder.
Solo se pueden probar las políticas de **BLAST** y **Falsos Positivos** en Policy Playground. Las políticas de **Corrección** aún pueden crearse desde el Centro de Políticas, pero se muestran como **Corrección (próximamente)** en el playground, ya que las correcciones de prueba aún no son compatibles.
### Probar una política
Para probar una política, selecciona un **proyecto** y un **archivo** y haz clic en **Test**. Mientras se ejecuta el escaneo, el botón muestra un indicador de progreso con el texto **Prueba...** y permanece deshabilitado. Si falta algún dato obligatorio, un mensaje bajo el botón indica qué debes añadir: el proyecto, el archivo o las instrucciones de la política.
De forma predeterminada, el selector solo muestra archivos en los que ya se han detectado hallazgos. Para probar un archivo que aún no existe, activa **Nuevo archivo de prueba**, selecciona un proyecto y escribe un nombre de archivo. El proyecto aporta al escaneo el contexto del lenguaje y el framework; después puedes escribir el código en el editor para probar la política.
### Revisión de resultados
Cuando finaliza el escaneo, los resultados aparecen bajo la vista previa del archivo. Cada hallazgo se muestra en una fila desplegable con su **gravedad**, **CWE** y **número de línea**. Despliega el hallazgo para leer la explicación y utiliza **Saltar a la línea** para ir a la línea correspondiente en la vista previa.
Si el escaneo finaliza sin coincidencias, el panel muestra el estado **No se han encontrado problemas para esta política**, lo que confirma que se ejecutó la prueba.
## Reglas de escaneo y comentarios de pull requests
Las reglas de escaneo y comentarios de PR controlan cuándo Corgea escanea las pull requests y cuándo publica comentarios sobre los hallazgos.
* **Solo escanear** ejecuta el escaneo de la pull request sin publicar comentarios sobre los hallazgos.
* **Escanear y Comentar** ejecuta el escaneo y comenta los hallazgos que coinciden con la regla.
* **Gravedad** limita las coincidencias a los niveles seleccionados. Déjalo vacío para incluir cualquier gravedad.
* **Clasificación para comentarios** limita los comentarios a determinados tipos de CWE. Déjalo vacío para comentar todos los CWE coincidentes.
* **Proyectos** y **Etiquetas de Proyecto** definen dónde se aplica la regla. Se aplica una regla cuando un proyecto es seleccionado directamente o tiene cualquier etiqueta seleccionada; Si ambos campos están vacíos, la regla se aplica a todos los proyectos.
* **Las integraciones** pueden limitar aún más la regla para que se extraigan de pull requests de integraciones seleccionadas de GitHub, GitLab o Azure DevOps. Déjalo vacío para usar solo el proyecto y el alcance de la etiqueta del proyecto.
Utiliza el filtro de etiquetas de proyecto en la página de reglas de PR para encontrar las reglas de Escanear y Comentar que se aplican a proyectos con una etiqueta específica. En la tabla de reglas, la columna Proyectos muestra proyectos seleccionados y etiquetas de proyecto como chips; las reglas sin proyecto ni alcance de etiqueta muestran **Todos los proyectos**, y las listas de alcance más largas se agrupan detrás de una descripción sugerida **+N más**.
## Mejores prácticas en políticas
Al redactar políticas, sigue estas mejores prácticas para proporcionar un contexto eficaz:
1. **Sé específico con tu entorno**: Detalla tu infraestructura, controles de seguridad y controles compensatorios.
2. **Incluye la lógica de negocio**: Explica las reglas de validación específicas del negocio, los flujos de datos y los requisitos de seguridad.
3. **Describe la arquitectura de seguridad**: Documenta tus capas de seguridad, límites de confianza y mecanismos de protección.
4. **Define el contexto de los datos**: Especifica cómo deben gestionarse los diferentes tipos de datos en tu entorno.
5. **Documenta las excepciones**: Indica los casos de negocio legítimos que puedan parecer problemas de seguridad.
## Ejemplos
Al crear ejemplos de políticas, sigue estos consejos para hacerlos más efectivos:
1. **Utiliza varios ejemplos**: Incluye entre 3 y 5 ejemplos diversos para cada tipo de política con el fin de:
* Mostrar diferentes casos de uso y escenarios
* Cubrir casos límite específicos de tu entorno
* Demostrar distintos niveles de complejidad
* Ilustrar diferentes controles de seguridad y medidas compensatorias
2. **Haz que los ejemplos sean relevantes**: Asegúrate de que los ejemplos:
* Reflejar tu infraestructura y arquitectura reales
* Incluir los controles de seguridad que utilizas
* Hacer referencia a tus herramientas y frameworks
* Ajustarse a tus patrones y prácticas de desarrollo
3. **Estructura los ejemplos claramente**: Formatea tus ejemplos con:
* Encabezados y etiquetas de sección claros
* Formato y sangría coherentes
* Comentarios detallados que explican puntos clave
* Etiquetas para separar diferentes componentes
4. **Incluye contexto**: Cada ejemplo debe proporcionar:
* El escenario empresarial específico
* Detalles relevantes de la infraestructura
* Controles de seguridad establecidos
* Comportamiento esperado y resultados
A continuación, se muestran ejemplos de políticas que demuestran estos principios:
### Ejemplo de política BLAST
**Tipo de política**: 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
```
### Ejemplo de política de falso positivo
**Tipo de política**: Falso positivo
```
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
```
### Ejemplo de política de corrección
Aquí tienes un ejemplo de una política de corrección que utiliza un middleware personalizado para proteger contra vulnerabilidades XSS:
**Tipo de política**: Corrección
````
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]
````
Con este contexto, Corgea puede generar correcciones que se integren correctamente con tu middleware de seguridad y sigan tus directrices de programación segura para proteger frente a XSS.
**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]
```
Aportar contexto detallado sobre el entorno empresarial, los controles de seguridad y la infraestructura permite que Corgea ofrezca análisis de seguridad más precisos y pertinentes para tus necesidades.
## Políticas generadas durante el prework
Cuando el prework está habilitado para tu empresa, Corgea puede generar políticas a partir del contexto del proyecto antes de que finalice el escaneo principal.
* Las políticas generadas aparecen en la tabla **Policies** con el valor **Generated By Corgea Prework** en `Source`.
* En los detalles del escaneo, la pestaña **Policies** muestra todas las políticas aplicadas al escaneo, incluidas las versiones antiguas archivadas o inactivas, y permite abrirlas para consultar sus detalles.
* Si habilitas **Policy Review** en **Policies > Settings**, las políticas se crean como **Inactive** para que el equipo pueda revisarlas y activarlas manualmente.
### Generar una política
Puedes iniciar manualmente la generación de políticas desde la página de PolicyIQ en cualquier momento.
En la página **PolicyIQ**, haz clic en el botón **Generate Policy** de la esquina superior derecha.
En el cuadro de diálogo, selecciona un **Pattern** (por ejemplo, Authentication), elige un **Project** y selecciona un **Policy Type**. Haz clic en **Generate** para comenzar.
Corgea ejecuta en segundo plano un escaneo **Corgea-Prework** para analizar el proyecto. Puedes consultar su progreso en la página **Scans**.
Cuando finaliza el proceso, la política generada aparece en la tabla **Policies**. Haz clic en ella para consultar los detalles, incluida una descripción con patrones de código reales detectados en el proyecto.
## Configuración de políticas de Corgea mediante YAML
Los clientes pueden definir políticas de seguridad para sus proyectos mediante un archivo `corgea.yaml`. Este archivo permite especificar políticas detalladas, como:
* Identificadores CWE concretos
* Políticas adaptadas a subcarpetas
* Pruebas de políticas nuevas en otra rama
Esta función está disponible con los planes `Scale` y `Enterprise` y debe habilitarse por separado. Para obtener más información, [contacta con nosotros](https://corgea.com/contact).
Como referencia, consulta este [repositorio de ejemplo](https://github.com/Corgea/mini-juice-shop).
Puedes definir [políticas principales](https://github.com/Corgea/mini-juice-shop/blob/main/corgea.yaml) de carácter general.
También encontrarás ejemplos de políticas específicas para subcarpetas:
* [Políticas del frontend](https://github.com/Corgea/mini-juice-shop/blob/main/frontend/corgea.yaml)
* [Políticas del backend](https://github.com/Corgea/mini-juice-shop/blob/main/backend/corgea.yaml)
Estas configuraciones ayudan a detectar vulnerabilidades teniendo en cuenta la responsabilidad de cada carpeta. Resultan especialmente útiles en monorepos, ya que permiten configurar el contexto adecuado.
### Flujo de trabajo para actualizar corgea.yaml
Crea una rama nueva con el archivo corgea.yaml y abre una pull request. Esto iniciará automáticamente un escaneo de la rama. También puedes iniciarlo manualmente desde la página del proyecto.
Ve a la página de PoliciesIQ, donde encontrarás una sección denominada `Policy File in Repos`.
Haz clic en la sección para revisar las políticas generadas a partir del archivo corgea.yaml.
Haz clic en la columna `Associated Issues` para consultar los hallazgos activados por la política.
Realiza los cambios necesarios hasta obtener los resultados esperados y después fusiona la pull request para incluir el archivo corgea.yaml en la rama principal.
### Configuración básica de corgea.yaml
La configuración básica de corgea.yaml tiene este aspecto:
```
# 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`: Tipo de política. Puede ser “scan”, “false\_positive” o “fix”.
* `description`: Contenido de la política. Explica el contexto adicional o las directrices de seguridad internas que permiten adaptar los hallazgos de vulnerabilidades.
## Configuración avanzada de corgea.yaml
También puedes añadir estos campos:
* `instruction_type`: Determina cómo interactúan las instrucciones de la política con las políticas integradas de Corgea. Puede ser `"append"` u `"overwrite"`. Con `"append"`, las instrucciones se añaden a las políticas integradas y se conservan ambos conjuntos de reglas. Con `"overwrite"` (valor predeterminado), las instrucciones sustituyen por completo el comportamiento predeterminado de Corgea.
* `guidance_text`: Indicaciones estáticas opcionales que se muestran a los desarrolladores al consultar hallazgos asociados a la política. Utilízalas para incluir instrucciones del equipo, enlaces internos o contexto de remediación.
```
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`: Solo se aplica a "fix" y "false\_positive". Permite asociar una política a CWE concretos.
Por ejemplo:
```
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`: Permite excluir rutas de un escaneo de políticas concreto mediante expresiones glob.
```
excludes:
- "config/*"
- "migrations/*"
```
* `ignore_paths`: Permite excluir carpetas globalmente de todos los escaneos y de la creación de hallazgos.
(Nota: estas rutas se omiten globalmente, no solo en una política concreta. Los patrones como `**/vendor/**` coinciden a cualquier profundidad.)
```
ignore_paths:
- "test/*"
```
* `path`: Permite gestionar todo de forma centralizada mediante una ruta, en lugar de mantener archivos corgea.yaml separados en las subcarpetas.
Por ejemplo, mini-juice-shop puede utilizar un único archivo corgea.yaml como [este](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')
```
Cuando inicias un escaneo en una rama con un YAML centralizado:
