Credactor

Encontre o segredo. Corrija-o. Faça commit limpo.

Scanners de segredos são bons em soar o alarme e não ajudam muito a apagá-lo. Eles entregam uma lista de credenciais vazadas e deixam a limpeza com você. O Credactor fecha o ciclo: ele encontra um segredo hardcoded e o reescreve no lugar, para que um vazamento passe da detecção à correção em um único comando.

Manter credenciais fora do código-fonte é uma prática de segurança básica, não opcional. O Credactor torna essa base barata de manter, na sua máquina antes de um commit ou no CI antes de um merge. Execute-o sozinho ou junto com os scanners em que você já confia.

# O Credactor encontra isto:
db_password = "h8Tq2vKp9mRz4Wd"

# Por padrão, ele reescreve o segredo como um sentinela que falha ruidosamente em tempo de execução:
db_password = "REDACTED_BY_CREDACTOR"

# Com --replace-with env, ele escreve uma referência que lê do ambiente:
db_password = os.environ["DB_PASSWORD"]

A redação reescreve arquivos na sua árvore de trabalho. Se um segredo já foi commitado, rotacione a chave e limpe o histórico também (por exemplo, com git filter-repo). Reescrever um arquivo não substitui a revogação de uma credencial vazada.

Por que o Credactor

• Redação, não apenas detecção. A maioria dos scanners para na descoberta. O Credactor substitui o segredo no lugar: um sentinela ruidoso REDACTED_BY_CREDACTOR que falha em tempo de execução por padrão, ou uma referência de variável de ambiente ciente da linguagem (Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP e shell), como os.environ["KEY"]. A substituição é código válido. Se o arquivo ainda não incluir o import correspondente (por exemplo, import os), adicione-o.
• Seguro por padrão. Escritas atômicas, backups automáticos .bak, proteções de limite de symlink e permissões de arquivo, e mascaramento completo de segredos em toda saída. Se um backup seguro não puder ser gravado, o Credactor pula o arquivo em vez de reescrevê-lo às cegas, e uma falha no meio da escrita deixa o original intacto.
• Zero dependências em tempo de execução. Biblioteca padrão Python 3.11+ pura, mais um extra opcional para codificações não UTF-8.
• Feito para o pipeline. Saída SARIF para GitHub Code Scanning, um gate --ci somente leitura com códigos de saída precisos, um hook de pre-commit (beta) e ingestão de relatórios Gitleaks ou TruffleHog. Detecte com Gitleaks ou TruffleHog, corrija com o Credactor.

Instalação

pip install credactor

Requer Python 3.11+. Sem outras dependências. Funciona em Linux, macOS e Windows (testado em CI no Linux e Windows).

A partir do código-fonte:

git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .

credactor então funciona a partir de qualquer diretório.

Início rápido

Execute --dry-run primeiro e revise as descobertas antes de redigir. Falsos positivos são possíveis, e sob --fix-all um falso positivo é reescrito. Suprima valores conhecidos como seguros com # credactor:ignore ou uma entrada .credactorignore.

credactor --dry-run .                 # escaneia, não altera nada
credactor .                           # escaneia e redige interativamente (s/n por descoberta)
credactor --fix-all .                 # redige tudo após uma confirmação
credactor --fix-all --yes .           # redige não interativamente (CI / scripts)
credactor --ci .                      # gate somente leitura: sai com 1 em descobertas
credactor --replace-with env .        # redige para referências de variáveis de ambiente em vez do sentinela

Hook de pre-commit (beta)

A integração do hook está em beta. Execute credactor --dry-run . manualmente antes de confiar apenas nele.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.6.0   # fixe na tag da versão mais recente
    hooks:
      - id: credactor

Detecção

O Credactor detecta os tipos de credenciais que mais vazam e atribui a cada um uma severidade para que você possa fazer triagem rapidamente.

Tokens determinísticos de provedores (os prefixos acima) são sinalizados independentemente da entropia. Detectores heurísticos (JWTs, strings de conexão, hex, Base64) devem superar um piso de entropia. Hex ou Base64 isolado é sinalizado apenas quando entre aspas. Um valor de alta entropia sem aspas é capturado apenas em uma variável com nome de credencial, o que poupa SHAs e checksums do git. Para as regras completas de detecção e severidade, consulte o Manual.

