Рекомендации по созданию приложения GitHub

Выберите минимальные необходимые разрешения

При регистрации GitHub Appвыберите минимальные разрешения, необходимые вашим GitHub App. Если какие-либо ключи или маркеры для приложения скомпрометируются, это приведет к ограничению объема ущерба, который может произойти. Дополнительные сведения о выборе разрешений см. в разделе Выбор разрешений для приложения GitHub.

Когда GitHub App создает маркер доступа к установке или маркер доступа пользователя, вы можете дополнительно ограничить репозитории, к которым приложение может получить доступ, и разрешения, имеющиеся у маркера. Дополнительные сведения см. в разделе [AUTOTITLE и Создание маркера доступа к установке для приложения GitHub](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app).

Оставайтесь под ограничением скорости

Подпишитесь на события веб-перехватчика вместо опроса API для данных. Это поможет GitHub App оставаться в пределах ограничения скорости API. Дополнительные сведения см. в разделе [AUTOTITLE и Использование веб-перехватчиков с приложениями GitHub](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events).

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

По возможности рекомендуется использовать консолидированные запросы GraphQL вместо запросов REST API, чтобы помочь вам оставаться в пределах скорости. Дополнительные сведения см. в разделе [AUTOTITLE и Сравнение REST API GitHub и API GraphQL](/graphql).

Если вы достигнете ограничения скорости и должны повторить запрос API, используйте x-ratelimit-reset заголовки или Retry-After ответы. Если эти заголовки недоступны, дождитесь экспоненциального увеличения времени между повторными попытками и вызовите ошибку после определенного числа повторных попыток. Дополнительные сведения см. в разделе Рекомендации по использованию REST API.

Защита учетных данных приложения

Вы можете создать закрытый ключ и секрет клиента для данных GitHub App. С помощью этих учетных данных приложение может создавать маркеры доступа к установке, маркеры доступа пользователей и маркеры обновления. Эти маркеры можно использовать для выполнения запросов API от имени установки или пользователя приложения.

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

Закрытые ключи

Закрытый ключ для данных GitHub App предоставляет доступ к каждой учетной записи, в которую установлено приложение.

Попробуйте сохранить закрытый ключ GitHub Appв хранилище ключей, например Azure Key Vault, и сделать его только для входа.

Кроме того, ключ можно сохранить в качестве переменной среды. Однако это не так сильно, как хранение ключа в хранилище ключей. Если злоумышленник получает доступ к среде, он может считывать закрытый ключ и получать постоянную проверку подлинности как GitHub App.

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

Не следует создавать более закрытые ключи, чем вам нужны. Следует удалить закрытые ключи, которые больше не нужны. Дополнительные сведения см. в разделе Управление закрытыми ключами для приложений GitHub.

Секреты клиента

Секреты клиентов используются для создания маркеров доступа пользователей для приложения, если приложение не использует поток устройств. Дополнительные сведения см. в разделе Создание маркера доступа пользователя для приложения GitHub.

Если ваше приложение является веб-сайтом или веб-приложением, рассмотрите возможность хранения секрета клиента в хранилище ключей, например Azure Key Vault, или в качестве зашифрованной переменной среды или секрета на сервере.

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

Маркеры доступа установки, маркеры доступа пользователей и маркеры обновления

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

Если приложение является веб-сайтом или веб-приложением, необходимо зашифровать маркеры на серверной части и обеспечить безопасность в системах, которые могут получить доступ к маркерам. Рассмотрите возможность хранения маркеров обновления в отдельном месте от активных маркеров доступа.

Если приложение является собственным клиентом, клиентским приложением или работает на пользовательском устройстве (а не на серверах), возможно, вы не сможете защитить маркеры, а также приложение, которое выполняется на серверах. Не следует создавать маркеры доступа к установке, так как для этого требуется закрытый ключ. Вместо этого необходимо создать маркеры доступа пользователей. Маркеры следует хранить с помощью механизма, рекомендуемого для платформы вашего приложения, и помните, что механизм хранения может быть не полностью безопасным.

Использование соответствующего типа токена

GitHub Apps может создавать маркеры доступа установки или маркеры доступа пользователей для выполнения запросов API, прошедших проверку подлинности.

Маркеры доступа к установке будут атрибутировать действия приложения. Это полезно для автоматизации, которая действует независимо от пользователей.

Маркеры доступа пользователей будут атрибутировать действия пользователю и приложению. Это полезно для выполнения действий на основе ввода пользователем или от имени пользователя.

