Sift Secrets

Triaje de exposición de credenciales y datos sensibles para recursos compartidos de archivos.

Cuando aparece un recurso compartido abierto, la pregunta nunca es "¿este repositorio tiene una clave filtrada". Es "¿qué se ha expuesto y qué tengo que rotar antes del cierre del día?" sift está construido para esa pregunta: alta exhaustividad, una cola de revisión rápida, y un bucle de retroalimentación para que cualquier cosa que detectes a simple vista se convierta en una regla que encuentre las otras doscientas copias.

Python 3.11+, solo biblioteca estándar. Sin pip install, sin internet, sin paso de compilación. Se ejecuta en un portátil de IR bloqueado, que es donde lo necesitas.```bash sift survey \fileserver\openshare # how big is this thing sift copy \fileserver\openshare C:\IR\case-4471 # take a throttled copy sift scan C:\IR\case-4471 # scan it, opens the triage UI

Escanear en el lugar también funciona. Pruébelo primero en un recurso compartido de credenciales fabricadas:```bash
sift demo C:\temp\demoshare

sift.cmd es un lanzador que funciona desde cualquier directorio. Para escribir sift en lugar de la ruta completa, añade C:\Dev\sift a PATH:```bash setx PATH "%PATH%;C:\Dev\sift"

Para una máquina sin Python en absoluto, `python build_portable.py` genera
`dist/sift-secrets-<version>-portable-win64.zip`: el runtime embebible oficial de python.org
más este árbol de fuentes, listo para descomprimir y ejecutar mediante el
`sift.cmd` incluido. ~11 MB, sin instalación, sin derechos de administrador, y nada en él está
compilado ni reempaquetado — consulta el docstring en `build_portable.py` para saber por qué
eso supera a un .exe congelado en un portátil de IR bloqueado.

---

## Por qué no simplemente gitleaks o trufflehog

Ambas son buenas herramientas que resuelven un problema distinto.

Son herramientas de **precisión** creadas para CI, donde un falso positivo le cuesta a un
desarrollador toda la tarde, así que disparan principalmente sobre cosas con forma de
clave API de un proveedor conocido. trufflehog va más allá y prefiere secretos que puede
*verificar* llamando a la API del proveedor, lo cual es una señal genuinamente excelente que
el regex no puede reproducir.

El triaje de recursos compartidos invierte la ecuación. Un humano ya está leyendo cada
resultado, así que un falso positivo cuesta tres segundos. Lo que te cuesta es un **falso negativo**.

Las claves API de proveedores definitivamente se filtran en los recursos compartidos: una
copia de seguridad de la raíz web, un script de despliegue, la carpeta de proyecto de alguien
copiada a la unidad departamental, y hay un `.env` con una clave de Stripe activa dentro.
Esos casos merecen detectarse, y sift los detecta. Pero también son la parte que gitleaks y
trufflehog ya manejan bien. El hueco está en todo lo demás, y en un recurso compartido es la
mayor parte:

| Lo que los escáneres de CI pasan por alto | Por qué lo ignoran |
|---|---|
| `web.config` con una cadena de conexión SQL | No es un formato de clave conocido, no hay proveedor contra el que verificar |
| `Map-Drives.ps1` con `net use ... /user:` | Solo un comando de shell con una palabra detrás |
| `New Hire Setup Guide.docx` | Archivo de Office, leído como binario, omitido por completo |
| `unattend.xml`, GPP `Groups.xml` | Artefactos de despliegue de Windows para los que nadie escribió un detector |
| `confCons.xml`, `.rdg`, WinSCP.ini | Contraseñas almacenadas de forma reversible, pero no un "formato de secreto" |
| `passwords.xlsx` | Es un ZIP. Los escáneres de texto plano ven binario y continúan |
| `.kdbx`, `.pfx`, `id_rsa` | Bytes opacos: el *nombre de archivo* es el hallazgo |
| Un `.bak` con una cadena de conexión dentro | Binario, por lo que nunca se lee |

sift cubre esos casos, incluye sus propias reglas de claves de proveedor e **importa los
paquetes de reglas y hallazgos de otras herramientas** — TOML de gitleaks, YAML de
Kingfisher/Titus y JSON de trufflehog — para que no tengas que elegir entre herramientas.

El trabajo previo más cercano es [Snaffler](https://github.com/SnaffCon/Snaffler), que es
excelente en la mitad de nombres de archivo y clasificación de esto y es la inspiración
directa de las reglas de nombres de archivo. Lo que no tiene — y lo que resulta ser el
auténtico cuello de botella cuando tienes 400 hallazgos — es un bucle de revisión.

---

## El bucle

1. **Escanea** el recurso compartido.
2. **Trabaja la cola.** Cada hallazgo muestra sus líneas circundantes con la coincidencia
   resaltada. Las teclas de flecha amplían el contexto; un clic abre el archivo completo en
   VS Code en esa línea, o en Notepad.
3. **Detecta un fallo.** Lo harás. Resáltalo en la vista previa y pulsa `r`.
4. **sift propone patrones** y te dice en vivo cuántas veces coincidiría cada uno con todo
   lo ya leído.
5. **Guárdalo.** El re-escaneo en caché tarda aproximadamente un segundo, y los nuevos
   hallazgos aparecen en la cola con tus decisiones de triaje intactas.

El paso 5 es la parte que hace que el resto valga la pena. Los hallazgos se identifican por
`(path, rule, line, value-hash)`, así que un re-escaneo vuelve a insertar las mismas filas y tu
estado, notas y propietario se mantienen. Sin eso, tendrías que revisar de nuevo los mismos
300 hallazgos en cada iteración y abandonarías en la tercera.

---

## Comandos```bash
# size it up first: file count, total bytes, biggest folders, transfer estimates
sift survey \\fileserver\share

# take a rate-limited local copy (resumable; gentle = 5 MB/s by default)
sift copy \\fileserver\share C:\IR\case-4471 --speed gentle

# scan a share and open the triage UI
sift scan \\fileserver\share

# maximum recall: more noise, but a human is reading anyway
sift scan D:\dfs\dept --tier 3

# re-open the UI over the most recent scan
sift ui

# build a share of fabricated credentials, scan it, open the UI
sift demo C:\temp\demoshare

# inherit other tools' vendor-key rules, then use them in the live rescan loop
sift import-rules gitleaks.toml                    # gitleaks TOML
sift import-rules path/to/kingfisher/data/rules    # a directory of YAML

# pull in what the other scanners found, into the same queue
trufflehog filesystem \\fileserver\share --json > th.json
sift import-findings th.json

# hand off to the incident record (redacted unless you say otherwise)
sift export --fmt pdf --status confirmed --out ir-4471.pdf
sift export --fmt csv --out ir-4471.csv
sift export --fmt pdf --no-redact       # plaintext; handle as evidence

sift rules                              # what is loaded
sift selftest                           # detection tests against a synthetic share

# ask vendors whether confirmed findings are still live. NETWORK. Opt-in.
sift validate --status confirmed

Anywhere sift appears you can use python -m sift instead, from the C:\Dev\sift directory.

Opciones que vale la pena conocer

Dónde vive el estado

Los hallazgos van a una carpeta por objetivo bajo %LOCALAPPDATA%\sift\, nunca al directorio de trabajo: la base de datos contiene credenciales en texto plano, y ejecutar la herramienta desde el directorio personal no debería dejar una ahí sin aviso. Cada recurso compartido tiene su propio almacén, de modo que dos operaciones nunca comparten una cola de triaje. sift ui sin argumentos reabre el más reciente; --data DIR lo anula.

Las reglas personalizadas son globales, en %LOCALAPPDATA%\sift\user-rules.json, de modo que un patrón que escribas durante una operación te ayuda en el siguiente recurso compartido que examines.

Antes de escanear: examinar y adquirir

Ambos están en la cabecera de la interfaz, junto al cuadro de ruta, y en la CLI.

Comprobar tamaño es un recorrido solo de stat. No se abre nada, por lo que es barato incluso a través de SMB, y te indica el número de archivos, los bytes totales, las carpetas más grandes, el desglose por extensión, cuánto leería realmente sift y cuánto tardaría una copia a cada velocidad. Apuntar un escáner a una raíz DFS desconocida y esperar es así como desaparece una tarde.

Copiar localmente baja primero el recurso compartido a una carpeta local. Merece la pena porque:

• escanear una copia local es mucho más rápido que miles de idas y vueltas SMB;
• es repetible, de modo que añadir una regla y volver a escanear no vuelve a martillar el servidor de archivos;
• el original no se toca, que es la diferencia entre "lo miramos" y "lo preservamos" si el incidente llega al ámbito legal.

La transferencia está limitada en velocidad, con un valor predeterminado de 5 MB/s. Saturar el enlace a un servidor de archivos de producción a las 2 de la tarde convierte tu investigación en un segundo incidente. Auméntala cuando sepas que la ruta está inactiva.

