Уроки безпечного коду для Bitbucket

RansomLeak може залишити в pull request у Bitbucket Cloud коментар із посиланням на короткий урок безпечного коду, коли сканер повідомляє про слабке місце в ньому. Це безкоштовно, не потребує облікового запису RansomLeak і не пов’язане з налаштуваннями вашої організації в RansomLeak. Працює в будь-якому робочому просторі Bitbucket Cloud, що використовує Bitbucket Pipelines.

Складників два. Більшості команд достатньо pipe. Застосунок RansomLeak — необов’язкове доповнення.

	Pipe	Pipe із застосунком
Що читає	Файл SARIF від вашого сканера	Той самий файл SARIF
Вартість	Безкоштовно	Безкоштовно
Коментар з уроками	Потрібен токен доступу до репозиторію, інакше лише звіт	Публікується від імені RansomLeak, токен не потрібен
Позначає завершений урок	Під час наступного запуску пайплайна	За кілька секунд
Звіт Code Insights	Так, ніколи не помилковий	Так, ніколи не помилковий
Потрібен адміністратор робочого простору	Ні	Так, один раз

Pipe

Додайте pipe після кроку, який запускає сканер і записує SARIF. Крок має мати oidc: true, щоб RansomLeak міг визначити, з якого робочого простору й репозиторію надійшов запит.

pipelines:
  pull-requests:
    '**':
      - step:
          name: Scan and learn
          oidc: true
          script:
            # ... your scanner writes results.sarif ...
            - pipe: docker://ghcr.io/ransomleak/secure-coding-pipe:1
              variables:
                SARIF: results.sarif
                BITBUCKET_ACCESS_TOKEN: $RANSOMLEAK_BB_TOKEN # optional

Pipe працює з CodeQL, Semgrep, Trivy, Gitleaks та іншими інструментами, правила яких мають CWE, CVE або GHSA, а також зі сканерами секретів. SARIF приймає шлях або glob, наприклад reports/**/*.sarif, до 50 МБ загалом. Pipe запускається лише в пайплайнах pull request. Інші пайплайни його пропускають.

Реєструватися не потрібно. Pipe входить у RansomLeak за допомогою токена OIDC цього кроку. Якщо контейнер pipe не отримує BITBUCKET_STEP_OIDC_TOKEN, передайте його явно: OIDC_TOKEN: $BITBUCKET_STEP_OIDC_TOKEN.

Коли сканер знаходить тип проблеми, для якого є урок, pipe записує для коміту звіт Code Insights із посиланнями на уроки. З токеном він також додає до pull request один коментар і надалі оновлює саме його. У коментарі до п’яти уроків, по одному на кожен окремий тип проблеми, кожен займає 5-10 хвилин.

Коментар RansomLeak у pull request Bitbucket із посиланням на урок SQL Injection

Коментар відображає те, про що повідомляє ваш сканер, тож для меншого шуму запускайте його лише на змінених файлах або з базовим рівнем (baseline). Якщо результат SARIF має baselineState, враховуються лише результати new і updated.

Дозвольте pipe коментувати (необов’язково)

Щоб отримувати коментар, дайте pipe токен доступу до репозиторію:

У репозиторії відкрийте Repository settings, потім Access tokens.
Створіть токен із дозволами Pull requests: Write і Repositories: Read.
У Repository settings, потім Repository variables, додайте його як захищену змінну з назвою RANSOMLEAK_BB_TOKEN.

Без токена pipe все одно публікує звіт Code Insights із кількістю уроків і посиланням Open lesson для кожного уроку та виводить примітку. Звіт з’являється в pull request у розділі Reports. Інший спосіб отримати коментар — встановити застосунок, токен йому не потрібен.

Позначки

Коли хтось завершує урок, позначка з’являється під час наступного запуску пайплайна для цього pull request, наприклад після наступного push. Без застосунку між запусками в pull request нічого не записується.

Той самий коментар після завершення уроку: урок позначено, показано дату завершення

Pipe ніколи не завершує вашу збірку помилкою. Якщо RansomLeak недоступний, токену бракує дозволу або файл SARIF відсутній чи пошкоджений, він виводить попередження й продовжує роботу.

Використання SonarQube замість файлу SARIF

Якщо SonarQube уже аналізує ваші pull request, pipe може читати його знахідки безпеки замість файлу SARIF. Вкажіть SONAR_HOST_URL і не передавайте SARIF. Потрібне рівно одне джерело: якщо вказано обидва або жодного, pipe виводить попередження й нічого не робить.

- step:
    name: Scan and learn
    oidc: true
    script:
      # спочатку запустіть сканування SonarQube для pull request у тому самому step
      - pipe: docker://ghcr.io/ransomleak/secure-coding-pipe:1
        variables:
          SONAR_HOST_URL: https://sonarcloud.io
          SONAR_ORGANIZATION: my-workspace
          SONAR_PROJECT_KEY: my-workspace_my-repo
          SONAR_TOKEN: $SONAR_READ_TOKEN
          BITBUCKET_ACCESS_TOKEN: $RANSOMLEAK_BB_TOKEN # optional

Змінна	Примітки
`SONAR_HOST_URL`	URL вашого SonarQube Server або `https://sonarcloud.io` для SonarQube Cloud.
`SONAR_PROJECT_KEY`	Ключ проєкту в Sonar.
`SONAR_ORGANIZATION`	Лише для SonarQube Cloud.
`SONAR_TOKEN`	Потрібен дозвіл Browse на проєкт. Зберігайте його як захищену змінну. Для публічних проєктів SonarQube Cloud необов’язковий.
`SONAR_INCLUDE_HOTSPOTS`	За замовчуванням `false`. Значення `true` додає security hotspots рівня HIGH і MEDIUM, які ще чекають перевірки.
`SONAR_WAIT_TIMEOUT`	Скільки секунд чекати на аналіз Sonar коміту пайплайна. За замовчуванням `300`.

Якщо сканування в тому самому step залишило report-task.txt, pipe чекає саме на цей аналіз. Інакше в SonarQube Cloud він чекає на аналіз BITBUCKET_COMMIT, а в Server читає останній аналіз.
Pipe читає відкриті вразливості та CWE-ідентифікатори кожного правила. Знахідки без CWE уроку не отримують, крім правил лише з тегом OWASP для A06 та A10.
SonarQube Server потребує Developer Edition або вищої. Community Build не аналізує pull request, тож там використовуйте SARIF з іншим сканером.
Токен Sonar надсилається лише на ваш хост Sonar і ніколи не потрапляє до RansomLeak. До RansomLeak йдуть лише назва сканера (SonarQube), CWE-ідентифікатори та категорії OWASP.
Pipe ніколи не завершує вашу збірку помилкою. Якщо Sonar прочитати не вдалося, він виводить попередження й продовжує роботу.

Застосунок RansomLeak (необов’язково)

Застосунок публікує коментар з уроками від імені RansomLeak, позначає уроки одразу після завершення й підтримує звіт Code Insights в актуальному стані. Токен доступу йому не потрібен.

Адміністратор робочого простору встановлює його один раз для всього простору за посиланням для встановлення. Застосунок просить доступ на читання й запис до pull request і репозиторіїв, більше нічого.

Застосунок уже працює. Встановити застосунок RansomLeak для Bitbucket.

Коли застосунок встановлено, pipe питає RansomLeak, хто має публікувати. Публікує застосунок, а pipe лише записує звіт. Якщо pipe вже залишив коментар у цьому pull request, застосунок створює власний з усіма уроками й позначками, а попередній коментар pipe замінюється коротким посиланням на нього. Активним залишається один коментар з уроками.

Якщо застосунок видалено з робочого простору, наступний запуск pipe знову публікує коментар за допомогою токена, а завершені уроки лишаються позначеними. Щоб припинити використання застосунку, видаліть його в налаштуваннях робочого простору.

Pull request із форків

