legitify

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

Installation

Installation is possible in several ways:

• For macOS (or linux) using homebrew:

brew install legitify

• You can download the latest legitify release from https://github.com/Legit-Labs/legitify/releases, each archive contains:

  • Legitify binary for the desired platform
  • Built-in policies provided by Legit Security

• From source with the following steps:

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

• As a GitHub CLI extension (check out https://github.com/Legit-Labs/gh-legitify for more information)

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

CI - Legitify Custom GitHub Action

You can run legitify as part of a CI process with the legitify Custom GitHub Actions:

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

Checkout the action file for additional parameters and configuration.

Provenance

To enhance the software supply chain security of legitify's users, as of v0.1.6, every legitify release contains a SLSA Level 3 Provenance document.
The provenance document refers to all artifacts in the release, as well as the generated docker image.
You can use SLSA framework's official verifier to verify the provenance.
Example of usage for the darwin_arm64 architecture for the v0.1.6 release:

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

Commands

analyze

SCM_TOKEN=<your_token> legitify analyze

By default, legitify will check the policies against all your resources (organizations, repositories, members, actions). Archived repositories are skipped.

You can control which resources will be analyzed with command-line flags namespace and org:

• --namespace (-n): will analyze policies that relate to the specified resources
• --org: will limit the analysis to the specified GitHub organizations or GitLab group, excluding archived repositories
• --repo: will limit the analysis to the specified GitHub repositories or GitLab projects
• --scm: specify the source code management platform. Possible values are: github or gitlab. Defaults to github. Please note: when running on GitLab, --scm gitlab is required.
• --enterprise: will specify which enterprises should be analyzed. Please note: in order to analyze an enterprise, an enterprise slug must be provided.

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

The above command will test organization and member policies against org1 and org2.

gpt-analysis

SCM_TOKEN=<your_token> OPENAI_TOKEN=<token> ./legitify gpt-analysis --repo org1/repo1 --org org1

GPT-3 based analysis of the security posture of the provided repository or organization.

NOTE: The repository/organization metadata is sent to openai servers.

Flags:

• --org: will limit the analysis to the specified GitHub organizations or GitLab group
• --repo: will limit the analysis to the specified GitHub repositories or GitLab projects
• --scm: specify the source code management platform. Possible values are: github or gitlab. Defaults to github.
• --token: token for the SCM (or set the SCM_TOKEN environment variable)
• --openai-token: token for openai API (or set OPENAI_TOKEN environment variable)

Must provide either --org or --repo or both.

Generating openai token:

1. Go to https://beta.openai.com/signup and create an openai account
2. Under https://platform.openai.com/account/api-keys press "Create new secret key"

GitHub Action Usage

You can also run legitify as a GitHub action in your workflows, see the action_examples directory for concrete examples.

Requirements

GitHub (Cloud and Enterprise Server)

1. To get the most out of legitify, you need to be an owner of at least one GitHub organization. Otherwise, you can still use the tool if you're an admin of at least one repository inside an organization, in which case you'll be able to see only repository-related policies results.
2. legitify requires a GitHub personal access token (PAT) to analyze your resources successfully, which can be either provided as an argument (-t) or as an environment variable (SCM_TOKEN). The PAT needs the following scopes for full analysis:

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

See Creating a Personal Access Token for more information.
Fine-grained personal access tokens are currently not supported.

GitHub Enterprise Server

You can run legitify against a GitHub Enterprise Server instance if you set the endpoint URL in the environment variable SERVER_URL:

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

GitLab Cloud/Server