legitify

https://user-images.githubusercontent.com/107790206/210602039-2d022692-87ea-4005-b9c6-f091158de3ce.mov

Установка

Установка возможна несколькими способами:

• Для macOS (или linux) с помощью homebrew:

brew install legitify

• Вы можете загрузить последний релиз legitify с https://github.com/Legit-Labs/legitify/releases, каждый архив содержит:

  • Бинарный файл Legitify для нужной платформы
  • Встроенные политики от Legit Security

• Из исходного кода, выполнив следующие шаги:

git clone [email protected]:Legit-Labs/legitify.git
go run main.go analyze ...

• Как расширение GitHub CLI (подробнее на https://github.com/Legit-Labs/gh-legitify)

gh extension install legit-labs/gh-legitify
gh legitify

CI - Пользовательское действие GitHub для Legitify

Вы можете запускать legitify в рамках CI-процесса с помощью пользовательских действий GitHub:

name: Legitify Analyze
on:
    workflow_dispatch:
    schedule:
      - cron: '0 11 * * 1-5'

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Legitify Action
        uses: Legit-Labs/legitify@main
        with:
          github_token: ${{ secrets.PAT_FOR_LEGITIFY }}
          ignore-policies: |
             non_admins_can_create_public_repositories
             requires_status_checks

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

Происхождение (Provenance)

Для повышения безопасности цепочки поставок ПО пользователей legitify, начиная с версии v0.1.6, каждый релиз legitify содержит документ SLSA Level 3 Provenance.
Документ происхождения относится ко всем артефактам в релизе, а также к сгенерированному образу Docker.
Вы можете использовать официальный верификатор SLSA framework для проверки происхождения.
Пример использования для архитектуры darwin_arm64 для релиза v0.1.6:

VERSION=0.1.6
ARCH=darwin_arm64
./slsa-verifier verify-artifact --source-branch main --builder-id 'https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.2.2' --source-uri "git+https://github.com/Legit-Labs/legitify" --provenance-path multiple.intoto.jsonl ./legitify_${VERSION}_${ARCH}.tar.gz

Команды

analyze

SCM_TOKEN=<your_token> legitify analyze

По умолчанию legitify проверяет политики для всех ваших ресурсов (организации, репозитории, участники, действия). Архивные репозитории пропускаются.

Вы можете управлять анализируемыми ресурсами с помощью флагов командной строки namespace и org:

• --namespace (-n): анализировать политики, относящиеся к указанным ресурсам
• --org: ограничить анализ указанными организациями GitHub или группами GitLab, исключая архивные репозитории
• --repo: ограничить анализ указанными репозиториями GitHub или проектами GitLab
• --scm: укажите платформу управления исходным кодом. Возможные значения: github или gitlab. По умолчанию github. Обратите внимание: при работе с GitLab требуется --scm gitlab.
• --enterprise: укажите, какие предприятия следует анализировать. Обратите внимание: для анализа предприятия необходимо указать его slug.

SCM_TOKEN=<your_token> legitify analyze --org org1,org2 --namespace organization,member

Приведённая выше команда проверит политики организации и участников для org1 и org2.

gpt-analysis

SCM_TOKEN=<your_token> OPENAI_TOKEN=<токен> ./legitify gpt-analysis --repo org1/repo1 --org org1

Анализ безопасности предоставленного репозитория или организации на основе GPT-3.

ПРИМЕЧАНИЕ: Метаданные репозитория/организации отправляются на серверы openai.

Флаги:

• --org: ограничить анализ указанными организациями GitHub или группами GitLab
• --repo: ограничить анализ указанными репозиториями GitHub или проектами GitLab
• --scm: укажите платформу управления исходным кодом. Возможные значения: github или gitlab. По умолчанию github.
• --token: токен для SCM (или установите переменную окружения SCM_TOKEN)
• --openai-token: токен для API openai (или установите переменную окружения OPENAI_TOKEN)

Необходимо указать --org, --repo или оба.

Генерация токена openai:

1. Перейдите на https://beta.openai.com/signup и создайте учётную запись openai
2. На странице https://platform.openai.com/account/api-keys нажмите "Create new secret key"

Использование в GitHub Action

Вы также можете запускать legitify как GitHub Action в ваших рабочих процессах — см. конкретные примеры в директории action_examples.

Требования

GitHub (Cloud и Enterprise Server)

1. Чтобы получить максимум от legitify, вы должны быть владельцем хотя бы одной организации GitHub. В противном случае вы всё ещё можете использовать инструмент, если вы являетесь администратором хотя бы одного репозитория внутри организации; в этом случае вы увидите только результаты политик, связанных с репозиторием.
2. Legitify требует персональный токен доступа GitHub (PAT) для успешного анализа ваших ресурсов. Токен можно передать как аргумент (-t) или как переменную окружения (SCM_TOKEN). Для полного анализа PAT требует следующие области видимости:

admin:org, read:enterprise, admin:org_hook, read:org, repo, read:repo_hook

См. Создание персонального токена доступа для получения дополнительной информации.
Персональные токены доступа с детальной настройкой (fine-grained) в настоящее время не поддерживаются.

GitHub Enterprise Server

Вы можете запускать legitify против экземпляра GitHub Enterprise Server, если установите URL конечной точки в переменной окружения SERVER_URL:

export SERVER_URL="https://github.example.com/"
SCM_TOKEN=<your_token> legitify analyze --org org1,org2 --namespace organization,member

GitLab Cloud/Server

1. Как упоминалось в предыдущем разделе, вы должны быть владельцем хотя бы одной группы GitLab. В противном случае вы всё ещё можете использовать инструмент, если вы являетесь администратором хотя бы одного проекта внутри группы; в этом случае вы увидите только результаты политик, связанных с проектом.
2. Legitify требует персональный токен доступа GitLab (PAT) для успешного анализа ваших ресурсов. Токен можно передать как аргумент (-t) или как переменную окружения (SCM_TOKEN). Для полного анализа PAT требует следующие области видимости: read_api, read_user, read_repository, read_registry См. Создание персонального токена доступа для получения дополнительной информации.
   Для работы с GitLab Cloud установите флаг scm: --scm gitlab. Для работы с GitLab Server также необходимо указать SERVER_URL:

export SERVER_URL="https://gitlab.example.com/"
SCM_TOKEN=<your_token> legitify analyze --namespace organization --scm gitlab

ПРИМЕЧАНИЕ 1: Для игнорирования недействительного сертификата сервера передайте флаг --ignore-invalid-certificate

ПРИМЕЧАНИЕ 2: Для учётных записей GitLab без премиум-доступа некоторые политики (например, политики защиты веток) будут пропущены

Пространства имён (Namespaces)

Пространства имён в legitify — это ресурсы, которые собираются и проверяются на соответствие политикам. В настоящее время поддерживаются следующие пространства имён:

1. organization – политики уровня организации GitHub (или группы GitLab) (например, «Двухфакторная аутентификация не применяется для организации»)
2. actions – политики действий GitHub на уровне организации (например, «Запуски GitHub Actions не ограничены проверенными действиями»)
3. member – политики уровня участника (например, «Обнаружен устаревший администратор»)
4. repository – политики уровня репозитория GitHub (или проекта GitLab) (например, «Проверка кода как минимум двумя рецензентами не применяется»). Примечание: архивные репозитории игнорируются, если только они не указаны напрямую через аргумент --repo.
5. runner_group – политики групп раннеров (например, «раннер может использоваться публичными репозиториями»)

По умолчанию legitify анализирует все пространства имён. Вы можете ограничиться только выбранными с помощью флага --namespace, после которого указывается список выбранных пространств имён через запятую.

Параметры вывода

По умолчанию legitify выводит результаты в удобочитаемом формате. Это включает список нарушений политик, отсортированный по серьёзности, а также сводную таблицу, отсортированную по пространству имён.

Форматы вывода

С помощью флага --output-format (-f) legitify поддерживает вывод результатов в следующих форматах:

1. human-readable – удобочитаемый текст (по умолчанию).
2. json – стандартный JSON.
3. sarif – формат SARIF (информация).

Схемы вывода

С помощью флага --output-scheme legitify поддерживает вывод результатов в различных схемах группировки. Примечание: для вывода нестандартных схем необходимо указать --output-format=json.

1. flattened – без группировки; плоский список политик с их нарушениями (по умолчанию).
2. group-by-namespace – группировка политик по пространству имён.
3. group-by-resource – группировка политик по ресурсу, например, конкретная организация/репозиторий.
4. group-by-severity – группировка политик по степени серьёзности.

Назначение вывода

• --output-file – полный путь к файлу вывода (по умолчанию: без файла вывода, вывод в stdout).
• --error-file – полный путь к файлу журнала ошибок (по умолчанию: ./error.log).

Цвета

При выводе в удобочитаемом формате legitify поддерживает традиционный флаг --color[=when] со следующими опциями:

• auto – цветной вывод, если stdout является терминалом, без цвета в противном случае (по умолчанию).
• always – цветной вывод независимо от места назначения вывода.
• none – вывод без цвета независимо от места назначения вывода.

Прочее

• Используйте флаг --failed-only, чтобы отфильтровать пройденные/пропущенные проверки из результата.
• Используйте --ignore-policies-path $PATH и укажите файл с политиками, которые вы хотите игнорировать, чтобы пропустить конкретные политики. Одна политика на строку, например: no_conversation_resolution requires_status_checks ─╯

Поддержка Scorecard — только для репозиториев GitHub (сервер/облако)

Scorecard — это проект с открытым исходным кодом от OSSF:

Scorecards — это автоматизированный инструмент, который оценивает ряд важных эвристик («проверок»), связанных с безопасностью программного обеспечения, и присваивает каждой проверке оценку от 0 до 10. Вы можете использовать эти оценки, чтобы понять конкретные области для улучшения с целью усиления безопасности вашего проекта. Вы также можете оценить риски, которые вносят зависимости, и принимать обоснованные решения о принятии этих рисков, оценке альтернативных решений или работе с мейнтейнерами для улучшений.

Legitify поддерживает запуск scorecard для всех репозиториев организации, применяя политики оценки и показывая результаты с помощью флага --scorecard:

• no – не запускать scorecard (по умолчанию).
• yes – запустить scorecard и применить политику, которая оповещает о каждом репозитории с оценкой ниже 7.0.
• verbose – запустить scorecard, применить политику, которая оповещает о каждом репозитории с оценкой ниже 7.0, и встроить её вывод в вывод legitify.

Legitify выполняет следующие проверки scorecard:

Политики

Legitify поставляется с набором политик для каждой SCM в директории policies/.

Эти политики задокументированы здесь.

Участие

Спасибо, что решили внести вклад в Legitify! Мы поощряем и ценим любые виды вклада. Вот несколько ресурсов, которые помогут вам начать:

• Руководство по внесению вклада
• Кодекс поведения
• Открыть Issue
• Открыть Pull Request

Поддержка

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

Legitify и платформа Legit Security

Если вам понравился Legitify, вам обязательно понравится платформа Legit Security!

• Она автоматизирует проверки Legitify для всех окружений, обнаруживает больше систем и показывает все результаты в простом веб-приложении для управления в масштабе.
• Legit Security — это комплексное решение для безопасности CI/CD вместе с управлением положением дел в области безопасности приложений (ASPM), которое охватывает безопасность приложений от начала до конца.
• Это SaaS-платформа, созданная для инженерных, DevOps и команд безопасности, которой доверяют многие ведущие организации по всему миру.

Ниже приведено сравнение возможностей Legitify и Legit:

Чтобы ознакомиться с Legit, посетите наш веб-сайт или запишитесь на демо