nccgroup/secretscrubProcessa a saída SARIF de ferramentas de análise estática para detectar e mascarar segredos embutidos no código-fonte, criando uma cópia limpa sem os segredos originais.
O SecretScrub vai eliminar todos os seus segredos sujos embutidos no código. Este script processa arquivos no formato de arquivo SARIF, que é gerado por várias ferramentas de análise estática. A ferramenta examina um diretório no sistema de arquivos e cria uma nova cópia do diretório com todas as ocorrências de segredos detectadas nos arquivos SARIF mascaradas. Como os segredos geralmente residem nos históricos do Git, o diretório .git é omitido da cópia resultante.
Embora o SARIF seja um formato padrão do setor, existem variações na saída SARIF produzida por várias ferramentas. Como resultado, as únicas ferramentas atualmente suportadas são as seguintes.
| Ferramenta | Versão | Comentários |
|---|---|---|
| Trivy | 0.37.0 | |
| Gitleaks | 8.15.2 | Só funciona com relatórios gerados usando a opção --no-git para examinar um sistema de arquivos, mas não o repositório Git subjacente, se houver um. |
| ccs | 1d055c542dbdb6e7b96279d4df03ea9b556eb27a | A saída do Ccs deve ser pré-processada para o formato SARIF usando o script ccs2sarif.py acompanhante. |
| cq | 011697a9e371e37a6ac9f714b3980672bc6108e7 | A saída do CQ deve ser pré-processada para o formato SARIF usando o script cq2sarif.py acompanhante. Como a saída do CQ pode ser muito ruidosa, é recomendável realizar a operação de mascaramento separadamente ou nomear os arquivos de modo que o arquivo CQ apareça por último no diretório. |
| BinDetect | Uma ferramenta integrada que detecta arquivos binários que normalmente passam despercebidos por outras ferramentas orientadas a texto. |
Devido às variações na saída SARIF, é possível que a saída gerada por versões futuras da ferramenta não funcione corretamente.
As dependências estão listadas no arquivo requirements.txt. Em resumo, os seguintes pacotes são necessários:
| Pacote |
|---|
$ python secretscrub.py --input <path> --srcdir <path> --outdir <path> [--report <path>]
$ python secretscrub.py --analyse-with <analysis-tool-list> --srcdir <path> --outdir <path> [--report <path>]
NOTA: Para funcionar, as ferramentas devem estar presentes e instaladas no sistema atual:
A imagem Docker criada a partir desta árvore de código-fonte inclui a ferramenta SecretScrub e cópias das ferramentas Trivy, GitLeaks, ccs e cq.
Se tiver sido criada com a tag secretscrub:latest, o seguinte comando iniciará uma operação completa de análise e mascaramento com um relatório correspondente.
sudo docker run -it -v <source-path>:/src:ro -v <output-path>:/out secretscrub:latest --analyse-with trivy,gitleaks,bindetect
Observe que isso envolve mapear dois volumes dentro do contêiner. O primeiro -- <source-path> -- deve conter o código-fonte original, sem mascaramento. O segundo -- <output-path> -- receberá a saída mascarada e o relatório.
Os exemplos a seguir pressupõem que o código-fonte esteja armazenado em um subdiretório chamado src e que o SecretScrub esteja instalado em um subdiretório chamado tools.
$ python tools/secretscrub.py --analse-with trivy,gitleaks,bindetect --srcdir src --outdir src-redacted
sudo docker run -it -v <source-path>:/src:ro -v <output-path>:/out secretscrub:latest --analyse-with trivy,gitleaks,bindetect
| Versão |
|---|
| asn1 | 2.7.0 |
| filetype | 1.2.0 |
| py7zr | 0.20.5 |
| pyzipper | 0.3.6 |
| regex | 2023.5.5 |
| sarif-tools | 1.0.0 |
| Parâmetro | Definição |
|---|
| input | O local dos resultados SARIF que devem ser processados. Pode conter vários arquivos SARIF gerados por diferentes ferramentas suportadas. |
| srcdir | O local do código-fonte original que foi examinado para produzir os resultados CQ que devem ser processados. |
| outdir | O local onde os arquivos de origem mascarados devem ser armazenados. |
| placeholder | O espaço reservado a ser inserido no lugar de todos os segredos detectados. Ele aceita as seguintes substituições: - ${tool} O nome da ferramenta usada para detectar o segredo- ${rule} O nome da regra usada para detectar o segredo- ${regex} A expressão regular associada à regra usada para detectar o segredo- ${yaml} Uma estrutura no estilo de fluxo YAML contendo (se conhecidos) apenas os nomes da ferramenta e da regra usadas para detectar o segredo- ${yaml_regex} Uma estrutura no estilo de fluxo YAML contendo (se conhecidos) os nomes da ferramenta e da regra e a expressão regular usada para detectar o segredo |
| process-archives | Um sinalizador para indicar |
| report | O local e o nome de um relatório CSV a ser gerado contendo detalhes dos segredos mascarados. |
| report-encryption | Se um arquivo de relatório for gerado, o método de criptografia a ser usado. Valores possíveis: none, zip-aes256. Padrão: zip-aes256 |
| log-level | O nível de registro (log) usado para a saída da ferramenta. Valores possíveis: critical, fatal, error, warning, info, debug. Padrão: info |
| Parâmetro | Definição |
|---|
| analyse-with | Uma lista separada por vírgulas de ferramentas a serem invocadas. Ela pode incluir qualquer uma das seguintes: trivy, gitleaks, ccs. cq, bindetect |
| srcdir | O local do código-fonte original que foi examinado para produzir os resultados CQ que devem ser processados. |
| outdir | O local onde os arquivos de origem mascarados devem ser armazenados. |
| placeholder | O espaço reservado a ser inserido no lugar de todos os segredos detectados. Ele aceita as seguintes substituições: - ${tool} O nome da ferramenta usada para detectar o segredo- ${rule} O nome da regra usada para detectar o segredo- ${regex} A expressão regular associada à regra usada para detectar o segredo- ${yaml} Uma estrutura no estilo de fluxo YAML contendo (se conhecidos) apenas os nomes da ferramenta e da regra usadas para detectar o segredo- ${yaml_regex} Uma estrutura no estilo de fluxo YAML contendo (se conhecidos) os nomes da ferramenta e da regra e a expressão regular usada para detectar o segredo |
| report | O local e o nome de um relatório CSV a ser gerado contendo detalhes dos segredos mascarados. |
| report-encryption | Se um arquivo de relatório for gerado, o método de criptografia a ser usado. Valores possíveis: none, zip-aes256. Padrão: zip-aes256 |
| log-level | O nível de registro (log) usado para a saída da ferramenta. Valores possíveis: critical, fatal, error, warning, info, debug. Padrão: info |
| Ferramenta | Comentários |
|---|
| Trivy | O comando trivy deve estar instalado e acessível no PATH. |
| GitLeaks | O comando gitleaks deve estar instalado e acessível no PATH. |
| ccs | O arquivo ccs.py deve estar localizado em um subdiretório chamado ccs dentro do diretório que contém o arquivo secretscrub.py. |
| cq | Os arquivos cq.py e fn.py devem estar localizados em um subdiretório chamado cq dentro do diretório que contém o arquivo secretscrub.py. |
| bindetect | Atualmente, isso está incluído no secretscrub e nenhuma instalação adicional é necessária. |