РУКОВОДСТВО ПО БЕЗОПАСНОСТИ СЕРВЕРОВ

Проверка JavaScript-бандлов на утёкшие ключи API

Коротко: чтобы узнать, нет ли в JavaScript вашего сайта секретных ключей API, запускайте сканер секретов (gitleaks или TruffleHog) на папке сборки (dist/ или .next/) перед каждым деплоем, а раз в неделю проверяйте файлы скриптов, которые скачивают живые страницы. Всё, что попало во фронтенд-бандл, публично, поэтому найденный секретный ключ нужно перевыпустить, а не прятать. Заодно проверьте, что вы не публикуете source maps.

JavaScript-бандл это минифицированный файл, который сборщик (Vite, webpack) делает из вашего исходного кода. Браузер скачивает его, а значит, прочитать его может любой. Руководство входит в кластер самостоятельного мониторинга безопасности и продолжает чек-лист безопасности для вайб-кодинга. Сканируйте только то, чем владеете. Все команды здесь направлены на вашу папку сборки или ваш сайт; мы запускали их против локального тестового контейнера.

Быстрый результат (15 минут)

  • Выведите имена переменных, которые уходят в браузер, но похожи на секретные (значения не печатаются): grep -oE '^(NEXT_PUBLIC|VITE)_[A-Z0-9_]*(SECRET|PRIVATE|TOKEN|PASSWORD)[A-Z0-9_]*' .env*
  • Запустите gitleaks dir dist --no-banner --redact и прочитайте RuleID каждой находки.
  • Запросите у своего сайта source map: curl -s -o /dev/null -w "%{http_code}\n" https://example.com/assets/YOUR_FILE.js.map. Код 200 и JSON значат, что карта публична (подробнее).
  • Настройте скрипт деплоя так, чтобы он останавливался при ненулевом коде выхода сканера (пример).
Пять шагов: сборка, скан dist, остановка деплоя при ненулевом коде, выкладка чистой сборки, еженедельный скан сайта
Барьер перед деплоем и еженедельный скан живого сайта используют одни и те же сканеры.

Почему сборщики кладут секреты во фронтенд

Коду в браузере нужна конфигурация, например идентификатор аналитики или адрес API. Сборщики фронтенда передают её, копируя переменные окружения в бандл на этапе сборки, и оба популярных фреймворка описывают это как правило:

  • Next.js. В руководстве по переменным окружения сказано, что переменные без префикса NEXT_PUBLIC_ доступны только в Node.js, а переменная с префиксом встраивается («inlined») при сборке в JavaScript, который уходит в браузер, и после этого зафиксирована.
  • Vite. В руководстве по env и режимам сказано, что переменные VITE_ попадают в клиентский исходный код после сборки и не должны содержать чувствительные данные, например ключи API.

Поэтому префикс это решение опубликовать значение. Типичный путь к ошибке (наше описание, не из документации): переменная в браузере равна undefined, кто-то добавляет префикс, чтобы заработало, и секретный ключ оказывается в файле, который скачивает каждый посетитель. Минификация его не скрывает. Это ошибка того же рода, что и открытый файл .env, только на шаг позже. Правило из управления секретами: секреты живут в серверных переменных окружения, а браузер обращается к вашему бэкенду. Если фронтенд пишет ИИ-ассистент, сначала задайте ему правила безопасности для ИИ-ассистентов и узнайте, чего стоит утёкший ключ.

Публичные по замыслу ключи и секретные

Не каждый ключ в бандле это утечка: некоторые вендоры выпускают ключи, предназначенные для браузера. В таблице только то, что говорит документация самих вендоров:

КлючВ браузере?Что говорит документация
Публикуемый ключ Stripe (pk_)ДаСтраница ключей Stripe называет его безопасным для публикации и пригодным для фронтенда. Секретные (sk_) и ограниченные (rk_) ключи помечены как небезопасные.
Публикуемый ключ Supabase (прежний anon)ДаВ документации Supabase он назван безопасным для публикации, включая исходный код, а доступ определяет Row Level Security. Секретный ключ (прежний service_role) только для бэкенда и обходит все политики.
Веб-ключ API FirebaseДа, при наличии правилПо документации Firebase ключи, ограниченные сервисами Firebase, не нужно считать секретами, но данные нужно защищать правилами безопасности (Security Rules). Ключ Gemini Developer API никогда не должен попадать в ваш код.
Идентификатор ключа доступа AWS и секретный ключ доступаНетВ документации IAM сказано не помещать ключи доступа и учётные данные в файлы приложения.
Две колонки: ключи, которым не место во фронтенде, и ключи, которые документация вендоров называет безопасными для браузера
Публичный ключ безопасен только вместе с правилами за ним, например Row Level Security или Security Rules Firebase.

«Публичный» ключ безопасен только потому, что его что-то ограничивает, поэтому проверьте правила за ним: Row Level Security в Supabase и правила безопасности Firebase. Сканер не знает, какой именно ключ нашёл, поэтому решаете вы, по документации вендора. Если тип ключа не назван публичным, считайте его секретным и выдавайте серверным ключам только нужные права (принцип наименьших привилегий).

Собираем тестовый фронтенд и сканируем его перед деплоем

Прежде чем сканировать настоящий проект, убедитесь, что сканер работает на бандле, который вы контролируете. Мы собрали демо на Vite в контейнере Ubuntu 24.04 (Node 22.23.4, Vite 8.3.7) с намеренной ошибкой: секретные значения лежат в переменных VITE_. В файле .env явно поддельные значения:

VITE_STRIPE_PUBLISHABLE_KEY=pk_test_EXAMPLEFAKEPUBLISHABLE0000
VITE_STRIPE_SECRET_KEY=sk_live_FAKEDEMOKEYNOTREAL1a2B3c4D5e6F7g8H
VITE_INTERNAL_API_TOKEN=3f9a1c7e5b2d4086a1f3c9e7d5b30c11

Код читает их через import.meta.env и отправляет секретные в заголовке Authorization. (Первая попытка лишь проверяла, заданы ли значения, и минификатор их выбросил: значение, которым ничто не пользуется, в бандл не попадает.) Соберите проект и покажите файлы с поддельным ключом Stripe; флаг -l печатает только имена файлов, а не секрет:

npm install vite
npx vite build
grep -rlE "(sk|rk)_live_[A-Za-z0-9]+" dist
dist/assets/index-B9n7qF_d.js

Поддельный секрет теперь лежит открытым текстом в файле, который скачивает каждый браузер. Используйте явно поддельные ключи, как здесь; никогда не вставляйте в тест настоящий ключ.

Сканируйте папку, которую пишет сборщик, ведь именно её вы собираетесь публиковать. Мы проверяли dist/ от Vite. Next.js по умолчанию пишет в .next (документация distDir), там лежат и серверные файлы, так что находка там не обязательно публична. Сборку Next.js мы не запускали.

gitleaks. В README gitleaks есть команда dir для сканирования папок и файлов без истории git, а для установки указаны образы Docker и Homebrew. Загрузка образов в нашей среде блокировалась, поэтому мы запускали официальный релизный бинарник для Linux (8.30.1) в контейнере Ubuntu; образы Docker мы не проверяли.

gitleaks dir dist --no-banner --redact -v
Вывод gitleaks при скане папки dist: скрытый секрет, правило stripe-access-token, имя файла, одна утечка и код выхода 1
Сокращённый вывод нашего теста на Ubuntu 24.04: действовать нужно по имени правила и коду выхода.
Finding:     REDACTED
Secret:      REDACTED
RuleID:      stripe-access-token
Entropy:     4.868508
File:        dist/assets/index-B9n7qF_d.js
Line:        1

WRN leaks found: 1

-v печатает каждую находку, --redact скрывает секрет в логах, а RuleID называет сработавшее правило. По README код выхода при утечке равен 1 (меняется флагом --exit-code).

TruffleHog. В README TruffleHog описана команда trufflehog filesystem. Мы использовали релиз 3.99.8:

trufflehog filesystem dist --no-update --no-verification --fail
Found unverified result
Detector Type: Stripe
Raw result: sk_live_FAKEDEMOKEYNOTREAL1a2B3c4D5e6F7g8H
File: dist/assets/index-B9n7qF_d.js

--no-update отключает проверку обновлений, --no-verification оставляет сканирование локальным (см. предупреждение о проверке), а --fail делает код выхода 183 при наличии результатов; по README 0 значит «чисто», а 1 значит ошибку. TruffleHog напечатал секрет целиком, поэтому считайте логи CI чувствительными. Коды выхода зависят от инструмента, поэтому проверьте оба исхода сами: когда мы убрали секрет и пересобрали проект, gitleaks написал no leaks found, и оба инструмента завершились с кодом 0.

