Просмотр кода страницы Приём событий безопасности и логов аудита GitHub Advanced Security


= Приём событий безопасности и логов аудита GitHub Advanced Security =
Приоритизируйте результаты безопасности GitHub, обогащая их контекстом времени выполнения.

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

== Обзор ==
Интеграция '''Ключ-АСТРОМ''' с '''GitHub Advanced Security''' ('''GHAS''') позволяет пользователям унифицировать и контекстуализировать результаты уязвимостей по инструментам и продуктам DevSecOps, обеспечивая центральную приоритизацию, визуализацию и автоматизацию результатов безопасности.

'''GitHub Advanced Security''' включает '''Code Security''' и '''Secret Protection''', которые генерируют результаты уязвимостей для артефактов разработки, таких как код и контейнеры. '''Ключ-АСТРОМ''' наблюдает за сущностями времени выполнения, связанными с этими артефактами. Приём и обогащение результатов уязвимостей помогают пользователям сосредоточиться на рисках с высоким влиянием, затрагивающих производственные приложения.

Кроме того, пользователи '''GitHub''' могут использовать контекст времени выполнения '''Ключ-АСТРОМ''' для приоритизации оповещений '''GitHub Advanced Security''' на основе развёрнутых артефактов и риска времени выполнения в вашей среде '''Kubernetes'''. Когда вы подключаете '''Ключ-АСТРОМ''' к '''GitHub''', вы видите видимость развёртывания для образов контейнеров, которые '''Ключ-АСТРОМ''' сопоставляет с вашими репозиториями, вместе с сигналами риска времени выполнения. Вы можете использовать этот контекст, чтобы сосредоточить исправление на оповещениях, которые затрагивают развёрнутые артефакты, особенно когда '''Ключ-АСТРОМ''' обнаруживает условия времени выполнения с более высоким риском.

== Варианты использования ==
С принятыми данными вы можете реализовать различные сценарии, такие как:

* Визуализация и анализ результатов безопасности
* Автоматизация и оркестрация результатов безопасности
* Обнаружение пробелов в покрытии результатов безопасности

== Требования ==
Ниже приведены требования для '''GitHub''' и '''Ключ-АСТРОМ'''.

=== Требования GitHub ===
Для сбора данных безопасности расширению необходимы учётные данные аутентификации с соответствующими разрешениями. У вас есть два варианта, описанных ниже.

==== Аутентификация на основе приложения GitHub ====
'''Рекомендуется'''

Аутентификация на основе приложения '''GitHub''':

* Позволяет осуществлять гранулярный контроль разрешений
* Может собирать логи аудита уровня организации
* Имеет более высокие лимиты частоты '''API'''

Чтобы зарегистрировать и установить приложение '''GitHub''', выполните следующие шаги.

'''1. Зарегистрируйте приложение GitHub'''

Следуйте инструкциям в разделе «Регистрация приложения GitHub» со следующими значениями:

* Для '''GitHub App Name''' введите <code>astromkeyAppSec-&#x3C;Your Company&#x3E;</code>, заменив <code>&#x3C;Your Company&#x3E;</code> на своё значение.
* Для '''Homepage URL''' введите <code>https://astromkey.com</code>.
* Снимите флажок '''Webhook''' > '''Active'''.
* Включите следующие разрешения:

   * Разрешения репозитория:
      * '''Contents''': Read-only
      * '''Dependabot alerts''': Read-only
      * '''Code scanning alerts''': Read-only (требуется при приёме событий сканирования кода)
      * '''Secret scanning alerts''': Read-only (требуется при приёме событий сканирования секретов)
      * '''Artifact metadata''': Read-and-write (требуется при отправке контекста времени выполнения в '''GitHub''')
      * '''Attestations''': Read-only (требуется при отправке контекста времени выполнения в '''GitHub''')
   * Разрешения организации:
      * '''Administration''': Read-only (требуется для логов аудита)

* Чтобы указать место установки приложения, выберите одно из следующего:

   * '''Any account''' (позволяет установить приложение в нескольких организациях и даже в учётной записи пользователя, что упростит ваши конфигурации мониторинга)
   * '''Only this account''' (приложение устанавливается в текущей учётной записи; это означает, что вам понадобятся несколько приложений и конфигураций мониторинга, чтобы охватить несколько организаций в рамках предприятия)
'''2. Сгенерируйте закрытый ключ для приложения'''

# Выберите вкладку '''General''' и перейдите в настройки только что зарегистрированного приложения.
# Скопируйте '''Client ID''' (он понадобится вам при настройке конфигурации мониторинга).
# В разделе '''Private keys''' сгенерируйте закрытый ключ (он понадобится вам при настройке конфигурации мониторинга).

