Subida de Findings

El endpoint de findings es el punto de entrada para todos los hallazgos generados por los scanners. La CLI lo usa automáticamente al ejecutar gerion scan ... --push.

Nota

Este endpoint solo acepta POST (subida de hallazgos). La consulta y lectura de findings se realiza desde el dashboard y no está expuesta públicamente.

Prerequisito

Obtén un JWT previamente con el endpoint de autenticación M2M.

Endpoint

POST https://api.gerion.dev/api/v1/findings
Authorization: Bearer <jwt>
Content-Type: application/json

El JWT debe haber sido generado con una API Key que tenga el permiso write:findings.

Body

{
  "metadata": {
    "repository_name": "mi-org/mi-repo",
    "branch_name": "main",
    "scan_type": "SECRETS",
    "build_id": "build-2026-001",
    "code_path": "/src",
    "commit_hash": "abc123def456",
    "commit_author": "committer@acme.com"
  },
  "findings": [
    {
      "finding_id": "secret-001",
      "title": "AWS Access Key expuesta",
      "severity": "CRITICAL",
      "scan_type": "SECRETS",
      "repository_name": "mi-org/mi-repo",
      "branch_name": "main",
      "build_id": "build-2026-001",
      "code_path": "/src",
      "active": true,
      "mitigated": false,
      "false_positive": false,
      "creation_date": "2026-03-19T10:00:00Z",
      "last_update_date": "2026-03-19T10:00:00Z",
      "file_path": "config/deploy.sh",
      "line_number": 42
    }
  ]
}

Campos de metadata

Campo	Tipo	Requerido	Descripción
repository_name	string	✓	Nombre del repositorio (org/repo).
branch_name	string	✓	Rama escaneada.
build_id	string	✓	Identificador del build/pipeline.
code_path	string	✓	Ruta raíz del código escaneado.
scan_type	string	—	SAST, SCA, SECRETS, IAC. Si se omite, se infiere de los findings.
commit_hash	string	—	Hash del commit escaneado.
commit_author	string	—	Autor del commit.

Campos de cada finding

Campo	Tipo	Requerido	Descripción
finding_id	string	✓	ID único del hallazgo (generado por el scanner). Usado para deduplicación.
title	string	✓	Título descriptivo.
severity	string	—	CRITICAL, HIGH, MEDIUM, LOW. Se normaliza a mayúsculas.
scan_type	string	—	SAST, SCA, SECRETS, IAC.
repository_name	string	✓	Debe coincidir con metadata.repository_name.
branch_name	string	✓	Rama del hallazgo.
build_id	string	✓	Build en el que se detectó.
code_path	string	✓	Ruta raíz del proyecto.
active	bool	✓	true si el hallazgo sigue presente.
mitigated	bool	✓	true si fue mitigado en este scan.
false_positive	bool	✓	true si está marcado como falso positivo.
creation_date	string	✓	ISO 8601.
last_update_date	string	✓	ISO 8601.
file_path	string	—	Ruta del fichero afectado.
line_number	int	—	Línea del hallazgo.
cve	string	—	CVE relacionado (p.ej. CVE-2021-44228).
cwe	string[]	—	Lista de CWEs relacionados.
description	string	—	Descripción detallada.
component_name	string	—	Componente afectado (SCA/IAC).
component_version	string	—	Versión del componente.
component_fix	string	—	Versión que corrige el problema.

Respuesta exitosa (201)

{
  "success": true,
  "message": "Findings processed successfully",
  "result": {
    "created": 3,
    "updated": 1,
    "mitigated": 0,
    "duplicates": 2
  }
}

Deduplicación

El servidor deduplica por la clave (finding_id, organization_id, repository_name, branch_name, scan_type). Si un hallazgo ya existe, se actualiza en lugar de crearse. Los findings presentes en ejecuciones anteriores pero ausentes en el payload actual se marcan como mitigados automáticamente.

Errores comunes

Código	Causa
401	JWT ausente, expirado o inválido.
403	El JWT no tiene el permiso write:findings.
422	Body con campos inválidos o faltantes.
429	Rate limit superado (30 req/s, burst 10).