Credactor

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

Scanners de segredos são bons em tocar o alarme, mas não ajudam muito a apagá-lo. Eles entregam uma lista de credenciais vazadas e deixam a limpeza para você. Credactor fecha o ciclo: ele encontra um segredo codificado e o reescreve no local, então um vazamento vai 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. Credactor torna essa base barata de manter, na sua máquina antes de um commit ou em CI antes de um merge. Execute-o sozinho ou junto com os scanners que você já confia.

# Credactor finds this:
db_password = "h8Tq2vKp9mRz4Wd"

# By default it rewrites the secret as a sentinel that fails loudly at runtime:
db_password = "REDACTED_BY_CREDACTOR"

# With --replace-with env, it writes a reference that reads from the environment:
db_password = os.environ["DB_PASSWORD"]

A substituição do segredo 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 Credactor

• Substituição, não apenas detecção. A maioria dos scanners para na descoberta. Credactor substitui o segredo no local: um sentinela REDACTED_BY_CREDACTOR que falha na 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 a importação correspondente (por exemplo import os), adicione-a.
• Seguro por padrão. Escritas atômicas, backups automáticos .bak, proteções de limite de link simbólico e permissões de arquivo, e mascaramento completo do segredo em cada saída. Se um backup seguro não puder ser escrito, 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 de tempo de execução. Biblioteca padrão Python 3.11+ pura, mais um extra opcional para codificações não UTF-8.
• Construído para o pipeline. Saída SARIF para GitHub Code Scanning, uma porta de entrada --ci somente leitura com códigos de saída precisos, um hook pre-commit (beta) e ingestão de relatórios Gitleaks ou TruffleHog (BETA, e mais por vir). Detecte com Gitleaks ou TruffleHog, corrija com Credactor.

Instalar

pip install credactor

Requer Python 3.11+. Nenhuma outra dependência. Executa em Linux, macOS e Windows (testado em CI em Linux e Windows).

A partir da 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 .                 # scan, change nothing
credactor .                           # scan, then redact interactively (y/n per finding)
credactor --fix-all .                 # redact everything after one confirmation
credactor --fix-all --yes .           # redact non-interactively (CI / scripts)
credactor --ci .                      # read-only gate: exit 1 on findings
credactor --replace-with env .        # redact to env-var references instead of the sentinel

Hook 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.5.0   # pin to the latest release tag
    hooks:
      - id: credactor

Detecção

Credactor detecta os tipos de credenciais que vazam com mais frequência e atribui a cada um uma gravidade para que você possa triar rapidamente.

Tokens de provedor determinísticos (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 isolados são sinalizados apenas quando entre aspas. Um valor de alta entropia não entre aspas é capturado apenas em uma variável nomeada como credencial, o que poupa SHAs e somas de verificação do git. Para as regras completas de detecção e gravidade, veja o Manual.

O conjunto de regras nativo do Credactor é mais restrito que o de um scanner dedicado, e alguns formatos de provedor (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 (BETA)

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 em relação às suas próprias descobertas (na sobreposição, a gravidade mais alta vence). Uma passagem de correção cobre sua varredura e a 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 alvo. Veja o Guia de Integração 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
• Listas de permissão inline # credactor:ignore e .credactorignore (globs, file:line, literais de valor)
• Configuração por repositório via .credactor.toml
• 29 tipos de arquivo fonte/config/notas prontos para uso (.txt incluso); --scan-json para incluir JSON; --fail-on-error para falhar quando um arquivo não puder ser lido

Tipos de arquivo escaneados

.py .js .ts .jsx .tsx .sh .bash .env .cfg .ini .toml .yaml .yml .rb .go .java

Além disso, variantes .env.* / .env-* (.env.local, .env.production) e arquivos SSH / 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 as 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 construção e lançamento do Credactor é endurecido de ponta a ponta; detalhes completos no documento de Segurança.

• Zero dependências de 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.
• Cadeia de ferramentas com hash fixo. As construções de CI e lançamento instalam a partir de um arquivo de bloqueio --require-hashes, com o backend de construção incluído (python -m build --no-isolation contra um setuptools fixado), então uma dependência adulterada falha na construção.
• Artefatos verificados byte a byte em relação à fonte. Em cada push e antes de cada publicação, scripts/audit_wheel.py compara o wheel e o sdist com a fonte commitada byte a byte (sha256 vs git HEAD); qualquer arquivo adicionado, ausente ou alterado falha na verificação, então uma etapa de construção não pode injetar código despercebida.
• CI com SHA fixo e privilégio mínimo. GitHub Actions fixam em SHAs de commit, e os tokens de fluxo de trabalho permanecem restritos — contents: read por padrão, id-token: write apenas para o job de publicação.

Documentação

Licença

Apache 2.0. Veja LICENSE.