> ## Documentation Index > Fetch the complete documentation index at: https://docs.corgea.app/llms.txt > Use this file to discover all available pages before exploring further. # Findings y detecciones > Qué endpoints describen la vulnerabilidad en sí y cuáles describen cómo la reportó un escaneo concreto La API describe las vulnerabilidades en dos niveles. * Una **detección** es una aparición de una vulnerabilidad en un escaneo, tal como la reportó ese escaneo: el archivo y la línea, el paquete y el CVE, o la regla de IaC. Cada escaneo genera detecciones nuevas con ids nuevos. Los endpoints del grupo **Gestión de hallazgos** (Issues) devuelven detecciones; una *incidencia* (issue) y una *detección* son lo mismo. * Un **finding** es la vulnerabilidad en sí, dentro de un proyecto y a lo largo de todos los escaneos que la detectaron. Tiene un único id que no cambia entre escaneos, y es donde vive el triaje: estado, comentario, responsable, fecha de caducidad del riesgo aceptado, fecha límite y SLA. > [!NOTE] > > **`/detections` es la misma API que `/issues`, con un nombre nuevo.** Cada endpoint del grupo **Gestión de hallazgos** (Issues) también se sirve bajo `/detections`, con el mismo código, los mismos parámetros y la misma respuesta. La llamamos `/detections` porque «issue» se confundía fácilmente con un finding: cada resultado es la detección de una vulnerabilidad en un escaneo, no la vulnerabilidad en sí. Usa `/detections` en las integraciones nuevas. `/issues` sigue siendo compatible, así que las integraciones existentes no necesitan cambios. ![Tres escaneos, cada uno con su propia detección, que apuntan a un mismo finding con la decisión de triaje](https://mintcdn.com/corgea/iJfCXTeBC6cZmqD9/images/api/findings-detections-light.es.svg?fit=max\&auto=format\&n=iJfCXTeBC6cZmqD9\&q=85\&s=335bc9915686629dead853c356cec2f3) | | Finding | Detección (incidencia) | | - | - | - | | Qué es | Una vulnerabilidad en un proyecto | Una aparición de esa vulnerabilidad en un escaneo | | Id | El mismo UUID en reescaneos, ramas y migraciones de huellas digitales | Un id nuevo en cada escaneo | | Triaje | Vive aquí | Refleja el de su finding | | Úsalo para | Sincronizar tickets, triaje masivo, métricas, «¿sigue abierta?» | Código, números de línea, correcciones, informes por escaneo | | Enlace al otro nivel | `latest_detection.id` | `finding_id` | ## Pasar de un nivel al otro Cada elemento de detección incluye el `finding_id` de su finding. Agrupa las detecciones por ese campo, nunca por `first_detection_date`, que es una propiedad del finding y no una clave. El campo solo es `null` en las detecciones ingeridas antes de que existieran los findings. Cada finding incluye `latest_detection`: su detección más reciente, con el id que aceptan los endpoints de detecciones y el localizador propio de cada familia (`file_path` y `line_number`; `path`, `package`, `version` y `cve`; o `path`, `rule_id`, `start_line` y `end_line`). Un cambio de triaje hecho en cualquiera de los dos niveles se aplica al finding y, por tanto, a todas sus detecciones. ## Qué endpoint llamar | Quieres | Llama a | | - | - | | Todo lo que reportó un escaneo, con las ubicaciones en el código | `GET /api/v1/scan/{scan_id}/detections` y las variantes de SCA, contenedores e IaC | | La explicación y la corrección de una aparición concreta | `GET /api/v1/detections/{issue_id}` | | Una fila por vulnerabilidad, filtrada por proyecto, estado o urgencia | `GET /api/v1/findings` | | Qué cambió desde tu última sincronización | `GET /api/v1/findings?status_changed_since=…` | | Vulnerabilidades cuyas detecciones se eliminaron junto con un escaneo o un proyecto | `GET /api/v1/findings?detection_state=retired` | | El estado de triaje de una vulnerabilidad | `GET /api/v1/findings/{finding_id}` | | Cambiar el estado de un conjunto de vulnerabilidades | `PATCH /api/v1/triage/findings` con `finding_ids` o una `rule` | | Cambiar el estado a través de una detección concreta; el cambio se aplica a su finding | `PATCH /api/v1/detections/{issue_id}` | ## Los endpoints de detecciones `/detections` es el nuevo nombre de los endpoints del grupo **Gestión de hallazgos** (Issues), no una API distinta. Cada uno de ellos responde bajo ambas rutas: | Ruta de issues | Ruta de detections | | - | - | | `/api/v1/issues` | `/api/v1/detections` | | `/api/v1/issue/{issue_id}` | `/api/v1/detections/{issue_id}` | | `/api/v1/issues/sca`, `/api/v1/issues/sca/{issue_id}` | `/api/v1/detections/sca`, `/api/v1/detections/sca/{issue_id}` | | `/api/v1/issues/container`, `/api/v1/issues/iac` | `/api/v1/detections/container`, `/api/v1/detections/iac` | | `/api/v1/scan/{scan_id}/issues` y sus variantes | `/api/v1/scan/{scan_id}/detections` y sus variantes | Ambas rutas ejecutan el mismo código y devuelven la misma respuesta, incluidas las claves `issues` y `total_issues`. Usa `/detections` en las integraciones nuevas; `/issues` sigue siendo compatible. ## Los endpoints de findings `GET /api/v1/findings` devuelve una fila por finding, de más reciente a más antiguo según su primera detección, paginada con `page` y `page_size` (hasta 100) y con un recuento `total_findings`. Salvo que se indique lo contrario, los filtros aceptan listas separadas por comas: | Parámetro | Valores | | - | - | | `issue_type` | `sast`, `secret`, `logic_auth`, `code_quality`, `dependency`, `container`, `iac`. Por defecto: todas las familias de seguridad que el token puede ver (todas menos `code_quality`) | | `status` | `open`, `fix_in_progress`, `accepted_risk`, `false_positive`, `fixed`, `duplicate` | | `urgency` | `CR`, `HI`, `ME`, `LO` | | `project_id` | Ids de proyecto | | `project` | Un nombre de proyecto | | `repo` | Subcadena de la URL del repositorio | | `cwe` | `CWE-79` o `79` | | `detection_state` | `active` (por defecto), `retired`, `all` | | `status_changed_since` | Fecha y hora en ISO 8601, o una fecha que se interpreta como medianoche UTC: findings cuyo triaje cambió después de ese instante | | `created_since` | Fecha y hora en ISO 8601, o una fecha que se interpreta como medianoche UTC: findings detectados por primera vez después de ese instante | | `assigned_to` | Un id de usuario | | `sort_by` | `-created_at` (por defecto), `created_at`, `urgency`, `-urgency`, `status`, `-status`, `status_changed_at`, `-status_changed_at`. `created_at` es el momento en que el finding se detectó por primera vez, el mismo instante que filtra `created_since`. No aparece en la respuesta y coincide con `first_detection_date` salvo que las detecciones más antiguas del finding se hayan eliminado con su escaneo | No existe un filtro `branch`: un finding pertenece a un proyecto, y la rama es una propiedad de sus detecciones. El token necesita el mismo permiso de visualización que la lista de detecciones de la familia; indicar una familia que no puede ver devuelve un `403`. `GET /api/v1/findings/{finding_id}` devuelve un finding con la misma estructura: sus campos de triaje, `urgency`, `classification`, `project`, `detection_state`, `first_detection_date`, `last_detection_date`, `detections_count` y `latest_detection`. ### `detection_state` Un finding está `active` mientras tenga una detección en su proyecto, y pasa a `retired` cuando su última detección se elimina junto con su escaneo o su proyecto. Un finding que un reescaneo ya no reporta no se retira: sigue `active` y su `status` pasa a `fixed`. Un finding retirado conserva su triaje, de modo que una detección que reaparece se asocia al mismo id de finding y hereda la misma decisión. > [!NOTE] > > `detection_state` es `null`, y `GET /api/v1/findings` responde `404`, hasta que el índice de findings de la cuenta esté completo. Los endpoints de detecciones y `GET /api/v1/findings/{finding_id}` no se ven afectados. ## Triaje por finding `PATCH /api/v1/triage/findings` acepta `finding_ids`: una lista de ids de finding (obtenidos de `GET /api/v1/findings` o del `finding_id` de los elementos de detección) o de ids de detección. Un id de finding equivale a la detección más reciente del finding, y la decisión alcanza a todas sus detecciones. Los ids que no resuelven a nada se devuelven en `unresolved_ids` y cuentan como no coincidentes, así que un lote con un id obsoleto aplica igualmente el resto. El triaje masivo abarca las familias SAST, secretos, lógica, calidad de código y dependencias; un id de contenedor o de IaC se devuelve en `unresolved_ids`, y las filas de auditoría indican `finding_type` como `sast` o `sca`. Una `rule` puede incluir un ámbito `statuses`, de modo que una sola llamada puede, por ejemplo, pasar a falso positivo todos los findings que hoy son riesgo aceptado. ## Un bucle de sincronización Usa el id del finding como clave del ticket. El id de una detección cambia con cada escaneo; el de un finding, no. Cada ejecución lee tres listas y escribe un lote. Todas las listas están paginadas: pide `page=1, 2, …` con `page_size=100` hasta que `page` alcance `total_pages`. Guarda la hora de inicio de la ejecución como fecha y hora ISO 8601 completa en UTC, y pásala como `` la próxima vez. 1. `GET /api/v1/findings?created_since=`: abre un ticket por cada finding nuevo. Un finding nuevo aún no tiene cambios de triaje, así que el paso 2 no lo devuelve. 2. `GET /api/v1/findings?status_changed_since=&detection_state=all`: aplica los cambios de triaje, incluidos los de findings retirados. Un finding cuyo `status` pasó a `fixed` cierra su ticket. 3. `GET /api/v1/findings?detection_state=retired`: concilia los findings retirados. La retirada no registra ninguna hora ni cambia el estado, así que ninguno de los dos cursores la devuelve. Compara esta lista completa con tus tickets abiertos y cierra o marca los que aparezcan. Si una detección reaparece, el finding vuelve a estar `active` con el mismo id. 4. `PATCH /api/v1/triage/findings` con `finding_ids`: envía a Corgea las decisiones tomadas en el sistema de tickets. Lee `unresolved_ids` incluso con un `200`. Esos ids, entre ellos todos los findings de contenedores e IaC, no se actualizaron, mientras que el resto del lote sí. Añade `issue_type` a cada llamada de lista si sincronizas findings de calidad de código, que el valor por defecto excluye. Un `404` de `GET /api/v1/findings` significa que el índice de findings de la cuenta aún no está completo, no que no haya nada que sincronizar. Vuelve a intentarlo más tarde y conserva el cursor anterior. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.