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.

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). |