Visión general

Secure Code Warrior® Trust Agent proporciona una herramienta de comprobación de CI que se puede ejecutar dentro de las canalizaciones de CI y se puede activar cuando se realiza una solicitud de incorporación de cambios. La comprobación se realizará correctamente o no en función del cumplimiento de los contribuyentes de la solicitud de incorporación de cambios con la política del Agente de confianza.

Implementación

La herramienta de comprobación de CI se proporciona como una imagen de contenedor de Docker que es publicado en GitHub y disponible en el registro de contenedores en ghcr.io/securecodewarrior/scw-policy-gate-ci.

La imagen de contenedor publicada es compatible con GitHub Actions, pero también se puede usar dentro de cualquier sistema de CI que admita la ejecución de un contenedor dentro de sus canalizaciones. Con el tiempo, se lanzará compatibilidad nativa adicional con sistemas de CI populares.

Hemos adoptado el control de versiones semántico para las versiones de imágenes de contenedor. Mientras estés en acceso anticipado, te recomendamos que uses el método Versión secundaria (p. ej. 0.2), ya que puede haber cambios importantes (por ejemplo, parámetros de configuración necesarios) entre las versiones secundarias de acceso anticipado. Una vez que esté disponible para el público en general, se recomienda utilizar el método Versión principal (p. ej. 1).

Acciones de GitHub

A continuación, se proporciona un ejemplo de archivo de flujo de trabajo de GitHub Actions que demuestra cómo se puede activar la herramienta de verificación de CI a partir de las solicitudes de incorporación de cambios:

on:
  pull_request:

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # commit history is required
      - name: SCW Policy Gate CI Check
        uses: docker://ghcr.io/securecodewarrior/scw-policy-gate-ci:0.2
        with:
          api-token: ${{ secrets.SCW_TRUST_AGENT_API_KEY }}
          api-url: <API endpoint URL - see below>
          repository-path: .

El api-url que especifique dependerá de la instancia de SCW que haya seleccionado durante la incorporación:

Por ejemplo, en Estados Unidos: https://trust-agent.prod-us.prod.securecodewarrior.com
Por ejemplo, en la UE: https://trust-agent.prod-eu.prod.securecodewarrior.com

También puede confirmar la URL del punto de conexión de la API desde el Agente de confianza navegando a Administración > Configuración del agente de confianza > Administrar política > Puerta de póliza > Conectar repositorios.

Otros sistemas de CI

Para otros sistemas de CI capaces de ejecutar un contenedor Docker, se requerirá alguna configuración adicional en función de su configuración específica. La herramienta de verificación de CI se puede ejecutar desde cualquier CLI, con los valores adecuados pasados a través de variables de entorno u opciones de línea de comandos.

A continuación se enumeran las variables de entorno admitidas:

SCW_API_KEY: Establezca la clave de API de SCW. Por seguridad, se prefiere la variable de entorno a la opción de línea de comandos. SeguirEsta guíapara crear la clave de la API de administración.
SCW_API_URL: Establezca la URL del punto de conexión de la API de SCW que se utilizará para la comprobación de acceso. La variable de entorno será anulada por la opción de línea de comandos si se proporcionan ambas. Consulte la sección anterior para determinar la URL a utilizar.

A continuación se enumeran las opciones de línea de comandos admitidas:

--api-token string: (Obligatorio) Establezca el token de la API de SCW. ADVERTENCIA: Por motivos de seguridad, es preferible utilizar la variable de entorno SCW_API_KEY en lugar de la opción de línea de comandos. SeguirEsta guíapara crear la clave de la API de administración.
--api-url string: (Obligatorio) Establezca la URL del punto de conexión de la API de SCW que se utilizará para la comprobación de compuertas. Invalida la variable de entorno SCW_API_URL. Consulte la sección anterior para determinar la URL a utilizar.
--repository-path string: (Obligatorio) Establezca la ruta relativa al repositorio, por ejemplo, '.' para el directorio actual.
--base-ref string: (Obligatorio) Establezca la referencia base que se utilizará para la comprobación, por ejemplo, 'main' o 'master'.
--head-ref string: Establezca la referencia principal que se utilizará para la comprobación, por ejemplo, 'mi-rama-característica'.
--log-level string: Establezca el nivel de registro, uno de los siguientes: DEBUG, INFO, WARN, ERROR.
--payload-only: Prepare la carga útil de la solicitud, la salida como JSON y salga. Si se establece, el api-token y api-url Las opciones no son obligatorias.
--Version: Muestra la información de la versión y salir.

