TruffleHog

Находите утёкшие учётные данные.

---

---

:mag_right: Сейчас сканирует

...и многое другое

Чтобы узнать больше о TruffleHog, его функциях и возможностях, посетите нашу страницу продукта.

:globe_with_meridians: TruffleHog Enterprise

Заинтересованы в непрерывном мониторинге Git, Jira, Slack, Confluence, Microsoft Teams, Sharepoint (и других) на предмет учётных данных? У нас есть корпоративный продукт, который может помочь! Узнайте больше на https://trufflesecurity.com/trufflehog-enterprise.

Мы используем доходы от корпоративного продукта для финансирования более замечательных проектов с открытым исходным кодом, от которых может выиграть всё сообщество.

Что такое TruffleHog 🐽

TruffleHog — это самый мощный инструмент для обнаружения, классификации, проверки и анализа секретов. В данном контексте под секретом понимается учётные данные, которые машина использует для аутентификации перед другой машиной. Это включает ключи API, пароли к базам данных, приватные ключи шифрования и многое другое.

Обнаружение 🔍

TruffleHog может искать секреты во многих местах, включая Git, чаты, вики, журналы, платформы тестирования API, объектные хранилища, файловые системы и многое другое.

Классификация 📁

TruffleHog классифицирует более 800 типов секретов, соотнося их с конкретной сущностью, к которой они принадлежат. Это секрет AWS? Секрет Stripe? Секрет Cloudflare? Пароль Postgres? Приватный ключ SSL? Иногда по внешнему виду это сложно определить, поэтому TruffleHog классифицирует всё, что находит.

Проверка ✅

Для каждого секрета, который TruffleHog может классифицировать, он также может выполнить вход, чтобы подтвердить, активен ли этот секрет или нет. Этот шаг критически важен для понимания, существует ли активная непосредственная угроза или нет.

Анализ 🔬

Для примерно 20 наиболее часто утекающих типов учётных данных, вместо отправки одного запроса для проверки возможности входа, TruffleHog может отправить множество запросов, чтобы узнать всё, что можно о секрете. Кто его создал? К каким ресурсам он может получить доступ? Какие разрешения он имеет на эти ресурсы?

:loudspeaker: Присоединяйтесь к нашему сообществу

Есть вопросы? Обратная связь? Заходите в Slack или Discord и общайтесь с нами.

Присоединяйтесь к нашему Slack-сообществу

Присоединяйтесь к Secret Scanning Discord

:tv: Демо

docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --org=trufflesecurity

:floppy_disk: Установка

Для вас доступно несколько вариантов:

Пользователи MacOS

brew install trufflehog

Docker:

_{Убедитесь, что движок Docker запущен, перед выполнением следующих команд:}

    Unix

docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

    Командная строка Windows

docker run --rm -it -v "%cd:/=\%:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

    Windows PowerShell

docker run --rm -it -v "${PWD}:/pwd" trufflesecurity/trufflehog github --repo https://github.com/trufflesecurity/test_keys

    Mac M1 и M2

docker run --platform linux/arm64 --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

Бинарные релизы

Download and unpack from https://github.com/trufflesecurity/trufflehog/releases

Сборка из исходного кода

git clone https://github.com/trufflesecurity/trufflehog.git
cd trufflehog; go install

Использование скрипта установки

curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

Использование скрипта установки, проверка сигнатуры контрольной суммы (требуется установленный cosign)

curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -v -b /usr/local/bin

Использование скрипта установки для установки конкретной версии

curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin <ReleaseTag like v3.56.0>

:closed_lock_with_key: Проверка артефактов

Контрольные суммы применяются ко всем артефактам, и результирующий файл контрольных сумм подписывается с помощью cosign.

Вам понадобится следующий инструмент для проверки подписи:

• Cosign

Шаги проверки следующие:

1. Загрузите нужные файлы артефактов, а также следующие файлы со страницы релизов.

   • trufflehog_{version}_checksums.txt
   • trufflehog_{version}_checksums.txt.pem
   • trufflehog_{version}_checksums.txt.sig

