Acción de Github de Ostorlab

1. Generar una nueva clave API

Para usar la Acción de Github de Ostorlab, el primer paso es generar una clave API. Para hacerlo, simplemente siga los siguientes pasos:

Vaya a report.ostorlab.co

Haga clic en el botón Menu

Haga clic en Integrations/API para expandir

Haga clic en API Keys

Haga clic en New API Key, asigne un nombre a la clave y elija su rol, luego haga clic en Create Key. También puede definir una fecha de caducidad.

Copie la clave desde el aviso con Copy Key: solo se muestra una vez.

2. Añadir la Acción de Github de Ostorlab a su flujo de trabajo

Una vez que haya generado su API, añádala a los Secretos de GitHub. Asegúrese de que el nombre coincida con secrets. en el archivo YAML. Puede seguir los pasos en la documentación de Github en el siguiente enlace para obtener instrucciones más detalladas.

El siguiente paso es actualizar su flujo de trabajo para añadir un paso de Ostorlab para activar el escaneo. A continuación, se muestra un ejemplo que realiza un escaneo rápido en un APK de Android y falla el pipeline si el nivel de riesgo del escaneo es superior a HIGH (es decir, CRITICAL).

on: [push]
jobs:
  ostorlab_test:
    runs-on: ubuntu-latest
    name: Test ostorlab ci actions.
    steps:
      - uses: actions/checkout@v4
      - name: build ostorlab.apk
        run: mv InsecureBankv2.apk ostorlab.apk
      - name: Launch Ostorlab scan
        id: start_scan
        uses: Ostorlab/ostorlab_actions@v2.1.0
        with:
          scan_profile: fast_scan # Especifique qué perfil de escaneo utilizar para el escaneo (consulte la sección de escaneo).
          asset_type: android-apk # tipo de activo a escanear.
          target: ostorlab.apk # ruta del objetivo a escanear.
          scan_title: title_scan_ci # escriba un título para su escaneo.
          ostorlab_api_key: ${{ secrets.ostorlab_api_key }} # su clave api secreta.
          break_on_risk_rating: HIGH # Esperar los resultados del escaneo y forzar el fallo de la acción si el riesgo del escaneo es mayor (aquí: CRITICAL)
          max_wait_minutes: 30
      - name: Get scan id
        run: echo "Scan Created with id ${{ steps.start_scan.outputs.scan_id }} you can access the full report at https://report.ostorlab.co/scan/${{ steps.start_scan.outputs.scan_id }}/"

3. Escaneo de Aplicaciones Web

Además de las aplicaciones móviles, Ostorlab también admite el escaneo de aplicaciones web a través de flujos de trabajo de GitHub. Para escanear aplicaciones web, configure su flujo de trabajo como se muestra en el siguiente ejemplo:

on: [push]
jobs:
  ostorlab_web_scan:
    runs-on: ubuntu-latest
    name: Test ostorlab web scan.
    steps:
      - uses: actions/checkout@v4
      - name: Launch Ostorlab web scan
        id: start_scan
        uses: Ostorlab/ostorlab_actions@v2.1.0
        with:
          scan_profile: full_web_scan
          asset_type: link --url
          target: https://target1.ostorlab.co --url https://target2.ostorlab.co --url https://target3.ostorlab.co
          scan_title: web_scan_ci
          ostorlab_api_key: ${{ secrets.ostorlab_api_key }}
          break_on_risk_rating: HIGH
          max_wait_minutes: 60
      - name: Get scan id
        run: echo "Scan Created with id ${{ steps.start_scan.outputs.scan_id }} you can access the full report at https://report.ostorlab.co/scan/${{ steps.start_scan.outputs.scan_id }}/"

Para el escaneo de aplicaciones web:

• Utilice scan_profile: full_web_scan
• Establezca asset_type: link --url
• Enumere sus URL de destino con el indicador --url para cada URL adicional

Las acciones de Github de Ostorlab toman las siguientes entradas:

scan_profile, que es una opción obligatoria que especifica el perfil de escaneo, puede ser fast_scan solo para análisis estático rápido, full_scan para cobertura completa estática, dinámica y de backend, o full_web_scan para escaneo de aplicaciones web.

asset_type, una opción obligatoria que especifica el tipo de activo de destino, por ejemplo, APK de Android, IPA de iOS o enlace para aplicaciones web.

target, una opción obligatoria. Es un archivo de destino a escanear o una URL para aplicaciones web.

scan_title, una opción opcional. Es un título para identificar su escaneo.

ostorlab_api_key, una opción obligatoria. Puede obtenerla del panel de Ostorlab, en Integrations/API luego en API Keys.

break_on_risk_rating, una opción opcional. Cuando se define, la acción espera a que termine el escaneo y el pipeline falla si el nivel de riesgo del escaneo es estrictamente superior al valor proporcionado: HIGH solo falla con un escaneo CRITICAL. Sin esta opción, la acción no espera el resultado.

max_wait_minutes, una opción opcional. Es el tiempo máximo de espera en minutos (por defecto: 20) cuando se define break_on_risk_rating. Si el escaneo no ha terminado al final de la espera, el paso falla con un error de tiempo de espera.

extra, una opción opcional. es un argumento adicional para pasar a la CLI de Ostorlab. Un caso de uso común es pasar las credenciales de prueba del escaneo.

Puede proporcionar sus archivos SBOM o Lock para mejorar el análisis del escaneo, para hacerlo utilice la entrada extra para pasar el SBOM, por ejemplo para agregar un archivo package lock dot json utilice el siguiente ejemplo:

Aquí puede ver la lista de los archivos admitidos:

Ostorlab admite realizar pruebas autenticadas con contraseña de inicio de sesión simple o entradas personalizadas identificadas con nombre o etiqueta y pasando el valor. Para pasar las credenciales de prueba, dado que la Acción YAML de Github no admite pasar objetos complejos, puede utilizar la entrada extra para pasar las credenciales de prueba. Por ejemplo, para añadir inicio de sesión y contraseña y credenciales personalizadas con nombres y valores personalizados, añada la siguiente entrada:

En cuanto a la salida de la acción, es posible acceder al scan_id utilizando la siguiente sintaxis ${{ steps.STEP_ID.outputs.scan_id }}.

4. Use la Aplicación de GitHub Ostorlab Security Scanner para proporcionar información procesable directamente en su PR

La Aplicación de GitHub Ostorlab Security Scanner debe utilizarse en conjunto con un flujo de trabajo de Acciones de GitHub de Ostorlab como se explica en los pasos 1 y 2.

La Aplicación de GitHub Ostorlab Security Scanner está diseñada para ayudar a los desarrolladores a mejorar la seguridad de su código al proporcionar información procesable directamente en los Pull Requests. Integra la seguridad en el flujo de trabajo de desarrollo con el objetivo principal de identificar exactamente qué fragmento de código introdujo la vulnerabilidad, proporcionar información procesable y sugerencias de código que puede confirmar automáticamente. Este documento proporciona instrucciones sobre cómo configurar y utilizar la Aplicación.

1. Añadir la Aplicación de GitHub:

   1. Vaya a la Aplicación Ostorlab Security Scanner.
      
   2. Haga clic en Add.
      
   3. Elija la cuenta donde desea instalar la aplicación.
      
   4. Haga clic en Install for free.
      

   5. Proporcione los permisos necesarios:

      • Acceso de Read & Write a pull requests.
      • Acceso de Metadata para el repositorio.

      

   6. Haga clic en Install para finalizar la configuración.
      

2. Cómo utilizar:

   1. El siguiente paso es actualizar su flujo de trabajo para añadir un paso de Ostorlab para activar el escaneo como se describe en los pasos 1 y 2.
      
   2. Cree un pull request que incorpore el flujo de trabajo actualizado con Ostorlab.
      
      Después de que se complete el escaneo, Ostorlab Security Scanner comentará automáticamente en su pull request, identificando exactamente dónde se introdujo la vulnerabilidad y proporcionando fragmentos de código de la solución.
      

5. Del escaneo a la corrección verificada

Para evitar que los cambios arriesgados lleguen a una release, ejecute el escaneo en cinco etapas:

Etapa	Qué se ejecuta
1. Escanear cada pull request	La acción se ejecuta en cada pull request: un Fast Scan para un build móvil, o un Full Web Scan para una aplicación web.
2. Condicionar al riesgo	El build falla cuando la calificación de riesgo del escaneo es estrictamente superior a break_on_risk_rating.
3. Enviar los tickets a Jira o Linear	Los hallazgos se convierten en tickets de Ostorlab, sincronizados con Jira o Linear.
4. Verificar la corrección	Un escaneo posterior marca un ticket corregido como FIXED VERIFIED o lo vuelve a abrir. Un Single Vulnerability Assessment vuelve a probar un hallazgo.
5. Evaluación en profundidad antes de la release	Un Deep Agentic Scan se ejecuta antes de la release, no en cada pull request.

Escanear cada pull request y condicionar al riesgo

Ejecute el workflow en las pull requests: defina on: pull_request en lugar de on: [push]. break_on_risk_rating hace fallar el build cuando la calificación de riesgo del escaneo es estrictamente superior al valor definido, y max_wait_minutes limita la espera (20 minutos por defecto). Para elegir un umbral, consulte Calificación de riesgo para conocer el significado de cada calificación.

Enviar los tickets a Jira o Linear

Ostorlab crea automáticamente un ticket para cada problema de seguridad recién detectado y agrega las apariciones posteriores de la misma vulnerabilidad en el mismo ticket. Para enviar esos tickets al gestor de incidencias de su equipo, active la creación automática de incidencias en la integración de Jira o de Linear. Ambas requieren una suscripción empresarial. En cualquiera de las dos integraciones, elija las calificaciones de riesgo de los tickets que se sincronizarán: solo los tickets con esas calificaciones llegan a Jira o Linear.

Verificar la corrección

Cuando un desarrollador publica una corrección, marque el ticket como corregido. Un escaneo posterior que ejecute las mismas pruebas comprueba entonces la corrección: si la vulnerabilidad no aparece, el ticket se marca automáticamente como FIXED VERIFIED; en caso contrario, se vuelve a abrir el mismo ticket. Los tickets marcados como excepción o como falso positivo se mantienen tal como están. Consulte Ciclo de vida del ticket.

Para volver a probar un hallazgo sin un nuevo escaneo completo, ejecute un Single Vulnerability Assessment directamente desde el ticket reportado. Suele tardar de 2 a 10 minutos.

Comprobaciones continuas y evaluaciones en profundidad

Las comprobaciones continuas se ejecutan en cada pull request o según una programación y terminan en minutos. Las evaluaciones en profundidad se ejecutan antes de una release, tardan de 1 a 3 horas y validan las cadenas de ataque y la lógica de negocio con una prueba de concepto. Consulte Comparación de tipos de escaneo.

Escaneo	Cuándo ejecutarlo	Duración típica	Qué cubre	Proveedor de IA
Fast Scan (comprobación continua)	En cada pull request, en CI	De 1 a 5 minutos	Análisis estático	Ninguno
Full Scan (comprobación continua)	Según una programación	De 15 a 45 minutos	Pruebas estáticas, dinámicas y de backend	Ninguno
Deep Agentic Scan (evaluación en profundidad)	Antes de una release	De 1 a 3 horas	Pentest con agentes de IA: cadenas de ataque, lógica de negocio, hallazgos validados con una prueba de concepto	Cyber Models o su propia clave (BYOK)

• Full Scans programados: cree una regla de monitorización con una programación CRON, o una regla CONTINUOUS que escanea cuando el activo cambia, y seleccione Full Scan. Consulte Crear regla de monitorización.
• Deep Agentic Scan previo a la release: inícielo desde Scanning > New Scan en la plataforma. Consulte Mobile Deep Agentic Scan o Web Deep Agentic Scan. Necesita un proveedor de IA: Cyber Models o su propia clave (BYOK). Sus hallazgos son producidos por agentes de IA, sin validación humana.

Esta guía describió cómo añadir la Acción de GitHub de Ostorlab a un flujo de trabajo, escanear aplicaciones web, utilizar la Aplicación de GitHub Ostorlab Security Scanner y ejecutar un pipeline de release, del escaneo a la corrección verificada.