garita added to PyPI
El manejo de repositorios Git conlleva un riesgo crítico: la involuntaria exposición de información sensible como datos personales y credenciales confidenciales. Los identificadores oficiales (como CURP, RFC, CLABE, CPF, CUIT, RUT, DNI, IBAN), números de teléfono, nombres propios o secretos criptográficos deben mantenerse fuera del control de versiones.
Este desafío surge porque es habitual que un proyecto requiera versionar información financiera—datos susceptibles de una auditoría exhaustiva—mientras que la base de datos poblacional o el padrón de individuos no debe registrarse bajo ningún concepto. Las leyes de protección de datos lo regulan estrictamente, y la naturaleza acumulativa del historial de Git nunca olvida un dato.
La regla de oro es clara: se puede versionar el identificador del lote o su adeudo asociado, pero jamás se debe registrar la vinculación directa entre ese lote y la identidad física de la persona que lo reside. La complejidad aumenta porque soluciones existentes presentan limitaciones; por ejemplo, Microsoft Presidio solo cubre una fracción de países, dejando fuera a naciones clave como México. Otros guardianes rechazan patrones de Datos Personales Identificables (PII) o cobran tarifas elevadas por patrones personalizados, y herramientas más antiguas carecen de mantenimiento actualizado.
Además, los mecanismos de seguridad no son perfectos: un detector que solo busca cadenas arbitrarias de cierta longitud puede generar una cantidad abrumadora de falsos positivos. Este ruido excesivo provoca que los desarrolladores comiencen a ignorar completamente al sistema de vigilancia, lo cual eleva la probabilidad de que el dato real se filtre sin ser detectado.
Un defecto estructural común es confiar en listas fijas: cualquier detector que compare su patrón contra una lista preescrita corre el riesgo fatal de registrar esa misma lista como un dato personal más. Para evitarlo, teóricamente habría que almacenar dicho padrón dentro del propio repositorio —lo cual es precisamente lo que se busca impedir.
La solución avanzada radica en aprovechar los generadores de datos sintéticos utilizados para la fase de pruebas y semillas iniciales de cualquier proyecto con manejo de datos reales. Estos generadores ya poseen el conocimiento intrínseco sobre qué nombres o identificadores réels nunca deben generar accidentalmente.
Este proceso de verificación puede ejecutarse leyendo las estructuras del código fuente (AST) sin necesidad de ejecutar dicho archivo, permitiendo centralizar la vigilancia en una única lista maestra. Esto asegura que cuando se actualiza el listado de personas, el mecanismo de control se actualiza instantáneamente y en un único punto.
El mismo concepto de protección aplica a los clientes corporativos. En repositorios dedicados a consultoría o casos de estudio, se documenta el sector operativo, pero jamás debe aparecer el nombre del cliente final. Los detectores modernos aceptan la identificación por atributos menos sensibles (como un dominio web o un número de serie de dispositivo) y bloquean cualquier aparición de datos que apunte al nombre real, sugiriendo en su lugar usar un alias asociado al sector.
La configuración debe ser lo suficientemente flexible para manejar fallos: el sistema debe avisar si una fuente de información no está disponible (por ejemplo, si el archivo auxiliar falta), pero sin detener la ejecución por completo. Esto garantiza que la herramienta sea útil en entornos reales, tolerando ausencias temporales sin pasar a un estado de alarma permanente.
Los identificadores oficiales pertenecen a una carpeta dedicada por país. Hoy existen dieciséis módulos de control, y esta estructura modular permite la actualización uniforme: al agregar la normativa de un nuevo país, solo se añade un archivo detector; el motor centraliza las pruebas y los ajustes para que cualquier modificación llegue a todos en paralelo.
Desde una perspectiva técnica avanzada, múltiples identificadores —como el NIT guatemalteco o el RUC paraguayo— comparten la misma base lógica (módulo 11), lo que implica que un número válido en un país muy probablemente será válido en otro. Por ello, los detectores avanzados no solo validan el número, sino que emiten un hallazgo único que presenta a ambos candidatos de identificación, evitando contradicciones.
La precisión máxima se logra asociando la validación al contexto geográfico (el país). Esto determina si el resultado del chequeo es inequívoco. La implementación sigue una regla estricta: solo se acepta un identificador cuyo formato pueda contrastarse con una fuente oficial de datos, ya que un detector basado únicamente en patrones genera ruido inútil.
Es crucial implementar las comprobaciones no solo durante la Integración Continua (CI), sino también a nivel de ‘hook’ o anzuelo pre-commit. De lo contrario, cuando el dato personal falla y se detecta en fase CI, este ya ha sido incorporado al historial mediante un commit. Arreglarlo pasa de ser tan simple como “borrar una línea” a tener que reescribir todo el historial del repositorio.
Estos sistemas trabajan con capas complementarias; ninguna función sustituye por completo a la otra. Además, los resultados no deben quedar limitados al registro inmediato de ejecución. Utilizando formatos estandarizados como SARIF, GitHub puede convertir el hallazgo en una alerta de escaneo persistente, manteniendo un historial y estado propio para cada detección.
Para auditar completamente la información sensible, es vital revisar no solo las versiones actuales del código, sino absolutamente todas las versiones que han pasado por el repositorio. El riesgo persiste: un secreto podría haber sido comprometido hace meses e incluso haber sido “borrado” en una commit posterior. Git nunca olvida; ese dato sigue viviendo en cada copia o *fork* del proyecto.
Los reportes de seguridad deben separar qué datos siguen activos en el árbol principal (donde se pueden arreglar rutinariamente) y cuáles residen únicamente en el historial, donde la solución no es simplemente borrar un archivo. Si se detecta una credencial sensible, debe rotarse inmediatamente; intentar limpiar el historial con comandos manuales puede ser peligroso.
Como capa de seguridad permanente, resulta esencial implementar auditorías mensuales que emiten alertas en sistemas de gestión de seguridad. Estas alertas no solo apuntan a la ruta del commit donde se introdujo el dato —incluso si ese archivo ya ha sido removido— sino que lo hacen mediante un rastreo inmutable (commit + ruta + regla), identificando el fallo para siempre sin revelar el valor sensible.
En caso de haber hallazgos previos en un repositorio, es posible “congelar” esta deuda técnica. Esto permite que la plataforma de CI solo falle ante nuevas vulnerabilidades, mientras que las antiguas se mantienen visibles en el reporte como una responsabilidad aceptada hasta la fecha actual.
Todo proceso de seguridad tiene secciones opcionales, salvo el listado maestro de nombres protegidos. Cuando se configura una “exención” (el término técnico para excepciones o *allowlists*), esta es una regla liberadora que requiere obligatoriamente un motivo escrito y justificativo. Si este motivo falta, la herramienta se niega a ejecutar el bloque, forzando al usuario a documentar por qué esa excepción sigue siendo necesaria.
La razón de ser del motivo es evitar la acumulación de código o reglas sin propósito. Sin una justificación escrita, las excepciones corren el riesgo de convertirse en código abandonado, imposible de revisar y que se vuelve un pasivo técnico peligroso con el tiempo.
Finalmente, cada hallazgo debe ofrecer tres elementos: qué dato es, por qué representa un peligro real, y cómo remediar la situación. De lo contrario, simplemente arrojar una alerta sin explicación lleva a los usuarios a proponer desactivar el mecanismo de seguridad en su totalidad.
