> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindfort.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ejecutar MindFort en pipelines de CI/CD

> Ejecuta evaluaciones de seguridad de MindFort desde CI/CD, con ejemplos de GitHub Actions para iniciar evaluaciones, consultar hallazgos y descargar informes.

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:

1. **API Key**: genera una desde el [panel de MindFort](https://cloud.mindfort.app) en **Settings > API Keys**.
2. **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`.

```yaml theme={null}
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
```

> [accordion] 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`.

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

```bash theme={null}
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](https://docs.mindfort.ai/es/api-reference/findings) 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.

```bash theme={null}
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:

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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"
  }'
```

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.