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

Impedisce di committare password e altre informazioni sensibili in un repository git.

.. contents:: :depth: 2

Sinossi

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>]

Descrizione

git-secrets analizza commit, messaggi di commit e merge --no-ff per impedire l'aggiunta di segreti nei tuoi repository git. Se un commit, un messaggio di commit o qualsiasi commit in una cronologia di merge --no-ff corrisponde a uno dei tuoi pattern di espressioni regolari proibiti configurati, il commit viene rifiutato.

Installazione di git-secrets

git-secrets deve essere posizionato da qualche parte nel tuo PATH in modo che venga riconosciuto da git quando si esegue git secrets.

*nix (Linux/macOS)


Puoi usare il target ``install`` del Makefile fornito per installare ``git secrets`` e la pagina man.
Puoi personalizzare il percorso di installazione usando le variabili PREFIX e MANPREFIX.

::

    make install

Windows
~~~~~~~

Esegui lo script powershell ``install.ps1`` fornito. Questo copierà i file necessari
in una directory di installazione (``%USERPROFILE%/.git-secrets`` di default) e aggiungerà
la directory al ``PATH`` dell'utente corrente.

::

    PS > ./install.ps1

Homebrew (per utenti macOS)

brew install git-secrets

.. warning::

**Non hai ancora finito! DEVI installare i git hook per ogni repo in cui**
**desideri usare** ``git secrets --install``.

Ecco un rapido esempio di come assicurarsi che un repository git venga analizzato per segreti ad ogni commit::

cd /path/to/my/repo
git secrets --install
git secrets --register-aws

Configurazione avanzata

Aggiungi un template di configurazione se vuoi aggiungere hook a tutti i repository che inizializzerai o clonerai in futuro.

git secrets --register-aws --global

Aggiungi hook a tutti i tuoi repository locali.

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

Aggiungi provider personalizzati per analizzare le credenziali di sicurezza.

git secrets --add-provider -- cat /path/to/secret/file/patterns

Prima di rendere pubblico un repository

Con git-secrets è anche possibile analizzare un repository includendo tutte le revisioni:

git secrets --scan-history

Opzioni

Modalità operative


Ciascuna di queste opzioni deve apparire per prima sulla riga di comando.

``--install``
    Installa i git hook per un repository. Una volta che gli hook sono installati per un repository git,
    i commit e i merge non-fast-forward per quel repository verranno impediti
    di committare segreti.

``--scan``
    Analizza uno o più file alla ricerca di segreti. Quando un file contiene un segreto, il
    testo corrispondente dal file analizzato verrà scritto su stdout e lo
    script terminerà con un codice di uscita diverso da zero. Ogni riga corrispondente verrà scritta con
    il nome del file che ha corrisposto, due punti, il numero di riga che ha corrisposto,
    due punti e poi la riga di testo che ha corrisposto. Se non vengono forniti file,
    vengono analizzati tutti i file restituiti da ``git ls-files``.

``--scan-history``
    Analizza il repository includendo tutte le revisioni. Quando un file contiene un segreto, il
    testo corrispondente dal file analizzato verrà scritto su stdout e lo
    script terminerà con un codice di uscita diverso da zero. Ogni riga corrispondente verrà scritta con
    il nome del file che ha corrisposto, due punti, il numero di riga che ha corrisposto,
    due punti e poi la riga di testo che ha corrisposto.

``--list``
    Elenca la configurazione di ``git-secrets`` per il repo corrente o nella configurazione git globale.

``--add``
    Aggiunge un pattern proibito o consentito.

``--add-provider``
    Registra un provider di segreti. I provider di segreti sono eseguibili che quando
    invocati generano pattern proibiti che ``git-secrets`` deve trattare come
    proibiti.