Одна неожиданность: пример идентификатора ключа AWS из документации (AKIAIOSFODNN7EXAMPLE) gitleaks не показал, потому что в его правиле для AWS есть исключение для значений на EXAMPLE, а TruffleHog пропустил ключ в формате Stripe с этим словом. Проверяйте сканеры подделкой без него.

Сканируем JavaScript живого сайта

Скан сборки проверяет то, что вы собирались выложить. Скан живого сайта проверяет то, что сервер отдаёт на самом деле: ловит неверную сборку, загруженную вручную, или старый файл, оставшийся на сервере. Сохраните скрипт как scan-live.sh и используйте только на своём сайте:

#!/bin/sh
# Download the scripts a page references and scan them. Only for your own site.
set -eu
SITE="${1:?usage: scan-live.sh https://your-site.example}"
WORK="$(mktemp -d)"
trap 'rm -rf "$WORK"' EXIT

curl -fsS "$SITE/" -o "$WORK/index.html"
grep -oE '(src|href)="/[^"]+\.m?js"' "$WORK/index.html" | cut -d'"' -f2 | sort -u |
while read -r path; do
  curl -fsS "$SITE$path" -o "$WORK/$(basename "$path")"
  echo "downloaded $SITE$path"
done
gitleaks dir "$WORK" --no-banner --redact

Скрипт использует curl (-f завершается ошибкой при ошибочных ответах HTTP), чтобы получить главную страницу и каждый скрипт с адресом от корня, и сканирует папку. Мы отдали демо-сборку из локального контейнера Caddy и запустили скрипт из второго контейнера Ubuntu 24.04:

./scan-live.sh http://jsscan-site:8080
downloaded http://jsscan-site:8080/assets/index-B9n7qF_d.js
WRN leaks found: 1

Ограничения: скрипт видит только скрипты, названные в HTML главной страницы, поэтому лениво подгружаемые части, другие страницы и скрипты, добавленные через JavaScript, не охвачены. Поэтому основной проверкой остаётся скан сборки. Для более широкого обзора того, что открыто на ваших доменах, см. сравнение Nuclei, reNgine и Uptime Kuma (шаблоны токенов Nuclei мы здесь не проверяли); ваша поверхность атаки больше, чем JavaScript.

Source maps: как проверить и перестать их публиковать

Source map это файл, который связывает минифицированный код с вашим исходным. В документации Chrome DevTools объясняется, что при загруженной карте браузер выполняет минифицированный код, а панель Sources показывает код, который вы написали. Для читателя это исходные имена, комментарии и структура. В карте нашего демо лежал весь исходный src/main.js вместе с комментариями, в поле sourcesContent.

Крупный план экрана ноутбука, заполненного плотными строками разноцветного исходного кода на тёмном фоне
Собранный бандл это стена кода, которую никто не читает, и секрет легко может в ней затеряться. Фото: Markus Spiske, StockSnap, CC0

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

curl -s https://example.com/assets/YOUR_FILE.js | tail -n 1
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/assets/YOUR_FILE.js.map
curl -s https://example.com/assets/YOUR_FILE.js.map | head -c 12

В нашем контейнере сборка с картами вернула //# sourceMappingURL=index-B9n7qF_d.js.map, статус 200 и тело, начинающееся с {"version":3. Если ваш сервер перенаправляет неизвестные адреса на index.html, один лишь код 200 ничего не доказывает, смотрите на тело: настоящая карта это JSON.

Перестаньте их публиковать. Документированные опции:

  • Vite. build.sourcemap по умолчанию false; true создаёт отдельный файл, а 'hidden' создаёт его без комментария со ссылкой. Наша обычная сборка карту не создала, и адрес вернул 404. Сборка с 'hidden' файл всё же создала, и наш сервер продолжил отдавать его с кодом 200, поэтому скрытая карта безопасна, только если вы её не загружаете.
  • Next.js. productionBrowserSourceMaps в продакшене выключена, пока вы её не включите; если включить, карты лежат рядом с JavaScript и отдаются автоматически.

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

Нужен второй взгляд на то, что открывает ваш сайт?

Бесплатная проверка в режиме только чтения покажет, что видно из интернета на вашем сервере и что исправлять в первую очередь.

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

Автоматизация: барьер перед деплоем и еженедельная проверка

Барьер перед деплоем. Поставьте сканы между сборкой и загрузкой. С set -e оболочка останавливается на первом ненулевом коде выхода, поэтому находка блокирует деплой. Мы проверили это в демо-проекте (его скрипт build это vite build):

#!/bin/sh
set -eu
npm run build
gitleaks dir dist --no-banner --redact
trufflehog filesystem dist --no-update --no-verification --fail
echo "scans clean, deploying"
# ./deploy.sh goes here

С подложенным секретом скрипт завершился с кодом 1 после gitleaks и до последней строки не дошёл; без секрета он напечатал scans clean, deploying и завершился с 0. Сервисы CI работают так же: шаг падает при ненулевом коде. Один раз проверьте сценарий с находкой, прежде чем доверять барьеру. Сам деплой разобран в руководстве как безопасно развернуть приложение на VPS.

Еженедельная проверка живого сайта. Держите scan-live.sh и эту обёртку в /opt/jsscan с владельцем без лишних прав (см. изоляцию проектов на одном VPS), сохраните её как weekly-scan.sh и сделайте исполняемой командой chmod +x:

#!/bin/sh
SITE=https://example.com
if ! OUT=$(/opt/jsscan/scan-live.sh "$SITE" 2>&1); then
  printf '%s\n' "$OUT" | tail -n 20 | /opt/jsscan/notify-telegram.sh "JS secret scan failed: $SITE"
fi

notify-telegram.sh это условное имя любого скрипта, который отправляет сообщение в Telegram. Как создать бота и отправить сообщение, объяснено в руководстве плановые сканирования Nuclei с оповещениями в Telegram, поэтому повторять это не будем; ещё один путь показан в руководстве Uptime Kuma с Telegram. В crontab(5) поля идут так: минута, час, день месяца, месяц, день недели, поэтому строка ниже запускает скрипт по понедельникам в 06:17:

17 6 * * 1 /opt/jsscan/weekly-scan.sh

Скрипты мы запускали вручную; cron и доставку в Telegram не проверяли.

Ложные срабатывания и что делать при настоящей находке

Проверенные ложные срабатывания. Фиксируйте решение в файле, а не игнорируйте сканер. В gitleaks блок [[allowlists]] в .gitleaks.toml вместе с [extend] useDefault = true (он сохраняет правила по умолчанию) добавляет ваше исключение:

[extend]
useDefault = true

[[allowlists]]
description = "Demo placeholder we have reviewed"
regexTarget = "secret"
regexes = ["^sk_live_FAKEDEMOKEYNOTREAL"]

Запустите gitleaks dir dist -c .gitleaks.toml. В нашем тесте находка исчезла (код 0), а без файла вернулся код 1. Делайте исключения узкими и не вносите в список настоящий секрет.

В README также описаны baseline (--baseline-path с прошлым отчётом) и файл отпечатков .gitleaksignore, помеченный как экспериментальный. Подводный камень для результатов сборки: baseline работал на неизменной сборке, но после правки кода хеш в имени файла изменился, находка перестала совпадать, и скан снова упал. Отпечаток содержит имя файла, так что от .gitleaksignore ждите того же (не проверяли). TruffleHog описывает строчный комментарий trufflehog:ignore, но минификаторы удаляют комментарии, поэтому используйте --exclude-detectors или --exclude-paths (оба есть в --help).

Настоящая находка. В таком порядке:

  1. Сначала перевыпустите или отзовите ключ. В документации Stripe сказано, что скомпрометированный секретный или ограниченный ключ нужно перевыпустить, чтобы заблокировать злоупотребление; срок «Now» сразу удаляет старый ключ, а отложенный срок оставляет оба рабочими до 7 дней. Для утёкшего ключа выбирайте немедленное истечение.
  2. Проверьте журналы использования у провайдера с момента публикации файла. Страница ключей Stripe описывает журналы запросов по каждому ключу, а документация AWS IAM рекомендует CloudTrail для контроля ключей доступа. Незнакомые запросы это повод для реагирования на инцидент.
  3. Перенесите вызов на сервер, пересоберите проект, удалите старые файлы бандла с сервера и из кэша CDN (из-за хешей в именах они остаются доступными) и повторите скан живого сайта.
  4. Историю Git чистите в последнюю очередь, см. что делать, если ключ API утёк на GitHub, и посмотрите журналы сервера, если ключ использовал ваш бэкенд.

Что сканеры не видят и что отправляет проверка

Что они пропускают. Сканер ищет по шаблонам, поэтому это страховка, а не доказательство. В наших тестах:

  • Ключ, разбитый на части и склеенный в коде (["sk_li", "ve_...", "..."].join("")), не нашёл ни один инструмент.
  • 32-символьный шестнадцатеричный токен в заголовке Authorization не нашёл ни один: у него нет префикса вендора, а в минифицированном бандле пропало имя переменной, которое нужно общим правилам «key» или «token».
  • Тот же ключ в формате Stripe, закодированный в base64 внутри atob(), нашли оба. Справка gitleaks 8.30.1 показывает декодирование до глубины 5 по умолчанию.