Las transferencias se reanudan: se omite un archivo de destino con el mismo tamaño y mtime, de modo que una adquisición interrumpida al 80% continúa donde se detuvo. Los archivos bloqueados o denegados se registran y se omiten en lugar de abortar la ejecución.

Informes

PDF, CSV, MD y JSON, desde la cabecera de la interfaz o sift export --fmt.

El PDF es el que se entrega para el registro del incidente: una portada con el objetivo, totales por severidad y estado de triaje, las reglas más frecuentes, valores reutilizados entre archivos y, después, los hallazgos agrupados por severidad. Se genera directamente, sin librería PDF, por lo que funciona en una máquina que nunca ha visto pip.

Las exportaciones están enmascaradas por defecto. Los valores se enmascaran, cada página lleva una marca de banner, y el endpoint solo desactiva el enmascarado con un redact=0 explícito: una solicitud truncada o malformada no puede filtrar nada. Desactivar el enmascarado en la interfaz requiere confirmar un diálogo de advertencia, y el archivo resultante lleva la marca de banner UNREDACTED - CONTAINS PLAINTEXT CREDENTIALS en cada página.

La base de datos de hallazgos sigue guardando los valores reales, porque un analista necesita saber qué contraseña se filtró para saber qué rotar. El límite es lo que sale de la herramienta.

Trabajando con la cola

Todo es clicable. El control ordenar en la parte superior de la lista de resultados reordena por severidad, ruta de archivo, regla, estado de triaje o más reciente, con un botón para invertir el orden. Las facetas de la barra lateral filtran por severidad, categoría, regla y valor reutilizado. El triaje, la expansión de contexto, abrir un archivo y crear reglas son todo botones.

Los atajos de teclado siguientes son aceleradores para una cola larga, no la única forma de manejarla.

El botón instantánea convierte el fragmento resaltado en un PNG para pegarlo en un ticket de incidente; copiar fragmento hace lo mismo como markdown.

Seguridad

La interfaz muestra credenciales en texto plano en vivo en una ventana del navegador, por lo que:

• se vincula solo a 127.0.0.1 y rechaza cualquier otra cosa sin --unsafe-bind;
• requiere un token aleatorio por lanzamiento, entregado en la URL de lanzamiento y guardado después en una cookie SameSite=Strict;
• valida la cabecera Host, de modo que una página hostil no pueda hacerle DNS rebinding;
• envía una CSP sin orígenes externos en absoluto: nada en la página puede exfiltrar lo que muestra;
• se niega a leer o abrir cualquier ruta que no esté ya en la base de datos de hallazgos, de modo que /api/context no es una lectura arbitraria de archivos y /api/open no es un lanzamiento arbitrario de procesos.

La base de datos de hallazgos contiene credenciales en texto plano por diseño: un analista de IR necesita saber qué contraseña se filtró para saber qué rotar. Trata %LOCALAPPDATA%\sift\<target>\findings.db como evidencia: mismo manejo que el propio recurso compartido, y elimínala cuando la operación se cierre. Usa --redact si va a salir del perímetro del incidente.

Y la obvia: ejecuta sift solo contra sistemas en los que estés autorizado a acceder.

Cómo están organizadas las reglas

sift/rules_builtin.py - reglas de contenido. sift/rules_filename.py - reglas de nombres de archivo. Ambos son Python plano con patrones de cadena cruda, por lo que son legibles y comparables mediante diff; las reglas de usuario viven en JSON en .sift/user-rules.json.

Tres niveles te permiten intercambiar precisión por exhaustividad:

• Nivel 1 - inequívocos. Formatos de claves de proveedor, bloques PEM, cpassword de GPP, volcados NTLM, contraseñas de bind de LDAP. La forma por sí sola es prueba.
• Nivel 2 (por defecto) - reglas de proximidad. "Una palabra parecida a secreto cerca de un valor." Ahí vive la mayor parte de la exposición real en recursos compartidos.
• Nivel 3 - cadenas de alta entropía sin etiquetar, hex largo, IBANs. Ruidosos, pero cuando estás delimitando el alcance de una brecha prefieres leer 400 coincidencias que perderte una.

Una regla también puede llevar min_digits, min_lowercase, min_uppercase y min_special, de modo que una sola regla ruidosa puede ajustarse sin tocar el resto, y examples - cadenas que debe seguir coincidiendo.

Reglas que se comprueban a sí mismas

examples es la mitad útil. sift selftest ejecuta cada regla contra las cadenas para las que fue escrita, a través de todo el recorrido: coincidencia, extracción y, luego, los filtros de supresión. Ese último paso es el que importa, porque la regresión que realmente ocurre no es un patrón que deja de coincidir; es un filtro de ruido, ajustado por buenas razones en otro lugar, que se está comiendo silenciosamente un hallazgo real a su paso.

