rxb06/credactorDigitalize. 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.**
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.
<img alt="Credactor: scan, redact, commit clean" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="1280" height="320" />
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.
```python
# 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
```bash
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:
```bash
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:
```bash
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`.
```bash
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.
```yaml
# .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
```yaml
- 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:
```yaml
- 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](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#github-action) 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](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity).
> 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:
```bash
gitleaks dir . -f json -r gitleaks.json
credactor --from-gitleaks gitleaks.json --fix-all --yes .
betterleaks dir . -f json -r betterleaks.json
credactor --from-betterleaks betterleaks.json --fix-all --yes .
```
`--from-gitleaks` / `--from-trufflehog` / `--from-betterleaks` (ou uma tabela `[ingest]` em `.credactor.toml`) requerem um diretório como alvo — aponte o Credactor para a mesma raiz contra a qual o scanner correu. Os caminhos dos relatórios são resolvidos em relação ao diretório de trabalho, e um relatório é um snapshot: regenere-o após redigir ou alterar a árvore. Consulte o [guia de Integração em CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md).
## Mais funcionalidades
- Redação interativa ou em lote; uma string de substituição personalizada via `--replacement`; `--scan-history` para analisar o histórico de commits do git
- Backups seguros: `--secure-delete` (sobrescreve e remove o `.bak`; eleva a fasquia contra recuperação casual, não é uma garantia forense) ou `--secure-backup-dir` para guardar backups fora do repositório
- Listas de permissões inline `# credactor:ignore` e `.credactorignore` (globs, `file:line`, literais de valor)
- Configuração por repositório via `.credactor.toml`
- 29 tipos de ficheiros de código/config/notas de origem (incluindo `.txt`); `--scan-json` para incluir JSON; `--fail-on-error` para falhar quando um ficheiro não pode ser lido
## Tipos de ficheiros analisados
> `.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 ficheiros SSH / de chave privada (`id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`), todos correspondidos pelo nome do ficheiro em vez da extensão. O JSON é excluído por predefinição porque as respostas de API produzem uma elevada taxa de falsos positivos; adicione `--scan-json` para o incluir. Um ficheiro nomeado diretamente na linha de comandos é analisado mesmo que a sua extensão não conste desta lista.
## Códigos de saída
| Código | Significado |
|---|---|
| `0` | Sem resultados, ou todos resolvidos |
| `1` | Resultados não resolvidos |
| `2` | Erro (por exemplo: caminho inválido, `--replacement` perigoso, `--ci --fix-all`, um relatório de ingestão em falta ou inválido, ou `--fail-on-error` com um ficheiro ilegível) |
## Reforço da cadeia de fornecimento
Uma ferramenta de segurança deve ser segura de instalar, não apenas segura de executar. O pipeline de build e release do Credactor é reforçado de ponta a ponta; detalhes completos no [documento de Segurança](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening).
- **Zero dependências de runtime.** Um `pip install credactor` predefinido não puxa nenhum pacote de terceiros (apenas o extra opcional `[encoding]`), pelo que não há nada a verificar no momento da instalação.
- **Toolchain com hashes fixados.** Os builds de CI e de release instalam a partir de um lockfile `--require-hashes`, incluindo o backend de build (`python -m build --no-isolation` contra um setuptools fixado), pelo que uma dependência adulterada falha o build.
- **Artefactos 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 ficheiro adicionado, em falta ou alterado falha o gate, pelo que um passo de build não pode injetar código sem ser notado.
- **CI com SHAs fixados e privilégio mínimo.** As GitHub Actions fixam-se a SHAs de commit, e os tokens dos workflows mantêm-se restritos — `contents: read` por predefinição, `id-token: write` apenas para o job de publicação.
## Documentação
| Documento | Descrição |
|----------|-------------|
| [Guia de Configuração](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | Instalação, configuração, integração CI/CD |
| [Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | Referência completa: cada flag, modo e combinação, comportamento de substituição e backup, deteção e severidade, códigos de saída e limitações (comportamento verificado por testes) |
| [Exemplos](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | Fluxos de trabalho comuns com saída |
| [Integração em CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Hooks de pre-commit, pipelines de CI |
| [Segurança](https://github.com/rxb06/credactor/blob/main/docs/security.md) | Modelo de ameaças, medidas de reforço, limitações conhecidas |
| [Changelog](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | Histórico de versões |
| [Contribuir](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | Configuração de desenvolvimento, estilo de código, processo de PR |
| [Aviso Legal](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | Limitações, utilização segura, garantia |
## Licença
Apache 2.0. Consulte [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE).