awslabs/git-secretsTe impide comprometer secretos y credenciales en repositorios git
===========
git-secrets
===========
-------------------------------------------------------------------------------------------
Evita que comprometas contraseñas y otra información sensible en un repositorio de git.
-------------------------------------------------------------------------------------------
.. contents:: :depth: 2
Sinopsis
--------
::
git secrets --scan [-r|--recursive] [--cached] [--no-index] [--untracked] [<files>...]
git secrets --scan-history
git secrets --install [-f|--force] [<target-directory>]
git secrets --list [--global]
git secrets --add [-a|--allowed] [-l|--literal] [--global] <pattern>
git secrets --add-provider [--global] <command> [arguments...]
git secrets --register-aws [--global]
git secrets --aws-provider [<credentials-file>]
Descripción
-----------
``git-secrets`` escanea commits, mensajes de commit y fusiones ``--no-ff`` para evitar agregar secretos en tus repositorios git. Si un commit, mensaje de commit o cualquier commit en un historial de fusión ``--no-ff`` coincide con uno de tus patrones de expresiones regulares prohibidas configurados, entonces el commit es rechazado.
Instalación de git-secrets
--------------------------
``git-secrets`` debe estar ubicado en algún lugar de tu PATH para que ``git`` lo reconozca al ejecutar ``git secrets``.
\*nix (Linux/macOS)
~~~~~~~~~~~~~~~~~~~
Puedes usar el objetivo ``install`` del Makefile proporcionado para instalar ``git secrets`` y la página de manual. Puedes personalizar la ruta de instalación usando las variables PREFIX y MANPREFIX.
::
make install
Windows
~~~~~~~
Ejecuta el script de PowerShell ``install.ps1`` proporcionado. Esto copiará los archivos necesarios a un directorio de instalación (``%USERPROFILE%/.git-secrets`` por defecto) y agregará el directorio al ``PATH`` del usuario actual.
::
PS > ./install.ps1
Homebrew (para usuarios de macOS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
brew install git-secrets
.. warning::
**¡Aún no has terminado! DEBES instalar los hooks de git para cada repositorio con el que desees usar** ``git secrets --install``.
Aquí hay un ejemplo rápido de cómo asegurarse de que un repositorio git sea escaneado en busca de secretos en cada commit::
cd /path/to/my/repo
git secrets --install
git secrets --register-aws
Configuración avanzada
----------------------
Agrega una plantilla de configuración si deseas agregar hooks a todos los repositorios que inicialices o clones en el futuro.
::
git secrets --register-aws --global
Agrega hooks a todos tus repositorios locales.
::
git secrets --install ~/.git-templates/git-secrets
git config --global init.templateDir ~/.git-templates/git-secrets
Agrega proveedores personalizados para escanear credenciales de seguridad.
::
git secrets --add-provider -- cat /path/to/secret/file/patterns
Antes de hacer público un repositorio
--------------------------------------
Con git-secrets también es posible escanear un repositorio incluyendo todas las revisiones:
::
git secrets --scan-history
Opciones
--------
Modos de operación
~~~~~~~~~~~~~~~~~~~
Cada una de estas opciones debe aparecer primero en la línea de comandos.
``--install``
Instala los hooks de git para un repositorio. Una vez que los hooks están instalados para un repositorio git, los commits y las fusiones no fast-forward de ese repositorio se evitarán que comprometan secretos.
``--scan``
Escanea uno o más archivos en busca de secretos. Cuando un archivo contiene un secreto, el texto coincidente del archivo escaneado se escribirá en la salida estándar y el script saldrá con un estado distinto de cero. Cada línea coincidente se escribirá con el nombre del archivo que coincidió, dos puntos, el número de línea que coincidió, dos puntos y luego la línea de texto que coincidió. Si no se proporcionan archivos, se escanean todos los archivos devueltos por ``git ls-files``.
``--scan-history``
Escanea el repositorio incluyendo todas las revisiones. Cuando un archivo contiene un secreto, el texto coincidente del archivo escaneado se escribirá en la salida estándar y el script saldrá con un estado distinto de cero. Cada línea coincidente se escribirá con el nombre del archivo que coincidió, dos puntos, el número de línea que coincidió, dos puntos y luego la línea de texto que coincidió.
``--list``
Lista la configuración de ``git-secrets`` para el repositorio actual o en la configuración global de git.
``--add``
Agrega un patrón prohibido o permitido.
``--add-provider``
Registra un proveedor de secretos. Los proveedores de secretos son ejecutables que, cuando se invocan, generan patrones prohibidos que ``git-secrets`` debe tratar como prohibidos.
``--register-aws``
Agrega patrones comunes de AWS a la configuración de git y garantiza que las claves presentes en ``~/.aws/credentials`` no se encuentren en ningún commit. Se agregan las siguientes comprobaciones:
- IDs de clave de acceso de AWS mediante ``(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}``
- Claves de API de Amazon Bedrock. De larga duración mediante ``ABSK[A-Za-z0-9+/]{109,}=*`` y de corta duración mediante ``bedrock-api-key-YmVkcm9jay5hbWF6b25hd3MuY29t``
- Asignaciones de clave secreta de acceso de AWS mediante ":" o "=" rodeados de comillas opcionales
- Asignaciones de ID de cuenta de AWS mediante ":" o "=" rodeados de comillas opcionales
- Patrones permitidos para claves de AWS de ejemplo (``AKIAIOSFODNN7EXAMPLE`` y ``wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY``)
- Credenciales conocidas de ``~/.aws/credentials``
.. note::
Si bien los patrones registrados por este comando deberían detectar la mayoría de las instancias de credenciales de AWS, estos patrones **no** garantizan detectarlas **todas**. ``git-secrets`` debe usarse como un medio adicional de seguro; aún debes hacer tu debida diligencia para asegurarte de no comprometer credenciales en un repositorio.
``--aws-provider``
Proveedor de secretos que genera las credenciales encontradas en un archivo INI. Opcionalmente puedes proporcionar la ruta a un archivo INI.
Opciones para ``--install``
~~~~~~~~~~~~~~~~~~~~~~~~~
``-f, --force``
Sobrescribe los hooks existentes si están presentes.
``<target-directory>``
Cuando se proporciona, instala los hooks de git en el directorio dado. Se asume el directorio actual si no se proporciona ``<target-directory>``.
Si el ``<target-directory>`` proporcionado no está en un repositorio git, se creará el directorio y los hooks se colocarán en ``<target-directory>/hooks``. Esto puede ser útil para crear directorios de plantilla de git para usar con ``git init --template <target-directory>``.
Puedes ejecutar ``git init`` en un repositorio que ya ha sido inicializado. De la `documentación de git init <https://git-scm.com/docs/git-init>`_:
De la documentación de git: Ejecutar ``git init`` en un repositorio existente es seguro. No sobrescribirá cosas que ya están allí. La razón principal para volver a ejecutar ``git init`` es recoger plantillas recién agregadas (o para mover el repositorio a otro lugar si se proporciona ``--separate-git-dir``).
Se instalan los siguientes hooks de git:
1. ``pre-commit``: Se usa para comprobar si alguno de los archivos modificados en el commit utiliza patrones prohibidos.
2. ``commit-msg``: Se usa para determinar si un mensaje de commit contiene un patrón prohibido.
3. ``prepare-commit-msg``: Se usa para determinar si un commit de fusión introducirá un historial que contenga un patrón prohibido en algún punto. Ten en cuenta que este hook solo se invoca para fusiones no fast-forward.
.. note::
Git solo permite que se ejecute un solo script por hook. Si el repositorio contiene subdirectorios estilo Debian como ``pre-commit.d`` y ``commit-msg.d``, entonces los hooks de git se instalarán en estos directorios, lo que asume que has configurado los hooks correspondientes para ejecutar todos los scripts encontrados en estos directorios. Si estos subdirectorios de git no están presentes, entonces los hooks de git se instalarán en el directorio ``.git/hooks`` del repositorio git.
Ejemplos
^^^^^^^^
Instalar hooks de git en el directorio actual::
cd /path/to/my/repository
git secrets --install
Instalar hooks de git en un repositorio diferente al directorio actual::
git secrets --install /path/to/my/repository
Crear una plantilla de git que tenga ``git-secrets`` instalado y luego copiar esa plantilla en un repositorio git::
git secrets --install ~/.git-templates/git-secrets
git init --template ~/.git-templates/git-secrets
Sobrescribir hooks existentes si están presentes::
git secrets --install -f
Opciones para ``--scan``
~~~~~~~~~~~~~~~~~~~~~~
``-r, --recursive``
Escanea los archivos dados de forma recursiva. Si se encuentra un directorio, se escaneará. Si no se proporciona ``-r``, se ignorarán los directorios.
``-r`` no se puede usar junto con ``--cached``, ``--no-index`` o ``--untracked``.
``--cached``
Busca blobs registrados en el archivo de índice.
``--no-index``
Busca archivos en el directorio actual que no estén gestionados por git.
``--untracked``
Además de buscar en los archivos rastreados en el árbol de trabajo, ``--scan`` también busca en archivos no rastreados.
``<files>...``
La ruta a uno o más archivos en disco para escanear en busca de secretos.
Si no se proporcionan archivos, se escanean todos los archivos devueltos por ``git ls-files``.
Ejemplos
^^^^^^^^
Escanear todos los archivos del repositorio::
git secrets --scan
Escanea un solo archivo en busca de secretos::
git secrets --scan /path/to/file
Escanea un directorio recursivamente en busca de secretos::
git secrets --scan -r /path/to/directory
Escanea múltiples archivos en busca de secretos::
git secrets --scan /path/to/file /path/to/other/file
Puedes escanear usando globbing::
git secrets --scan /path/to/directory/*
Escanear desde stdin::
echo 'hello!' | git secrets --scan -
Opciones para ``--list``
~~~~~~~~~~~~~~~~~~~~~~
``--global``
Lista solo la configuración de git-secrets en la configuración global de git.
Opciones para ``--add``
~~~~~~~~~~~~~~~~~~~~~
``--global``
Agrega patrones a la configuración global de git
``-l, --literal``
Escapa los caracteres especiales de expresiones regulares en el patrón proporcionado para que el patrón se busque literalmente.
``-a, --allowed``
Marca el patrón como permitido en lugar de prohibido. Los patrones permitidos se utilizan para filtrar falsos positivos.
``<pattern>``
El patrón de expresión regular a buscar.
Ejemplos
^^^^^^^^
Agrega un patrón prohibido al repositorio actual::
git secrets --add '[A-Z0-9]{20}'
Agrega un patrón prohibido a la configuración global de git::
git secrets --add --global '[A-Z0-9]{20}'
Agrega una cadena que se busca literalmente (``+`` se escapa)::
git secrets --add --literal 'foo+bar'
Agrega un patrón permitido::
git secrets --add -a 'allowed pattern'
Opciones para ``--register-aws``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``--global``
Agrega variables de configuración específicas de AWS a la configuración global de git.
Opciones para ``--aws-provider``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``[<credentials-file>]``
Si se proporciona, especifica la ruta personalizada a un archivo INI para escanear. Si no se proporciona, se asume ``~/.aws/credentials``.
Opciones para ``--add-provider``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``--global``
Agrega el proveedor a la configuración global de git.
``<command>``
Comando del proveedor a invocar. Cuando se invoca, se espera que el comando escriba patrones prohibidos separados por nuevas líneas en la salida estándar. Cualquier argumento adicional proporcionado se pasa al comando.
Ejemplos
^^^^^^^^
Registra un proveedor de secretos con argumentos::
git secrets --add-provider -- git secrets --aws-provider
Saca secretos de un archivo::
git secrets --add-provider -- cat /path/to/secret/file/patterns
Definición de patrones prohibidos
----------------------------
Se utilizan expresiones regulares compatibles con ``egrep`` para determinar si un commit o mensaje de commit contiene algún patrón prohibido. Estas expresiones regulares se definen mediante el comando ``git config``. Es importante tener en cuenta que diferentes sistemas usan diferentes versiones de egrep. Por ejemplo, al ejecutar en macOS, usarás una versión diferente de ``egrep`` que al ejecutar en algo como Ubuntu (BSD vs GNU).
Puedes agregar patrones de expresiones regulares prohibidas a tu configuración de git usando ``git secrets --add <pattern>``.
Ignorar falsos positivos
------------------------
A veces una expresión regular puede coincidir con falsos positivos. Por ejemplo, los SHAs de commit de git se parecen mucho a las claves de acceso de AWS. Puedes especificar muchos patrones de expresiones regulares diferentes como falsos positivos usando el siguiente comando:
::
git secrets --add --allowed 'my regex pattern'
También puedes agregar patrones de expresiones regulares para filtrar falsos positivos a un archivo ``.gitallowed`` ubicado en el directorio raíz del repositorio. Las líneas que comienzan con ``#`` se omiten (línea de comentario) y las líneas vacías también se omiten.
Primero, git-secrets extraerá todas las líneas de un archivo que contengan una coincidencia prohibida. En los resultados coincidentes se incluirá la ruta completa al nombre del archivo que coincidió, seguido de ':', seguido del número de línea que coincidió, seguido de toda la línea del archivo que coincidió con un patrón de secreto. Luego, si has definido expresiones regulares permitidas, git-secrets verificará si todas las líneas coincidentes coinciden con al menos una de tus expresiones regulares permitidas registradas. Si todas las líneas marcadas como secreto son canceladas por una coincidencia permitida, entonces el texto del sujeto no contiene secretos. Si alguna de las líneas coincidentes no coincide con una expresión regular permitida, entonces git-secrets fallará el commit/fusión/mensaje.
.. important::
Así como es una mala práctica agregar patrones prohibidos demasiado ambiciosos, también es una mala práctica agregar patrones permitidos demasiado indulgentes. Asegúrate de probar tus patrones utilizando llamadas ad-hoc a ``git secrets --scan $filename`` para asegurarte de que funcionen según lo previsto.
Proveedores de secretos
----------------
A veces deseas verificar una coincidencia de patrón exacta contra un conjunto de secretos conocidos. Por ejemplo, es posible que desees asegurarte de que ninguna credencial presente en ``~/.aws/credentials`` aparezca en un commit. En estos casos, es mejor dejar estos secretos en una ubicación en lugar de esparcirlos en repositorios git en las configuraciones de git. Puedes usar "proveedores de secretos" para obtener este tipo de credenciales. Un proveedor de secretos es un ejecutable que, cuando se invoca, genera patrones prohibidos separados por nuevas líneas.
Puedes agregar proveedores de secretos usando el comando ``--add-provider``::
git secrets --add-provider -- git secrets --aws-provider
Observa el uso de ``--``. Esto garantiza que cualquier argumento asociado con el proveedor se pase al proveedor cada vez que se invoca al escanear en busca de secretos.
Ejemplo paso a paso
-------------------
Veamos un ejemplo. Dado el siguiente texto de sujeto (almacenado en ``/tmp/example``)::
This is a test!
password=ex@mplepassword
password=******
More test...
Y los siguientes patrones registrados:
::
git secrets --add 'password\s*=\s*.+'
git secrets --add --allowed --literal 'ex@mplepassword'
Ejecutar ``git secrets --scan /tmp/example`` dará como resultado el siguiente error de salida::
/tmp/example:3:password=******
[ERROR] Matched prohibited pattern
Possible mitigations:
- Mark false positives as allowed using: git config --add secrets.allowed ...
- List your configured patterns: git config --get-all secrets.patterns
- List your configured allowed patterns: git config --get-all secrets.allowed
- Use --no-verify if this is a one-time false positive
Desglosando esto, el valor del patrón prohibido ``password\s*=\s*.+`` coincidirá con las siguientes líneas::
/tmp/example:2:password=ex@mplepassword
/tmp/example:3:password=******
...Pero la primera coincidencia se filtrará debido a que coincide con la expresión regular permitida ``ex@mplepassword``. Debido a que todavía hay una línea restante que no coincidió, se considera un secreto.
Debido a que las líneas coincidentes se colocan en líneas que comienzan con el nombre del archivo y el número de línea (por ejemplo, ``/tmp/example:3:...``), puedes crear patrones permitidos que tengan en cuenta los nombres de archivo y números de línea en la expresión regular. Por ejemplo, podrías poner en la lista blanca un archivo completo usando algo como::
git secrets --add --allowed '/tmp/example:.*'
git secrets --scan /tmp/example && echo $?
# Outputs: 0
Alternativamente, podrías permitir un número de línea específico de un archivo si es poco probable que esa línea cambie, usando algo como lo siguiente:
::
git secrets --add --allowed '/tmp/example:3:.*'
git secrets --scan /tmp/example && echo $?
# Outputs: 0
Ten esto en cuenta al crear patrones permitidos para asegurarte de que tus patrones permitidos no coincidan inadvertidamente debido al hecho de que el nombre del archivo está incluido en el texto de sujeto contra el cual se comparan los patrones permitidos.
Saltar la validación
-------------------
Usa la opción ``--no-verify`` en caso de una coincidencia de falso positivo en un commit, fusión o mensaje de commit. Esto omitirá la ejecución del hook de git y te permitirá realizar el commit o la fusión.
Acerca de
---------
- Autor: `Michael Dowling <https://github.com/mtdowling>`_
- Seguimiento de problemas: el código fuente de este proyecto y el seguimiento de problemas se encuentran en
`https://github.com/awslabs/git-secrets <https://github.com/awslabs/git-secrets>`_
- Agradecimientos especiales a Adrian Vatchinsky y Ari Juels de la Universidad de Cornell por proporcionar sugerencias y comentarios.
Copyright 2015 Amazon.com, Inc. o sus afiliados. Todos los derechos reservados.