El Escáner de Secretos detecta posibles claves de API, tokens de acceso, credenciales, URLs de webhook y otros valores sensibles en los activos compatibles de Apidog. Los hallazgos muestran dónde aparece un posible secreto sin mostrar su valor completo.
Este tutorial explica cómo revisar un hallazgo, responder a una exposición real, registrar la resolución y añadir un patrón de detección personalizado cuando tu equipo utiliza un formato de secreto interno.
Antes de empezar
El Escáner de Secretos está disponible en el plan Enterprise SaaS. Actualmente no está disponible en Apidog On-Premises.
El acceso depende de tu rol:
| Rol | Acciones disponibles |
|---|---|
| Propietario o Administrador de la Organización | Ver informes a nivel de organización para todos los equipos |
| Propietario o Administrador de Equipo | Revisar hallazgos de equipo, resolver o reabrir hallazgos, gestionar patrones personalizados y ver análisis |
| Miembro de Equipo o Invitado | Ver hallazgos solo para proyectos a los que tienen acceso |
Usa valores ficticios al realizar pruebas. Nunca pegues una credencial real en un recurso simplemente para confirmar que el escaneo funciona.
Paso 1: Revisar el informe de la organización
Los Propietarios y Administradores de la Organización pueden usar el informe de la organización para identificar equipos con hallazgos no resueltos.
- Abre el informe de Escáner de Secretos a nivel de organización.
- Revisa los recuentos de hallazgos no resueltos y fugas publicadas.
- Verifica la última hora de detección y el estado del escaneo.
- Abre el equipo afectado o contacta a su Propietario o Administrador de Equipo.
El informe de la organización ayuda a los administradores a identificar qué equipos requieren seguimiento.
El informe es una vista de clasificación. La investigación y resolución tienen lugar en las páginas del Escáner de Secretos del equipo afectado.
Paso 2: Abrir y filtrar los hallazgos del equipo
En el equipo, abre Escáner de Secretos y selecciona Secretos Detectados.
Usa los filtros disponibles para acotar la lista por:
- estado
- proyecto
- patrón
- tipo de recurso
- palabra clave
Cada hallazgo se agrupa por su patrón de detección y una huella digital segura. Un hallazgo puede tener varias ocurrencias cuando el mismo valor detectado aparece en más de una ubicación.
Los valores están enmascarados. Usa el proyecto, el tipo de recurso, el recuento de ocurrencias y la ubicación de origen para investigar el hallazgo.
Empieza con los hallazgos no resueltos marcados como exposición publicada, luego revisa los hallazgos que aparecen en varios recursos o proyectos.
Paso 3: Inspeccionar cada ocurrencia
Abre un hallazgo y revisa sus ocurrencias. Para cada ocurrencia, confirma:
- el proyecto y el recurso que contienen el valor
- el tipo de recurso y la ubicación de origen
- si el valor aparece en la documentación publicada
- la primera y la última vez detectada
- si el valor es una credencial real o un falso positivo
No te fíes solo del fragmento enmascarado al decidir si un valor es real. Revisa el recurso de origen y, cuando sea necesario, pide al propietario del recurso que identifique el sistema emisor sin copiar la credencial en un ticket o mensaje de chat.
Paso 4: Responder a una exposición real
El Escáner de Secretos informa de posibles exposiciones; no cambia la credencial. Maneja un secreto confirmado en el sistema donde fue emitido.
Usa este orden:
- Revoca, rota o invalida la credencial en el servicio externo.
- Revisa los registros de uso disponibles en busca de actividad inesperada.
- Elimina el valor de cada ocurrencia de origen mostrada en Apidog.
- Reemplaza el valor bruto con una variable apropiada o una referencia de Secreto de Vault cuando el flujo de trabajo aún necesite la credencial.
- Guarda cada recurso modificado para que un escaneo asíncrono pueda ejecutarse de nuevo.
Si la credencial aparece en la documentación publicada, trátala como expuesta externamente, incluso si no se observa un uso sospechoso.
Eliminar un valor de Apidog no invalida las copias que ya puedan existir en otros lugares. La rotación o revocación es la acción de contención principal para una fuga real.
Paso 5: Registrar la resolución
Una vez completada la respuesta, establece la razón de resolución del hallazgo.
| Razón de resolución | Úsala cuando |
|---|---|
| Revocado | El valor era un secreto real y ha sido revocado, rotado o invalidado fuera de Apidog |
| Falso positivo | El valor detectado no es un secreto |
| No se corregirá | El valor es un secreto real, pero el equipo ha aceptado el riesgo y no lo cambiará |
Marcar un hallazgo como resuelto solo cambia su estado en Apidog. No revoca, rota, invalida, elimina ni reemplaza el valor subyacente.
Si se hace necesaria una acción adicional, reabre el hallazgo.
Paso 6: Verificar la limpieza
El Escáner de Secretos se ejecuta de forma asíncrona en lugar de en tiempo real. Los escaneos se activan cuando se añade un recurso compatible o cuando se selecciona Guardar después de que se modifica un recurso compatible.
Después de la remediación:
- confirma que todas las ocurrencias de origen conocidas fueron modificadas
- guarda los recursos afectados
- espera un tiempo para el escaneo asíncrono
- revisa el hallazgo y su última hora de detección
- confirma por separado que la antigua credencial ya no funciona en el servicio emisor
El estado del escáner no es una prueba de validez de credenciales. Verifica la revocación en el servicio externo.
Paso 7: Añadir un patrón de detección personalizado
Los Propietarios y Administradores de Equipo pueden crear patrones personalizados para formatos de secreto específicos de la organización.
- Abre Escáner de Secretos > Patrones.
- Selecciona la opción para crear un patrón personalizado.
- Introduce un nombre claro.
- Añade la expresión regular y cualquier palabra clave útil.
- Prueba con un valor ficticio.
- Habilita el patrón y guárdalo.
Los límites actuales son:
- hasta 5 patrones personalizados por equipo;
- nombre del patrón de hasta 128 caracteres;
- expresión regular de hasta 256 caracteres en la interfaz de usuario;
- hasta 10 palabras clave;
- cada palabra clave de hasta 64 caracteres.
Los patrones incorporados son de solo lectura. Sus expresiones regulares internas no se muestran y no pueden ser editadas, eliminadas, habilitadas o deshabilitadas.
Paso 8: Revisar los análisis del equipo
Los Propietarios y Administradores de Equipo pueden abrir Análisis para revisar dónde se concentran los hallazgos.
Usa los análisis para identificar proyectos, patrones y tipos de activos que necesitan una revisión adicional.
Los análisis pueden ayudar a priorizar el trabajo, pero cada hallazgo aún requiere una investigación a nivel de origen.
Tipos de activos compatibles
El Escáner de Secretos actualmente escanea activos compatibles que incluyen:
- APIs y solicitudes de API
- casos de API
- módulos de proyecto y variables de módulo de proyecto
- ejemplos de respuesta
- documentos Markdown y esquemas de datos
- variables de entorno, globales y de equipo
- scripts comunes y parámetros comunes
El detalle de origen disponible para una ocurrencia depende de su tipo de recurso y de los permisos del visor.
Resolución de problemas
| Problema | Qué revisar |
|---|---|
| Un cambio reciente aún no tiene resultado | El escaneo es asíncrono. Confirma que el recurso fue guardado y revísalo de nuevo más tarde. |
| Un miembro del equipo no puede ver un hallazgo | Confirma que el miembro tiene acceso al proyecto relacionado. |
| Un usuario no puede gestionar patrones o análisis | La gestión de patrones y los análisis requieren acceso de Propietario o Administrador de Equipo. |
| Un hallazgo resuelto aún contiene un secreto funcional | El estado de resolución no altera la credencial. Revócala o rótala en el servicio emisor. |
| Un repositorio externo no es escaneado | El Escáner de Secretos no escanea repositorios externos de GitHub o GitLab. Usa también los controles de escaneo del proveedor del repositorio. |
Limitaciones importantes
El Escáner de Secretos no impide que los usuarios ingresen secretos, bloquee la publicación de documentación, escanee repositorios externos ni garantiza la detección de cada formato de secreto. Tampoco elimina automáticamente los valores de origen ni los reemplaza con variables o referencias de Vault.
Úsalo como parte de un proceso de gestión de credenciales que también incluye la emisión con el mínimo privilegio, almacenamiento seguro, rotación, revocación y monitoreo de uso.
Tutoriales relacionados sobre gobernanza de API:
Estos tutoriales cubren controles complementarios para gobernar un espacio de trabajo de API empresarial:
- Marco de Gobernanza de API — conecta la propiedad, los controles, la evidencia y las decisiones del ciclo de vida.
- Mapeo de Grupos SAML con Microsoft Entra ID — asigna acceso de equipo desde grupos de proveedores de identidad.
- Escáner de Secretos — revisa posibles credenciales expuestas en activos compatibles de Apidog.
- Registros de Auditoría — investiga y exporta la actividad administrativa de la organización.
- Aprovisionamiento SCIM — gestiona usuarios de la organización a través del ciclo de vida de la identidad.
- Políticas Empresariales — configura controles de credenciales, membresía, sesiones SSO e invitaciones.
- Equipos de API de autoservicio gobernados — permite equipos creados por miembros mientras se mantiene la supervisión de la propiedad.
- Integración de GitHub Enterprise Cloud — conecta repositorios GHE.com compatibles para flujos de trabajo OpenAPI.
Documentación oficial relacionada: