rxb06/credactorСканируй. Редактируй. Коммить чисто.
[](https://pypi.org/project/credactor/)
[](https://github.com/rxb06/credactor/actions/workflows/ci.yml)
[](https://github.com/rxb06/credactor/blob/main/LICENSE)
# Credactor
**Найди секрет. Исправь его. Закоммить чисто.**
Сканеры секретов хорошо умеют бить тревогу, но мало помогают её устранить. Они выдают список утёкших учётных данных и оставляют уборку вам. Credactor замыкает цикл: он находит захардкоженный секрет и переписывает его на месте, так что утечка проходит путь от обнаружения до исправления одной командой.
<img alt="Credactor: scan, redact, commit clean" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="1280" height="320" />
Держать учётные данные вне исходного кода — это базовая практика безопасности, а не опциональная. Credactor делает соблюдение этой базовой практики дешёвым: на вашей машине до коммита или в CI до слияния. Запускайте его отдельно или вместе со сканерами, которым вы уже доверяете.
```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"]
```
> Редактирование переписывает файлы в вашем **рабочем дереве**. Если секрет уже был закоммичен, смените ключ и очистите историю (например, с помощью `git filter-repo`). Перезапись файла не заменяет отзыв утёкших учётных данных.
---
## Почему Credactor
- **Редактирование, а не только обнаружение.** Большинство сканеров останавливаются на находке. Credactor заменяет секрет на месте: громкий маркер `REDACTED_BY_CREDACTOR`, который по умолчанию падает во время выполнения, или языко-зависимую ссылку на переменную окружения (Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP и shell), например `os.environ["KEY"]`. Замена является валидным кодом. Если файл ещё не содержит соответствующий импорт (например, `import os`), добавьте его.
- **Безопасность по умолчанию.** Атомарные записи, автоматические резервные копии `.bak`, защита границ симлинков и прав доступа к файлам, а также полное маскирование секретов во всех выводах. Если безопасную резервную копию записать нельзя, Credactor пропускает файл, а не переписывает его вслепую, а сбой в середине записи оставляет оригинал нетронутым.
- **Ноль зависимостей времени выполнения.** Чистая стандартная библиотека Python 3.11+, плюс опциональное дополнение для не-UTF-8 кодировок.
- **Создан для пайплайна.** Вывод SARIF для GitHub Code Scanning, read-only шлюз `--ci` с точными кодами выхода, pre-commit хук и приём отчётов Gitleaks, TruffleHog или Betterleaks. Обнаруживайте сканером, который вы уже запускаете, устраняйте с помощью Credactor.
## Установка
```bash
pip install credactor
```
Требуется Python 3.11+. Никаких других зависимостей. Работает на Linux, macOS и
Windows (протестировано в CI на Linux и Windows).
На macOS и Linux его можно установить через Homebrew:
```bash
brew install rxb06/tap/credactor
```
Формула устанавливает в собственный virtualenv и включает опциональное
дополнение `[encoding]`, так что установка через Homebrew также обнаруживает секреты в
не-UTF-8 файлах. Обычный `pip install credactor` не включает это дополнение; добавьте его с помощью
`pip install 'credactor[encoding]'`, если хотите такое же покрытие.
Из исходников:
```bash
git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .
```
После этого `credactor` работает из любого каталога.
## Быстрый старт
> Сначала запустите `--dry-run` и просмотрите находки перед редактированием. Ложные срабатывания возможны, и при `--fix-all` ложное срабатывание будет переписано. Подавляйте известные безопасные значения с помощью `# credactor:ignore` или записи в `.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
```
### Pre-commit хук
> Хук проверяет только проиндексированное содержимое, поэтому уже закоммиченный секрет не
> будет помечен повторно. Используйте `credactor --scan-history .`, чтобы проверить то, что уже находится в репозитории.
```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]
```
Действие всегда передаёт `--ci`, поэтому оно сообщает и блокирует, но никогда не переписывает
checkout. Находки приводят к провалу шага; установите `fail-on-findings: false`, чтобы сообщать
без блокировки. Ошибка приводит к провалу шага в любом случае.
Загрузка в Code Scanning вместо провала при находках:
```yaml
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
Для загрузки заданию нужны `permissions: security-events: write`. См.
[руководство по интеграции с CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#github-action) для всех входных параметров,
включая приём отчётов Gitleaks, TruffleHog и Betterleaks.
## Обнаружение
Credactor обнаруживает типы учётных данных, которые утекают чаще всего, и присваивает каждому уровень серьёзности, чтобы вы могли оценивать их с первого взгляда.
| Категория | Примеры | Серьёзность |
|---|---|---|
| Ключи облачных провайдеров | AWS (`AKIA…`), GCP (`AIza…`), Stripe (`sk_live_…`), Slack (`xoxb-…`) | Critical |
| Токены платформ | GitHub (`ghp_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`) | Critical |
| Приватные ключи | PEM-блоки (`-----BEGIN … PRIVATE KEY-----`) | Critical |
| JWT | `eyJ…` трёхсегментные токены | High |
| Строки подключения | URL со встроенными учётными данными (`scheme://user:pass@host`) | High |
| Переменные учётных данных | `password = "…"`, `api_key = "…"`, `secret_key = "…"` | High/Medium/Low |
| XML-атрибуты | `<add key="Password" value="…" />` | High/Medium/Low |
| Строки с высокой энтропией | hex в кавычках (32–64 символа) / Base64 (60+ символов) | Medium/Low |
Детерминированные токены провайдеров (префиксы выше) помечаются независимо от энтропии. Эвристические детекторы (JWT, строки подключения, hex, Base64) должны превысить порог энтропии. Отдельный hex или Base64 помечается только в кавычках. Значение с высокой энтропией без кавычек ловится только на переменной с именем учётных данных, что избавляет от ложных срабатываний на git SHA и контрольные суммы. Полные правила обнаружения и серьёзности см. в [Руководстве](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity).
> Собственный набор правил Credactor уже, чем у специализированного сканера, и некоторые форматы провайдеров (например, SendGrid, Twilio и вебхуки Slack) не обнаруживаются. Его преимущество — устранение: объедините его с Gitleaks, TruffleHog или Betterleaks для самого широкого обнаружения или запускайте отдельно.
## Объедините с другим сканером и отредактируйте всё
Credactor работает самостоятельно, но в компании становится сильнее. Уже запускаете Gitleaks, TruffleHog или Betterleaks? Передайте их отчёт в Credactor, и он отредактирует объединённый набор, дедуплицированный относительно собственных находок (при пересечении побеждает более высокая серьёзность). Один проход устранения покрывает ваш скан и их:
```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` (или таблица `[ingest]` в `.credactor.toml`) требуют цели-каталога — направьте Credactor на тот же корень, против которого работал сканер. Пути к отчётам разрешаются относительно рабочего каталога, а отчёт — это снимок: перегенерируйте его после редактирования или изменения дерева. См. [руководство по интеграции с CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md).
## Дополнительные возможности
- Интерактивное или пакетное редактирование; пользовательская строка замены через `--replacement`; `--scan-history` для сканирования истории git-коммитов
- Безопасные резервные копии: `--secure-delete` (перезаписать и удалить `.bak`; повышает планку против случайного восстановления, но не является форензической гарантией) или `--secure-backup-dir` для хранения резервных копий вне репозитория
- Встроенные allowlist-ы `# credactor:ignore` и `.credactorignore` (glob-шаблоны, `file:line`, литералы значений)
- Конфигурация для каждого репозитория через `.credactor.toml`
- 29 типов файлов исходного кода/конфигурации/заметок из коробки (включая `.txt`); `--scan-json` для включения JSON; `--fail-on-error` для провала, когда файл не удаётся прочитать
## Сканируемые типы файлов
> `.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`
Плюс варианты `.env.*` / `.env-*` (`.env.local`, `.env.production`) и файлы SSH / приватных ключей (`id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`), все сопоставляются по имени файла, а не по расширению. JSON исключён по умолчанию, потому что ответы API дают высокий уровень ложных срабатываний; добавьте `--scan-json`, чтобы включить его. Файл, указанный напрямую в командной строке, сканируется, даже если его расширения нет в этом списке.
## Коды выхода
| Код | Значение |
|---|---|
| `0` | Нет находок или все устранены |
| `1` | Неустранённые находки |
| `2` | Ошибка (например: неверный путь, опасный `--replacement`, `--ci --fix-all`, отсутствующий или недействительный отчёт приёма, или `--fail-on-error` при нечитаемом файле) |
## Укрепление цепочки поставок
Инструмент безопасности должен быть безопасным для установки, а не только безопасным для запуска. Пайплайн сборки и релиза Credactor укреплён от начала до конца; полные детали в [документе по безопасности](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening).
- **Ноль зависимостей времени выполнения.** Обычный `pip install credactor` не подтягивает сторонних пакетов (только опциональное дополнение `[encoding]`), так что проверять при установке нечего.
- **Инструментарий с закреплёнными хешами.** Сборки CI и релизов устанавливаются из lockfile с `--require-hashes`, включая backend сборки (`python -m build --no-isolation` против закреплённого setuptools), так что подделанная зависимость проваливает сборку.
- **Артефакты побайтово сверяются с исходниками.** При каждом push и перед каждой публикацией `scripts/audit_wheel.py` сравнивает wheel и sdist с закоммиченными исходниками побайтово (sha256 против `git HEAD`); любой добавленный, отсутствующий или изменённый файл проваливает шлюз, так что шаг сборки не может незаметно внедрить код.
- **CI с закреплёнными SHA и минимальными привилегиями.** GitHub Actions закреплены на commit SHA, а токены workflow остаются узкими — `contents: read` по умолчанию, `id-token: write` только для задания публикации.
## Документация
| Документ | Описание |
|----------|-------------|
| [Руководство по настройке](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | Установка, конфигурация, интеграция с CI/CD |
| [Руководство](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | Полный справочник: каждый флаг, режим и комбинация, поведение замены и резервного копирования, обнаружение и серьёзность, коды выхода и ограничения (поведение проверено тестами) |
| [Примеры](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | Типичные рабочие процессы с выводом |
| [Интеграция с CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Pre-commit хуки, пайплайны CI |
| [Безопасность](https://github.com/rxb06/credactor/blob/main/docs/security.md) | Модель угроз, меры укрепления, известные ограничения |
| [Changelog](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | История версий |
| [Участие в разработке](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | Настройка разработки, стиль кода, процесс PR |
| [Отказ от ответственности](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | Ограничения, безопасное использование, гарантии |
## Лицензия
Apache 2.0. См. [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE).