Referencia de la API de hallazgos

Usa GET /v1/findings (clave de API) o la herramienta MCP list_findings (OAuth) para explorar hallazgos mediante programación. Ambas interfaces usan los mismos filtros y devuelven los mismos campos de resumen.

Listar hallazgos

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 "sort_by=severity" \
  --data-urlencode "limit=25"

Parámetros de consulta

Parámetro	Valor predeterminado	Descripción
`target_id`	—	Filtrar por un objetivo (UUID de Target Inventory)
`assessment_id`	—	Filtrar por hallazgos de una ejecución de evaluación (UUID de Assessments)
`status`	`ACTIVE`	Filtro de ciclo de vida: `ACTIVE`, `RESOLVED` o `ARCHIVED`
`exclude_secured`	`false`	Cuando es `true`, omite las sondas informativas seguras (`severity=secured`)
`severity`	—	Filtrar por severidad: `critical`, `high`, `medium`, `low` o `secured` (`info` es un alias obsoleto de `secured`)
`sort_by`	`severity`	`severity` (primero la puntuación más alta) o `created_at`
`order_direction`	`desc`	Dirección de ordenación: `asc` o `desc`
`search`	—	Buscar por ID, título, descripción, endpoint o impacto del hallazgo
`status_filter`	—	Filtro de vulnerabilidad: `vulnerable`, `secured` o `all`
`active_only`	`false`	Cuando es `true`, devuelve solo hallazgos activos
`org_wide`	`false`	Parámetro de compatibilidad; omite `target_id` y `assessment_id` para obtener resultados de toda la organización
`assigned_to_me`	`false`	Cuando es `true`, devuelve solo los hallazgos asignados al usuario actual
`assigned_to`	—	Filtrar por ID de usuario asignado
`unassigned`	`false`	Cuando es `true`, devuelve solo los hallazgos sin persona asignada
`finding_type`	—	Solo los hallazgos `red-team` están disponibles mediante la API pública
`limit`	`25`	Tamaño de página (máximo `100`)
`offset`	`0`	Desplazamiento para la paginación

Respuesta

Cada elemento de findings incluye:

Campo	Descripción
`id`	UUID del hallazgo
`assessment_id`	UUID de la evaluación cuando está asociado a una evaluación
`target_name`	Nombre del objetivo cuando está disponible
`finding_type`	Siempre `red-team`
`title`	Título del hallazgo
`severity`	`critical`, `high`, `medium`, `low` o `secured`
`severity_score`	Puntuación numérica (puede ser `0` para elementos de severidad baja o seguros)
`overridden_severity`	Anulación de severidad seleccionada por el usuario cuando se ha establecido
`status`	`ACTIVE`, `RESOLVED` o `ARCHIVED`
`target_id`	UUID del objetivo
`created_at`	Marca de tiempo ISO 8601
`updated_at`	Marca de tiempo ISO 8601 del último cambio visible del hallazgo
`retest_status`	Estado de ejecución actual de la nueva prueba cuando existe una
`retest_started_at`	Cuándo comenzó a ejecutarse la nueva prueba actual
`retest_completed_at`	Cuándo se completó o falló la nueva prueba actual
`retest_failure_reason`	Motivo visible para el cliente por el que no se pudo ejecutar una nueva prueba
`retest_in_progress`	`true` mientras una nueva prueba está en cola o en ejecución

La respuesta también incluye total, limit, offset y next_cursor para la paginación. Usa offset hasta que offset + len(findings) >= total; next_cursor es un marcador de paginación opaco.

Coincidir con el panel

La interfaz de MindFort usa pestañas y filtros que se corresponden con parámetros de la API:

Vista del panel	Equivalente en API / MCP
Open (solo vulnerables, predeterminada)	`status=ACTIVE` y `exclude_secured=true`
Open (incluye sondas seguras)	`status=ACTIVE` (omite `exclude_secured` o usa `exclude_secured=false`)
Resolved	`status=RESOLVED`
Archived	`status=ARCHIVED`
Hallazgos de una evaluación	`assessment_id=<uuid>`

Sin exclude_secured=true, los resultados de la lista incluyen hallazgos informativos de sondas secured (severity=secured) que el panel oculta en la pestaña Open predeterminada. Esto puede explicar por qué los recuentos de la API o de MCP parecen más altos que los de la interfaz.

Ejemplos

Vulnerabilidades de un objetivo (coincide con la pestaña Open predeterminada):

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

Hallazgos de una evaluación específica:

curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "assessment_id=${MINDFORT_ASSESSMENT_ID}" \
  --data-urlencode "exclude_secured=true"

Hallazgos archivados:

curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "status=ARCHIVED"

Obtener los detalles de un hallazgo

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

Devuelve todos los campos, incluidos description, impact, evidence, approach, remediation_advice, status y el contexto de decisión de la nueva prueba. Usa retest_status para interpretar la ejecución actual:

QUEUED: aceptada, pero aún no se está ejecutando
RUNNING: la ejecución está en curso
FAILED: la ejecución no pudo completarse; revisa retest_failure_reason
COMPLETED: la validación terminó y su resultado se aplicó al ciclo de vida del hallazgo

Actualizar el estado

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"}'

Valores válidos: ACTIVE, RESOLVED, ARCHIVED. Cuando status es RESOLVED, puedes incluir resolve_reason (FIX o WONT_FIX) y, opcionalmente, resolve_context (máximo 2000 caracteres). Las actualizaciones masivas están disponibles en POST /v1/findings/status con hasta 50 finding_ids.

Anular la severidad

curl -X PATCH "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/severity" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"severity":"high"}'

Valores aceptados: critical, high, medium, low, secured. Pasa null para eliminar una anulación. info solo se acepta como alias obsoleto de secured.

Volver a probar un hallazgo

curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/retest" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"

Inicia una nueva prueba asíncrona para un hallazgo ACTIVE, RESOLVED o ARCHIVED. La solicitud falla si ya hay otra nueva prueba en cola o en ejecución. Consulta GET /v1/findings/{finding_id} periódicamente después de que se acepte la solicitud. Cuando la nueva prueba se completa, MindFort aplica el resultado de la validación:

Un resultado que indica que el problema está corregido en las condiciones probadas establece el hallazgo en RESOLVED.
Un resultado que indica que el problema sigue siendo reproducible establece el hallazgo en ACTIVE.
Un fallo de ejecución deja el resultado de seguridad sin cambios y rellena retest_failure_reason.

Las transiciones de la nueva prueba a RUNNING y FAILED actualizan el campo updated_at del hallazgo, por lo que los consumidores basados en cambios pueden detectarlas.

Comentarios

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

curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/comments" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content":"Patched in PR #482 — ready for retest."}'

Edita con PATCH /v1/findings/{finding_id}/comments/{comment_id} y elimina con DELETE /v1/findings/{finding_id}/comments/{comment_id}.

Resúmenes de parches

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

Devuelve los hallazgos que tienen actividad de parches, incluidos pr_url, patch_status y patch_state. Usa assigned_to_me=true para limitar los resultados a los hallazgos del usuario actual o search para buscar por ID, título, descripción, endpoint o impacto del hallazgo. Las organizaciones autorizadas reciben la URL almacenada del pull request de GitHub, incluidas las URL de repositorios privados. La actividad de parches es independiente del estado del ciclo de vida del hallazgo.

Analíticas

Los endpoints de analíticas de hallazgos aceptan un target_id opcional. Omítelo para obtener métricas de toda la organización. GET /v1/findings/severity-score-history acepta granularity (day, week o month), y las métricas de remediación aceptan además las fechas inclusivas opcionales from y to.

Endpoint	Descripción
`GET /v1/findings/counts`	Recuentos de ciclo de vida, exposición y severidad
`GET /v1/findings/severity-distribution`	Distribución por severidad
`GET /v1/findings/category-distribution`	Distribución por OWASP y etiquetas de vulnerabilidad
`GET /v1/findings/severity-score-history`	Historial de puntuación de severidad
`GET /v1/findings/metrics/current`	Métricas de seguridad actuales
`GET /v1/findings/metrics/timeseries`	Métricas de series temporales (`from`, `to`, `granularity` opcional)
`GET /v1/findings/metrics/remediation`	Métricas de remediación (MTTR)
`GET /v1/findings/metrics/sla`	Métricas de incumplimiento de SLA
`GET /v1/findings/metrics/aging`	Rangos de antigüedad de los hallazgos

La puntuación de salud del objetivo está disponible en GET /v1/targets/{target_id}/health-score.

MCP

La guía de MCP expone los mismos filtros semánticos en la herramienta list_findings. Pasa target_id, assessment_id, status, exclude_secured, severity, sort_by, order_direction, search o filtros de asignación; las herramientas de colecciones de MCP usan un cursor opaco en lugar de un desplazamiento sin procesar. Después de una actualización del servidor, no necesitas reinstalar MCP. Mantén la misma URL https://api.mindfort.app/mcp y reinicia tu agente o inicia un chat nuevo para que cargue el esquema de herramientas más reciente.

Recuperar una credencial de nueva prueba

Cuando retest_failure_code identifica un fallo de autenticación o una credencial no disponible, vuelve a intentarlo con una credencial sustituta del mismo objetivo. La solicitud pública de nueva prueba acepta target_credential_id para una credencial principal sustituta. Para revisar ambas cuentas de un hallazgo con credenciales duales, usa el panel. La sustitución solo se permite después de un fallo de credencial que cumpla los requisitos. Cambia las credenciales de futuras nuevas pruebas, no las credenciales registradas para el hallazgo original. Revisa retest_failure_reason para ver la explicación visible para el cliente. Consulta Volver a probar hallazgos.

Registrar un falso positivo

Al actualizar el estado del ciclo de vida de un hallazgo, una decisión de falso positivo usa status: "ARCHIVED", resolve_reason: "FALSE_POSITIVE" y un resolve_context no vacío que explique la decisión. FIX y WONT_FIX son motivos de resolución para hallazgos RESOLVED. Consulta el esquema del endpoint de estado para ver el contrato completo de la solicitud.

Getting Started

Core Workflows

Advanced Features

Integrations

Help & Support

Listar hallazgos

Parámetros de consulta

Respuesta

Coincidir con el panel

Ejemplos

Obtener los detalles de un hallazgo

Actualizar el estado

Anular la severidad

Volver a probar un hallazgo

Comentarios

Resúmenes de parches

Analíticas

MCP

Recuperar una credencial de nueva prueba

Registrar un falso positivo

​Listar hallazgos

​Parámetros de consulta

​Respuesta

​Coincidir con el panel

​Ejemplos

​Obtener los detalles de un hallazgo

​Actualizar el estado

​Anular la severidad

​Volver a probar un hallazgo

​Comentarios

​Resúmenes de parches

​Analíticas

​MCP

​Recuperar una credencial de nueva prueba

​Registrar un falso positivo

Listar hallazgos

Parámetros de consulta

Respuesta

Coincidir con el panel

Ejemplos

Obtener los detalles de un hallazgo

Actualizar el estado

Anular la severidad

Volver a probar un hallazgo

Comentarios

Resúmenes de parches

Analíticas

MCP

Recuperar una credencial de nueva prueba

Registrar un falso positivo