Setting up GitHub

• Creating Personal Access Token
• Creating GitHub App
  • Using in CI
  • Using in CLI
• Setting up 2FA (Experimental)

Creating Personal Access Token

For the auditor to run, you need to pass in a personal access token (PAT) with the following permissions:

See here on how to create a PAT in GitHub. Once the token is created, you can export it as an environment variable and then pass it to the auditor (e.g., if you add export GIT_TEST_TOKEN=<your token> to .bashrc/.zshrc then you may pass the token to the auditor binary as such: ./bin/auditor --organization <your_org> --tokenName GIT_TEST_TOKEN

Creating GitHub App

Official GitHub App docs.

PATs are very easy to setup however they have some disadvantages:

• they represent a person
• the person they represents needs to have all necessary permissions within an org (practicaly needs to be an admin in the org)
• as PAT represents a person, it has all permissions of that person, including all orgs that person is a member of. Therefore PAT permissions are not very well scoped.

GitHub applcations solve these issues by allowing to scope access tokens to an organization directly, not people. That is done by installing GitHub application within an org which then allows to create GitHub access tokens tied to that application installation. This makes using GitHub Apps especially useful if you would like to run auditor in CI.

As we currently do not offer hosted GitHub application, you will need to create and install private application within your org by following steps below:

1. Create GitHub App. App should have these permissions:

   • Organization (all read-only)
     • Administration
     • Members
     • Self-hosted runners
     • Webhooks
   • Repo (all read-only)
     • Metadata

2. Note App ID of the created app

3. Add Private Key for the App

4. Install app within your org.

5. Note installation ID (from the URL):

   https://github.com/organizations/{orgid}/settings/installations/{installtion-id}
   

Using in CI

To generate app access token in GitHub actions you can use action-github-app-token. You will need to:

• save app id as github action secret
• save private key as github action secret

Using in CLI

Official GitHub CLI does not support creating application tokens but we can use obtain-github-app-installation-access-token:

export GITHUB_APP_ID={from above}
export GITHUB_INSTALLATION_ID={from above}
export GITHUB_PRIVATE_KEY={path to .pem file}
export GH_SECURITY_AUDITOR_TOKEN=$(
    npx obtain-github-app-installation-access-token \
        --appId=$GITHUB_APP_ID \
        --installationId=$GITHUB_INSTALLATION_ID \
        --privateKey=$GITHUB_PRIVATE_KEY
)

Setting up 2FA (Experimental)

To set it 2FA for this repo, follow the steps below:

1. Follow GitHub's 2FA setup process, but at the “Scan this barcode with your app” step, click the “enter this text code instead” link.

   

   A window pops-up showing “your two-factor secret,” a short string of letters and digits

2. Store this secret alongside other secrets/environment variables in your system. For instance you can add the following to your ~/.zshrc or ~/.bashrc:

   export GH_SECURITY_AUDITOR_OTP_SEED=nzxxiidbebvwk6jb

3. Invoke 2fa every time you use the tool as follows:

   github-analyzer \
       --organization crashappsec \
       --token "$GH_SECURITY_AUDITOR_TOKEN" \
       --enableStats \
       --enableScraping \
       --username "$GH_SECURITY_AUDITOR_USERNAME" \
       --password "$GH_SECURITY_AUDITOR_PASSWORD" \
       --otpSeed "$GH_SECURITY_AUDITOR_OTP_SEED"