Закрытый ключ позволяет аутентифицированные запросы от расширения; обязательно защитите его.

'''3. Установите приложение'''

Установите приложение '''GitHub''' на любые учётные записи (пользователей или организации), которые вы хотите отслеживать.

Мы рекомендуем использовать аттестации артефактов для связывания ваших пакетов образов контейнеров с соответствующими репозиториями '''GitHub'''. Это обеспечивает надёжное обогащение контекстом времени выполнения независимо от реестра контейнеров. Если для пакета образа нет аттестации, '''Ключ-АСТРОМ''' пытается сопоставить образ с репозиторием на основе шаблона полного имени образа (поддерживается только для образов, размещённых на <code>ghcr.io</code>).

==== Аутентификация на основе PAT ====
Аутентификация на основе '''Personal Access Token''' ('''PAT'''):

* Позволяет быстрее настроить
* Подходит для быстрой проверки интеграции
* Позволяет собирать логи аудита

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

Чтобы сгенерировать '''Personal Access Token''', следуйте инструкциям в разделе «Управление вашими персональными токенами доступа», обязательно указав следующие значения:

* Токен должен быть '''Classic Personal Access Token'''.
* '''Expiration''': если вы установите срок действия токена, вы несёте ответственность за его обновление.
* '''Scopes''':

   * <code>repo</code>: полный контроль
   * <code>audit_log</code>: <code>read:audit_log</code>

=== Требования Ключ-АСТРОМ ===

* '''АктивныйШлюз''' версии 1.310+, который должен иметь возможность:

   * Запускать фреймворк '''Расширения 2.0'''
   * Достигать '''URL'''-адресов конечных точек '''API''' '''GitHub'''

* Разрешения:

   * Для запуска расширений: перейдите в раздел '''Расширения''', выберите '''Расширения''' и откройте '''Техническую информацию'''.
   * Для запроса принятых данных: <code>storage:security.events:read</code>.

* Сгенерируйте токен доступа с областью <code>openpipeline.events_security</code> и сохраните его для дальнейшего использования.
* Чтобы отправлять контекст времени выполнения в '''GitHub''', сгенерируйте токен платформы со следующими областями и сохраните его для дальнейшего использования:

   * <code>storage:smartscape:read</code>
   * <code>storage:buckets:read</code>
   * <code>storage:security.events:read</code>

* Опционально: настройте '''Ключ-АСТРОМ Runtime Vulnerability Analytics''' ('''RVA'''), чтобы получать оценки экспозиции в интернете и активов чувствительных данных для отслеживаемых контейнеров.

== Активация и настройка ==

# В '''Ключ-АСТРОМ''' найдите '''GitHub Advanced Security''' и выберите '''Установить'''.
# Следуйте инструкциям на экране для настройки расширения.
# Проверьте конфигурацию, выполнив следующие запросы в '''Notebooks''':

'''Для логов аудита:'''<pre>
fetch logs
| filter log.source=="GitHub Advanced Security"
</pre>'''Для событий результатов:'''<pre>
fetch security.events
| filter dt.system.bucket == "default_securityevents"
| filter event.provider=="GitHub Advanced Security"
AND event.type=="VULNERABILITY_FINDING"
</pre>'''Для событий сканирования:'''<pre>
fetch security.events
| filter dt.system.bucket == "default_securityevents"
| filter event.provider=="GitHub Advanced Security"
  AND event.type=="VULNERABILITY_SCAN"
</pre>Чтобы подтвердить, что контекст времени выполнения передаётся, перейдите в раздел '''Packages''' в '''GitHub''' и откройте '''Linked artifacts''' для вашей организации. Запись развёртывания указывает на успешную передачу.

После установки и запуска расширения вы можете получить к нему доступ и управлять им в '''Ключ-АСТРОМ''' через раздел '''Расширения'''.

== Детали ==

=== Как это работает ===
'''Как работает приём GitHub Advanced Security'''

'''1. События и логи собираются из продуктов GHAS''' Интеграция '''Ключ-АСТРОМ''' '''GHAS''' — это расширение, развёрнутое в '''АктивныйШлюз''' '''Ключ-АСТРОМ''', которое периодически собирает результаты безопасности и логи аудита с помощью '''GitHub REST API'''.

'''2. Результаты безопасности и логи принимаются в Ключ-АСТРОМ''' Результаты безопасности принимаются в платформу '''Ключ-АСТРОМ''' через выделенную конечную точку приёма безопасности '''OpenPipeline'''.

'''3. Результаты безопасности и логи обрабатываются и сохраняются''' Конечная точка приёма '''OpenPipeline''' обрабатывает и сопоставляет результаты безопасности в соответствии с соглашениями '''Семантического словаря'''.

Они хранятся в бакете <code>default_securityevents</code>.

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

'''4. Контекст времени выполнения отправляется в GitHub как записи развёртывания''' '''Ключ-АСТРОМ''' запрашивает данные для сбора контекста времени выполнения для рабочих нагрузок '''Kubernetes''', работающих в вашей среде. Этот контекст сопоставляется с отслеживаемыми репозиториями с использованием аттестаций артефактов или имён образов (для образов, размещённых на <code>ghcr.io</code>). Полученный контекст времени выполнения затем передаётся в '''GitHub''' как записи развёртывания.

== Лицензирование и затраты ==
Информацию о выставлении счетов см. в разделе «События».

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

В сильно сегментированных сетях наборы функций могут отражать сегменты вашей среды. Затем при создании конфигурации мониторинга вы можете выбрать набор функций и соответствующую группу '''АктивныйШлюз''', которая может подключиться к этому конкретному сегменту.

Все метрики, не отнесённые ни к одному набору функций, считаются стандартными и всегда сообщаются.

Метрика наследует набор функций подгруппы, которая, в свою очередь, наследует набор функций группы. Кроме того, набор функций, определённый на уровне метрики, переопределяет набор функций, определённый на уровне подгруппы, который, в свою очередь, переопределяет набор функций, определённый на уровне группы.

== Часто задаваемые вопросы ==
'''Какая модель данных используется для логов и событий безопасности, поступающих из интеграции GHAS?'''

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

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

Логи аудита представляют логи активности пользователей в продуктах '''GHAS'''.

'''Какие результаты безопасности GHAS импортируются в Ключ-АСТРОМ?''' Если расширение настроено на приём данных с интервалом в n часов, то при каждом запуске расширения принимаются все события безопасности ('''Dependabot''', сканирование кода и оповещения сканирования секретов), обновлённые за последние n часов.

При первом приёме мы учитываем оповещения, обновлённые за последние m часов, где m — это интервал первого приёма, настроенный в конфигурации мониторинга.

Если сканирования не происходили, результаты не принимаются, даже если у проекта есть открытые проблемы.

'''Какие поля расширения добавляются к основным полям событий, принятых из GHAS?''' Пространство имён <code>github</code> добавляется для извлечения нескольких специфичных для '''GHAS''' атрибутов для удобства пользователя поверх исходного '''JSON''' проблемы, который хранится в поле <code>event.original_content</code>.

Примеры:

* <code>github.dependency.relationship</code>
* <code>github.dependency.scope</code>
* <code>github.epss.percentage</code>
* <code>github.epss.percentile</code>
* <code>github.ecosystem</code>

'''Какие типы активов GHAS поддерживаются Ключ-АСТРОМ для контекстуализации во время выполнения?''' <code>CODE_ARTIFACT</code>: все результаты из продуктов '''GitHub Advanced Security''', полученные в результате оценки артефактов кода, сопоставляются со значением <code>CODE_ARTIFACT</code> в поле <code>object.type</code>, а пространства имён <code>artifact</code> и <code>component</code> добавляются с соответствующими полями:

* <code>artifact.repository.name</code> представляет имя репозитория, в котором размещён артефакт.
* <code>artifact.path</code> — полный путь к файлу, представляющему артефакт кода.
* <code>component.name</code> представляет имя уязвимой библиотеки внутри артефакта кода.
* <code>component.version</code> содержит версию уязвимого компонента.

'''GitHub''' предоставляет только граничные значения, а не точную версию, например <code>&#x3C;1.4</code>. Это ограничивает возможность сопоставления компонентов времени выполнения, поскольку версия в этом случае не сопоставляется.

'''Какой контекст времени выполнения из Ключ-АСТРОМ передаётся в GitHub?''' '''Ключ-АСТРОМ''' отправляет записи развёртывания в '''GitHub''' для всех образов контейнеров, идентифицированных в отслеживаемых контейнерах, которые соответствуют аттестациям артефактов образов, доступных настроенному пользователю в '''GitHub'''. Если '''Runtime Vulnerability Analytics''' ('''RVA''') включён для отслеживаемых контейнеров, записи развёртывания включают оценки экспозиции в интернете и активов чувствительных данных.

'''Пример запроса:'''<pre>
smartscapeNodes CONTAINER, from: -2h
| filter exists(k8s.namespace.name) // will update to filter to configured namespaces
| expand k8s.workload.id=coalesce(references[is_part_of.k8s_deployment],
                        coalesce(references[is_part_of.k8s_daemonset],
                            coalesce(references[is_part_of.k8s_cronjob],
                            coalesce(references[is_part_of.k8s_statefulset],
                                coalesce(references[is_part_of.k8s_job],
                                references[is_part_of.k8s_replicaset])))))
| lookup [
smartscapeNodes {{K8S_DEPLOYMENT, K8S_CRONJOB, K8S_DAEMONSET, K8S_JOB, K8S_STATEFULSET, K8S_REPLICASET}}, from:now()-2h
], sourceField:k8s.workload.id, lookupField:id, fields:{{k8s.workload.id_classic=id_classic}}
| join [
// query vulnerabilities
fetch security.events
| filter event.type=="VULNERABILITY_STATE_REPORT_EVENT"
AND event.level=="ENTITY"
// for all the affected workloads
| expand k8s.workload.id_classic=related_entities.kubernetes_workloads.ids
| summarize {{
    exposure_status=collectDistinct(vulnerability.davis_assessment.exposure_status),
    data_assets_status=collectDistinct(vulnerability.davis_assessment.data_assets_status)
}}, by:{{k8s.workload.id_classic}}
| fieldsAdd exposure_status=if(in("PUBLIC_NETWORK",exposure_status),"PUBLIC_NETWORK", else:
                            if(in("ADJACENT_NETWORK",exposure_status),"ADJACENT_NETWORK", else:
                            if(in("NOT_DETECTED",exposure_status),"NOT_DETECTED", else:"NOT_AVAILABLE")))
| fieldsAdd data_assets_status=if(in("REACHABLE",data_assets_status),"REACHABLE", else:
                            if(in("NOT_DETECTED",data_assets_status),"NOT_DETECTED", else:"NOT_AVAILABLE"))
], kind:leftOuter, on:{{k8s.workload.id_classic}}, fields:{{exposure_status, data_assets_status}}
| fieldsAdd exposure_status=coalesce(exposure_status,"NOT_AVAILABLE"),
            data_assets_status=coalesce(data_assets_status,"NOT_AVAILABLE")
| fields container.image.digest, container.image.name, k8s.namespace.name, exposure_status, data_assets_status
| dedup container.image.digest, container.image.name, k8s.namespace.name, exposure_status, data_assets_status
</pre>'''Как я могу использовать контекст времени выполнения в GitHub?''' Вы можете использовать видимость развёртывания и сигналы риска времени выполнения для фильтрации и приоритизации оповещений сканирования кода '''GitHub''' и '''Dependabot''', в том числе в кампаниях безопасности.

Например, чтобы найти уязвимости, которые затрагивают развёрнутые артефакты, подверженные интернету, используйте:<pre>
has:deployment AND runtime-risk:internet-exposed
</pre>Сигналы риска времени выполнения включают:

* Экспозиция в публичном интернете (<code>runtime-risk:internet-exposed</code>)
* Доступ к активам чувствительных данных (<code>runtime-risk:sensitive-data</code>)

'''Как нормализуется оценка риска для результатов GHAS?''' '''Ключ-АСТРОМ''' нормализует серьёзность и оценки риска для всех результатов, принятых через текущую интеграцию. Это помогает согласованно приоритизировать результаты независимо от их источника.

Уровни и оценки риска '''Ключ-АСТРОМ''' сопоставляются из исходной серьёзности и оценки '''GHAS'''.

* <code>dt.security.risk.level</code> — берётся из уровня серьёзности '''GHAS''' и сопоставляется из исходных значений в <code>finding.severity</code>.
* <code>dt.security.risk.score</code> — берётся из уровня серьёзности '''GHAS''' и сопоставляется со статическими оценками. Оценка '''CVSS''', сообщаемая '''GHAS''', доступна в <code>finding.score</code>; однако она может не всегда соответствовать сообщённой серьёзности.

{| class="wikitable"
!dt.security.risk.level (сопоставлено из finding.severity)
!dt.security.risk.score (сопоставлено из dt.security.risk.level)
|-
|critical → CRITICAL
|10,0
|-
|high/error → HIGH
|8,9
|-
|medium/warning → MEDIUM
|6,9
|-
|low/note → LOW
|3,9
|}
Оповещениям сканирования секретов присваивается уровень риска по умолчанию '''HIGH'''. Вы можете настроить этот параметр в разделе '''Дополнительные параметры''' во время настройки расширения.