2. Проверьте подпись:

   shell cosign verify-blob <путь к trufflehog_{version}_checksums.txt> \ --certificate <путь к trufflehog_{version}_checksums.txt.pem> \ --signature <путь к trufflehog_{version}_checksums.txt.sig> \ --certificate-identity-regexp 'https://github\.com/trufflesecurity/trufflehog/\.github/workflows/.+' --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

3. После того как подпись подтверждена как действительная, можно перейти к проверке соответствия SHA256-сумм загруженному артефакту:

   shell sha256sum --ignore-missing -c trufflehog_{version}_checksums.txt

Замените {version} на версию загруженного файла.

В качестве альтернативы, если вы используете скрипт установки, передайте опцию -v для проверки подписи. Для этого требуется, чтобы двоичный файл Cosign был установлен до запуска скрипта установки.

:rocket: Быстрый старт

1: Сканирование репозитория только на проверенные секреты

Команда:

trufflehog git https://github.com/trufflesecurity/test_keys --results=verified

Ожидаемый вывод:

🐷🔑🐷  TruffleHog. Unearth your secrets. 🐷🔑🐷

Found verified result 🐷🔑
Detector Type: AWS
Decoder Type: PLAIN
Raw result: AKIAYVP4CIPPERUVIFXG
Line: 4
Commit: fbc14303ffbf8fb1c2c1914e8dda7d0121633aca
File: keys
Email: counter <counter@counters-MacBook-Air.local>
Repository: https://github.com/trufflesecurity/test_keys
Timestamp: 2022-06-16 10:17:40 -0700 PDT
...

2: Сканирование организации GitHub только на проверенные секреты

trufflehog github --org=trufflesecurity --results=verified

3: Сканирование организации GitHub с исключением архивных репозиториев

trufflehog github --org=trufflesecurity --exclude-archived

4: Сканирование репозитория GitHub только на проверенные секреты с выводом в формате JSON

Команда:

trufflehog git https://github.com/trufflesecurity/test_keys --results=verified --json

Ожидаемый вывод:

{"SourceMetadata":{"Data":{"Git":{"commit":"fbc14303ffbf8fb1c2c1914e8dda7d0121633aca","file":"keys","email":"counter \u003ccounter@counters-MacBook-Air.local\u003e","repository":"https://github.com/trufflesecurity/test_keys","timestamp":"2022-06-16 10:17:40 -0700 PDT","line":4}}},"SourceID":0,"SourceType":16,"SourceName":"trufflehog - git","DetectorType":2,"DetectorName":"AWS","DecoderName":"PLAIN","Verified":true,"Raw":"AKIAYVP4CIPPERUVIFXG","Redacted":"AKIAYVP4CIPPERUVIFXG","ExtraData":{"account":"595918472158","arn":"arn:aws:iam::595918472158:user/canarytokens.com@@mirux23ppyky6hx3l6vclmhnj","user_id":"AIDAYVP4CIPPJ5M54LRCY"},"StructuredData":null}
...

TruffleHog также может выводить результаты в формате SARIF с помощью флага --sarif вместо --json. GitHub code scanning нативно понимает формат SARIF, поэтому его загрузка позволяет отображать находки прямо в диффах pull request'ов и на вкладке Security репозитория, а также отслеживать их статус как новые/исправленные между сканированиями, вместо повторного отчета об одних и тех же находках при каждом запуске — см. раздел TruffleHog GitHub Action ниже для получения инструкций по загрузке. Обратите внимание, что, в отличие от других форматов вывода, результаты SARIF буферизируются в памяти на всё время сканирования и записываются в конце, поскольку SARIF требует единый JSON-документ, а не поток — это нормально для типичных сканирований, но сканирования с очень большим количеством результатов будут использовать пропорционально больше памяти.

5: Сканирование репозитория GitHub + его Issues и Pull Request'ов

trufflehog github --repo=https://github.com/trufflesecurity/test_keys --issue-comments --pr-comments

6: Сканирование S3-бакета на высокодостоверные результаты (проверенные + неизвестные)

trufflehog s3 --bucket=<bucket name> --results=verified,unknown

7: Сканирование S3-бакетов с использованием IAM-ролей

trufflehog s3 --role-arn=<iam role arn>

8: Сканирование репозитория GitHub с использованием SSH-аутентификации в Docker

docker run --rm -v "$HOME/.ssh:/root/.ssh:ro" trufflesecurity/trufflehog:latest git ssh://github.com/trufflesecurity/test_keys

9: Сканирование отдельных файлов или директорий

trufflehog filesystem path/to/file1.txt path/to/file2.txt path/to/dir

10: Сканирование локального git-репозитория

Клонируйте git-репозиторий. Например, репозиторий test keys.

git clone git@github.com:trufflesecurity/test_keys.git

Запустите trufflehog из родительской директории (вне git-репозитория).

trufflehog git file://test_keys --results=verified,unknown

Чтобы защититься от вредоносных git-конфигураций при локальном сканировании (см. CVE-2025-41390), TruffleHog клонирует локальные git-репозитории во временную директорию перед сканированием. Это соответствует рекомендациям Git по безопасности. Если вы хотите указать собственный путь для клонирования репозитория (вместо tmp), используйте флаг --clone-path. Если вы хотите пропустить процесс локального клонирования и сканировать репозиторий напрямую (делайте это только для доверенных репозиториев), используйте флаг --trust-local-git-config.

11: Сканирование GCS-бакетов только на проверенные секреты

trufflehog gcs --project-id=<project-ID> --cloud-environment --results=verified

12: Сканирование Docker-образа только на проверенные секреты

Используйте флаг --image несколько раз для сканирования нескольких образов.

# to scan from a remote registry
trufflehog docker --image trufflesecurity/secrets --results=verified

# to scan from the local docker daemon
trufflehog docker --image docker://new_image:tag --results=verified

# to scan from an image saved as a tarball
trufflehog docker --image file://path_to_image.tar --results=verified

13: Сканирование в CI

Установите флаг --since-commit на вашу ветку по умолчанию, в которую происходит слияние (например, "main"). Установите флаг --branch на имя ветки вашего PR (например, "feature-1"). В зависимости от используемой CI/CD-платформы это значение можно получить динамически (например, CIRCLE_BRANCH в Circle CI и TRAVIS_PULL_REQUEST_BRANCH в Travis CI). Если репозиторий клонирован и целевая ветка уже извлечена в процессе CI/CD, флага --branch HEAD должно быть достаточно. Флаг --fail вернет код ошибки 183, если будут найдены действительные учетные данные.

trufflehog git file://. --since-commit main --branch feature-1 --results=verified,unknown --fail

14: Сканирование рабочей области Postman

Используйте флаги --workspace-id, --collection-id, --environment несколько раз для сканирования нескольких целей.

trufflehog postman --token=<postman api token> --workspace-id=<workspace id>

15: Сканирование сервера Jenkins

trufflehog jenkins --url https://jenkins.example.com --username admin --password admin

16: Сканирование сервера Elasticsearch

Сканирование локального кластера

Есть два способа аутентификации в локальном кластере с помощью TruffleHog: (1) имя пользователя и пароль, (2) сервисный токен.

Подключение к локальному кластеру с именем пользователя и паролем

trufflehog elasticsearch --nodes 192.168.14.3 192.168.14.4 --username truffle --password hog

Подключение к локальному кластеру с сервисным токеном

trufflehog elasticsearch --nodes 192.168.14.3 192.168.14.4 --service-token ‘AAEWVaWM...Rva2VuaSDZ’

Сканирование кластера Elastic Cloud

Для сканирования кластера в Elastic Cloud вам понадобится Cloud ID и API-ключ.

trufflehog elasticsearch \
  --cloud-id 'search-prod:dXMtY2Vx...YjM1ODNlOWFiZGRlNjI0NA==' \
  --api-key 'MlVtVjBZ...ZSYlduYnF1djh3NG5FQQ=='

17. Сканирование GitHub-репозитория на предмет перекрёстных ссылок на форки и удалённых коммитов

Следующая команда перечислит удалённые и скрытые коммиты в GitHub-репозитории, а затем просканирует их на наличие секретов. Это функция альфа-версии.

trufflehog github-experimental --repo https://github.com/<USER>/<REPO>.git --object-discovery

В дополнение к обычному выводу TruffleHog, флаг --object-discovery создаёт два файла в новой директории $HOME/.trufflehog: valid_hidden.txt и invalid.txt. Они используются для отслеживания состояния во время перечисления коммитов, а также для предоставления пользователям полного списка всех скрытых и удалённых коммитов (valid_hidden.txt). Если вы хотите автоматически удалять эти файлы после сканирования, добавьте флаг --delete-cached-data.

Примечание: Перечисление всех допустимых коммитов в репозитории с помощью этого метода занимает от 20 минут до нескольких часов, в зависимости от размера вашего репозитория. Мы добавили индикатор прогресса, чтобы вы были в курсе, сколько времени займёт перечисление. Само сканирование секретов выполняется очень быстро.

Для получения дополнительной информации о перекрёстных ссылках на форки, пожалуйста, прочитайте наш пост в блоге.

18. Сканирование Hugging Face

Сканирование модели, датасета, Space или Bucket в Hugging Face

trufflehog huggingface \
    --model <model_id> \
    --dataset <dataset_id> \
    --space <space_id> \
    --bucket <bucket_id>

Сканирование всех моделей, датасетов, Spaces и Buckets, принадлежащих организации или пользователю Hugging Face

trufflehog huggingface --org <orgname> --user <username>

(Необязательно) При сканировании организации или пользователя вы можете пропустить целый класс ресурсов с помощью --skip-all-models, --skip-all-datasets, --skip-all-spaces, --skip-all-buckets ИЛИ конкретный ресурс с помощью --ignore-models <model_id>, --ignore-datasets <dataset_id>, --ignore-spaces <space_id>, --ignore-buckets <bucket_id>.

Сканирование обсуждений и комментариев к PR

trufflehog huggingface --model <model_id> --include-discussions --include-prs

19. Сканирование stdin-ввода

aws s3 cp s3://example/gzipped/data.gz - | gunzip -c | trufflehog stdin

:question: Часто задаваемые вопросы

• Я вижу только 🐷🔑🐷 TruffleHog. Unearth your secrets. 🐷🔑🐷 и программа завершает работу, в чём дело?
  • Это означает, что секреты не были обнаружены
• Почему сканирование занимает много времени при сканировании GitHub-организации?
  • Неаутентифицированные GitHub-сканы имеют ограничения на количество запросов. Чтобы улучшить лимиты, добавьте флаг --token с персональным токеном доступа
• Там написано, что приватный ключ был проверен, что это значит?
  • Проверенный результат означает, что TruffleHog подтвердил действительность учётных данных, проверив их через API сервиса. Для приватных ключей мы подтвердили, что ключ можно использовать вживую для SSH или SSL-аутентификации. Ознакомьтесь с нашим постом в блоге Driftwood, чтобы узнать больше Пост в блоге
• Есть ли простой способ игнорировать конкретные секреты?
  • Если сканируемый источник поддерживает номера строк, вы можете добавить комментарий trufflehog:ignore в строке, содержащей секрет, чтобы игнорировать этот секрет.

:newspaper: Что нового в v3?

TruffleHog v3 — это полная переработка на Go с множеством новых мощных функций.

• Мы добавили более 700 детекторов учётных данных, поддерживающих активную проверку через соответствующие API.
• Мы также добавили встроенную поддержку сканирования GitHub, GitLab, Docker, файловых систем, S3, GCS, Circle CI и Travis CI.
• Мгновенно проверяйте приватные ключи среди миллионов пользователей GitHub и миллиардов TLS-сертификатов с помощью нашей технологии Driftwood.
• Сканируйте бинарные файлы, документы и другие форматы файлов
• Доступно как GitHub Action и как pre-commit хук

Что такое проверка учётных данных?

Для каждого потенциально обнаруженного учётного данными мы тщательно реализовали программную проверку через API, к которому, как мы считаем, они относятся. Проверка устраняет ложные срабатывания и предоставляет три статуса результата:

• verified: Учётные данные подтверждены как действительные и активные путём тестирования API
• unverified: Учётные данные обнаружены, но не подтверждены как действительные (могут быть недействительными, просроченными или проверка отключена)
• unknown: Проверка была предпринята, но не удалась из-за ошибок, таких как сбой сети или API

Например, детектор учётных данных AWS выполняет вызов API GetCallerIdentity к AWS API, чтобы проверить, активны ли учётные данные AWS.

:memo: Использование

TruffleHog имеет подкоманду для каждого источника данных, который вы можете сканировать:

• git
• github
• gitlab
• huggingface
• docker
• s3
• filesystem (файлы и каталоги)
• syslog
• circleci
• travisci
• gcs (Google Cloud Storage)
• postman
• jenkins
• elasticsearch
• stdin
• multi-scan

Каждая подкоманда может иметь опции, которые вы можете увидеть с помощью флага --help, предоставленного подкоманде:

$ trufflehog git --help
usage: TruffleHog [<flags>] <command> [<args> ...]

TruffleHog is a tool for finding credentials.


Flags:
  -h, --[no-]help                Show context-sensitive help (also try --help-long and --help-man).
      --log-level=0              Logging verbosity on a scale of 0 (info) to 5 (trace). Can be
                                 disabled with "-1".
      --[no-]profile             Enables profiling and sets a pprof and fgprof server on :18066.
  -j, --[no-]json                Output in JSON format.
      --[no-]json-legacy         Use the pre-v3.0 JSON format. Only works with git, gitlab,
                                 and github sources.
      --[no-]github-actions      Output in GitHub Actions format.
      --[no-]sarif               Output in SARIF format for upload to GitHub code scanning (e.g.
                                 via github/codeql-action/upload-sarif).
      --concurrency=12           Number of concurrent workers.
      --[no-]no-verification     Don't verify the results.
      --results=RESULTS          Specifies which type(s) of results to output: verified (confirmed
                                 valid by API), unknown (verification failed due to error),
                                 unverified (detected but not verified), filtered_unverified
                                 (unverified but would have been filtered out). Defaults to
                                 verified,unverified,unknown.
      --[no-]no-color            Disable colorized output
      --[no-]allow-verification-overlap
                                 Allow verification of similar credentials across detectors
      --[no-]filter-unverified   Only output first unverified result per chunk per detector if there
                                 are more than one results.
      --filter-entropy=FILTER-ENTROPY
                                 Filter unverified results with Shannon entropy. Start with 3.0.
      --config=CONFIG            Path to configuration file.
      --[no-]print-avg-detector-time
                                 Print the average time spent on each detector.
      --[no-]no-update           Don't check for updates.
      --[no-]fail                Exit with code 183 if results are found.
      --[no-]fail-on-scan-errors
                                 Exit with non-zero error code if an error occurs during the scan.
      --verifier=VERIFIER ...    Set custom verification endpoints.
      --[no-]custom-verifiers-only
                                 Only use custom verification endpoints.
      --detector-timeout=DETECTOR-TIMEOUT
                                 Maximum time to spend scanning chunks per detector (e.g., 30s).
      --archive-max-size=ARCHIVE-MAX-SIZE
                                 Maximum size of archive to scan. (Byte units eg. 512B, 2KB, 4MB)
      --archive-max-depth=ARCHIVE-MAX-DEPTH
                                 Maximum depth of archive to scan.
      --archive-timeout=ARCHIVE-TIMEOUT
                                 Maximum time to spend extracting an archive.
      --include-detectors="all"  Comma separated list of detector types to include. Protobuf name or
                                 IDs may be used, as well as ranges.
      --exclude-detectors=EXCLUDE-DETECTORS
                                 Comma separated list of detector types to exclude. Protobuf name
                                 or IDs may be used, as well as ranges. IDs defined here take
                                 precedence over the include list.
      --[no-]no-verification-cache
                                 Disable verification caching
      --[no-]force-skip-binaries
                                 Force skipping binaries.
      --[no-]force-skip-archives
                                 Force skipping archives.
      --[no-]skip-additional-refs
                                 Skip additional references.
      --user-agent-suffix=USER-AGENT-SUFFIX
                                 Suffix to add to User-Agent.
      --[no-]version             Show application version.

Commands:
help [<command>...]
    Show help.

git [<flags>] <uri>

    Find credentials in git repositories.

github [<flags>]
    Find credentials in GitHub repositories.

github-experimental --repo=REPO [<flags>]
    Run an experimental GitHub scan. Must specify at least one experimental sub-module to run:
    object-discovery.

gitlab --token=TOKEN [<flags>]
    Find credentials in GitLab repositories.

filesystem [<flags>] [<path>...]
    Find credentials in a filesystem.

s3 [<flags>]
    Find credentials in S3 buckets.

gcs [<flags>]
    Find credentials in GCS buckets.

syslog --format=FORMAT [<flags>]
    Scan syslog

circleci --token=TOKEN
    Scan CircleCI

docker [<flags>]
    Scan Docker Image


travisci --token=TOKEN
    Scan TravisCI

postman [<flags>]
    Scan Postman

elasticsearch [<flags>]
    Scan Elasticsearch

jenkins --url=URL [<flags>]
    Scan Jenkins

huggingface [<flags>]
    Find credentials in HuggingFace datasets, models and spaces.

stdin
    Find credentials from stdin.

multi-scan
    Find credentials in multiple sources defined in configuration.

json-enumerator [<path>...]
    Find credentials from a JSON enumerator input.

analyze
    Analyze API keys for fine-grained permissions information.

Например, чтобы сканировать git-репозиторий, начните с

trufflehog git https://github.com/trufflesecurity/trufflehog.git

Конфигурация

TruffleHog поддерживает определение пользовательских regex-детекторов и нескольких источников в файле конфигурации, предоставляемом через флаг --config. Regex-детекторы можно использовать с любой подкомандой, а источники, определенные в конфигурации, предназначены только для подкоманды multi-scan.

Формат конфигурации для источников можно найти на странице документации по конфигурации источников от Truffle Security.

Пример конфигурации источника GitHub и справочник по опциям:

sources:
- connection:
    '@type': type.googleapis.com/sources.GitHub
    repositories:
    - https://github.com/trufflesecurity/test_keys.git
    unauthenticated: {}
  name: example config scan
  type: SOURCE_TYPE_GITHUB
  verify: true

Вы можете определить несколько подключений в ключе sources (см. выше), и TruffleHog будет сканировать все источники одновременно.

S3

Источник S3 поддерживает принятие IAM-ролей для сканирования в дополнение к IAM-пользователям. Это упрощает пользователям сканирование нескольких AWS-аккаунтов без необходимости полагаться на жестко заданные учетные данные для каждого аккаунта.

IAM-идентичность, которую изначально использует TruffleHog, должна иметь привилегии AssumeRole в качестве принципала в политике доверия каждой принимаемой IAM-роли.

Чтобы сканировать конкретный бакет, используя локально заданные учетные данные или метаданные экземпляра, если вы находитесь на EC2-инстансе:

trufflehog s3 --bucket=<bucket-name>

Чтобы сканировать конкретный бакет, используя принятую роль:

trufflehog s3 --bucket=<bucket-name> --role-arn=<iam-role-arn>

Несколько ролей можно передать как отдельные аргументы. Следующая команда попытается сканировать каждый бакет, который каждая роль имеет права перечислять в S3 API:

trufflehog s3 --role-arn=<iam-role-arn-1> --role-arn=<iam-role-arn-2>

Коды выхода:

• 0: Ошибок нет и результатов не найдено.
• 1: Произошла ошибка. Источники могли не завершить сканирование.
• 183: Ошибок не было, но результаты были найдены. Возвращается только при использовании флага --fail.

:octocat: TruffleHog Github Action

Общее использование

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: Secret Scanning
      uses: trufflesecurity/trufflehog@main
      with:
        extra_args: --results=verified,unknown

В приведенном выше примере конфигурации мы сканируем на предмет живых секретов во всех PR и пушах в ветку main. Сканируются только изменения кода в указанных коммитах. Если вы хотите сканировать всю ветку, см. раздел "Расширенное использование" ниже.

Мелкое клонирование (Shallow Cloning)

Если вы интегрируете TruffleHog в отдельный рабочий процесс и не запускаете никакой другой CI/CD-инструментарий вместе с TruffleHog, мы рекомендуем использовать мелкое клонирование для ускорения вашего рабочего процесса. Вот пример того, как это сделать:

...
      - shell: bash
        run: |
          if [ "${{ github.event_name }}" == "push" ]; then
            echo "depth=$(($(jq length <<< '${{ toJson(github.event.commits) }}') + 2))" >> $GITHUB_ENV
            echo "branch=${{ github.ref_name }}" >> $GITHUB_ENV
          fi
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "depth=$((${{ github.event.pull_request.commits }}+2))" >> $GITHUB_ENV
            echo "branch=${{ github.event.pull_request.head.ref }}" >> $GITHUB_ENV
          fi
      - uses: actions/checkout@v3
        with:
          ref: ${{env.branch}}
          fetch-depth: ${{env.depth}}
      - uses: trufflesecurity/trufflehog@main
        with:
          extra_args: --results=verified,unknown
...

В зависимости от типа события (push или PR), мы вычисляем количество коммитов. Затем мы добавляем 2, чтобы мы могли ссылаться на базовый коммит до наших изменений кода. Мы передаем это целочисленное значение в флаг fetch-depth в действии checkout в дополнение к соответствующей ветке. Теперь наш процесс checkout должен быть намного короче.

Обнаружение канареечных токенов

TruffleHog статически обнаруживает https://canarytokens.org/.

Расширенное использование

- name: TruffleHog
  uses: trufflesecurity/trufflehog@main
  with:
    # Repository path
    path:
    # Start scanning from here (usually main branch).
    base:
    # Scan commits until here (usually dev branch).
    head: # optional
    # Extra args to be passed to the trufflehog cli.
    extra_args: --log-level=2 --results=verified,unknown
    # Scan with a specific TruffleHog version (default: latest).
    version:
    # Docker image to pull. Override to use a registry mirror (default: ghcr.io/trufflesecurity/trufflehog).
    image:

Если вы хотите указать конкретные base и head ссылки, вы можете использовать аргумент base (флаг --since-commit в TruffleHog CLI) и аргумент head (флаг --branch в TruffleHog CLI). Мы рекомендуем использовать эти аргументы только для очень специфических случаев использования, когда поведение по умолчанию не работает.

Чтобы вместо этого загрузить результаты в сканирование кода GitHub, запустите TruffleHog напрямую с --sarif и передайте вывод в github/codeql-action/upload-sarif:

- name: TruffleHog
  run: trufflehog filesystem . --sarif --no-verification > results.sarif
- name: Upload SARIF results
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Расширенное использование: Сканирование всей ветки

- name: scan-push
        uses: trufflesecurity/trufflehog@main
        with:
          base: ""
          head: ${{ github.ref_name }}
          extra_args: --results=verified,unknown

TruffleHog GitLab CI

Пример использования

stages:
  - security

security-secrets:
  stage: security
  allow_failure: false
  image: alpine:latest
  variables:
    SCAN_PATH: "." # Set the relative path in the repo to scan
  before_script:
    - apk add --no-cache git curl jq
    - curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin
  script:
    - trufflehog filesystem "$SCAN_PATH" --results=verified,unknown --fail --json | jq
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

