Github Analyzer

Audits a GitHub organization for potential security issues. The tool is currently in pre-alpha stage and only supports limited functionality, however we will be actively adding checks in the upcoming months, and welcome feature requests or contributions! Once the analysis is complete, a static HTML with the summary of the results is rendered in localhost:3000 as shown below:

• Available Checks
• Sample Output
• How to run
• Running locally
• Running using Docker
• Permissions
• Credits

Available Checks

Sample Output

For each issue identified, a JSON with associated information will be generated. A sample output snippet is as follows:

...
 {
  "id": "CONFIG_AS_1",
  "name": "Secret scanning disabled for new repositories",
  "severity": 3,
  "category": "Information disclosure to untrusted parties",
  "tags": [
   "GitHub Advanced Security feature"
  ],
  "description": "Secret scanning disabled for org testorg",
  "resource": [
   {
    "id": "testorg",
    "kind": "Organization"
   }
  ],
  "cwes": [
   319
  ],
  "remediation": "Pleasee see https://docs.github.com/en/github-ae@latest/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories for how to enable secret scanning in your repositories"
 },
 {
  "id": "AUTH_2FA_2",
  "name": "Users without 2FA configured",
  "severity": 2,
  "category": "Authentication",
  "description": "The following collaborators have not enabled 2FA: testuser1, testuser2",
  "resource": [
   {
    "id": "testuser1",
    "kind": "UserAccount"
   },
   {
    "id": "testuser2",
    "kind": "UserAccount"
   }
  ],
  "cwes": [
   308
  ],
  "remediation": "Please see https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication for steps on how to configure 2FA for individual accounts"
 }
...

How to run

You can see available options via the --help flag.

Running locally

• Install with: sh go install -v github.com/crashappsec/github-analyzer/cmd/github-analyzer@latest
• Run with: sh $GOPATH/bin/github-analyzer \ --organization <your org name> \ --token "$GH_SECURITY_AUDITOR_TOKEN"

Running using Docker

• After cloning the repo, build the container using: sh docker compose build --no-cache
• Run

sh docker compose run \ --rm --service-ports \ github-analyzer \ --organization <your org name> \ --output output \ --token "$GH_SECURITY_AUDITOR_TOKEN"

Permissions

For API-based based checks, you need to pass in GitHub Token (either personal access token (PAT) or token derived from GitHub app installation) with the appropriate permissions. Example usage:

github-analyzer \
    --organization <your org name> \
    --token "$GH_SECURITY_AUDITOR_TOKEN"

See our wiki for instructions on setting up a token to be used with the github-analyzer.

For experimental scraping-based checks, you need to pass in your username and password, as well your two factor authentication one-time-password, as needed. Example usage:

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

See our wiki for instructions on setting up a token to be used with the analyzer.

Credits

Project was originally ported from Mike de Libero's auditor with the author's permission.

Using GitHub App Instead of Personal Access Token

For better security, it is recommended to use a GitHub App access token instead of a personal access token when running this tool internally within an organization.

Steps to generate access token using GitHub App

1. Go to GitHub Developer Settings: https://github.com/settings/apps

2. Click New GitHub App

3. Fill required details:

4. App name
5. Homepage URL (can be your org URL)

6. Disable webhook (not required)

7. Set permissions: Repository permissions:

8. Metadata: Read
9. Contents: Read
10. Administration: Read

Organization permissions: - Members: Read - Administration: Read

1. Click Create GitHub App

2. Generate a private key (.pem file)

3. Install the GitHub App to your organization

4. Generate a JWT token using the App ID and private key.

5. Exchange JWT for installation access token using GitHub API: https://api.github.com/app/installations/{installation_id}/access_tokens

6. Use this access token when running github-analyzer internally.

This approach avoids using personal access tokens and improves organizational security.