Pull request із форків отримують лише звіт Code Insights. Коментар не публікується ні з застосунком, ні без нього.

Що покрито

SQL-ін’єкції
Міжсайтовий скриптинг (XSS)
Обхід шляху (path traversal)
Ін’єкції команд
Підробка запитів на боці сервера (SSRF)
Секрети в коді
Зовнішні сутності XML (XXE)
Відкрите перенаправлення
Міжсайтова підробка запитів (CSRF)
Вразливі залежності

Для десеріалізації та слабкої криптографії уроків поки немає.

Знахідка зіставляється за її CWE. Знахідки сканерів секретів і рекомендації щодо залежностей зіставляються за типом сканера. Категорії OWASP і широкі батьківські CWE, як-от CWE-200, не використовуються, бо вони не вказують на один конкретний урок.

Виправлення коду не прибирає урок із коментаря.

Які дані надсилаються

Pipe надсилає лише ідентифікатори: назву сканера, ідентифікатори CWE правил, що дали результат, ознаку того, що правило є рекомендацією CVE або GHSA, номер pull request і хеш коміту. Ідентифікатори робочого простору, репозиторію й кроку беруться з підписаного токена OIDC. Вихідний код, назви файлів, номери рядків, повідомлення, фрагменти й секрети не залишають раннер.

RansomLeak не зберігає персональних даних розробників. Зберігається:

Якщо встановлено застосунок, один запис про встановлення для кожного робочого простору: ідентифікатор встановлення, UUID робочого простору, URL веб-тригера застосунку й секрет ретрансляції, який генеруємо ми й зберігаємо в зашифрованому вигляді. Жодних персональних даних. Видалення застосунку прибирає цей запис.
Для кожного завершеного уроку одна позначка завершення для кожного робочого простору, репозиторію, pull request і уроку, лише з ідентифікаторами й часом першого завершення. Вона видаляється через 30 днів.

Ми не зберігаємо імен, адрес електронної пошти й облікових даних Bitbucket. Ваш токен доступу залишається у вашому пайплайні й надсилається лише до Bitbucket. Див. політику конфіденційності.

Завершення не підтверджується

Посилання на урок належить pull request, а не людині. Будь-хто, хто може відкрити pull request, може відкрити посилання й позначити урок завершеним.

Позначка означає, що урок завершено за цим посиланням. Сприймайте її як підказку, а не як доказ того, хто саме пройшов навчання.

Усунення проблем

Що ви бачите	Що перевірити
Попередження про відсутній токен OIDC	Крок має мати `oidc: true`. Якщо воно є, передайте pipe `OIDC_TOKEN: $BITBUCKET_STEP_OIDC_TOKEN`.
Немає коментаря, лише звіт	Не задано `BITBUCKET_ACCESS_TOKEN`, а застосунок не встановлено, або pull request із форка.
Попередження про 401 або 403 від Bitbucket	Токену бракує Pull requests: Write або Repositories: Read, або його термін минув. Попередження називає потрібний дозвіл.
Попередження про 429	Bitbucket обмежив частоту запитів. Коментар пропускається в цьому запуску й повертається в наступному.
Pipe повідомляє, що пропускає запуск	Він працює лише в пайплайнах pull request. Розмістіть його в `pipelines: pull-requests:`.
Попередження про файл SARIF	Шлях нічого не знаходить, файл порожній чи пошкоджений або перевищує 50 МБ.
Уроків немає взагалі	Жодна знахідка не має відповідного уроку. Перевірте, що правила вашого сканера мають CWE, CVE або GHSA.
Немає звіту	Pipe не зміг дістатися до проксі Pipelines, що записує звіти Code Insights. Перегляньте попередження в журналі кроку.

Обмеження

Уроки англійською.
Лише Bitbucket Cloud. Bitbucket Data Center не підтримується.
Звіт і коментар записуються для вихідного коміту pull request.
Урок з’являється лише тоді, коли знахідка сканера має відповідний урок. Для знахідок без відповідного уроку коментаря немає, зокрема для знахідок лише з категорією OWASP.