O conjunto de regras nativo do Credactor é mais restrito que o de um scanner dedicado, e alguns formatos de provedores (por exemplo, SendGrid, Twilio e webhooks do Slack) não são detectados. Sua vantagem é a correção: combine-o com Gitleaks ou TruffleHog para a detecção mais ampla, ou execute-o sozinho.

Combine com outro scanner, redija tudo

O Credactor funciona sozinho e fica mais forte em companhia. Já usa Gitleaks ou TruffleHog? Passe o relatório deles para o Credactor e ele redige o conjunto combinado, deduplicado contra suas próprias descobertas (em sobreposição, a maior severidade vence). Uma única passada de correção cobre seu scan e o deles:

gitleaks dir . -f json -r gitleaks.json
credactor --from-gitleaks gitleaks.json --fix-all --yes .

--from-gitleaks / --from-trufflehog (ou uma tabela [ingest] em .credactor.toml) exigem um diretório como alvo — aponte o Credactor para a mesma raiz em que o scanner foi executado. Os caminhos do relatório são resolvidos em relação ao diretório de trabalho, e um relatório é um instantâneo: regenere-o após redigir ou alterar a árvore. Consulte o guia de Integração com CI.

Mais recursos

• Redação interativa ou em lote; uma string de substituição personalizada via --replacement; --scan-history para escanear o histórico de commits do git
• Backups seguros: --secure-delete (sobrescreve e remove o .bak; eleva a barra contra recuperação casual, não é uma garantia forense) ou --secure-backup-dir para armazenar backups fora do repositório
• Allowlists inline # credactor:ignore e .credactorignore (globs, file:line, literais de valor)
• Configuração por repositório via .credactor.toml
• 29 tipos de arquivos de código/config/notas prontos para uso (.txt incluído); --scan-json para incluir JSON; --fail-on-error para falhar quando um arquivo não pode ser lido

Tipos de arquivo escaneados

.py .js .ts .jsx .tsx .sh .bash .env .cfg .ini .toml .yaml .yml .rb .go .java .php .cs .kt .tf .hcl .conf .config .properties .xml .pem .key .crt .txt

Mais variantes .env.* / .env-* (.env.local, .env.production) e arquivos SSH / de chave privada (id_rsa, id_dsa, id_ecdsa, id_ed25519), todos correspondidos pelo nome do arquivo em vez da extensão. JSON é excluído por padrão porque respostas de API produzem uma alta taxa de falsos positivos; adicione --scan-json para incluí-lo. Um arquivo nomeado diretamente na linha de comando é escaneado mesmo que sua extensão não esteja nesta lista.

Códigos de saída

Endurecimento da cadeia de suprimentos

Uma ferramenta de segurança deve ser segura de instalar, não apenas segura de executar. O pipeline de build e release do Credactor é endurecido de ponta a ponta; detalhes completos no documento de Segurança.

• Zero dependências em tempo de execução. Um pip install credactor padrão não puxa pacotes de terceiros (apenas o extra opcional [encoding]), então não há nada a verificar no momento da instalação.
• Toolchain com hash fixado. Builds de CI e release instalam a partir de um lockfile --require-hashes, incluindo o backend de build (python -m build --no-isolation contra um setuptools fixado), para que uma dependência adulterada falhe o build.
• Artefatos verificados byte a byte contra o código-fonte. Em cada push e antes de cada publicação, scripts/audit_wheel.py compara o wheel e o sdist com o código-fonte commitado byte a byte (sha256 vs git HEAD); qualquer arquivo adicionado, ausente ou alterado falha o gate, para que uma etapa de build não possa injetar código despercebido.
• CI com SHA fixado e privilégio mínimo. GitHub Actions fixam em SHAs de commit, e os tokens dos workflows permanecem estreitos — contents: read por padrão, id-token: write apenas para o job de publicação.

Documentação

Licença

Apache 2.0. Consulte LICENSE.