В приведенном выше примере пайплайна мы сканируем на предмет живых секретов во всех каталогах и файлах репозитория. Это задание выполняется только тогда, когда источником пайплайна является событие запроса на слияние, что означает, что оно запускается при создании нового запроса на слияние.

Pre-commit Hook

TruffleHog можно использовать в pre-commit хуке, чтобы предотвратить утечку учетных данных до того, как они покинут ваш компьютер. См. документацию по pre-commit хуку для получения дополнительной информации.

Пользовательский Regex-детектор (альфа)

TruffleHog поддерживает обнаружение и проверку пользовательских регулярных выражений. Для обнаружения требуется как минимум одно регулярное выражение и ключевое слово. Ключевое слово — это фиксированный строковый литерал-идентификатор, который встречается внутри или вокруг регулярного выражения, подлежащего обнаружению. Для обеспечения максимальной гибкости проверки используется webhook, содержащий совпадения регулярных выражений.

TruffleHog отправит JSON POST-запрос, содержащий совпадения регулярных выражений, на настроенную конечную точку webhook. Если конечная точка ответит кодом состояния 200 OK, секрет считается проверенным. Если проверка не удалась из-за сетевых ошибок или ошибок API, результат помечается как неизвестный.

Пользовательские детекторы поддерживают несколько различных механизмов фильтрации: энтропию, регулярное выражение, нацеленное на всё совпадение, регулярное выражение, нацеленное на захваченный секрет, и списки исключённых слов, проверяемые по секрету (захваченная группа, если она есть, всё совпадение, если захваченной группы нет). Обратите внимание, что если в вашем пользовательском детекторе установлено несколько regex (в этом примере hogID и hogToken), то фильтры применяются к каждому регулярному выражению. Здесь приведён пример пользовательского детектора, использующего эти фильтры.

Раздел verify необязателен — если вы его опустите, совпадения всё равно будут сообщаться как непроверенные, webhook не требуется. Это делает пользовательские детекторы полезными для выявления общих жёстко заданных секретов (например, *.password=, *.secret=) в файлах конфигурации, таких как .properties, .env или .yaml, которые встроенные проверенные детекторы TruffleHog в противном случае не обнаружат. Здесь приведён пример, настроенный для этого случая использования.

Примечание: Эта функция является альфа-версией и может быть изменена.

Пример Regex-детектора

Здесь описано, как настроить пользовательский regex-детектор с сервером проверки.

Обнаружение общих JWT

TruffleHog поддерживает обнаружение и проверку подмножества общих JWT, которые он находит. В частности, если JWT использует криптографию с открытым ключом, а не HMAC, и открытый ключ может быть получен, TruffleHog может определить, является ли JWT действующим или нет.

:mag: Анализ

TruffleHog поддерживает более глубокий анализ учётных данных для просмотра их разрешений и ресурсов, к которым у них есть доступ.

trufflehog analyze

:heart: Участники

Этот проект существует благодаря всем людям, которые вносят свой вклад. [Внести вклад].

:computer: Внесение вклада

Вклад очень приветствуется! Пожалуйста, сначала ознакомьтесь с нашими правилами внесения вклада.

Мы больше не принимаем вклады в TruffleHog v2, но этот код доступен в ветке v2.

Добавление новых детекторов секретов

Мы опубликовали документацию и инструменты для начала работы по добавлению новых детекторов секретов. Давайте улучшать обнаружение вместе!

Использование в качестве библиотеки

В настоящее время trufflehog находится в активной разработке, и никаких гарантий стабильности публичных API на данный момент дать нельзя.

Изменение лицензии

Начиная с версии v3.0, TruffleHog выпускается под лицензией AGPL 3, включённой в LICENSE. TruffleHog v3.0 не использует ни одной части предыдущей кодовой базы, но были предприняты меры для сохранения обратной совместимости интерфейса командной строки. Работа, предшествующая этому выпуску, по-прежнему доступна по лицензии GPL 2.0 в истории этого репозитория, а также в предыдущих выпусках пакетов и тегах. Для принятия наших вкладов в будущем требуется заполненное CLA.