> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pwnbook.app/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Integration

> Connect Pwnbook to GitHub to enable PR-based threat modeling, repository scanning, and webhook-driven security automation for your development workflows.

## Overview

The GitHub integration bridges your development workflow and your security engagements. Connect GitHub repositories to Pwnbook to:

* Automatically trigger threat model reviews when pull requests are opened
* Run security scans against repository code
* Receive webhook-driven notifications about repository security events
* Import repository structure into architecture models

## Setting up the GitHub App

<Steps>
  <Step title="Install the Pwnbook GitHub App">
    1. Go to **Organization Settings** → **Marketplace** → **GitHub**.
    2. Click **Install GitHub App**.
    3. You'll be redirected to GitHub to install the Pwnbook GitHub App.
    4. Select the GitHub organization or personal account where you want to install the app.
    5. Choose which repositories to grant access to (specific repositories or all repositories).
    6. Click **Install**.

    You'll be redirected back to Pwnbook once installation is complete.
  </Step>

  <Step title="Connect repositories to engagements">
    After installing the app, connect specific repositories to your Pwnbook engagements:

    1. Open an engagement.
    2. Go to **Settings** → **Integrations** → **GitHub**.
    3. Click **Connect Repository**.
    4. Select a repository from the list (shows all repos the app has access to).
    5. Click **Connect**.

    A repository can be connected to multiple engagements if needed.
  </Step>

  <Step title="Configure webhook events">
    Choose which GitHub events trigger actions in Pwnbook:

    1. In the GitHub integration settings, click **Configure Events**.
    2. Toggle the events you want to handle (see [Webhook events](#webhook-events) below).
    3. Click **Save**.

    GitHub automatically sends webhook events to Pwnbook for the repositories the app is installed on.
  </Step>
</Steps>

## PR threat modeling

When a pull request is opened against a connected repository, Pwnbook can automatically analyze the changes and suggest threat model updates.

### How it works

1. A developer opens a pull request.
2. Pwnbook receives the webhook event and analyzes the diff.
3. If security-relevant changes are detected (authentication, authorization, data handling, cryptography, external service calls, etc.), Pwnbook identifies applicable threats.
4. Suggested threats are added to the threat model linked to the connected engagement.
5. You receive a notification to review the suggestions.
6. Optionally, Pwnbook posts a comment on the pull request with its findings.

### Enabling PR threat modeling

1. Open the engagement linked to the repository.
2. Go to **Threat Models** and create or open a threat model.
3. In the threat model settings, enable **GitHub PR Integration**.
4. Select the connected repository.
5. Save.

### PR comments

If PR comments are enabled, Pwnbook will post a security review comment on each PR it analyzes. The comment includes:

* A summary of detected security-relevant changes
* Applicable threat categories
* Links to the relevant threat model in Pwnbook
* Recommended actions

<Note>PR comments appear from the GitHub account associated with the Pwnbook GitHub App installation. The Pwnbook GitHub App needs write access to Pull Request comments to post reviews.</Note>

## Repository scanning

Repository scanning analyzes connected repositories for security issues in the codebase.

To run a repository scan:

1. Go to **Organization Settings** → **Integrations** → **GitHub**.
2. Select a connected repository.
3. Click **Run Scan**.
4. Choose the scan type (full scan or incremental since last scan).
5. Click **Start**.

Scan results appear in the connected engagement under a dedicated scan results section.

## Webhook events

Pwnbook can respond to the following GitHub webhook events:

| Event                      | Pwnbook action                                           |
| -------------------------- | -------------------------------------------------------- |
| `pull_request.opened`      | Trigger PR threat model analysis                         |
| `pull_request.synchronize` | Re-analyze updated PR diffs                              |
| `pull_request.closed`      | Mark PR threat model review as resolved                  |
| `push`                     | Trigger incremental repository scan on branch push       |
| `repository.created`       | Notify connected engagement of new repository            |
| `security_advisory`        | Import GitHub security advisory into engagement findings |

## Disconnecting a repository

To remove a repository connection:

1. Open the engagement.
2. Go to **Settings** → **Integrations** → **GitHub**.
3. Click **Disconnect** next to the repository.

Disconnecting stops future events from being processed. Existing data is retained.

## Uninstalling the GitHub App

To completely remove the Pwnbook GitHub App from your GitHub account or organization:

1. Go to **GitHub** → **Settings** → **Applications** → **Installed GitHub Apps**.
2. Find Pwnbook and click **Configure**.
3. Click **Uninstall**.

<Warning>Uninstalling the GitHub App immediately stops all webhook delivery and PR analysis. Reconnecting requires reinstalling the app from the Pwnbook marketplace.</Warning>