Ejecutar MindFort en pipelines de CI/CD

Integra MindFort en tus pipelines de CI/CD para solicitar evaluaciones de seguridad en los eventos de push, pull request o despliegue que configures. Esto ayuda a que las pruebas de seguridad formen parte habitual de tu flujo de trabajo de desarrollo.

Requisitos previos

Antes de configurar tu pipeline, necesitarás:

API Key: genera una desde el panel de MindFort en Settings > API Keys.
Target ID: encuéntralo en Target Inventory haciendo clic en el objetivo que quieres evaluar.

Guarda tu clave de API como secreto en tu plataforma de CI/CD. Nunca la confirmes (commit) en tu repositorio.

Ejemplos de GitHub Actions

Iniciar una evaluación

Este ejemplo solicita una evaluación de seguridad de tu objetivo en cada push o PR a main. El inicio de una ejecución depende de que el objetivo esté listo, de los créditos disponibles y de si ya hay otra evaluación en curso. Configura el método de evaluación con la variable MINDFORT_ASSESSMENT_METHOD (balanced, deep o ultra). Estos valores corresponden a las etiquetas del panel Balanced, Deep y Ultra. Opcionalmente, establece assessment_type en black-box (predeterminado) o white-box.

name: MindFort Security Assessment

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  mindfort-assessment:
    name: Trigger MindFort Assessment
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Assessment
        id: trigger
        run: |
          RESPONSE=$(curl -s -w "\n%{http_code}" \
            -X POST "https://api.mindfort.app/v1/assessments/run" \
            -H "Authorization: Bearer ${{ secrets.MINDFORT_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "target_id": "${{ vars.MINDFORT_TARGET_ID }}",
              "assessment_method": "${{ vars.MINDFORT_ASSESSMENT_METHOD || 'balanced' }}"
            }')

          HTTP_CODE=$(echo "$RESPONSE" | tail -1)
          BODY=$(echo "$RESPONSE" | sed '$d')

          echo "status_code=$HTTP_CODE" >> "$GITHUB_OUTPUT"
          echo "response=$BODY" >> "$GITHUB_OUTPUT"

          if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
            echo "::error::MindFort API returned HTTP $HTTP_CODE: $BODY"
            exit 1
          fi

          ASSESSMENT_ID=$(echo "$BODY" | jq -r '.assessment_id')
          echo "assessment_id=$ASSESSMENT_ID" >> "$GITHUB_OUTPUT"
          echo "Assessment triggered: $ASSESSMENT_ID"

      - name: Summary
        if: always()
        run: |
          echo "### MindFort Assessment" >> "$GITHUB_STEP_SUMMARY"
          if [ "${{ steps.trigger.outputs.assessment_id }}" != "" ]; then
            echo "- **Assessment ID:** \`${{ steps.trigger.outputs.assessment_id }}\`" >> "$GITHUB_STEP_SUMMARY"
            echo "- **Status:** Triggered" >> "$GITHUB_STEP_SUMMARY"
          else
            echo "- **Status:** Failed (HTTP ${{ steps.trigger.outputs.status_code }})" >> "$GITHUB_STEP_SUMMARY"
          fi

Secretos y variables necesarios

Tipo	Nombre	Descripción
Secreto	`MINDFORT_API_KEY`	Tu clave de API de MindFort
Variable	`MINDFORT_TARGET_ID`	UUID del objetivo que se va a evaluar
Variable	`MINDFORT_ASSESSMENT_METHOD`	Opcional: `balanced` (predeterminado), `deep` o `ultra`

Listar objetivos y hallazgos

Usa los endpoints de toda la organización cuando quieras descubrir primero los objetivos y después listar los hallazgos de todos los objetivos o de uno solo. Estos endpoints usan paginación con limit y offset e incluyen un recuento total.

curl -G "https://api.mindfort.app/v1/targets" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "limit=25"

curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "exclude_secured=true" \
  --data-urlencode "severity=critical" \
  --data-urlencode "sort_by=severity" \
  --data-urlencode "limit=25"

GET /v1/findings devuelve resúmenes de hallazgos con identificadores, metadatos del objetivo, severidad y cualquier anulación, estado del ciclo de vida, marcas de tiempo y estado de la nueva prueba. La respuesta incluye los metadatos de paginación total, limit, offset y next_cursor. El valor predeterminado es status=ACTIVE; establece exclude_secured=true para que coincida con la pestaña Open del panel (solo vulnerabilidades). Usa assessment_id para limitar los resultados a una ejecución de evaluación. Consulta la API de hallazgos para ver todos los filtros. Usa GET /v1/findings/{finding_id} para obtener todos los detalles, incluidos description, impact, evidence, approach y remediation_advice.

Cancelar una evaluación

Usa el assessment_id devuelto por POST /v1/assessments/run o copiado de la página Assessments.

curl -X POST "https://api.mindfort.app/v1/assessments/${MINDFORT_ASSESSMENT_ID}/cancel" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

El endpoint no acepta cuerpo de solicitud.

Consultar el progreso de la evaluación

Usa el endpoint de detalles de la evaluación cuando un pipeline necesite el progreso por etapas o un motivo de fallo final:

curl "https://api.mindfort.app/v1/assessments/${MINDFORT_ASSESSMENT_ID}" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

Usa stage_progress para seguir cada etapa de la evaluación. NOT_STARTED significa que no se ha registrado ningún estado; RUNNING o ACTIVE indica trabajo en curso. Las evaluaciones fallidas pueden incluir un failure_reason que explica el problema. Si falla la creación de la evaluación, revisa el code de error público estable. Por ejemplo, assessment_credits_insufficient distingue la capacidad de facturación de la autorización, mientras que assessment_queue_loading admite reintento e incluye Retry-After.

Actualizar el estado de un hallazgo

Usa las actualizaciones de estado para mantener sincronizado el estado de clasificación desde la automatización. Al resolver, puedes incluir resolve_reason (FIX o WONT_FIX) y, opcionalmente, resolve_context.

curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/status" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"status":"RESOLVED","resolve_reason":"FIX"}'

Los valores de estado válidos son ACTIVE, RESOLVED y ARCHIVED.

Generar un informe

Crea un informe para un objetivo, consulta su estado periódicamente y descárgalo cuando esté listo.

curl -X POST "https://api.mindfort.app/v1/reports" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "'"${MINDFORT_TARGET_ID}"'",
    "include_secured_findings": true,
    "include_resolved_findings": false,
    "report_detail_level": "full"
  }'

curl "https://api.mindfort.app/v1/reports/${MINDFORT_REPORT_ID}" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

curl "https://api.mindfort.app/v1/reports/${MINDFORT_REPORT_ID}/download" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

Descripción general

Endpoints

Ejecutar MindFort en pipelines de CI/CD

Requisitos previos

Ejemplos de GitHub Actions

Iniciar una evaluación

Listar objetivos y hallazgos

Cancelar una evaluación

Consultar el progreso de la evaluación

Actualizar el estado de un hallazgo

Generar un informe

​Requisitos previos

​Ejemplos de GitHub Actions

​Iniciar una evaluación

​Listar objetivos y hallazgos

​Cancelar una evaluación

​Consultar el progreso de la evaluación

​Actualizar el estado de un hallazgo

​Generar un informe

Requisitos previos

Ejemplos de GitHub Actions

Iniciar una evaluación

Listar objetivos y hallazgos

Cancelar una evaluación

Consultar el progreso de la evaluación

Actualizar el estado de un hallazgo

Generar un informe