Skip to main content

​
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

1

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.
2

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.
3

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 below).
  3. Click Save.
GitHub automatically sends webhook events to Pwnbook for the repositories the app is installed on.

​
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
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.

​
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:
EventPwnbook action
pull_request.openedTrigger PR threat model analysis
pull_request.synchronizeRe-analyze updated PR diffs
pull_request.closedMark PR threat model review as resolved
pushTrigger incremental repository scan on branch push
repository.createdNotify connected engagement of new repository
security_advisoryImport 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.
Uninstalling the GitHub App immediately stops all webhook delivery and PR analysis. Reconnecting requires reinstalling the app from the Pwnbook marketplace.