# Trufflehog

### Overview

TruffleHog — сканер для поиска утечек секретов (токены, API keys, ключи доступа, креды) в исходном коде и артефактах. В TRAIO используется как **Secrets Detection** сканер и поддерживает два режима запуска: **Directory Scan** и **Git Scan**.

### Requirements <a href="#requirements" id="requirements"></a>

* В **Sequences** перед этим инструментом должен быть добавлен job **Code Downloader**

### Run modes <a href="#run-modes" id="run-modes"></a>

Поддерживаются два режима:

* **Directory Scan** (`TRUFFLE_MODE=dir`) — сканирует файловую систему по пути, который передаёт TRAIO.
* **Git Scan** (`TRUFFLE_MODE=git`) — сканирует .git

### How it works

Сканер использует официальный docker-образ:

* `registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:latest`

Команда запуска

```bash
TMP="/tmp/trufflehog.jsonl"
JQ="/tmp/jq"

# Stage 0 — Validate correct choose of parser
echo "Stage 0 — Validate correct choose of parser SCAN_TYPE='$SCAN_TYPE' TRUFFLE_MODE='$TRUFFLE_MODE'"

case "$SCAN_TYPE" in
  "Trufflehog - Git Scan")
    [ "$TRUFFLE_MODE" = "git" ] || { echo "ERROR: Config mismatch: SCAN_TYPE='$SCAN_TYPE' requires TRUFFLE_MODE=git"; exit 2; }
    ;;
  "Trufflehog - Directory Scan")
    [ "$TRUFFLE_MODE" = "dir" ] || { echo "ERROR: Config mismatch: SCAN_TYPE='$SCAN_TYPE' requires TRUFFLE_MODE=dir"; exit 2; }
    ;;
esac


# Stage 1 — Scanning
echo "Stage 1 — Scan Scanning TRUFFLE_MODE=$TRUFFLE_MODE"
case "$TRUFFLE_MODE" in
  dir) trufflehog filesystem "$SEC_CODE_FOLDER" --json $EXTRA_ARGS > "$TMP" || true ;;
  git) trufflehog git "file://$SEC_CODE_FOLDER" --json $EXTRA_ARGS > "$TMP" || true ;;
  *) echo "Unknown TRUFFLEHOG_MODE=$TRUFFLE_MODE. Use: dir|git"; exit 2 ;;
esac

# Stage 2 — Empty report fallback 
echo "Stage 2 — Empty report fallback check"
[ -s "$TMP" ] || { echo "[]" > "/data/$REPORT_FILE_NAME"; exit 0; }

# Stage 3 — Install needed tools to convert report (install curl + download jq)
echo "Stage 3 — Install needed tools to convert report (install curl & fetch jq)"
apk add --no-cache curl >/dev/null
curl -fsSL -o "$JQ" "https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-linux-amd64"
chmod +x "$JQ"

# Stage 4 — Convert JSONL report -> To parsable JSON array
echo "Stage 4 — Convert JSONL report -> To parsable JSON array"
"$JQ" -s '.' "$TMP" > "/data/$REPORT_FILE_NAME" || echo "[]" > "/data/$REPORT_FILE_NAME"
```

### Environment variables

<table data-header-hidden><thead><tr><th></th><th width="262.5"></th><th></th><th width="240.5"></th></tr></thead><tbody><tr><td>Переменная</td><td>Пример</td><td>Обязательная</td><td>Описание</td></tr><tr><td>SEC_CODE_FOLDER</td><td></td><td>Да</td><td>Путь к исходному коду. Проставляется автоматический</td></tr><tr><td>REPORT_FILE_NAME</td><td><code>trufflehog.json</code></td><td>Да</td><td>Имя отчёта</td></tr><tr><td>SCAN_TYPE</td><td><code>Trufflehog - Directory Scan</code></td><td>Да</td><td>Тип сканирования для парсинга Возможные значения: <code>Trufflehog - Directory Scan</code>, <code>Trufflehog - Git Scan</code>.</td></tr><tr><td>TRUFFLE_MODE</td><td><code>git</code> или <code>dir</code></td><td>Да</td><td>Режим запуска: <code>dir</code> или <code>git</code></td></tr><tr><td>EXTRA_ARGS</td><td></td><td>Нет</td><td>Дополнительные CLI-флаги, которые прокидываются в TruffleHog.</td></tr></tbody></table>

#### EXTRA\_ARGS

* `--no-verification` — отключить внешнюю верификацию секретов
* `--results=unverified,unknown` — оставить только непроверенные/unknown результаты

### Severity and CWE

TruffleHog не отдаёт severity и CWE

Рекомендуемые дефолты в TRAIO:

* **Severity:** `Medium` по умолчанию

### Notes / Troubleshooting

* **JSON format:** TruffleHog отдаёт JSONL; в пресете используется `jq -s '.'` для конвертации в JSON array.
* **Network access:** для работы пресета нужен исходящий доступ к Alpine репозиториям (для `apk add curl`) и GitHub (для скачивания `jq`).

### Links

* [Trufflehog Github](https://github.com/trufflesecurity/trufflehog)