Se gana su puesto de inmediato. Añadir ejemplos a las reglas existentes destapó una brecha real: un guion bajo es un carácter de palabra, por lo que el \b inicial en la regla de asignación genérica se negaba a coincidir dentro de DB_PASSWORD, MYSQL_PASSWORD o REDIS_PASSWORD - tres de los nombres de variable de credenciales más comunes que existen, omitidos silenciosamente. El ejemplo parecía obviamente correcto y no coincidía, que es exactamente para lo que sirve.

Las reglas que escribes en la interfaz obtienen esto gratis: la línea que seleccionaste se guarda como ejemplo de la regla, de modo que una regla que edites seis meses después te dice cuándo ha dejado de coincidir con aquello que te hizo escribirla.

Importar paquetes de reglas de otras herramientas

sift import-rules acepta un .toml de gitleaks, un .yml estilo Kingfisher/Titus, o un directorio de ellos. Contra el paquete de Kingfisher eso supone 1.073 de 1.082 reglas importadas, trayendo consigo sus mínimos de entropía, requisitos de dígitos y mayúsculas/minúsculas, y ejemplos. El YAML lo lee sift/yamlmini.py, un lector para el subconjunto que usan estos paquetes: sin dependencias, y lanza una excepción ante anclas y etiquetas en lugar de fingir que las entiende.

Dos cosas se descartan deliberadamente en el proceso de importación:

• Bloques validation:, que nombran una URL por regla. sift solo contacta con hosts codificados en validate.py. Un paquete de reglas que pudiera nombrar un endpoint estaría eligiendo a dónde se envían tus hallazgos, y un archivo de reglas es datos, no una decisión.
• Cualquier regla cuyo patrón ya no coincide con su propio ejemplo documentado. Los paquetes están escritos para Rust y Hyperscan, donde [[:alnum:]] es una clase POSIX; Python lo lee como un conjunto de caracteres literales, lo compila alegremente y coincide con lo incorrecto. La traducción se comprueba contra los ejemplos de cada regla, de modo que un patrón que sobrevivió a la compilación pero cambió de significado se rechaza en lugar de quedarse silenciosamente sin activarse nunca. Doce de las reglas de Kingfisher no superan esa comprobación y no se importan.

Que la propia supresión de sift descartara un ejemplo dado no descalifica la regla: esos paquetes incluyen deliberadamente muestras falsas (keyXXXXXXXX, ...EXAMPLE), por lo que el filtro de marcadores de posición acierta sobre el ejemplo y no dice nada sobre el patrón. Ser estricto con eso descartó 121 reglas que funcionaban antes de que se estableciera la distinción.

La supresión hace tanto trabajo como la detección

Las reglas genéricas de secretos se abandonan por el ruido, así que los filtros de ruido están ajustados con tanto cuidado como los patrones. Medido contra un árbol real de 6.000 archivos, las reglas de supresión siguientes reducen los hallazgos de 1.088 a 257 sin pérdida de exhaustividad en el corpus de prueba:

• Referencias de código con puntos. password: process.env.DB_PASS es una variable, no un valor. Esta única supresión elimina la mayor parte del ruido de las reglas genéricas en árboles de código fuente.
• Anotaciones de tipo. def login(user: str, password: str) es una firma.
• Valores que empiezan con puntuación son una regex que cortó una expresión a medias, no una credencial.
• La prosa requiere un dígito o símbolo. Sin eso, la regla lee inglés sobre credenciales: "a credential in the URL is reported and stripped" produce "reported". 99 falsos positivos en un árbol enseñaron eso.
• Directorios de compilación y caché (.wrangler, .next, site-packages, node_modules, …) además de bundles minificados y mapas de origen se omiten. El texto generado por máquinas solo produce falsos positivos generados por máquinas.

Deliberadamente no hay ninguna regla de contenido https://user:pass@host con una cola laxa. La versión obvia se activó 476 veces en un árbol de desarrollo, porque el JSON minificado no tiene espacios en blanco y el patrón recorría desde una URL a través de comillas y comas hasta encontrar un @ no relacionado cientos de caracteres después.

Pruebas```bash

python tests/run_all.py

Doce suites: detección contra un recurso compartido sintético (dividido en "lo
que ya detectan los escáneres de CI", "la brecha que esta herramienta aborda" y "señuelos que
deben permanecer en silencio"), la línea de comandos, el ranking de sugerencias de reglas, la exploración y
la adquisición limitada (incluyendo la medición del límite de velocidad contra el reloj de pared),
el escritor de PDF (analizado de vuelta como lo haría un lector, para demostrar que la redacción llegó
al contenido de la página), los importadores de gitleaks/trufflehog, la API HTTP incluyendo
cada guardia de seguridad, el análisis estático de la interfaz de usuario, y el lector de bloques para
archivos de gran tamaño (afirmando que un secreto en el último bloque aún reporta su verdadero
número de línea en todo el archivo).

Para obtener un recurso compartido con el que jugar:```bash
sift demo C:\temp\demoshare

Cada credencial de ese corpus es fabricada.

Verificación

Dos niveles, porque conllevan riesgos muy distintos.

Las sumas de comprobación son gratuitas y siempre están activas. Los tokens ghp_, npm_, de Atlassian ATATT, de Bitbucket ATCTT y los glpat- enrutables de GitLab llevan un CRC32 sobre su propio cuerpo. Recalcularlo responde sin conexión lo que antes requería internet: ¿es un token real o el ejemplo que alguien pegó en un README? Los hallazgos se etiquetan como checksum ok o malformed en la cola. Una suma de comprobación prueba la forma, no la vida: un token bien formado puede haber sido revocado hace un año.

La validación en vivo está desactivada hasta que la ejecutas. sift validate pregunta al proveedor si una credencial sigue funcionando. Es un comando separado, no una opción de scan, y te hace escribir validate en un aviso que primero nombra cada endpoint al que contactará. Las reglas de seguridad:

• Los endpoints están codificados en sift/validate.py. Ninguna regla —integrada, escrita por el usuario o importada del paquete de otro— puede proporcionar una URL. Sin esto, importar un paquete de reglas bastaría para enviar cada credencial del recurso compartido a una dirección elegida por el autor del paquete.
• El secreto viaja en una cabecera, nunca en una URL o cadena de consulta, por lo que se mantiene fuera de los registros de proxy y de los registros de acceso del proveedor.
• No se siguen las redirecciones. Un 302 es una instrucción para enviar la credencial a otro lugar.
• Solo se envían las credenciales que ya superan su suma de comprobación, por lo que los falsos evidentes nunca salen de la máquina.
• Se niega a ejecutarse contra un almacén --redact: si los valores están enmascarados porque la base de datos está saliendo del perímetro del incidente, transmitir el texto plano es exactamente lo que se está protegiendo.
• Cada llamada se escribe en validation-log.json, junto a la base de datos de hallazgos —proveedor, endpoint, hora, resultado— para que el encargo pueda decir con precisión qué se contactó.

Los intentos de validación aparecen en los registros de auditoría del propietario de la credencial, atribuidos a tu dirección, en ese momento. Eso a veces es exactamente lo que quieres y a veces alerta a un adversario que está observando. Decide antes de ejecutarlo; por eso pregunta.

Actualmente GitHub, npm, Slack y Stripe. trufflehog sigue verificando mucho más —ejecútalo e import-findings para tener ambos.

Limitaciones conocidas

• La verificación es limitada. Las sumas de comprobación cubren cinco familias de tokens; la validación en vivo cubre cuatro proveedores. trufflehog verifica cientos —ejecútalo e import-findings; los aciertos verificados se ordenan al principio.
• Los contenedores cifrados solo se identifican por nombre. Un .kdbx o .pfx se reporta por nombre; sift no intenta abrirlo.
• Las bases de datos SQLite se leen como tablas, no como bytes. Se detectan por cabecera en lugar de por extensión, se abren de solo lectura e inmutables para que no se escriba nada junto a un archivo que es evidencia. Las tablas de configuración clave/valor se recombinan en name=value; sin ello, la palabra secreta y su valor están en columnas separadas y ninguna regla ve el par.
• .7z, .rar y archivos anidados se marcan pero no se extraen. Solo se leen internamente los formatos basados en ZIP y los mensajes .eml.
• Los archivos superiores a --max-size se leen por bloques, no se almacenan en caché. Se escanean (una cadena de conexión en un .bak de 4 GB se encuentra, en su número de línea real), pero la caché de texto solo contiene lo que cabe, por lo que el reescaneo en caché de un segundo no los cubre: una regla nueva llega a un archivo grande en el siguiente escaneo completo.

Licencia

Apache-2.0. Consulta LICENSE.

El corpus de prueba de detección (sift/selftest.py, tests/) contiene credenciales con el formato correcto pero fabricadas a propósito; las alertas de escaneo de secretos para esas rutas se suprimen mediante .github/secret_scanning.yml.