Credactor

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

Os scanners de segredos são bons a soar o alarme e não ajudam muito a apagá-lo. Entregam-lhe uma lista de credenciais expostas e deixam a limpeza por sua conta. O Credactor fecha o ciclo: encontra um segredo codificado e reescreve-o no local, para que uma fuga passe da deteção à correção num único comando.

Manter credenciais fora do código-fonte é uma prática de segurança de base, não opcional. O Credactor torna essa base barata de manter, na sua máquina antes de um commit ou em CI antes de um merge. Execute-o por si só, ou ao lado dos scanners em que 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 redação reescreve ficheiros na sua working tree. Se um segredo já foi commitado, rode a chave e limpe também o histórico (por exemplo, com git filter-repo). Reescrever um ficheiro não substitui a revogação de uma credencial exposta.

---

Porquê o Credactor

• Redação, não apenas deteção. A maioria dos scanners para na descoberta. O Credactor substitui o segredo no local: um sentinela ruidoso REDACTED_BY_CREDACTOR que falha em runtime por predefinição, ou uma referência a 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 ficheiro ainda não incluir o import correspondente (por exemplo import os), adicione-o.
• Seguro por predefinição. Escritas atómicas, backups .bak automáticos, proteções de fronteira de symlink e de permissões de ficheiro, e mascaramento total do segredo em todas as saídas. Se não for possível escrever um backup seguro, o Credactor ignora o ficheiro em vez de o reescrever às cegas, e uma falha a meio da escrita deixa o original intacto.
• Zero dependências de runtime. Biblioteca padrão pura de Python 3.11+, 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 só de leitura com códigos de saída precisos, um hook de pre-commit e ingestão de relatórios do Gitleaks, TruffleHog ou Betterleaks. Detete com o scanner que já executa, remedeie 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 em Linux e Windows).

Em macOS e Linux pode instalá-lo com Homebrew:

brew install rxb06/tap/credactor

A fórmula instala num virtualenv próprio e inclui o extra opcional [encoding], pelo que uma instalação via Homebrew também deteta segredos em ficheiros não-UTF-8. Um simples pip install credactor deixa esse extra de fora; adicione-o com pip install 'credactor[encoding]' se quiser a mesma cobertura.

A partir do código-fonte:

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

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

Início rápido

Execute primeiro --dry-run e reveja os resultados 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 em .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 de pre-commit

O hook faz o gate apenas ao conteúdo em stage, pelo que um segredo já commitado não é novamente sinalizado. Use credactor --scan-history . para verificar o que já está no repositório.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.7.4   # pin to the latest release tag
    hooks:
      - id: credactor

GitHub Action

- uses: rxb06/[email protected]

A action passa sempre --ci, pelo que reporta e faz o gate mas nunca reescreve o checkout. Os resultados falham o passo; defina fail-on-findings: false para reportar sem fazer o gate. Um erro falha o passo de qualquer forma.

Carregue para Code Scanning em vez de falhar nos resultados:

- uses: rxb06/[email protected]
  with:
    format: sarif
    upload-sarif: true
    fail-on-findings: false

O job precisa de permissions: security-events: write para o upload. Consulte o guia de integração em CI para todas as entradas, incluindo a ingestão de relatórios do Gitleaks, TruffleHog e Betterleaks.

Deteção

O Credactor deteta os tipos de credenciais que mais frequentemente ficam expostos e atribui a cada um uma severidade para que possa fazer triagem num relance.

Categoria	Exemplos	Severidade
Chaves de fornecedores cloud	AWS (AKIA…), GCP (AIza…), Stripe (sk_live_…), Slack (xoxb-…)	Crítica
Tokens de plataformas	GitHub (ghp_, github_pat_), GitLab (glpat-), npm (npm_), PyPI (pypi-)	Crítica
Chaves privadas	Blocos PEM (-----BEGIN … PRIVATE KEY-----)	Crítica
JWTs	Tokens de três segmentos eyJ…	Alta
Strings de conexão	URLs com credenciais inline (scheme://user:pass@host)	Alta
Variáveis de credenciais	password = "…", api_key = "…", secret_key = "…"	Alta/Média/Baixa
Atributos XML	<add key="Password" value="…" />	Alta/Média/Baixa
Strings de alta entropia	hex entre aspas (32–64 caracteres) / Base64 (60+ caracteres)	Média/Baixa

Tokens determinísticos de fornecedores (os prefixos acima) são sinalizados independentemente da entropia. Os detetores heurísticos (JWTs, strings de conexão, hex, Base64) têm de ultrapassar um limite de entropia. Hex ou Base64 isolados só são sinalizados quando entre aspas. Um valor de alta entropia sem aspas só é apanhado numa variável com nome de credencial, o que poupa SHAs e checksums do git. Para as regras completas de deteção e severidade, consulte o Manual.

O conjunto de regras nativo do Credactor é mais restrito do que o de um scanner dedicado, e alguns formatos de fornecedores (por exemplo SendGrid, Twilio e webhooks do Slack) não são detetados. A sua vantagem é a remediação: combine-o com Gitleaks, TruffleHog ou Betterleaks para a deteção mais ampla, ou execute-o por si só.

Combine-o com outro scanner, redija tudo

O Credactor é autónomo, e torna-se mais forte em companhia. Já executa Gitleaks, TruffleHog ou Betterleaks? Passe o relatório deles ao Credactor e ele redige o conjunto combinado, deduplicado contra os seus próprios resultados (em sobreposição, vence a severidade mais alta). Uma passagem de remediação cobre o seu scan e o deles: