Ferret: Detecta Secretos en tus APIs Ahora

Ferret es una herramienta open-source que detecta secretos hardcodeados (API keys, tokens, credenciales de base de datos) en colecciones de Postman y archivos OpenAPI antes de que los compartas o los suba alguien a la nube. Escanea requests, headers y variables globales con patrones regex especializados, y encuentra lo que dejaste sin querer expuesto.

Ferret es una herramienta especializada para detectar secretos hardcodeados en colecciones de APIs, específicamente diseñada para Postman, OpenAPI y archivos de configuración HTTP. Desarrollada por BitsBob y publicada en GitHub, funciona como un scanner que identifica credenciales expuestas antes de que termines compartiendo tu colección con el equipo o la subas sin querer a un repositorio público.

¿Qué es Ferret y por qué detectar secretos en APIs?

Ponele que estás armando una colección Postman para tu equipo de desarrollo: requests a tu API, autenticación, variables de entorno con datos reales. Todo local, todo funciona. Compartís la colección con el equipo, alguien la sube a un repo compartido, al otro día descubrís que incluías tu API key de Stripe hardcodeada en una variable. Ahora cualquiera que acceda al repo tiene acceso a tus pagos. Así comienza el problema.

Ferret intenta evitar exactamente eso. Es una herramienta que escanea tus colecciones Postman, archivos OpenAPI y requests HTTP para encontrar credenciales expuestas antes de que terminen en lugares de los que no hay vuelta atrás. No requiere configuración complicada: apuntás a tu archivo de colección, y Ferret te dice qué encontró (si es que encontró algo).

El alcance es específico: enfocada en APIs, no en git completo. Si tu flujo es “desarrollo local con Postman” o “compartir colecciones entre equipos”, este es el punto de dolor que resuelve. GitGuardian y TruffleHog miran histórico git; Ferret mira tus archivos de configuración de APIs ahora.

El riesgo real: 23 millones de secrets expuestos

Los números no mienten (aunque a veces dan miedo). Durante 2024, Trufflesecurity detectó 23 millones de secrets en commits de GitHub, 12.8 millones de ellos en repositorios públicos. O sea: credenciales que cualquiera podía (y puede) acceder con una búsqueda simple.

¿Qué tipos de secretos? Los que te dan pesadillas: API keys de servicios de pago (Stripe, PayPal), tokens de GitHub, credenciales de bases de datos, claves privadas SSH, credenciales AWS. El coste de una sola expuesta no es menor: acceso no autorizado a datos, robo de identidad de tu servicio, facturación fraudulenta (si es un servicio de pago), exfiltración de información sensible.

Un caso concreto: el incident de DeepSeek encontró 12,000 API keys vivas y passwords en sus datos de entrenamiento. Alguien (o muchos somebodies) habían subido colecciones Postman o scripts de configuración a datasets públicos sin revisar qué contenían. Eso se ceba como malware en datos de entrenamiento IA.

El problema acá es que la mayoría de los desarrolladores NO sabe qué está adentro de sus archivos de configuración, especialmente en colecciones Postman que llevan meses evolucionar. Agregás una credencial para testear un endpoint, te olvidás que está ahí, y seis meses después compartes la colección (o alguien la descubre en un backup).

Cómo funciona Ferret: patrones regex y detección inteligente

Ferret no busca solo palabras clave como “password” o “api_key”. Usa patrones regex especializados que reconocen formatos de secrets reales: estructura de un token JWT, formato de una clave privada RSA, patrón de un AWS secret access key, sintaxis de un token Bearer. Detecta más de 50 tipos diferentes de secretos conocidos. Ya lo cubrimos antes en ejecutar herramientas de análisis sin API.

Lo importante es el segundo nivel: análisis de entropía. Incluso si ofuscás el nombre de tu variable a “xyz123”, Ferret detecta que la cadena tiene suficiente aleatoriedad como para ser un secret. No es búsqueda de palabras clave, es análisis de la estructura misma del dato.

Dónde escanea Ferret en una colección Postman:

• Headers de requests: Authorization, X-API-Key, custom headers donde metes credenciales.
• Request body: datos que envías en POST/PUT, incluyendo credenciales que pasás en el body.
• Variables globales: exactamente donde muchos metemos secretos para reutilizarlos (ojo con esto).
• Variables de environment: las que seteas por entorno (dev, staging, prod) — ahí se anida todo.
• Documentación de la colección: comentarios donde alguien documentó “poner tu token acá”.

La detección es proactiva, no reactiva. Corre cuando vos querés, en tu máquina, antes de compartir nada. No necesita conexión a internet, no sube tus datos a ningún lado. Eso es un plus importante si trabajás con información sensible.

Comparativa: Ferret vs GitGuardian, TruffleHog, Gitleaks

Acá viene el punto: no todas las herramientas de secrets scanning son iguales. Depende de dónde está el problema — si está en git, si está en tus archivos locales, si está en una colección Postman compartida. Mirá la tabla:

¿Cuándo usá cada una?

Ferret: Si tu flujo es “Postman local, compartir colecciones, no subís a git”. Es el especialista en APIs. Pre-commit hook antes de que alguien comparta la colección.

GitGuardian: Si querés monitoreo continuo SaaS. Corre en background, revisa cada commit que subes, te avisa si detecta algo. Mejor para equipos grandes con cero tolerancia a exposiciones.

TruffleHog: Si tenés repositorio viejo y necesitás audit histórico completo. Escanea todo el histórico git de una vez. También útil para escanear S3 buckets o filesystems.

Gitleaks: Si necesitás algo rápido, lightweight y open-source. Pre-commit hook simple, no requiere configuración. Menos patrones que GitGuardian, pero suficiente para 80% de los casos.

En la práctica: muchos equipos usan Ferret O Gitleaks en pre-commit local, y GitGuardian en CI/CD para segunda línea de defensa. No es exclusión mutua. Para más detalles técnicos, mirá diferencias de seguridad en plataformas de código.

Casos de uso reales: dónde se exponen los secretos

Acá vamos a algo que la mayoría vive pero no comenta mucho.

Caso 1: El desarrollador que compartió la colección Postman con credenciales de Stripe. Creó una colección para testear pagos, metió el API key vivo en una variable global (para no acordarse de cambiar cada request), la exportó, la compartió por Slack al equipo de QA. Al mes, la colección termina en un backup de alguien más, alguien la sube a un repo, un bot malicioso la encuentra. Al otro día, Stripe te notifica dos cargos sospechosos. El costo: cientos de dólares en fraude, más el tiempo de remediación.

Caso 2: Variables de ambiente en git (accidente clásico). Alguien pushea un `.env.local` con credenciales AWS por error. No lo ve nadie (repo privado, pequeño equipo), pero está ahí. Un exemployado tiene acceso al histórico del repo, baja el `.env` viejo, accede a tu RDS sin problemas. Semanas después descubrís acceso no autorizado en logs.

Caso 3: Documentación con ejemplos. Un endpoint en Postman tiene comentario/descripción que dice “usar token: ghp_xyz123xyz123”. Alguien ve la documentación (copiloto, reviewer, outsider con acceso) y usa el token sin permiso.

Caso 4: Colección sincronizada con cloud sin cifrar. Postman Cloud sync habilitado, colección local tiene credenciales, la sincronización sube todo a los servidores de Postman. Si tu cuenta Postman se compromete, todas tus credenciales van con ella.

El patrón es siempre el mismo: credenciales en el lugar equivocado, circulan más de lo que pensás, alguien malintencionado (o curioso) las encuentra y las usa.

Integración en tu workflow DevSecOps

Instalar Ferret es sencillo. Está en PyPI y GitHub:

• pip install ferret-secrets (si usás Python)
• O descargá el ejecutable desde GitHub BitsBob/ferret
• O clonás el repo y ejecutás `python main.py`

Una vez instalado, la integración viene en tres niveles:

Nivel 1: Pre-commit hook local. Antes de que hagas commit, Ferret escanea los cambios. Si encuentra algo, el commit se bloquea. Configurás en `.git/hooks/pre-commit` una llamada a Ferret. Boomtown: nada sale de tu máquina.

Nivel 2: CI/CD pipeline (GitHub Actions, GitLab CI, Jenkins). Cada push a main o PR dispara Ferret automáticamente. Si encuentra secretos, falla el check. No mergea nada hasta que los secretos se resuelvan. Aquí es donde atrapás lo que se escapó del pre-commit.

Nivel 3: Escaneo programado (nightly o semanal). Una tarea que corre cada noche, escanea todo el repo (o colecciones Postman guardadas), te envia un reporte por Telegram o Slack. Detecta exposiciones históricas. Tema relacionado: herramientas automatizadas para auditoría de seguridad.

Configuración básica de GitHub Actions:

• Creás un `.github/workflows/ferret-scan.yml`
• Configurás para correr en `push`, `pull_request`
• Comando: `ferret scan –path . –report json`
• Si encuentra secretos, la acción falla y bloquea el merge

El tema acá es la frecuencia. Si solo lo hacés pre-commit, alguien que deshabilite hooks termina pasándose algo. Si lo hacés en CI/CD, atrapás casi todo. Si lo hacés nightly, tenés auditoría histórica.

Mejores prácticas: más allá de la detección

Detectar secretos es la primera línea de defensa. Pero la mejor defensa es no tenerlos ahí desde el principio.

Regla 1: .env para secrets locales, nunca en archivos que subes. Postman (si necesitás credenciales reales locales) debería leer de un `.env.local` que vos mismo creás y agregás a `.gitignore`. Postman Vault (feature integrada) copia las credenciales en runtime, no las guarda en JSON.

Regla 2: Rotate credenciales si las exponés. Detectaste una API key? No solo borrás el archivo. Regenerás la clave en el servicio (Stripe, AWS, lo que sea). Si no la rotás, está expuesta igual.

Regla 3: Secrets manager en serio. Para producción usá herramientas como HashiCorp Vault, AWS Secrets Manager o Azure Key Vault. Tu código nunca ve credenciales en texto plano. Pide la credencial al servicio, la recibe cifrada, la usa, listo. Es un paso más pero vale cada segundo si trabajás con datos críticos.

Regla 4: Educación de equipo. El mejor scanner no te salva si el desarrollador siguiente no sabe qué está haciendo. Una charla de 15 minutos sobre “dónde van los secretos y dónde no” evita 90% de los problemas. Enseñá: “si codeás una credencial, revisá antes de pushear” (ojo con esto), “Postman Cloud sync está habilitado? Deshabilitá si tenés creds locales”.

Regla 5: Audit log. Cuando alguien accede a un secreto, que quede registrado. No siempre Ferret cubre esto, pero si usás Vault o Secrets Manager, sí. Te ayuda a investigar si se comprometió algo.

Errores comunes al usar Ferret (y herramientas similares)

Error 1: Ignorar falsos positivos sin revisar. Ferret a veces marca cosas que no son secrets (un UUID largo, una hash de contraseña hasheada, una clave de ejemplo que es obviamente fake). Algunos desarrolladores la ignoran todas y crean un `.ferretignore`. Eso es peligroso. Mejor revisá cada match, aunque sea un segundo, antes de decidir “ignorar”.

Error 2: No integrar en pre-commit. Tener Ferret instalado pero no en pre-commit es como tener un detector de humo que nunca mirás. Configuralo una sola vez (5 minutos) y te salva meses de auditorías. Si solo lo usás cuando te acordás, es inútil. Esto se conecta con lo que analizamos en dónde almacenar código con mayor seguridad.

Error 3: Subir colecciones Postman a control de versión sin .gitignore. Tus colecciones locales con credenciales terminarán en git. Agregá `*.postman_collection.json` (o lo que uses) a `.gitignore` si incluyen secretos. Exportá sin credenciales para compartir con el equipo.

