GitHub Action: 42Crunch REST API Static Security Testing

Действие REST API Static Security Testing находит контракты REST API, соответствующие спецификации OpenAPI (OAS, ранее известной как Swagger), и выполняет по ним тщательные проверки безопасности. Поддерживаются OAS v2 и v3.0.x в форматах JSON и YAML.

Это действие можно использовать в следующих сценариях:

• Добавление автоматической задачи статического тестирования безопасности API (SAST) в ваши CI/CD конвейеры.
• Выполнение этих проверок при ревью pull request и/или слиянии кода.
• Отметка обнаруженных проблем в разделе Security / Code Scanning Alerts в GitHub.

Действие работает на основе 42Crunch API Security Audit. Security Audit выполняет статический анализ определения API, включающий более 300 проверок лучших практик и потенциальных уязвимостей, связанных с аутентификацией, авторизацией, а также ограничениями данных.

Поиск API в ваших репозиториях

По умолчанию это действие:

1. Ищет все файлы .json и .yaml в репозитории.
2. Выбирает файлы, использующие схему OpenAPI.
3. Выполняет проверку безопасности определений OpenAPI.

Таким образом, вы можете находить новые или изменённые контракты API в репозитории.

Вы можете точно настроить поведение действия, указав конкретные части репозитория или маски имён файлов, которые должны быть включены или исключены при поиске API. Вы можете даже полностью отключить поиск и вместо этого указать только конкретные файлы API для проверки и сопоставить их с существующими API в 42Crunch API Security Platform. Все эти параметры настраиваются в файле конфигурации 42c-conf.yaml. Дополнительные примеры см. здесь.

Все обнаруженные API загружаются в коллекцию API на платформе 42Crunch. По умолчанию действие использует переменные окружения GITHUB_REPOSITORY и GITHUB_REF для указания имени репозитория и ветки/тега/PR, из которых произошла коллекция API. Вы можете переопределить имя с помощью параметра действия default-collection-name. При последующих запусках API в коллекции синхронизируются с изменениями в вашем репозитории.

Использование этого действия для блокировки развёртывания уязвимых API

Добавьте это действие в свои CI/CD конвейеры в GitHub, и оно будет завершаться ошибкой для определений API, содержащих проблемы безопасности.

Security Audit присваивает каждому контракту API оценку от 0 до 100, отражающую поверхность безопасности ваших API. Вы можете использовать параметр min-score GitHub Action, чтобы задать пороговое значение оценки, при котором действие завершается ошибкой (по умолчанию — 75, если не указано другое значение). Это помогает выявлять определения API низкого качества и устранять проблемы как можно раньше, уже на этапе проектирования.

Более сложные условия завершения с ошибкой можно задать в файле конфигурации 42c-conf.yaml, например, оценку аудита по категориям (безопасность или проверка данных), уровень серьёзности проблем или даже конкретные проблемы по их идентификатору. Дополнительные примеры см. здесь.

Кроме того, плагин обеспечивает соблюдение шлюзов качества безопасности, определённых на уровне платформы (по умолчанию или на основе тегов). Шлюзы качества безопасности обеспечивают соблюдение требований безопасности приложений, определённых на уровне предприятия.

Чтение подробных отчётов с рекомендациями

При каждом запуске действие включает ссылку на подробный приоритизированный отчёт с рекомендациями для каждого вашего файла OpenAPI:

Перейдите по ссылкам, чтобы прочитать подробный отчёт на платформе 42Crunch:

Загрузка оповещений 42Crunch в code scanning GitHub

Вы также можете отслеживать проблемы, обнаруженные аудитом 42Crunch, непосредственно в GitHub, на вкладке Security, в разделе Code scanning alerts.

Чтобы включить эту функцию, просто добавьте upload-to-code-scanning:true в параметры действия в вашем GitHub workflow.

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

Начало работы

Это действие использует сервис 42Crunch API Security Audit. Перед использованием действия вам потребуется учётная запись на платформе 42Crunch. Если вы не являетесь клиентом 42Crunch, вы можете запросить бесплатную учётную запись на этой странице: https://42crunch.com/get-started/.

Затем выполните шаги, описанные в документации, чтобы создать API-токен для аутентификации действия на платформе 42Crunch, и сохраните его как секрет в GitHub.

Параметры действия

api-token

Обязательный параметр. API-токен, который GitHub Action использует для аутентификации на платформе 42Crunch. Не указывайте API-токен напрямую в файле workflow! Вместо этого создайте секрет GitHub в настройках репозитория и укажите его так, как показано в примере ниже.

min-score

Минимальная оценка аудита, которую должны достичь файлы OpenAPI, иначе действие завершится ошибкой. По умолчанию — 75.

upload-to-code-scanning

Загрузка результатов аудита в Github Code Scanning. По умолчанию — false. Обратите внимание, что для успешного выполнения этого шага workflow должен иметь соответствующие разрешения.

...
jobs:
  run_42c_audit:
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for results upload to Github Code Scanning
...

ignore-failures

Если задано значение true, принудительно завершает выполнение успешно, даже если заданные вами условия завершения с ошибкой (например, min-score или критерии SQG) выполнены. По умолчанию — false.

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

ignore-network-errors

Если задано значение true, принудительно завершает выполнение успешно, даже если произошла сетевая ошибка (например, сбой подключения к платформе 42Crunch и т. д.). По умолчанию — false.

skip-local-checks

Если задано значение true, отключает все условия завершения с ошибкой (например, минимальную оценку), заданные в файле 42c-conf.yaml, и завершает выполнение ошибкой только в том случае, если не соблюдены критерии, определённые в SQG. По умолчанию — false.

platform-url

URL-адрес, по которому вы обращаетесь к платформе 42Crunch. По умолчанию — https://us.42crunch.cloud.

Если вы корпоративный клиент, укажите URL-адрес, который вы используете для доступа к своей производственной платформе.

root-directory

Корневой каталог, содержащий файл конфигурации 42c-conf.yaml. Если не указан, используется текущий рабочий каталог плагина, который обычно соответствует корню проверенного репозитория.

default-collection-name

Имя коллекции по умолчанию, используемое при создании коллекций для обнаруженных API. Если имя не задано, имя по умолчанию создаётся на основе информации о репозитории и ветке/PR.

log-level

Уровень детализации в журналах: один из FATAL, ERROR, WARN, INFO, DEBUG. По умолчанию — INFO.

share-everyone

Автоматически предоставляет доступ к коллекциям API, созданным задачей CI/CD, всем пользователям вашей организации на платформе 42Crunch. Допустимые значения: OFF, READ_ONLY, READ_WRITE. По умолчанию — OFF. Обратите внимание, что учётная запись, от имени которой выполняется действие (владелец API-токена), должна иметь разрешение Share with Everyone, иначе задача завершится ошибкой 403.

json-report

Записывает отчёт о выполнении аудита в формате JSON в указанный файл. Отчёт о выполнении содержит список API, которые были созданы, обновлены и удалены. Это полезно, если вы хотите автоматически обрабатывать результаты выполнения аудита на последующем шаге конвейера. По умолчанию отчёт не записывается.

api-tags

Задача CI/CD может автоматически назначать теги вновь созданным API. Теги указываются в следующем формате: category1:name1 category2:name2. Этот флаг является необязательным.

sarif-report

Преобразует необработанный JSON-формат аудита в SARIF и сохраняет результаты в указанный файл. По умолчанию отчёт не записывается.

audit-timeout

Задаёт максимальное время ожидания (в секундах) для отчёта аудита. Задача завершится ошибкой, если результат не будет готов в течение этого интервала. По умолчанию: 600

Предварительные требования

Создайте API-токен на платформе 42Crunch и скопируйте его значение в секрет репозитория с именем API_TOKEN.

Примеры

Пример одного шага

Типичный новый шаг в существующем workflow выглядит так:

- name: 42crunch-static-api-testing
        uses: 42Crunch/api-security-audit-action@v4
        with:
          api-token: ${{ secrets.API_TOKEN }}
          default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
          log-level: info
          json-report: audit-action-report-${{ github.run_id }}
          sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF

Пример полного workflow

Типичный workflow, который проверяет содержимое репозитория, выполняет Security Audit для каждого найденного файла OpenAPI и сохраняет файл выполнения как артефакт, выглядит так:

name: "42crunch-audit-workflow"

# follow standard Code Scanning triggers
on:
  push:
    branches: [ "main" ]
  pull_request:
    # The branches below must be a subset of the branches above
    branches: [ "main" ]
  schedule:
    - cron: '19 9 * * 6'

env:
  PLATFORM_URL: https://us.42crunch.cloud

jobs:
  run_42c_audit:
    environment: QA
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for results upload to Github Code Scanning
    runs-on: ubuntu-latest
    steps:
      - name: checkout repo
        uses: actions/checkout@v3
      - name: 42crunch-static-api-testing
        uses: 42Crunch/api-security-audit-action@v4
        with:
          api-token: ${{ secrets.API_TOKEN }}
          platform-url: ${{ env.PLATFORM_URL}}
          default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
          # Upload results to Github code scanning
          upload-to-code-scanning: false
          log-level: info
          json-report: audit-action-report-${{ github.run_id }}
          sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
      - name: save-audit-report
        if: always()        
        uses: actions/upload-artifact@v3
        with:
          name: auditaction-report-${{ github.run_id }}
          path: audit-action-report-${{ github.run_id }}.json
          if-no-files-found: error

Поддержка

Действие поддерживается командой 42Crunch Ecosystems. Если вы столкнулись с проблемой или у вас есть вопрос, на который здесь нет ответа, вы можете создать обращение в службу поддержки на support.42crunch.com.

При сообщении о проблеме обязательно укажите:

• Версию GitHub Action
• Соответствующие журналы и сообщения об ошибках
• Шаги для воспроизведения проблемы