============= git-secrets

Impede que você faça commit de senhas e outras informações sensíveis em um repositório git.

.. contents:: :depth: 2

Sinopse

git secrets --scan [-r|--recursive] [--cached] [--no-index] [--untracked] [<arquivos>...]
git secrets --scan-history
git secrets --install [-f|--force] [<diretório-destino>]
git secrets --list [--global]
git secrets --add [-a|--allowed] [-l|--literal] [--global] <padrão>
git secrets --add-provider [--global] <comando> [argumentos...]
git secrets --register-aws [--global]
git secrets --aws-provider [<arquivo-de-credenciais>]

Descrição

O git-secrets verifica commits, mensagens de commit e merges --no-ff para evitar a adição de segredos aos seus repositórios git. Se um commit, mensagem de commit ou qualquer commit em um histórico de merge --no-ff corresponder a um de seus padrões de expressão regular proibidos configurados, o commit é rejeitado.

Instalação do git-secrets

O git-secrets deve ser colocado em algum lugar no seu PATH para que seja reconhecido pelo git ao executar git secrets.

*nix (Linux/macOS)


Você pode usar o alvo ``install`` do Makefile fornecido para instalar o ``git secrets`` e a página man.
Você pode personalizar o caminho de instalação usando as variáveis PREFIX e MANPREFIX.

::

    make install

Windows
~~~~~~~

Execute o script powershell ``install.ps1`` fornecido. Isso copiará os arquivos necessários
para um diretório de instalação (``%USERPROFILE%/.git-secrets`` por padrão) e adicionará
o diretório ao ``PATH`` do usuário atual.

::

    PS > ./install.ps1

Homebrew (para usuários macOS)

brew install git-secrets

.. warning::

**Você ainda não terminou! Você DEVE instalar os hooks git para cada repositório que
deseja usar com** ``git secrets --install``.

Aqui está um exemplo rápido de como garantir que um repositório git seja verificado por segredos em cada commit::

cd /caminho/para/meu/repositorio
git secrets --install
git secrets --register-aws

Configuração avançada

Adicione um modelo de configuração se quiser adicionar hooks a todos os repositórios que você inicializar ou clonar no futuro.

git secrets --register-aws --global

Adicione hooks a todos os seus repositórios locais.

git secrets --install ~/.git-templates/git-secrets
git config --global init.templateDir ~/.git-templates/git-secrets

Adicione provedores personalizados para verificar credenciais de segurança.

git secrets --add-provider -- cat /caminho/para/arquivo/de/padroes/secretos

Antes de tornar um repositório público

Com o git-secrets também é possível verificar um repositório incluindo todas as revisões:

git secrets --scan-history

Opções

Modos de Operação


Cada uma dessas opções deve aparecer primeiro na linha de comando.

``--install``
    Instala hooks git para um repositório. Após a instalação dos hooks para um repositório
    git, commits e merges não-fast-forward para esse repositório serão impedidos
    de fazer commit de segredos.

``--scan``
    Verifica um ou mais arquivos em busca de segredos. Quando um arquivo contém um segredo, o
    texto correspondente do arquivo sendo verificado será escrito na saída padrão e o
    script será encerrado com um status diferente de zero. Cada linha correspondente será escrita com
    o nome do arquivo que correspondeu, dois pontos, o número da linha que correspondeu,
    dois pontos e, em seguida, a linha de texto que correspondeu. Se nenhum arquivo for fornecido,
    todos os arquivos retornados por ``git ls-files`` são verificados.

``--scan-history``
    Verifica o repositório incluindo todas as revisões. Quando um arquivo contém um segredo, o
    texto correspondente do arquivo sendo verificado será escrito na saída padrão e o
    script será encerrado com um status diferente de zero. Cada linha correspondente será escrita com
    o nome do arquivo que correspondeu, dois pontos, o número da linha que correspondeu,
    dois pontos e, em seguida, a linha de texto que correspondeu.

``--list``
    Lista a configuração do ``git-secrets`` para o repositório atual ou no git config
    global.

``--add``
    Adiciona um padrão proibido ou permitido.

``--add-provider``
    Registra um provedor de segredos. Provedores de segredos são executáveis que, quando
    invocados, geram padrões proibidos que o ``git-secrets`` deve tratar como
    proibidos.