Un ejemplo de comando de ejecución de Docker que realizaría la comprobación de políticas con los contribuyentes de la clase my-feature-branch es la siguiente:

docker run --rm -e SCW_API_KEY=YOUR_API_KEY -e SCW_API_URL=https://trust-agent.prod-us.prod.securecodewarrior.com -- ghcr.io/securecodewarrior/scw-policy-gate-ci:0.2 --base-ref main --head-ref my-feature-branch --repository-path .

Tenga en cuenta el base-ref y head-ref Por lo general, el sistema de CI deberá rellenar los valores en función de las ramas base y de características de la solicitud de incorporación de cambios asociada. El base-ref El valor también se puede establecer en un nombre de rama troncal predeterminado, como main, en función de la convención de nomenclatura de ramas utilizada en su organización.

Bloquear vs Advertir

Una cosa importante a tener en cuenta es que la herramienta de verificación de CI simplemente devuelve el resultado de la verificación de políticas y la forma en que se interpretan los errores se puede configurar dentro de su sistema de CI.

Si se configura una comprobación fallida de una solicitud de incorporación de cambios en el sistema de CI para que sea SIN BLOQUEO a continuación, actuará como una advertencia solo dentro de la canalización de CI, proporcionando al desarrollador una notificación de que no se han cumplido los requisitos de su política de formación e información sobre cómo puede abordar la brecha. Sin embargo, si está configurado para ser una comprobación obligatoria que debe pasarse, actuará como un bloqueante Compruebe que puede impedir que el desarrollador fusione su solicitud de incorporación de cambios hasta que haya cumplido los requisitos de la política de entrenamiento.

Secure Code Warrior recomienda encarecidamente configurar la herramienta de verificación de CI en modo de advertencia durante al menos 6 meses antes de considerar convertirla en una verificación de bloqueo. Además, recomendamos comprobar el modelado de vista previa en la sección Policy Gating de la pantalla de configuración para asegurarse de que se detecta una proporción suficientemente alta (70+%) de confirmaciones permitidas para minimizar cualquier interrupción en los equipos de desarrollo que trabajan en repositorios dentro del ámbito de la configuración de Policy Gating. Puede limitar el alcance de la herramienta de verificación de CI a repositorios críticos solo configurando esto en la configuración de Policy Gating. Por favor, refiérase a Esta guía para obtener más información.

Implementación a escala

En el caso de las organizaciones con un gran número de repositorios, normalmente se requiere algún tipo de flujo de trabajo de plantilla que pueda ser actualizado y recogido automáticamente por repositorios individuales para evitar que cada repositorio tenga que configurarse con un flujo de trabajo o trabajo adicional.

Para las organizaciones en GitHub Enterprise, se pueden usar conjuntos de reglas para lograr esto, pero tu organización también puede tener un método alternativo personalizado. Por ejemplo, puede crear un conjunto de reglas de organización que se dirija a un conjunto de repositorios o a todos los repositorios (consulte la sección Documentación oficial para obtener más detalles), así como especificar las ramas de destino de esos repositorios:

A continuación, puede configurar un flujo de trabajo de plantilla y establecerlo como un flujo de trabajo obligatorio mediante el comando Requerir que los flujos de trabajo pasen antes de fusionarlos regla. Por favor, refiérase a la Documentación oficial para obtener instrucciones de configuración completas.

ADVERTENCIA IMPORTANTE: Esto ejecutará automáticamente el flujo de trabajo de la plantilla para todas las solicitudes de incorporación de cambios de los repositorios de destino y requerirá que la verificación pase antes de que se puedan fusionar las ramas, lo que pondrá la verificación de políticas en modo de bloqueo. Actualmente no parece haber una manera de configurar un conjunto de reglas de GitHub que ejecute automáticamente el flujo de trabajo de plantilla para todos los repositorios de destino sin requiriendo que el cheque debe ser aprobado.

Artículos relacionados:

Menu

Cómo conectar la puerta de enlace de políticas Trust Agent a sus canalizaciones CI