Acción de GitHub: Pruebas estáticas de seguridad de API REST de 42Crunch

La acción de Pruebas estáticas de seguridad de API REST localiza contratos de API REST que siguen la Especificación OpenAPI (OAS, anteriormente conocida como Swagger) y ejecuta comprobaciones de seguridad exhaustivas sobre ellos. Se admiten tanto OAS v2 como v3.0.x, en formato JSON y YAML.

Puede utilizar esta acción en los siguientes escenarios:

• Añadir una tarea automática de pruebas estáticas de seguridad de API (SAST) a sus flujos de trabajo de CI/CD.
• Realizar estas comprobaciones en las revisiones de pull requests o en las fusiones de código.
• Marcar los problemas localizados en las Alertas de seguridad / Code Scanning de GitHub.

La acción está impulsada por 42Crunch API Security Audit. Security Audit realiza un análisis estático de la definición de la API que incluye más de 300 comprobaciones sobre mejores prácticas y posibles vulnerabilidades relacionadas con la autenticación, la autorización y las restricciones de datos.

Descubra APIs en sus repositorios

De forma predeterminada, esta acción:

1. Buscará cualquier archivo .json y .yaml en el repositorio.
2. Seleccionará los archivos que usan el esquema OpenAPI.
3. Realizará la auditoría de seguridad en las definiciones OpenAPI.

De esta manera, puede localizar cualquier contrato de API nuevo o modificado en el repositorio.

Puede ajustar el comportamiento de la acción especificando partes concretas del repositorio o máscaras de nombres de archivo que se incluirán o excluirán en el descubrimiento de APIs. Incluso puede deshabilitar por completo el descubrimiento y, en su lugar, enumerar solo archivos de API específicos que se deben comprobar y asignarlos a sus APIs existentes en 42Crunch API Security Platform. Todos estos ajustes se configuran en el archivo de configuración 42c-conf.yaml. Para ver ejemplos avanzados, consulte aquí.

Todas las APIs descubiertas se cargan en una colección de APIs en 42Crunch Platform. De forma predeterminada, la acción utiliza las variables de entorno GITHUB_REPOSITORY y GITHUB_REF para nombrar el repositorio y la rama/etiqueta/PR de donde se origina la colección de APIs. Puede anular el nombre utilizando el parámetro de acción default-collection-name. En las ejecuciones posteriores, las APIs de la colección se mantienen sincronizadas con los cambios en su repositorio.

Use esta acción para bloquear el despliegue de APIs vulnerables

Añada esta acción a sus flujos de trabajo de CI/CD en GitHub y haga que falle en las definiciones de API que contengan problemas de seguridad.

Security Audit asigna a cada contrato de API una puntuación de auditoría de 0 a 100 que refleja la superficie de seguridad de sus APIs. Puede usar el parámetro min-score de la GitHub Action para establecer el umbral de la puntuación de auditoría a partir del cual la acción falla (el valor predeterminado es 75, si no se especifica otro). Esto ayuda a detectar definiciones de API de mala calidad y a abordar los problemas lo antes posible, ya en la fase de diseño.

Se pueden establecer condiciones de error más avanzadas en el archivo de configuración 42c-conf.yaml, como la puntuación de auditoría por categoría (seguridad o validación de datos), el nivel de gravedad de los problemas, o incluso problemas específicos, identificados por su ID de problema. Para ver ejemplos avanzados, consulte aquí.

Además, el plugin aplica los security quality gates definidos a nivel de plataforma (los predeterminados o los controlados por etiquetas). Los security quality gates aplican los requisitos de seguridad de las aplicaciones definidos dentro de la empresa.

Lectura de informes detallados y procesables

Cada vez que la acción se ejecuta, incluye un enlace al informe detallado, priorizado y procesable para cada uno de sus archivos OpenAPI:

Siga los enlaces para leer el informe detallado en 42Crunch Platform:

Subir alertas de 42Crunch al code scanning de GitHub

También puede hacer seguimiento de los problemas que la auditoría de 42Crunch encuentra directamente en GitHub, en la pestaña Security, bajo Code scanning alerts.

Para habilitarlo, simplemente incluya upload-to-code-scanning:true en los parámetros de la acción en su flujo de trabajo de GitHub.

Haga clic en cualquiera de las alertas para ver su ubicación exacta en su código y obtener los detalles de la vulnerabilidad y los pasos de corrección recomendados.

Primeros pasos

Esta acción utiliza el servicio 42Crunch API Security Audit. Antes de usar la acción, necesitará tener una cuenta en la plataforma 42Crunch. Si no es cliente de 42Crunch, puede solicitar una cuenta gratuita desde esta página: https://42crunch.com/get-started/.

A continuación, siga los pasos descritos en la documentación para crear un token de API para que la acción se autentique en 42Crunch Platform y guárdelo como un secreto en GitHub.

Parámetros de la acción

api-token

Obligatorio El token de API que la GitHub action utiliza para autenticarse en 42Crunch Platform. ¡No ponga su token de API directamente en el archivo de flujo de trabajo! En su lugar, cree un secreto de GitHub en la configuración de su repositorio y refiérase a él como se muestra en el ejemplo siguiente.

min-score

La puntuación de auditoría mínima que deben alcanzar los archivos OpenAPI; de lo contrario, la acción falla. El valor predeterminado es 75.

upload-to-code-scanning

Sube los resultados de la auditoría a Github Code Scanning. El valor predeterminado es false. Tenga en cuenta que el flujo de trabajo debe tener permisos específicos para que este paso tenga éxito.