``--register-aws``
    Adiciona padrões comuns da AWS ao git config e garante que chaves presentes
    em ``~/.aws/credentials`` não sejam encontradas em nenhum commit. As seguintes
    verificações são adicionadas:

    - IDs de Chave de Acesso AWS via ``(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}``
    - Chaves de API Amazon Bedrock. De longa duração via ``ABSK[A-Za-z0-9+/]{109,}=*`` e de curta duração via ``bedrock-api-key-YmVkcm9jay5hbWF6b25hd3MuY29t``
    - Atribuições de Chave Secreta de Acesso AWS via ":" ou "=" cercadas por aspas
      opcionais
    - Atribuições de ID de conta AWS via ":" ou "=" cercadas por aspas opcionais
    - Padrões permitidos para chaves AWS de exemplo (``AKIAIOSFODNN7EXAMPLE`` e
      ``wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY``)
    - Credenciais conhecidas de ``~/.aws/credentials``

    .. note::

        Embora os padrões registrados por este comando devam capturar a maioria
        das instâncias de credenciais AWS, esses padrões **não** garantem
        capturá-las **todas**. ``git-secrets`` deve ser usado como um meio extra de
        garantia — você ainda precisa fazer sua devida diligência para garantir que
        não faça commit de credenciais em um repositório.

``--aws-provider``
    Provedor de segredos que gera credenciais encontradas em um arquivo INI. Você pode
    opcionalmente fornecer o caminho para um arquivo INI.


Opções para ``--install``

-f, --force Sobrescreve hooks existentes se presentes.

<diretório-destino> Quando fornecido, instala hooks git no diretório especificado. O diretório atual é assumido se <diretório-destino> não for fornecido.

Se o ``<diretório-destino>`` fornecido não estiver em um repositório git, o
diretório será criado e os hooks serão colocados em
``<diretório-destino>/hooks``. Isso pode ser útil para criar diretórios de modelo git
para usar com ``git init --template <diretório-destino>``.

Você pode executar ``git init`` em um repositório que já foi inicializado.
Da `documentação do git init <https://git-scm.com/docs/git-init>`_:

    Da documentação do git: Executar ``git init`` em um repositório existente
    é seguro. Não sobrescreverá coisas que já estão lá. O
    principal motivo para reexecutar ``git init`` é incorporar modelos recém-adicionados
    (ou mover o repositório para outro lugar se
    ``--separate-git-dir`` for fornecido).

Os seguintes hooks git são instalados:

1. ``pre-commit``: Usado para verificar se algum dos arquivos alterados no commit
   usa padrões proibidos.
2. ``commit-msg``: Usado para determinar se uma mensagem de commit contém
   padrões proibidos.
3. ``prepare-commit-msg``: Usado para determinar se um commit de merge
   introduzirá um histórico que contenha um padrão proibido em algum ponto.
   Observe que este hook é invocado apenas para merges não fast-forward.

.. note::

    O Git permite apenas um único script por hook. Se o
    repositório contiver subdiretórios no estilo Debian como ``pre-commit.d``
    e ``commit-msg.d``, então os hooks git serão instalados nesses
    diretórios, o que pressupõe que você configurou os hooks
    correspondentes para executar todos os scripts encontrados nesses diretórios. Se
    esses subdiretórios git não estiverem presentes, então os hooks git serão
    instalados no diretório ``.git/hooks`` do repositório git.

Exemplos ^^^^^^^^

Instalar hooks git no diretório atual::

cd /caminho/para/meu/repositorio
git secrets --install

Instalar hooks git em um repositório diferente do diretório atual::

git secrets --install /caminho/para/meu/repositorio

Criar um modelo git que tenha git-secrets instalado e, em seguida, copiar esse modelo para um repositório git::

git secrets --install ~/.git-templates/git-secrets
git init --template ~/.git-templates/git-secrets

Sobrescrever hooks existentes se presentes::

git secrets --install -f

Opções para --scan


``-r, --recursive``
    Verifica os arquivos fornecidos recursivamente. Se um diretório for encontrado, o
    diretório será verificado. Se ``-r`` não for fornecido, os diretórios serão
    ignorados.

    ``-r`` não pode ser usado junto com ``--cached``, ``--no-index`` ou
    ``--untracked``.

