Welcome to octocats-security-app

octocats-security-app is a GitHub App that ensures the use of proper code reviews in all repositories within a given GitHub organization.

Note

This application has been designed to serve as a prototype (see Figure 1 below) to solve the following (fabricated) customer scenario:

"Our security team is asking for help ensuring proper reviews are being done to code being added into our repositories. We have hundreds of repositories in our organization. What is the best way we can achieve at scale? We are new to some of the out-of-the-box settings and the GitHub API. Can you please help us create a solution that will accomplish this for our security team?"

Design

To meet the customer's requirements, the organization can install a GitHub App (such as octocats-security-app), which uses GitHub Webhooks to react on repository creation and performs subsequent tasks (Apply protection, Create issue) by making requests to the GitHub GraphQL API:

Figure 1: Schematic diagram of the solution design.

The next section provides more details on the setup of this prototype and describes how to test-drive it locally.

Setup

To test this application locally, start by cloning this repository and install the dependencies:

git clone https://github.com/mnkiefer/octocats-security-app.git
cd octocats-security-app
npm ci

Before we can run the application, we need to choose a GitHub organization that the application will be registered and installed on so that we can receive its events.

Register the GitHub App

Important

You will need to store some of the information generated below in your app's root directory in a .env file which should contain the following:

APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"

For your convenience, they are marked in the following text with a " ✏️ " symbol.

1. Navigate to your organization's Settings page.

2. From the left-hand-side menu, choose: Developer Settings > GitHub Apps:
   Under the GitHub Apps section, press the button "New GitHub App".

3. Fill out the GitHub App form as follows:

   • GitHub App name: octocats-security-app
   • Homepage URL: https://github.com/mnkiefer/octocats-security-app
   • Webhook:
     • Active
     • To get the Webhook URL:
       • In a new browser window, navigate to smee.io
       • Click "Start a new channel"
       • Copy the full URL under "Webhook Proxy URL"
       • Replace the YOUR_WEBHOOK_URL string in your checked out application's package.json file scripts.
     • Webhook secret: Enter a random string → ✏️ PRIVATE_KEY_PATH
   • Permissions > Repository permissions:
     • Administration: Read and write
     • Issues: Read and write
   • Subscribe to events:
     • Repository
   • Where can this GitHub App be installed?:
     • Any account

4. Click on the "Create GitHub App" button. In the About section, you can find your registered app's App ID. → ✏️ APP_ID

5. Scroll down the page to the Private keys section and press the "Generate a private key" button. This will trigger a file download.
   Securely store this file and your local machine and keep track of its location path. → ✏️ PRIVATE_KEY_PATH

Install the GitHub App:

1. On the left-hand side menu, go to Public Page
2. Click on the Install button
   • Select your organization
   • All repositories
3. Click the Install button

Run the application

Now that the application has been registered and installed to the organization, we are ready for testing. To start the app's server, return to your local clone of this application and run:

npm ci
npm run dev

In your console output, you can verify that your setup is complete by checking that the server is listening for events and that your smee channel is forwarding to your local application.

You can now navigate to your organization page on GitHub and create a new repository, let's call it my-repo-0. Once your repository has been created, navigate to the new repositories Issues page and verify that an issue has been created (see Figure 2 below), notifying you that the main branch protection is now active for this repository.

Figure 2: The issue created by the GitHub App to notify the repository's creator (in this case @mnkiefer) about the applied main branch protection by the security team.

You can also check your server output logs to see the key events/tasks that have taken place:

[my-repo-0] - Received *repository.create* event
[my-repo-0] - Added *main* branch protection rule
[my-repo-0] - Opened issue #1

References

• GitHub App:
  • Deciding when to build a GitHub App
  • Best practices for creating a GitHub App
• GitHub Webhooks:
  • GitHub Webhooks
  • Building a GitHub App that responds to webhook events
• GitHub API:
  • Comparing GitHub's REST API and GraphQL API
  • GraphQL API Queries
• Text:
  • Basic writing and formatting syntax
• Images:
  • Ocitcons icons
  • Octodex images