Error 4: Confiar solo en Ferret y olvidarse de otros niveles. Ferret es una herramienta, no una solución completa. Usala con Postman Vault, Secrets Manager, rotación de credenciales, auditoría, educación. No es una varita mágica.

Error 5: No revisar el histórico git. Subiste un secreto hace 6 meses accidentalmente. Ferret hoy detecta la rama actual, pero el histórico tiene el secret. Usa TruffleHog o `git-secrets` para auditar histórico antes de hacer público el repo.

Preguntas Frecuentes

¿Cuál es la diferencia entre Ferret y GitGuardian?

Ferret escanea archivos locales (especialmente Postman y OpenAPI). GitGuardian monitorea repositorios git continuamente en el cloud. Ferret es offline y gratuito. GitGuardian es SaaS pagado pero cubre 200+ tipos de secretos y tiene alertas en tiempo real. Usá Ferret antes de compartir, GitGuardian en CI/CD para segunda línea.

¿Postman tiene una solución integrada para detectar secretos?

Sí. Postman tiene el Secret Scanner integrado en planes pagados, que escanea colecciones y detecta credenciales. Pero también tiene el Vault, que cifra credenciales en runtime. Si tu Postman es pagado, te recomiendo habilitar ambas cosas. Si es gratis, usá Ferret.

¿Ferret detecta tokens de GitHub?

Sí, detecta tokens de GitHub (formato `ghp_` o `gho_`), como así también AWS keys, API keys de Stripe, credenciales de base de datos y más de 50 formatos diferentes. Usa patrones regex que reconocen la estructura real de cada tipo de secret.

¿Puedo integrar Ferret en mi CI/CD actual (Jenkins, GitLab, GitHub Actions)?

Absolutamente. Ferret es CLI, así que cualquier sistema de CI/CD que execute comandos puede usarlo. GitHub Actions: agregás un paso `run: ferret scan`. GitLab: lo mismo en `.gitlab-ci.yml`. Jenkins: lo mismo en el Jenkinsfile. Si falla el scan, el job falla y bloquea el merge. Es el uso más común para equipos.

¿Qué pasa si descubro un secreto expuesto después de usarlo meses?

Regenerá la credencial inmediatamente en el servicio (revocar la API key, rotar la contraseña, cambiar el token). Revisa logs del servicio para ver si se usó sin autorización. Escanea tu histórico git con TruffleHog para ver cuánto tiempo estuvo expuesto. Notifica al equipo de seguridad si fue credencial crítica. Es incómodo pero evita daño mayor.

Conclusión

Ferret es una herramienta pequeña, especializada, que resuelve un problema muy específico: evitar que compartas credenciales hardcodeadas en colecciones Postman. No es perfecta (falsos positivos, necesita mantenimiento), pero es gratis, open-source, y te salva de dolores de cabeza reales.

El contexto es importante: 23 millones de secrets expuestos en 2024, equipos que no saben qué hay dentro de sus colecciones Postman, un único secret comprometido que abre acceso a datos críticos. Ferret corre antes de que todo eso suceda.

La mejor práctica es combinarla con otras defensas: Postman Vault, Secrets Manager, rotación de credenciales, pre-commit hooks, CI/CD checks, auditoría histórica, educación de equipo. No es un reemplazo de lo demás, es una capa más. (Y ojo con esto: automatizar lo máximo posible. Si lo dejás manual, la gente se saltea pasos.)

Si desarrollás APIs y usás Postman, agregá Ferret a tu flujo. Cinco minutos de configuración ahora te ahorran semanas de auditoría después.

Fuentes

• Ferret – Open Source Secrets Scanner en GitHub
• Trufflesecurity – 12,000 API keys encontradas en datos de entrenamiento de DeepSeek
• GitGuardian – Comparativa de herramientas de Secret Scanning
• Postman Secret Scanner – Documentación oficial
• GitGuardian – Soluciones de Secrets Scanning