``--cached``
    Pesquisa blobs registrados no arquivo de índice.

``--no-index``
    Pesquisa arquivos no diretório atual que não são gerenciados pelo git.

``--untracked``
    Além de pesquisar nos arquivos rastreados na árvore de trabalho,
    ``--scan`` também pesquisa em arquivos não rastreados.

``<arquivos>...``
    O caminho para um ou mais arquivos no disco para verificar segredos.

    Se nenhum arquivo for fornecido, todos os arquivos retornados por ``git ls-files`` são
    verificados.


Exemplos
^^^^^^^^

Verificar todos os arquivos no repositório::

    git secrets --scan

Verificar um único arquivo em busca de segredos::

    git secrets --scan /caminho/para/arquivo

Verificar um diretório recursivamente em busca de segredos::

    git secrets --scan -r /caminho/para/diretorio

Verificar vários arquivos em busca de segredos::

    git secrets --scan /caminho/para/arquivo /caminho/para/outro/arquivo

Você pode verificar usando globbing::

    git secrets --scan /caminho/para/diretorio/*

Verificar a partir da entrada padrão::

    echo 'olá!' | git secrets --scan -


Opções para ``--list``

--global Lista apenas a configuração do git-secrets no git config global.

Opções para --add


``--global``
    Adiciona padrões ao git config global

``-l, --literal``
    Escapa caracteres especiais de expressão regular no padrão fornecido para
    que o padrão seja pesquisado literalmente.

``-a, --allowed``
    Marca o padrão como permitido em vez de proibido. Padrões permitidos são
    usados para filtrar falsos positivos.

``<padrão>``
    O padrão regex a ser pesquisado.


Exemplos
^^^^^^^^

Adiciona um padrão proibido ao repositório atual::

    git secrets --add '[A-Z0-9]{20}'

Adiciona um padrão proibido ao git config global::

    git secrets --add --global '[A-Z0-9]{20}'

Adiciona uma string que é pesquisada literalmente (``+`` é escapado)::

    git secrets --add --literal 'foo+bar'

Adiciona um padrão permitido::

    git secrets --add -a 'padrão permitido'


Opções para ``--register-aws``

--global Adiciona variáveis de configuração específicas da AWS ao git config global.

Opções para --aws-provider


``[<arquivo-de-credenciais>]``
    Se fornecido, especifica o caminho personalizado para um arquivo INI a ser verificado. Se não
    for fornecido, ``~/.aws/credentials`` é assumido.


Opções para ``--add-provider``

--global Adiciona o provedor ao git config global.

<comando> Comando do provedor a ser invocado. Quando invocado, espera-se que o comando escreva padrões proibidos separados por novas linhas na saída padrão. Quaisquer argumentos extras fornecidos são passados para o comando.

Exemplos ^^^^^^^^

Registra um provedor de segredos com argumentos::

git secrets --add-provider -- git secrets --aws-provider

Extrai segredos de um arquivo::

git secrets --add-provider -- cat /caminho/para/arquivo/de/padroes/secretos

Definindo padrões proibidos

Expressões regulares compatíveis com egrep são usadas para determinar se um commit ou mensagem de commit contém algum padrão proibido. Essas expressões regulares são definidas usando o comando git config. É importante notar que diferentes sistemas usam diferentes versões do egrep. Por exemplo, ao executar no macOS, você usará uma versão diferente do egrep do que ao executar em algo como Ubuntu (BSD vs GNU).

Você pode adicionar padrões de expressão regular proibidos ao seu git config usando git secrets --add <padrão>.

Ignorando falsos positivos

Às vezes, uma expressão regular pode corresponder a falsos positivos. Por exemplo, SHAs de commit git se parecem muito com chaves de acesso AWS. Você pode especificar muitos padrões de expressão regular diferentes como falsos positivos usando o seguinte comando:

git secrets --add --allowed 'meu padrão regex'

Você também pode adicionar padrões de expressão regular para filtrar falsos positivos a um arquivo .gitallowed localizado no diretório raiz do repositório. Linhas começando com # são ignoradas (linha de comentário) e linhas vazias também são ignoradas.

Primeiro, o git-secrets extrairá todas as linhas de um arquivo que contêm uma correspondência proibida. Nos resultados correspondidos estará incluído o caminho completo para o nome do arquivo que foi correspondido, seguido por ':', seguido pelo número da linha que foi correspondido, seguido pela linha inteira do arquivo que foi correspondida por um padrão secreto. Em seguida, se você definiu expressões regulares permitidas, o git-secrets verificará se todas as linhas correspondidas coincidem com pelo menos uma de suas expressões regulares permitidas registradas. Se todas as linhas que foram sinalizadas como secretas forem canceladas por uma correspondência permitida, então o texto do assunto não contém nenhum segredo. Se alguma das linhas correspondidas não for correspondida por uma expressão regular permitida, então o git-secrets falhará no commit/merge/mensagem.

.. important::

Assim como é uma má prática adicionar padrões proibidos que são muito
abrangentes, também é uma má prática adicionar padrões permitidos que são muito
permissivos. Certifique-se de testar seus padrões usando chamadas ad hoc para
``git secrets --scan $nome_do_arquivo`` para garantir que eles funcionem como pretendido.

Provedores de segredos

Às vezes, você deseja verificar uma correspondência de padrão exata contra um conjunto de segredos conhecidos. Por exemplo, você pode querer garantir que nenhuma credencial presente em ~/.aws/credentials jamais apareça em um commit. Nesses casos, é melhor deixar esses segredos em um único local em vez de espalhá-los por repositórios git em git configs. Você pode usar "provedores de segredos" para buscar esses tipos de credenciais. Um provedor de segredos é um executável que, quando invocado, gera padrões proibidos separados por novas linhas.

Você pode adicionar provedores de segredos usando o comando --add-provider::

git secrets --add-provider -- git secrets --aws-provider

Observe o uso de --. Isso garante que quaisquer argumentos associados ao provedor sejam passados para ele toda vez que for invocado ao verificar segredos.

Exemplo passo a passo

Vamos dar uma olhada em um exemplo. Dado o seguinte texto de assunto (armazenado em /tmp/example)::

This is a test!
password=ex@mplepassword
password=******
More test...

E os seguintes padrões registrados:

git secrets --add 'password\s*=\s*.+'
git secrets --add --allowed --literal 'ex@mplepassword'

Executar git secrets --scan /tmp/example resultará na seguinte saída de erro::

/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

Detalhando isso, o valor do padrão proibido password\s*=\s*.+ corresponderá às seguintes linhas::

/tmp/example:2:password=ex@mplepassword
/tmp/example:3:password=******

...Mas a primeira correspondência será filtrada devido ao fato de corresponder à expressão regular permitida ex@mplepassword. Como ainda há uma linha restante que não correspondeu, é considerada um segredo.

Como as linhas correspondentes são colocadas em linhas que começam com o nome do arquivo e número da linha (por exemplo, /tmp/example:3:...), você pode criar padrões permitidos que levam em consideração nomes de arquivos e números de linha na expressão regular. Por exemplo, você poderia colocar um arquivo inteiro na lista de permissões usando algo como::

git secrets --add --allowed '/tmp/example:.*'
git secrets --scan /tmp/example && echo $?
# Outputs: 0

Alternativamente, você poderia permitir um número de linha específico de um arquivo se essa linha for improvável de mudar usando algo como o seguinte:

git secrets --add --allowed '/tmp/example:3:.*'
git secrets --scan /tmp/example && echo $?
# Outputs: 0

Tenha isso em mente ao criar padrões permitidos para garantir que seus padrões permitidos não sejam correspondidos inadvertidamente devido ao fato de o nome do arquivo estar incluído no texto do assunto contra o qual os padrões permitidos são correspondidos.

Ignorando validação

Use a opção --no-verify no caso de uma correspondência de falso positivo em um commit, merge ou mensagem de commit. Isso ignorará a execução do hook git e permitirá que você faça o commit ou merge.

Sobre

Autor: Michael Dowling <https://github.com/mtdowling>_
Rastreador de problemas: O código-fonte e o rastreador de problemas deste projeto podem ser encontrados em https://github.com/awslabs/git-secrets <https://github.com/awslabs/git-secrets>_
Agradecimentos especiais a Adrian Vatchinsky e Ari Juels da Cornell University por fornecer sugestões e feedback.

git-secrets

Mais Populares