La norma « allow »

Por norma general, el expediente de su póliza de Rego debe incluir una cláusula de « allow ». En el contexto de este proceso, esto no es solo una sugerencia, sino un requisito imprescindible.

El motor del pipeline consulta específicamente el valor booleano « allow » para tomar la decisión final sobre si se lleva a cabo o no la implementación. Si vas a proporcionar una política Rego personalizada, debes definir esta regla de forma explícita. Si falta la regla « allow » o si su resultado es « false », el proceso se detiene inmediatamente, bloquea la implementación y muestra los mensajes de denegación que hayas definido.

Para garantizar la máxima seguridad, OPA funciona según un estricto modelo de «cierre en caso de fallo». Tu política siempre debería establecer por defecto el valor « false » y solo evaluarse como « true » si se cumplen todas las condiciones de cumplimiento requeridas.

package one_pipeline.config
# Default deny
default allow := false
# Allow only if your custom checks pass
allow {
    check_sast_scans_passed
    check_secrets_scans_passed
}

Archivos de políticas y archivos de validación de datos

El archivo de políticas (.rego): la lógica

Aquí es donde debes escribir tus reglas y condiciones concretas. Por ejemplo, tu política podría establecer lo siguiente: «No autorices esta implementación a menos que se haya realizado un análisis de vulnerabilidades y los resultados indiquen que no hay ningún problema crítico». Puedes proporcionar tu archivo de políticas personalizado utilizando la propiedad de entorno del pipeline « policy-path ». Si no se proporciona ningún archivo de políticas, el proceso utiliza el archivo de políticas predeterminado.

El archivo de validación de datos (.json): los datos

Este archivo sirve como lista de referencia estática. En lugar de introducir los datos directamente en las reglas de Rego, este archivo sirve para mantener listas de variables aprobadas, como los registros de imágenes permitidos (us.icr.io o eu.icr.io) o repositorios específicos que están exentos de determinadas comprobaciones. Puedes proporcionar tu archivo de validación de datos utilizando la propiedad de entorno del canal « evidence-checks-config-path ». Si no se proporciona ningún archivo de validación de datos, el proceso utiliza el archivo de validación de datos predeterminado.

Archivo de ejemplo de validación de datos:

        package one_pipeline.config
        pre_deployment := {
            "com.ibm.prod_change_request": {
                "asset_type": [
                "*",
                "image"
                ],
                "source": [
                "prod",
                "stage"
                ],
                "target": [
                "prod",
                "stage"
                ],
                "recommended": [
                "*"
                ]
            }
        }
        post_deployment := {
            "com.ibm.prod_change_request": {
                "asset_type": [
                "*",
                "image"
                ],
                "source": [
                "prod",
                "stage"
                ],
                "target": [
                "prod",
                "stage"
                ],
                "recommended": [
                "*"
                ]
            }
        }

Cada bloque de la configuración define exactamente qué pruebas se esperan, de dónde proceden y con qué rigor deben aplicarse.

• El identificador del tipo de prueba (com.ibm.prod_change_request): la clave de nivel superior determina la categoría específica de la prueba que se está evaluando. Algunos ejemplos habituales son com.ibm.static-scan, com.ibm.unit-tests o com.ibm.image_signing.
• asset_type: Define el tipo de artefacto al que se aplica esta regla. Por ejemplo, podría aplicarse únicamente a image o a repo. Al utilizar « ["*"] », la regla se aplica a todos los tipos de activos.
• source (Entornos de origen): Define de dónde proceden las pruebas. Podría tratarse de una rama concreta o de un entorno de pipeline (por ejemplo, ci-pipeline, stage, prod).
• target (Entornos de destino): Define el entorno de destino en el que se está validando esta prueba para su implementación (por ejemplo, stage, prod). Aquí se puede encontrar más información sobre el origen y el destino.
• gating mode: Los últimos campos indican qué modo de filtrado deseas aplicar al tipo de prueba. Aquí puedes encontrar más información sobre los modos de sincronización compatibles.

Nota: Todas las comprobaciones previas a la implementación deben definirse en el array pre_deployment :{}, y todas las comprobaciones posteriores a la implementación deben definirse en el array post_deployment :{}. Además, si utilizas la ruta de política predeterminada, debes incluir la importación del paquete « one_pipeline.config » en tu archivo de registro de validación de datos.

El script del conversor de JSON a Rego

Aunque el proceso admite de forma nativa los archivos heredados de validación de datos JSON, es posible que, con el tiempo, desees modernizar tus configuraciones y pasarte a Rego nativo para adoptar plenamente el estándar «política como código».

Para facilitar esta tarea, ponemos a tu disposición un script de utilidad independiente que convierte automáticamente tus archivos de validación de datos JSON existentes al nuevo formato Rego.

Ubicación del script: /opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh

Cómo utilizar el script de conversión

Puedes ejecutar este script de forma local o dentro de una ejecución de pipeline. Al ejecutar el script de forma local, debes indicar explícitamente los entornos de destino y de origen.

# Convert a JSON config to Rego using named parameters
/opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh \
  --input ./legacy-evidence-config.json \
  --output ./new-evidence-config.rego \
  --target-env prod \
  --source-env master

Configuración flexible: varios archivos de validación

Los entornos complejos suelen requerir conjuntos de reglas modulares. Para facilitar esto, el proceso de validación de promociones te permite evaluar tus datos comparándolos con varias configuraciones al mismo tiempo.

Puedes proporcionar varios archivos de validación de datos indicando sus rutas como una lista separada por comas en el parámetro « evidence-checks-config-path ». En este caso, el proceso evaluará la carga útil de pruebas en función de cada archivo de configuración y generará una tabla de evaluación independiente para cada archivo. Además, en la sección de comentarios de PR verás las tablas de evaluación de cada archivo como comentarios independientes.

Comentarios automatizados sobre relaciones públicas

Para garantizar la máxima visibilidad, el proceso evalúa la información de evidencia actual en función de cada archivo de configuración que facilites. Una vez finalizada la evaluación, el proceso genera automáticamente tablas detalladas de resumen y evaluación, y las adjunta directamente a la solicitud de incorporación de cambios.

Si configuras varios archivos de validación de datos, el pipeline publica los resultados de cada archivo en un comentario independiente de la solicitud de incorporación de cambios. Esto ofrece a los revisores un desglose claro y exhaustivo del estado de cumplimiento en distintos contextos, sin mezclar los resultados.

Dentro de cada comentario de relaciones públicas, encontrarás:

• Tres tablas de evaluación: un desglose completo de los resultados de la validación. Para obtener más información sobre cómo interpretar estas tablas, consulta la sección « Cómo interpretar la tabla de verificación de pruebas ».
• Enlaces de configuración: Enlaces directos al archivo de validación de datos y al archivo de políticas específicos que se utilizaron para realizar esa evaluación concreta, lo que facilita la auditoría y la resolución de problemas de tus reglas.

Durante la fase de validación de la promoción, esta comprobación del cumplimiento de la OPA está diseñada para ofrecer visibilidad y recabar opiniones. Si se detectan problemas de cumplimiento con respecto a tus reglas, el proceso no se detiene ni falla. En cambio, el proceso completa su ejecución y publica los resultados detallados en el PR. De este modo, se garantiza que los desarrolladores reciban un informe completo de todas las deficiencias de cumplimiento y puedan subsanarlas sin que la compilación se interrumpa a mitad del proceso.

El objeto « table_results » (para comentarios sobre relaciones públicas)

Para generar las tablas detalladas de Markdown en los comentarios de tu PR, el proceso busca una estructura de datos específica denominada table_results.

Si tu política devuelve un objeto res dentro de table_results que contenga exactamente estos ocho campos, el proceso de canalización se encarga a partir de ahí. Analiza de forma segura tu salida y la transforma automáticamente en la tabla « Markdown », clara y detallada, que ves en la solicitud de incorporación de cambios:

table_results contains res if {
    # ... your custom evaluation logic goes here ...
    
    # Map your findings to the contract structure
    res := {
        "RuleType":       "Required",       
        "AssetType":      "image",          
        "AssetId":        "12345678",      
        "EvidenceTypeId": "com.ibm.scan",   
        "Tool":           "zap",         
        "Status":         "failure",        
        "Source":         "ci-pipeline",    
        "Target":         "prod",           
    }
}

La regla « allow » (para la ejecución en pipeline)

Como se ha mencionado anteriormente, la segunda parte obligatoria de este contrato es la norma « allow ».

¿Por qué es necesario?

Aunque « table_results » se encarga de generar los informes de tus comprobaciones de cumplimiento, la regla « allow » es el verdadero «kill switch» de la canalización. El motor del proceso está programado de forma fija para consultar el valor booleano « allow » con el fin de determinar la decisión final de seguir adelante o no.

Si proporcionas un archivo de políticas personalizado pero te olvidas de incluir la regla « allow », el proceso no sabrá cómo continuar. Al funcionar según un modelo de seguridad estricto de «fallo cerrado», por defecto hace que la ejecución del pipeline falle y bloquea la implementación.

Activación de OPA

Para habilitar el control de cumplimiento basado en OPA en tus pipelines de CD y CC, debes activar explícitamente el indicador « opt-in-rego-translation » (estableciéndolo en « true » o « 1 »).

Restricciones de configuración

Al igual que en el proceso de promoción, puedes proporcionar tanto un archivo de políticas (tu lógica) como un archivo de validación de datos (tus datos). Sin embargo, hay una diferencia fundamental: los procesos CD y CC solo aceptan actualmente un archivo de validación de datos cada vez, en lugar de una lista separada por comas.

Archivos adjuntos de las solicitudes de cambio (CR) y pasos finales del proceso

Cuando ejecutas el proceso de CD, el motor procesa tu archivo de validación de datos y lo adjunta a tu solicitud de cambio con fines de auditoría. El comportamiento de los archivos adjuntos depende totalmente del formato que se utilice:

• Si proporcionas un archivo de validación de datos JSON heredado: el proceso lo convierte automáticamente en segundo plano. Tanto el archivo JSON original como el archivo de configuración Rego generado se adjuntan al paso «Solicitud de cambio».
• Si proporcionas un archivo de validación de datos Rego nativo: el proceso solo adjunta directamente el archivo Rego que hayas proporcionado.

Este mismo comportamiento de adjuntado se aplica también al proceso de reconstrucción de la configuración que tiene lugar durante la etapa «CD Finish», al final del proceso.