Обфускация может скрыть и больше, а сканер не оценивает опасность: он видит строку, похожую на ключ, а не то, что она позволяет сделать.

Что отправляет проверка. В README TruffleHog сказано, что проверенный (verified) результат означает: инструмент подтвердил учётные данные, проверив их через API сервиса (для AWS это вызов, который выясняет, активны ли данные). Значит, при включённой проверке найденный ключ отправляется провайдеру, а проверка видна в журналах этого ключа. В README gitleaks, который мы читали, шага проверки нет. Мы убедились, что оба инструмента работают офлайн: с флагом Docker --network none gitleaks и TruffleHog с --no-verification всё равно нашли подложенный ключ. Если вы не уверены, что делает проверка, используйте --no-verification и считайте любую находку настоящей. «Verified» это сильный признак живого ключа; «unverified» не доказывает, что ключ мёртв, так что перевыпускайте в любом случае.

Что делать дальше, как мы проверяли и источники

  • Сканируйте сборку каждого проекта, а не только главного, каждую в своей папке (руководство по тесту изоляции).
  • Добавьте еженедельный скан к остальным внешним проверкам в кластере мониторинга.
  • Просите помощи, если в журналах провайдера видно подозрительное использование или вы не можете понять, публичен ли ключ по замыслу.

Как мы это проверяли. 9 ноября 2026 года мы собрали демо на Vite 8.3.7 с Node 22.23.4 в контейнере Ubuntu 24.04, подложили поддельные ключи и запустили gitleaks 8.30.1 и TruffleHog 3.99.8 (официальные релизные бинарники Linux arm64, контрольные суммы сверили с опубликованными) на dist/ и на локальном контейнере Caddy, который его отдавал. Загрузка образов Docker этих сканеров блокировалась в нашей среде, поэтому образы Docker, сборку Next.js, cron и настоящую доставку в Telegram мы не проверяли. Скан TruffleHog с включённой проверкой на подложенном ключе мы ни разу не запускали.

Источники. README gitleaks, README TruffleHog, переменные окружения Next.js, env и режимы Vite, ключи API Stripe, ключи API Supabase, ключи API Firebase, ключи доступа AWS IAM.

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

Как проверить, есть ли ключи API в JavaScript моего сайта?

Соберите сайт и запустите сканер секретов, например gitleaks (gitleaks dir dist) или TruffleHog (trufflehog filesystem dist), на папке сборки. Для живого сайта скачайте скрипты, на которые ссылается страница, и просканируйте их, только на своём сайте.

Безопасно ли хранить ключ API в переменной NEXT_PUBLIC_ или VITE_?

Только если ключ задуман публичным. Next.js встраивает переменные NEXT_PUBLIC_ в браузерный бандл при сборке, а документация Vite говорит, что переменные VITE_ попадают в клиентский код и не должны содержать ключи API.

Публикуемый ключ Stripe или ключ API Firebase в бандле это утечка?

Сам по себе нет. Stripe пишет, что публикуемые ключи безопасно использовать во фронтенде, а Firebase пишет, что ключи, ограниченные сервисами Firebase, не нужно считать секретами. Секретный ключ Stripe или ключ Gemini Developer API в бандле это утечка.

Раскрывают ли source maps мои ключи API?

Сами по себе нет, но карта может содержать весь исходный код с комментариями, и жёстко прописанный секрет легко прочитать. Чтобы проверить, запросите файл .map скрипта, и отключите карты или не выкладывайте их на сервер.

Что лучше для сканирования папки сборки: gitleaks или TruffleHog?

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

Отправляет ли TruffleHog мои ключи API провайдеру?

При включённой проверке да: в README сказано, что инструмент подтверждает учётные данные, проверяя их через API сервиса. Для локального сканирования используйте --no-verification.

Я нашёл секретный ключ в развёрнутом JavaScript. Что делать сначала?

Немедленно перевыпустите или отзовите ключ, затем проверьте журналы использования у провайдера на незнакомые запросы. Потом перенесите вызов на сервер, пересоберите проект, удалите старые файлы бандла и повторите скан живого сайта.

Не уверены, в каком состоянии ваш сервер?

Получите бесплатную проверку безопасности в режиме только чтения или поговорите с инженером по безопасности об управляемой защите.

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