``--register-aws``
    Aggiunge pattern AWS comuni alla configurazione git e garantisce che le chiavi
    presenti in ``~/.aws/credentials`` non vengano trovate in nessun commit. Vengono aggiunti i seguenti
    controlli:

    - ID di chiave di accesso AWS tramite ``(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}``
    - Chiavi API Amazon Bedrock. A lunga durata tramite ``ABSK[A-Za-z0-9+/]{109,}=*`` e a breve durata tramite ``bedrock-api-key-YmVkcm9jay5hbWF6b25hd3MuY29t``
    - Assegnazioni di chiave segreta di accesso AWS tramite ":" o "=" circondate da virgolette opzionali
    - Assegnazioni di ID account AWS tramite ":" o "=" circondate da virgolette opzionali
    - Pattern consentiti per chiavi AWS di esempio (``AKIAIOSFODNN7EXAMPLE`` e ``wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY``)
    - Credenziali note da ``~/.aws/credentials``

    .. note::

        Sebbene i pattern registrati da questo comando dovrebbero intercettare la maggior parte
        delle istanze di credenziali AWS, questi pattern **non** garantiscono di intercettarle
        **tutte**. ``git-secrets`` dovrebbe essere usato come un mezzo aggiuntivo di
        assicurazione: devi comunque fare la dovuta diligenza per assicurarti di non
        committare credenziali in un repository.

``--aws-provider``
    Provider di segreti che genera le credenziali trovate in un file INI. Puoi
    opzionalmente fornire il percorso di un file INI.


Opzioni per ``--install``

-f, --force Sovrascrive gli hook esistenti se presenti.

<target-directory> Quando fornito, installa i git hook nella directory specificata. La directory corrente viene assunta se <target-directory> non viene fornito.

Se la ``<target-directory>`` fornita non si trova in un repository git, la
directory verrà creata e gli hook verranno posizionati in
``<target-directory>/hooks``. Questo può essere utile per creare directory template git
da usare con ``git init --template <target-directory>``.

Puoi eseguire ``git init`` su un repository già inizializzato.
Dalla documentazione di `git init <https://git-scm.com/docs/git-init>`_:

    Dalla documentazione di git: Eseguire ``git init`` in un repository esistente
    è sicuro. Non sovrascriverà cose già presenti. Il
    motivo principale per rieseguire ``git init`` è raccogliere template appena aggiunti
    (o spostare il repository in un altro posto se viene fornito ``--separate-git-dir``).

Vengono installati i seguenti git hook:

1. ``pre-commit``: Usato per verificare se uno qualsiasi dei file modificati nel commit
   utilizza pattern proibiti.
2. ``commit-msg``: Usato per determinare se un messaggio di commit contiene un
   pattern proibito.
3. ``prepare-commit-msg``: Usato per determinare se un commit di merge
   introdurrà una cronologia che contiene un pattern proibito in qualsiasi punto.
   Tieni presente che questo hook viene invocato solo per merge non fast-forward.

.. note::

    Git permette solo l'esecuzione di un singolo script per hook. Se il
    repository contiene sottodirectory in stile Debian come ``pre-commit.d``
    e ``commit-msg.d``, allora i git hook verranno installati in queste
    directory, il che presuppone che tu abbia configurato gli hook corrispondenti
    per eseguire tutti gli script presenti in queste directory. Se
    queste sottodirectory git non sono presenti, allora i git hook verranno
    installati nella directory ``.git/hooks`` del repo git.

Esempi ^^^^^^

Installa i git hook nella directory corrente::

cd /path/to/my/repository
git secrets --install

Installa i git hook in un repository diverso dalla directory corrente::

git secrets --install /path/to/my/repository

Crea un template git che abbia git-secrets installato, e poi copia quel template in un repository git::

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

Sovrascrivi gli hook esistenti se presenti::

git secrets --install -f

Opzioni per --scan


``-r, --recursive``
    Analizza i file forniti ricorsivamente. Se viene incontrata una directory, la
    directory verrà analizzata. Se ``-r`` non viene fornito, le directory verranno
    ignorate.

    ``-r`` non può essere usato insieme a ``--cached``, ``--no-index`` o
    ``--untracked``.

``--cached``
    Cerca blob registrati nel file indice.

``--no-index``
    Cerca file nella directory corrente che non sono gestiti da git.

``--untracked``
    Oltre a cercare nei file tracciati nell'albero di lavoro,
    ``--scan`` cerca anche nei file non tracciati.

``<files>...``
    Il percorso di uno o più file su disco da analizzare per segreti.

    Se non vengono forniti file, vengono analizzati tutti i file restituiti da ``git ls-files``.


Esempi
^^^^^^

Analizza tutti i file nel repo::

    git secrets --scan

Analizza un singolo file alla ricerca di segreti::

    git secrets --scan /path/to/file

Analizza una directory ricorsivamente alla ricerca di segreti::

    git secrets --scan -r /path/to/directory

Analizza più file alla ricerca di segreti::

    git secrets --scan /path/to/file /path/to/other/file

Puoi analizzare usando wildcard::

    git secrets --scan /path/to/directory/*

Analizza da stdin::

    echo 'hello!' | git secrets --scan -


Opzioni per ``--list``

--global Elenca solo la configurazione di git-secrets nella configurazione git globale.

Opzioni per --add


``--global``
    Aggiunge pattern alla configurazione git globale.

``-l, --literal``
    Escapa i caratteri speciali delle espressioni regolari nel pattern fornito in modo
    che il pattern venga cercato letteralmente.

``-a, --allowed``
    Contrassegna il pattern come consentito invece che proibito. I pattern consentiti vengono
    usati per filtrare i falsi positivi.

``<pattern>``
    Il pattern regex da cercare.


Esempi
^^^^^^

Aggiunge un pattern proibito al repo corrente::

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

Aggiunge un pattern proibito alla configurazione git globale::

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

Aggiunge una stringa che viene cercata letteralmente (``+`` è escapato)::

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

Aggiungi un pattern consentito::

    git secrets --add -a 'allowed pattern'


Opzioni per ``--register-aws``

--global Aggiunge variabili di configurazione specifiche AWS alla configurazione git globale.

Opzioni per --aws-provider


``[<credentials-file>]``
    Se fornito, specifica il percorso personalizzato di un file INI da analizzare. Se non
    fornito, viene assunto ``~/.aws/credentials``.


Opzioni per ``--add-provider``

--global Aggiunge il provider alla configurazione git globale.

<command> Comando del provider da invocare. Quando invocato, ci si aspetta che il comando scriva pattern proibiti separati da nuove righe su stdout. Eventuali argomenti aggiuntivi forniti vengono passati al comando.

Esempi ^^^^^^

Registra un provider di segreti con argomenti::

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

Estrae segreti da un file::

git secrets --add-provider -- cat /path/to/secret/file/patterns

Definizione di pattern proibiti

Le espressioni regolari compatibili con egrep vengono utilizzate per determinare se un commit o un messaggio di commit contiene pattern proibiti. Queste espressioni regolari sono definite usando il comando git config. È importante notare che sistemi diversi usano versioni diverse di egrep. Ad esempio, quando si esegue su macOS, utilizzerai una versione diversa di egrep rispetto a quando esegui su qualcosa come Ubuntu (BSD vs GNU).

Puoi aggiungere pattern di espressioni regolari proibiti alla tua configurazione git usando git secrets --add <pattern>.

Ignorare i falsi positivi

A volte un'espressione regolare potrebbe corrispondere a falsi positivi. Ad esempio, gli SHA dei commit git assomigliano molto alle chiavi di accesso AWS. Puoi specificare molti pattern di espressioni regolari diversi come falsi positivi usando il seguente comando:

git secrets --add --allowed 'my regex pattern'

Puoi anche aggiungere pattern di espressioni regolari per filtrare i falsi positivi in un file .gitallowed situato nella directory radice del repository. Le righe che iniziano con # vengono saltate (riga di commento) e anche le righe vuote vengono saltate.

In primo luogo, git-secrets estrarrà tutte le righe da un file che contengono una corrispondenza proibita. Nei risultati della corrispondenza sarà incluso il percorso completo del nome del file che è stato abbinato, seguito da ':', seguito dal numero di riga che è stato abbinato, seguito dall'intera riga del file che è stata abbinata da un pattern di segreto. Poi, se hai definito espressioni regolari consentite, git-secrets controllerà per vedere se tutte le righe abbinate corrispondono ad almeno una delle tue espressioni regolari consentite registrate. Se tutte le righe che sono state contrassegnate come segreto vengono annullate da una corrispondenza consentita, allora il testo in esame non contiene alcun segreto. Se una qualsiasi delle righe abbinate non è abbinata da un'espressione regolare consentita, allora git-secrets fallirà il commit/merge/messaggio.

.. important::

Proprio come è una cattiva pratica aggiungere pattern proibiti troppo
avidi, è anche una cattiva pratica aggiungere pattern consentiti troppo
permissivi. Assicurati di testare i tuoi pattern usando chiamate ad hoc a
``git secrets --scan $filename`` per assicurarti che funzionino come previsto.

Provider di segreti

A volte vuoi controllare una corrispondenza esatta di pattern rispetto a un insieme di segreti noti. Ad esempio, potresti voler garantire che nessuna credenziale presente in ~/.aws/credentials appaia mai in un commit. In questi casi, è meglio lasciare questi segreti in una singola posizione piuttosto che disseminarli tra più repository git nelle configurazioni git. Puoi usare "provider di segreti" per recuperare questi tipi di credenziali. Un provider di segreti è un eseguibile che quando invocato produce pattern proibiti separati da nuove righe.

Puoi aggiungere provider di segreti usando il comando --add-provider::

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

Nota l'uso di --. Questo garantisce che eventuali argomenti associati al provider vengano passati al provider ogni volta che viene invocato durante l'analisi dei segreti.

Esempio guidato

Diamo un'occhiata a un esempio. Dato il seguente testo di esempio (memorizzato in /tmp/example)::

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

E i seguenti pattern registrati:

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

Eseguendo git secrets --scan /tmp/example, il risultato produrrà il seguente output di errore::

/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

Analizzando, il valore del pattern proibito password\s*=\s*.+ corrisponderà alle seguenti righe::

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

...Ma la prima corrispondenza verrà filtrata perché corrisponde all'espressione regolare consentita di ex@mplepassword. Poiché esiste ancora una riga rimanente che non ha corrisposto, viene considerata un segreto.

Poiché le righe corrispondenti sono poste su righe che iniziano con il nome del file e il numero di riga (ad esempio /tmp/example:3:...), puoi creare pattern consentiti che tengano conto dei nomi di file e dei numeri di riga nell'espressione regolare. Ad esempio, potresti inserire nella whitelist un intero file usando qualcosa come::

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

In alternativa, potresti consentire un numero di riga specifico di un file se quella riga è improbabile che cambi usando qualcosa come:

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

Tieni presente questo quando crei pattern consentiti per assicurarti che i tuoi pattern consentiti non vengano accidentalmente abbinati a causa del fatto che il nome del file è incluso nel testo di esempio rispetto al quale vengono abbinati i pattern consentiti.

Saltare la validazione

Usa l'opzione --no-verify in caso di falso positivo in un commit, merge o messaggio di commit. Questo salterà l'esecuzione dell'hook git e ti permetterà di effettuare il commit o il merge.

Informazioni

Autore: Michael Dowling <https://github.com/mtdowling>_
Issue tracker: Il codice sorgente e l'issue tracker di questo progetto si trovano su https://github.com/awslabs/git-secrets <https://github.com/awslabs/git-secrets>_
Un ringraziamento speciale ad Adrian Vatchinsky e Ari Juels dell'Università di Cornell per aver fornito suggerimenti e feedback.

git-secrets

Più Popolari