...
jobs:
  run_42c_audit:
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for results upload to Github Code Scanning
...

ignore-failures

Si se establece en true, fuerza la finalización correcta de la ejecución incluso si se cumplen las condiciones de error (como min-score o los criterios SQG) que haya establecido. El valor predeterminado es false.

Este parámetro puede resultar útil si desea detectar escenarios de error de SQG sin aplicarlos (es decir, dar un período de gracia a los equipos de desarrollo antes de empezar a romper las compilaciones).

ignore-network-errors

Si se establece en true, fuerza la finalización correcta de la ejecución incluso si se ha producido un error de red (como un fallo al conectarse a 42Crunch Platform, etc.). El valor predeterminado es false.

skip-local-checks

Si se establece en true, desactiva todas las condiciones de error (como la puntuación mínima) establecidas en el archivo 42c-conf.yaml y solo hace fallar la ejecución si no se cumplen los criterios definidos en las SQG. El valor predeterminado es false.

platform-url

La URL desde la que accede a 42Crunch Platform. El valor predeterminado es https://us.42crunch.cloud.

Si es un cliente empresarial, introduzca la URL que utiliza para acceder a su plataforma de producción.

root-directory

El directorio raíz que contiene el archivo de configuración 42c-conf.yaml. Si no se especifica, se utiliza el directorio de trabajo actual del plugin, que normalmente corresponde a la raíz del repositorio clonado.

default-collection-name

El nombre de colección predeterminado que se utiliza al crear colecciones para las APIs descubiertas. Si no se proporciona ningún nombre, se crea un nombre predeterminado a partir del repositorio y la información de la rama/PR.

log-level

Nivel de detalle en los logs, uno de: FATAL, ERROR, WARN, INFO, DEBUG. El valor predeterminado es INFO.

share-everyone

Comparte automáticamente las colecciones de APIs creadas por la tarea de CI/CD con todos los miembros de su organización en 42Crunch Platform. Los valores aceptados son: OFF, READ_ONLY, READ_WRITE. El valor predeterminado es OFF. Tenga en cuenta que la identidad con la que se ejecuta la acción (el propietario del token de API) debe tener el permiso Share with Everyone; de lo contrario, la tarea fallará con un error 403.

json-report

Escribe un informe de ejecución de auditoría en formato JSON en el archivo especificado. Un informe de ejecución detalla la lista de APIs que se crearon, actualizaron y eliminaron. Esto es útil si desea consumir automáticamente los resultados de la ejecución de la auditoría en un paso posterior del pipeline. De forma predeterminada, no se escribe ningún informe.

api-tags

La tarea de CI/CD puede asignar automáticamente etiquetas a las APIs recién creadas. Las etiquetas se especifican en el siguiente formato: category1:name1 category2:name2. Este indicador es opcional.

sarif-report

Convierte el formato JSON sin procesar de la auditoría a SARIF y guarda los resultados en el archivo especificado. De forma predeterminada, no se escribe ningún informe.

audit-timeout

Establece el tiempo de espera máximo (en segundos) para el informe de auditoría. La tarea fallará si el resultado no está listo dentro de ese intervalo. Valor predeterminado: 600

Requisitos previos

Cree un token de API en la plataforma 42Crunch y copie su valor en un secreto del repositorio llamado API_TOKEN.

Ejemplos

Ejemplo de un solo paso

Un paso nuevo típico en un flujo de trabajo existente se vería así:

- name: 42crunch-static-api-testing
        uses: 42Crunch/api-security-audit-action@v4
        with:
          api-token: ${{ secrets.API_TOKEN }}
          default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
          log-level: info
          json-report: audit-action-report-${{ github.run_id }}
          sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF

Ejemplo de flujo de trabajo completo

Un flujo de trabajo típico que comprueba el contenido del repositorio, ejecuta Security Audit en cada uno de los archivos OpenAPI encontrados en el proyecto y guarda el archivo de ejecución como artefacto se vería así:

name: "42crunch-audit-workflow"

# follow standard Code Scanning triggers
on:
  push:
    branches: [ "main" ]
  pull_request:
    # The branches below must be a subset of the branches above
    branches: [ "main" ]
  schedule:
    - cron: '19 9 * * 6'

env:
  PLATFORM_URL: https://us.42crunch.cloud

jobs:
  run_42c_audit:
    environment: QA
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for results upload to Github Code Scanning
    runs-on: ubuntu-latest
    steps:
      - name: checkout repo
        uses: actions/checkout@v3
      - name: 42crunch-static-api-testing
        uses: 42Crunch/api-security-audit-action@v4
        with:
          api-token: ${{ secrets.API_TOKEN }}
          platform-url: ${{ env.PLATFORM_URL}}
          default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
          # Upload results to Github code scanning
          upload-to-code-scanning: false
          log-level: info
          json-report: audit-action-report-${{ github.run_id }}
          sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
      - name: save-audit-report
        if: always()        
        uses: actions/upload-artifact@v3
        with:
          name: auditaction-report-${{ github.run_id }}
          path: audit-action-report-${{ github.run_id }}.json
          if-no-files-found: error

Soporte

La acción es mantenida por el equipo de 42Crunch Ecosystems. Si encuentra un problema o tiene una pregunta que no esté respondida aquí, puede crear un ticket de soporte en support.42crunch.com.

Al informar de un problema, incluya:

• La versión de la GitHub action
• Los registros (logs) y mensajes de error relevantes
• Los pasos para reproducir el problema