
Digitalize. Redija. Faça commit limpo.
[](https://pypi.org/project/credactor/)
[](https://github.com/rxb06/credactor/actions/workflows/ci.yml)
[](https://github.com/rxb06/credactor/blob/main/LICENSE)
# Credactor
**Encontre o segredo. Corrija-o. Faça commit limpo.**
A maioria dos scanners de segredos para no alerta: você recebe uma lista de credenciais vazadas e a limpeza é por sua conta. O Credactor encontra segredos embutidos no código e os reescreve no próprio local, de modo que um vazamento na sua árvore de trabalho passa de encontrado a corrigido com um único comando. Ele roda na sua máquina, como um hook de pré-commit ou como um gate de CI, e também pode corrigir o que o Gitleaks, o TruffleHog ou o Betterleaks encontram.
<img alt="Credactor: escaneie, redija, faça commit limpo" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="100%" />
```python
# Before
db_password = "h8Tq2vKp9mRz4Wd"
# credactor --fix-all . (default: a sentinel that fails loudly at runtime)
db_password = "REDACTED_BY_CREDACTOR"
# credactor --replace-with env --fix-all . (read it from the environment)
db_password = os.environ["DB_PASSWORD"]
```
> **A redação limpa sua árvore de trabalho.** Ela não revoga a credencial e
> não toca no histórico do git. Se um segredo já foi commitado ou compartilhado, rotacione-o
> e reescreva o histórico se precisar removê-lo de lá também (por exemplo, com
> `git filter-repo`).
## Por que o Credactor
- **Ele corrige, não apenas sinaliza.** Cada achado é substituído no local por um
sentinel, seu próprio marcador ou uma consulta de variável de ambiente na linguagem
do próprio arquivo.
- **Escritas cuidadosas.** Cada edição é planejada em memória, com backup prévio (modo
`0600`), gravada em um arquivo temporário e renomeada para o local. Um arquivo que mudou
durante a execução, um caminho que sai da raiz de varredura ou um bloco de chave privada é
ignorado com um aviso, e seu achado permanece reportado.
- **Funciona com o scanner que você já executa.** Alimente-o com um relatório do Gitleaks, TruffleHog ou
Betterleaks e ele corrige os achados deles e os seus em uma única
passagem deduplicada.
- **Feito para pipelines.** Um gate `--ci` somente leitura com códigos de saída claros, SARIF
2.1.0 com localizações de linha e coluna para o GitHub Code Scanning, uma GitHub Action
e um hook de pre-commit. Os segredos são mascarados em todos os formatos de relatório, e a saída
de texto é limpa para que um arquivo escaneado não possa injetar sequências de escape ou comandos
de workflow de CI no seu terminal ou log.
- **Releases verificadas contra seu código-fonte.** Biblioteca padrão pura do Python 3.11+ sem
dependências de runtime. Antes de uma release chegar ao PyPI, cada
arquivo do Credactor no wheel e no sdist é comparado byte a byte com o
código-fonte marcado, e os metadados do pacote devem corresponder ao `pyproject.toml` (veja
[Endurecimento da cadeia de suprimentos](#supply-chain-hardening)).
Onde ele não é a ferramenta certa por si só: suas regras integradas cobrem os
formatos de credenciais que vazam com mais frequência, em vez de centenas de provedores, e
ele não verifica se um segredo está ativo. Uma execução limpa significa que nada correspondeu
às suas regras, não que o código não contenha segredos. Combine-o com um scanner dedicado
para amplitude (veja [Traga seu próprio scanner](#bring-your-own-scanner)).
## Instalação
```bash
pip install credactor
```
Com o [uv](https://docs.astral.sh/uv/), instale-o como uma ferramenta ou execute-o uma vez
sem instalá-lo:
```bash
uv tool install credactor
uvx credactor --dry-run .
```
Ou com Homebrew no macOS e Linux:
```bash
brew install rxb06/tap/credactor
```
Requer Python 3.11 ou mais recente. Testado em CI no Linux e Windows, Python 3.11 a
3.13. Para arquivos em codificações diferentes de UTF-8, Latin-1 ou UTF-16 simples, adicione
o extra opcional: `pip install 'credactor[encoding]'` ou
`uv tool install 'credactor[encoding]'` (a fórmula do Homebrew o inclui).
## Início rápido
**1. Veja o que ele encontra.** Nada é alterado.
```bash
credactor --dry-run .
```
```text
======================================================================
CREDENTIAL SCAN REPORT -- 2 finding(s) in 1 file(s)
======================================================================
FILE: config.py
────────────────────────────────────────────────────────────
Line 3 [HIGH] [variable:db_password]
db_password = "h8Tq[REDACTED]"
Line 4 [CRITICAL] [pattern:AWS access key]
aws_key = "AKIA[REDACTED]"
```
Os relatórios mostram apenas os primeiros quatro caracteres de cada segredo.
**2. Corrija-os.** Revise primeiro as descobertas: `--fix-all` reescreve todas elas,
incluindo os falsos positivos. Para manter uma, adicione `# credactor:ignore` à sua linha
(consulte [Suprimir falsos positivos](#suppress-false-positives)) ou corrija
interativamente e responda `n`. Antes de cada arquivo ser alterado, uma cópia `.bak` é
gravada ao lado dele para que você possa desfazer.
```bash
credactor . # ask y/N for each finding (needs a terminal)
credactor --fix-all . # fix all after one confirmation
credactor --fix-all --yes . # fix all, no prompt (scripts)
credactor --replace-with env --fix-all . # environment lookups instead of the sentinel
```
O modo Env grava a consulta, não o import: adicione `import os` ou o
equivalente da sua linguagem se o arquivo não o tiver. No Windows Git Bash, execute o modo interativo
como `winpty credactor .`.
**3. Verifique e depois limpe os backups.** Cada `.bak` ainda contém o segredo
original, e o Credactor nunca edita seu `.gitignore`, então um simples `git add .`
o colocaria no stage.
```bash
diff config.py.bak config.py # check what changed
cp config.py.bak config.py # undo
```
Adicione `*.bak` e `*.credactor.tmp` ao `.gitignore` e exclua os backups quando
estiver satisfeito. Para manter os backups fora da árvore desde o início, passe
`--secure-backup-dir DIR` (um diretório fora do repositório) na execução de correção.
`--secure-delete` apaga cada backup, o que deixa o git como seu único
desfazer.
## Comandos em resumo
| Comando | O que faz | Altera arquivos |
|---|---|---|
| `credactor --dry-run .` | Relata as descobertas | Não |
| `credactor .` | Revisa e corrige uma descoberta por vez | Sim, com `y` |
| `credactor --fix-all .` | Corrige todas as descobertas após uma confirmação | Sim |
| `credactor --ci .` | Gate: sai com 1 se houver descobertas | Nunca |
| `credactor --staged --ci .` | Gate apenas no que está em stage para commit | Nunca |
| `credactor --scan-history .` | Escaneia os últimos 100 commits que alteraram arquivos | Nunca |
| `credactor --ci -f sarif . > results.sarif` | SARIF 2.1.0 para Code Scanning | Nunca |
| `credactor --ci -f json . > findings.json` | Relatório legível por máquina | Nunca |
Cada flag e combinação está no
[Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md).
## Use no pre-commit e no CI
### Hook de pre-commit
```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rxb06/credactor
rev: v2.7.5
hooks:
- id: credactor
```
```bash
pre-commit install
```
Cada `git commit` então verifica o conteúdo preparado (staged) e é bloqueado se contiver uma credencial. O hook nunca reescreve arquivos. Ele requer pre-commit 3.2.0 ou mais recente; sem o framework, consulte o
[hook autônomo](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#standalone-git-hook).
### GitHub Action
```yaml
steps:
- uses: actions/checkout@v7
- uses: rxb06/[email protected]
```
A Action sempre é executada com `--ci`, portanto nunca reescreve o checkout. Os achados fazem a etapa falhar, assim como qualquer erro. Para reportar ao Code Scanning em vez de falhar:
```yaml
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v7
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
O [guia de integração com CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md)
lista todas as entradas e saídas da Action e cobre o GitLab CI e etapas de shell simples.
## Traga seu próprio scanner
Já usa Gitleaks, TruffleHog ou Betterleaks? Entregue o relatório ao Credactor
e ele corrige os achados deles junto com os seus, deduplicados (em um
duplicado, a severidade mais alta é mantida). Visualize primeiro com `--dry-run`, como para
uma varredura nativa.
```bash
gitleaks dir . -f json -r gl.json
credactor --from-gitleaks gl.json --fix-all --yes .
trufflehog filesystem . --no-verification --json > th.json
credactor --from-trufflehog th.json --fix-all --yes .
betterleaks dir . -f json -r bl.json
credactor --from-betterleaks bl.json --fix-all --yes .
```
Aponte o Credactor para o mesmo diretório em que o scanner foi executado e regenere o
relatório após as alterações na árvore. Um relatório contém todos os segredos que encontrou em
texto simples e não é escaneado por si só (`.json` requer `--scan-json`), portanto grave-o
fora do repositório ou exclua-o após a execução. Uma descoberta que o Credactor não consegue
posicionar com segurança (sem número de linha válido, um caminho sob `.git`, um valor curto demais para
ser correspondido sozinho) permanece reportada e nunca é gravada. Detalhes e versões suportadas estão no
[Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#external-scanner-ingestion).
## O que ele detecta
| Categoria | Exemplos | Severidade |
|---|---|---|
| Chaves de nuvem e SaaS | AWS (`AKIA…`, `ASIA…`), GCP (`AIza…`), Stripe live (`sk_live_…`, `rk_live_…`), Slack (`xoxb-…`, `xoxp-…`) | Crítica |
| Tokens de plataforma | GitHub (`ghp_`, `gho_`, `ghs_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`) | Crítica |
| Chaves privadas | Blocos PEM (`-----BEGIN … PRIVATE KEY-----`, incluindo os criptografados), blocos de chave privada PGP | Crítica |
| JWTs | Tokens de três segmentos `eyJ…` | Alta |
| Strings de conexão | URLs com credenciais embutidas (`scheme://user:pass@host`) | Alta |
| Variáveis de credenciais | `password = "…"`, `api_key = "…"`, `secret_key = "…"` | Alta, Média ou Baixa |
| Atributos XML | `<add key="Password" value="…" />` | Alta, Média ou Baixa |
| Chaves de teste do Stripe | `sk_test_…` | Média |
| Strings de alta entropia | hex entre aspas (32 a 64 caracteres) ou Base64 (60 ou mais) | Média ou Baixa |
Os tokens de provedores são correspondidos pelo seu formato, portanto são encontrados mesmo em
comentários e independentemente da sua aleatoriedade. As correspondências heurísticas também precisam parecer
suficientemente aleatórias, e um valor hex ou Base64 isolado só é reportado quando está entre
aspas ou atribuído a uma variável com nome de credencial, o que poupa SHAs do git e
checksums. Placeholders como `changeme`, consultas de ambiente e referências de template
não são sinalizados.
**Bom saber:**
- **Chaves privadas são reportadas, nunca reescritas.** Rotacione a chave e exclua o
bloco manualmente; `--fix-all` conta isso como falha.
- **O histórico é somente leitura e limitado.** `--scan-history` cobre os 100 commits
mais recentes que alteraram arquivos e avisa quando o repositório tem mais de
100 commits.
- **Um conjunto fixo de tipos de arquivo** é escaneado: 29 extensões de código, configuração e texto
mais `.env.*` e arquivos de chave SSH (`id_rsa` e similares). JSON requer
`--scan-json`, e qualquer outra coisa requer `extra_extensions` em
`.credactor.toml`. Um arquivo que você nomear diretamente é sempre escaneado.
- **Arquivos ignorados pelo git são pulados ao percorrer um diretório**, e isso geralmente
inclui um `.env` local. O relatório de texto os lista, mas `-f json` e
`-f sarif` não dizem nada sobre eles. Para verificar um, nomeie-o diretamente:
`credactor --dry-run .env`.
- **Alguns formatos estão fora do escopo nativamente**, por exemplo chaves SendGrid e Twilio
e webhooks do Slack, assim como segredos criados em tempo de execução e valores com menos de 8
caracteres.
As regras completas estão no
[Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity),
e o modelo de ameaças está no
[documento de Segurança](https://github.com/rxb06/credactor/blob/main/docs/security.md).
## Como ele reescreve
| `--replace-with` | Resultado | Use quando |
|---|---|---|
| `sentinel` (padrão) | `"REDACTED_BY_CREDACTOR"` | Você quer que qualquer coisa que ainda use o segredo falhe ruidosamente |
| `env` | `os.environ["DB_PASSWORD"]` | O valor deve vir do ambiente |
| `custom` | `"<seu marcador>"` via `--replacement` | Você tem sua própria convenção |
O modo Env grava a consulta na linguagem do arquivo: `os.environ[…]` em Python,
`process.env[…]` em JavaScript e TypeScript, `ENV[…]` em Ruby, e a forma
nativa em Go, Java, Kotlin e PHP. Todos os outros tipos de arquivo recebem um
placeholder `${VAR}`, que é uma consulta real apenas onde algo o expande (um
script de shell, um carregador `.env`, muitas ferramentas de configuração). Em C# ele permanece uma string simples,
e em Terraform é lido como uma referência que não existe, então a configuração
falha na validação; use o sentinela para ambos. O nome vem do achado:
`db_password` torna-se `DB_PASSWORD`, e um tipo de token conhecido recebe seu próprio nome,
então uma chave AWS torna-se `AWS_ACCESS_KEY` independentemente do nome da variável. Onde
uma consulta quebraria o código (dentro de uma string maior, por exemplo), o sentinela é
usado em vez disso.
## Suprimir falsos positivos
Na própria linha, em um comentário `#`, `//`, `/* */` ou `<!-- -->`:
```python
example_key = "AKIAIOSFODNN7EXAMPLE" # credactor:ignore
```
Ou em um `.credactorignore` na raiz da varredura:
```text
tests/fixtures/*
app/settings.py:42
```
Uma entrada pode ser um glob, um `file:line` ou um valor exato. Um valor que contenha
`.`, `/`, `?` ou `*` (uma URL, um JWT, Base64) deve ser escrito como
`value:<literal>`, ou é lido como um glob e não tem efeito. Os achados de um
relatório ingerido são filtrados apenas por `.credactorignore`: um
`credactor:ignore` inline não os impede. Limiares, diretórios ignorados e
tipos de ficheiro adicionais vão num
[`.credactor.toml`](https://github.com/rxb06/credactor/blob/main/docs/setup.md).
## Códigos de saída
| Código | Significado |
|---|---|
| `0` | Sem achados, ou todos corrigidos |
| `1` | Achados por resolver |
| `2` | Erro, como um caminho inválido, uma combinação de flags inválida, um relatório ilegível ou `--config` explícito, ou `--staged` / `--scan-history` fora de um repositório git |
Um achado por resolver nunca termina com 0. Um ficheiro que o Credactor não conseguiu ler é apenas um
aviso por predefinição, por isso adicione `--fail-on-error` a um gate que tem de ler todos os
ficheiros; este termina então com 2. A lista completa está no
[Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#exit-codes).
## Reforço da cadeia de abastecimento
Uma ferramenta que lê todos os segredos do seu repositório deve ser segura de instalar,
não apenas segura de executar. Vários pacotes populares lançaram versões maliciosas
depois de um atacante entrar no seu pipeline de build ou de publicação: uma
dependência de build adulterada, um token de upload roubado ou um ficheiro introduzido no arquivo
de lançamento. O pipeline de lançamento do Credactor tem uma verificação específica para cada um desses casos.
- **Sem dependências de runtime.** `pip install credactor` instala o Credactor e
nada mais (o extra opcional `[encoding]` adiciona `charset-normalizer`), pelo que
não há código de terceiros para verificar no momento da instalação.
- **Cada lançamento é verificado contra o seu código-fonte.** Na CI e novamente antes da
publicação, `scripts/audit_wheel.py` compara cada ficheiro no wheel e
sdist que vem do repositório byte a byte (sha256) com o
código-fonte commitado, e rejeita qualquer outra coisa além dos metadados do pacote,
que devem corresponder ao `pyproject.toml`. Um módulo extra ou alterado, uma dependência
injetada, um comando redirecionado ou um ficheiro que está no tarball mas não no
git fazem falhar o lançamento.
- **Builds com hashes fixados.** As builds de CI e de lançamento instalam as suas ferramentas com
`pip install --require-hashes`, incluindo o backend de build, pelo que uma dependência
adulterada faz falhar a build em vez de chegar ao pacote.
- **Sem token de upload no pipeline.** Os lançamentos vão para o PyPI através de publicação
trusted OIDC a partir de um ambiente `pypi` dedicado, com atestações Sigstore,
e apenas quando a versão do pacote corresponde à tag de lançamento. O pipeline
não armazena nenhum token PyPI de longa duração.
- **CI restrita.** Cada GitHub Action está fixada a um SHA de commit, os tokens de workflow
são por predefinição só de leitura, os checkouts não guardam credenciais e o Dependabot
propõe atualizações mensalmente.
- **A Action instala fora do seu checkout.** A GitHub Action instala o
Credactor a partir do diretório temporário do runner com pip em modo isolado
(`python -I`) e depois executa o comando instalado.
Estas verificações mostram que o que é publicado corresponde ao código-fonte commitado na
tag de lançamento. Não conseguem tornar esse código-fonte fiável nem proteger uma máquina de build
que já esteja comprometida; o
[documento de Segurança](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening)
tem todos os detalhes e limites.
## Segurança
Reporte uma vulnerabilidade de forma privada através das
[GitHub Security Advisories](https://github.com/rxb06/credactor/security/advisories/new),
não num issue público. O [SECURITY.md](https://github.com/rxb06/credactor/blob/main/SECURITY.md)
lista as versões suportadas, e o
[documento de Segurança](https://github.com/rxb06/credactor/blob/main/docs/security.md)
abrange o modelo de ameaças, cada medida de reforço e os limites conhecidos.
## Documentação
| Documento | O que contém |
|---|---|
| [Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | Cada flag, modo e combinação, com comportamento verificado |
| [Configuração](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | Instalação e `.credactor.toml` |
| [Integração com CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Pre-commit, a GitHub Action, outros sistemas de CI, ingestão |
| [Exemplos](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | Fluxos de trabalho comuns com saída |
| [Segurança](https://github.com/rxb06/credactor/blob/main/docs/security.md) | Modelo de ameaças, hardening, limites conhecidos |
| [Aviso legal](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | Uso seguro e garantia |
| [Changelog](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | Histórico de versões |
| [Contribuição](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | Configuração de desenvolvimento e pull requests |
## Licença
Apache 2.0. Consulte [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE).