Cómo revisar y remediar hallazgos del Escáner de Secretos en Apidog
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 indican 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 personalizado para formatos de secretos internos.
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 del equipo, resolverlos o reabrirlos, gestionar patrones personalizados y ver análisis |
| Miembro de Equipo o Invitado | Ver hallazgos únicamente de los proyectos a los que tienen acceso |
Usa valores ficticios durante las pruebas. Nunca pegues una credencial real en un recurso solo para confirmar que el escaneo funciona.
1. Revisa el informe de la organización
Los Propietarios y Administradores de la Organización pueden usar el informe para identificar equipos con hallazgos sin resolver.
- Abre el informe del Escáner de Secretos a nivel de organización.
- Revisa los recuentos de hallazgos no resueltos y exposiciones publicadas.
- Comprueba 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 sirve para clasificar y priorizar. La investigación y resolución se realizan en las páginas del Escáner de Secretos del equipo afectado.
2. Abre y filtra los hallazgos del equipo
En el equipo, abre Escáner de Secretos y selecciona Secretos Detectados.
Filtra la lista por:
- estado
- proyecto
- patrón
- tipo de recurso
- palabra clave
Cada hallazgo se agrupa por patrón de detección y huella digital segura. Un mismo hallazgo puede tener varias ocurrencias si el valor detectado aparece en más de una ubicación.
Los valores están enmascarados. Usa el proyecto, el tipo de recurso, el número de ocurrencias y la ubicación de origen para investigar.
Empieza por los hallazgos no resueltos marcados como exposición publicada. Después, revisa los que aparecen en varios recursos o proyectos.
3. Inspecciona cada ocurrencia
Abre el hallazgo y revisa todas sus ocurrencias. 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 documentación publicada;
- la primera y la última vez que fue detectado;
- si es una credencial real o un falso positivo.
No decidas basándote únicamente en el fragmento enmascarado. Revisa el recurso de origen y, si es necesario, pide al propietario que identifique el sistema emisor. No copies la credencial en un ticket ni en un mensaje de chat.
4. Responde a una exposición real
El Escáner de Secretos informa de posibles exposiciones, pero no modifica ni invalida la credencial. Gestiona el secreto en el sistema donde fue emitido.
Sigue este orden:
- Revoca, rota o invalida la credencial en el servicio externo.
- Revisa los registros de uso disponibles para detectar actividad inesperada.
- Elimina el valor de cada ocurrencia de origen mostrada en Apidog.
- Si el flujo aún necesita la credencial, reemplaza el valor bruto por una variable o una referencia de Secreto de Vault.
- Guarda cada recurso modificado para permitir un nuevo escaneo asíncrono.
Si la credencial aparece en documentación publicada, trátala como expuesta externamente, aunque no observes un uso sospechoso.
Eliminar un valor de Apidog no invalida las copias que puedan existir en otros lugares. La rotación o revocación es la acción principal de contención ante una fuga real.
5. Registra la resolución
Después de completar 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 fue 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 acepta 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 necesita una acción adicional, reabre el hallazgo.
6. Verifica la limpieza
El Escáner de Secretos funciona de forma asíncrona, no en tiempo real. Los escaneos se activan cuando se añade un recurso compatible o cuando seleccionas Guardar después de modificarlo.
Después de aplicar la remediación:
- confirma que modificaste todas las ocurrencias de origen conocidas;
- guarda los recursos afectados;
- espera a que finalice el escaneo asíncrono;
- revisa el hallazgo y su última hora de detección;
- confirma por separado que la credencial anterior ya no funciona en el servicio emisor.
El estado del escáner no demuestra que una credencial sea válida o inválida. Verifica siempre la revocación en el servicio externo.
7. Añade un patrón de detección personalizado
Los Propietarios y Administradores de Equipo pueden crear patrones personalizados para formatos de secretos 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 las palabras clave relevantes.
- Prueba el patrón con un valor ficticio.
- Habilítalo y guárdalo.
Límites actuales:
- hasta 5 patrones personalizados por equipo;
- nombres de hasta 128 caracteres;
- expresiones regulares de hasta 256 caracteres en la interfaz;
- hasta 10 palabras clave;
- palabras clave de hasta 64 caracteres cada una.
Los patrones incorporados son de solo lectura. Sus expresiones regulares internas no se muestran y no pueden editarse, eliminarse, habilitarse ni deshabilitarse.
8. Revisa 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 requieren una revisión adicional.
Los análisis ayudan a priorizar el trabajo, pero cada hallazgo todavía requiere una investigación a nivel de origen.
Tipos de activos compatibles
Actualmente, el Escáner de Secretos analiza 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 depende del 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 se guardó y vuelve a revisarlo más tarde. |
| Un miembro del equipo no puede ver un hallazgo | Confirma que tiene acceso al proyecto relacionado. |
| Un usuario no puede gestionar patrones o análisis | Estas funciones requieren permisos de Propietario o Administrador de Equipo. |
| Un hallazgo resuelto aún contiene un secreto funcional | El estado de resolución no modifica la credencial. Revócala o rótala en el servicio emisor. |
| Un repositorio externo no es escaneado | El Escáner de Secretos no analiza 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 introduzcan secretos;
- no bloquea la publicación de documentación;
- no analiza repositorios externos;
- no garantiza la detección de todos los formatos de secretos;
- no elimina automáticamente los valores de origen;
- no reemplaza los valores por variables ni referencias de Vault.
Úsalo como parte de un proceso de gestión de credenciales que incluya 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 durante todo el 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 crear equipos 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
-&utm_medium=wanda&utm_content=n8n-post-automation)
Top comments (0)