Маркер доступа к установке ограничен на основе разрешений и доступа GitHub App. Маркер доступа пользователя ограничен на основе разрешения и доступа пользователя GitHub App, а также разрешения и доступа пользователя. Таким образом, если GitHub App принимает действие от имени пользователя, он всегда должен использовать маркер доступа пользователя вместо маркера доступа к установке. В противном случае приложение может позволить пользователю видеть или делать вещи, которые они не должны видеть или делать.

Приложение никогда не должно использовать пароль personal access token или GitHub для проверки подлинности.

Авторизовать тщательно и надежно

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

Использование устойчивого, уникального `id` для хранения пользователя

Проверка доступа организации для каждой новой проверки подлинности

При использовании маркера доступа пользователей следует отслеживать, для каких организаций авторизован маркер. Если организация использует единый вход SAML и пользователь не выполнил единый вход SAML, маркер доступа пользователя не будет иметь доступа к этой организации. Конечную точку GET /user/installations REST API можно использовать для проверки того, к каким организациям имеется доступ маркера доступа пользователей. Если пользователь не авторизован для доступа к организации, следует запретить доступ к данным организации в собственном приложении, пока не будет выполняться единый вход SAML. Дополнительные сведения см. в разделе «Конечные точки REST API для установки GitHub App».

Хранение пользовательских данных с помощью контекстов организации и предприятия

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

Например:

Пользователь находится в Mona организации, для которой требуется единый вход SAML и вход в приложение после выполнения единого входа. Теперь ваше приложение имеет доступ к тому, что пользователь делает внутри Mona.
Пользователь извлекает кучу кода из репозитория Mona и сохраняет его в приложении для анализа.
Позже пользователь переключает задания и удаляется из Mona организации.

Когда пользователь обращается к приложению, он по-прежнему видит код и анализ из Mona организации в учетной записи пользователя?

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

Срок действия маркеров

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

Срок действия маркеров доступа к установке истекает через один час, срок действия маркеров доступа пользователей истекает через восемь часов и срок действия маркеров обновления истекает через шесть месяцев. Однако вы также можете отозвать маркеры, как только они больше не нужны. Дополнительные сведения см. в статье DELETE /installation/token об отмене маркера доступа к установке и DELETE /applications/{client_id}/token отмене маркера доступа пользователя.

Кэширование маркеров

Маркеры доступа пользователей и маркеры доступа к установке предназначены для использования до истечения срока их действия. Необходимо кэшировать создаваемые маркеры. Прежде чем создать новый маркер, проверьте кэш, чтобы узнать, есть ли у вас действительный маркер. Повторное использованием маркеров сделает приложение быстрее, так как оно сделает меньше запросов на создание маркеров.

Создание плана по обработке нарушений безопасности

У вас должен быть план, чтобы вы могли своевременно обрабатывать любые нарушения безопасности.

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

Если маркеры доступа установки, маркеры доступа пользователей или маркеры обновления скомпрометируются, следует немедленно отозвать эти маркеры. Дополнительные сведения см. в статье DELETE /installation/token об отмене маркера доступа к установке и DELETE /applications/{client_id}/token отмене маркера доступа пользователя.

Выполнение регулярных проверок уязвимостей

Выбор подходящей среды

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

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

Использование секрета веб-перехватчика

Необходимо задать секрет веб-перехватчика для данных GitHub App и убедиться, что подпись входящих событий веб-перехватчика соответствует секрету. Это помогает убедиться, что входящее событие веб-перехватчика является допустимым событием GitHub.

Дополнительные сведения см. в разделе Использование веб-перехватчиков с приложениями GitHub. Пример см. в разделе Создание приложения GitHub, реагирующего на события веб-перехватчика.

Разрешить пользователям принимать новые разрешения

При добавлении разрешений репозитория или организации в GitHub Appпользователи, у которых установлено приложение на личная учетная запись или организации, получат сообщение электронной почты с запросом на просмотр новых разрешений. Пока пользователь не утвердит новые разрешения, установка приложения будет получать только старые разрешения.

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

Безопасное использование служб

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

Все службы, используемые приложением, должны иметь уникальный вход и пароль.
Приложения не должны совместно использовать учетные записи служб, такие как электронная почта или службы баз данных, для управления службой SaaS.
Только сотрудники с административными обязанностями должны иметь доступ администратора к инфраструктуре, в которую размещается ваше приложение.

Добавление ведения журнала и мониторинга

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

события аутентификации и авторизации;
изменения конфигурации службы;
операции чтения и записи объектов;
Изменения разрешений пользователей и групп
повышение прав роли до администратора;

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

Включение удаления данных

Если данные GitHub App доступны другим пользователям или организациям, необходимо предоставить пользователям и владелец организации способ удаления своих данных. Чтобы удалить данные, пользователи не должны отправлять сообщения электронной почты или обращаться в службу поддержки.