GitHub

Import GitHub security alerts: Dependabot and code-scanning alerts as risks, secret-scanning alerts as security signals.

GitHub flags weak spots in your code: vulnerable dependencies (Dependabot), exposed passwords and keys (secret scanning) and risky code patterns (code scanning). This connector brings those alerts into Aegis so they are assessed, owned and followed up like any other risk, and so an exposed secret is reviewed by a person in the security signal inbox (the queue where a reviewer accepts, merges or dismisses each alert a connector reports) before it becomes an incident.

At a glance

Direction Into Aegis.
What it brings in Open Dependabot and secret-scanning alerts of the GitHub organisation you name, and code-scanning alerts of one repository when a sync names that repository. A sync needs an organisation: without one it stops with an Organization not configured error.
Where it lands Dependabot and code-scanning alerts become risks; secret-scanning alerts go to the security signal inbox for review.
Credentials and permissions A GitHub OAuth app (client ID and secret) requesting the scopes security_events and repo; an administrator signs in once with Authorize with GitHub.
Owner of imported records A sync you start yourself gives its risks to you. Scheduled and webhook syncs give them to the connector's Default owner of imported risks. Signals have no owner until a reviewer accepts one.
When it runs On demand with the sync button on the connector page or through the API, on a sync schedule, and when the inbound GitHub webhook fires.
Set it up /connectors/github, by people allowed to configure connectors, on a plan that includes the connector.

Who uses it

The page only works when the GitHub connector is part of your organisation's plan; otherwise every save and sync is refused.

What's on this screen

The page opens under the breadcrumb Connectors / GitHub, with the title GitHub Security Connector and one line explaining that security alerts are synced as risks and incidents. Once a configuration has been saved, a link below that line, Map the statuses and fields of synced tickets →, opens the mapping editor for this connector; the note under it says the mapping only shapes the tickets the connector feeds into security processes. On the captured screen nothing is saved yet, so the link is absent.

From top to bottom the page then shows:

The captured screen shows the page before anything has been saved: the Configuration card with empty fields, — in the owner list and the amber note starting at the bottom edge. The cards below it are further down the page.

Setting it up

First create an OAuth app in GitHub (Settings > Developer settings > OAuth Apps) and set its callback URL to the address the Setup Instructions card shows. Then open /connectors/github. The Configuration card starts with a blue note listing the OAuth app scopes GitHub must grant, followed by the fields below.

  1. Paste the OAuth app's Client ID, the only required field. As soon as it holds text, Save Configuration becomes available.
  2. Enter the Client Secret. Once saved it is shown as asterisks; leave the field blank to keep the stored secret.
  3. Enter the GitHub Organization to import from. The field hint offers to leave it blank for personal repositories, but a sync currently needs an organisation and stops without one.
  4. Choose the Default owner of imported risks — the active user who receives the risks that scheduled syncs and GitHub webhooks bring in. The list offers the people in your user directory.
  5. Read the amber note under the field if it is showing: with no default owner, scheduled and webhook imports go to whoever last saved the configuration, or else the oldest active administrator. The note disappears as soon as you pick an owner.
The GitHub connector form with the default owner of imported risks — /connectors/github.
The GitHub connector form with the default owner of imported risks — /connectors/github.

Select Save Configuration at the foot of the card. The button reads Saving... while it works; if the save fails, a red message appears at the top of the form. After a successful save the mapping-editor link appears under the page title and the connection card asks you to authorise.

Authorise and test the connection

  1. In Connection Status, read the orange note: OAuth authorisation is required to connect to GitHub. Select Authorize with GitHub. Your browser goes to GitHub, where you approve the app, and returns to the connector page.
  2. Select Test Connection. The button reads Testing..., then the status changes. On success a green box shows Connected to GitHub with the GitHub user, the organisation and how many repositories are accessible, and a Re-authorize button appears next to the test button.
  3. If the test fails, a red box gives the reason. If the last sync failed, a separate red box, Last recorded error, shows that error and when it happened, even when a fresh test succeeds.

These cards are below the part of the page in the captured screen, so no screenshot shows them.

Run a sync from the page

The Security Alert Sync card appears once the connection test succeeds. It lets you choose what one manual sync imports. It was not on the captured screen, so no screenshot shows it.

  1. Under Select alert types to sync:, tick the sources. Dependabot Alerts (creates risks with CVE links) and Secret Scanning Alerts (sent to the signal inbox for review) are ticked by default; Code Scanning Alerts (creates risks) is not.
  2. Under Minimum severity to sync (for Dependabot and Code Scanning):, tick the severities to include: Critical, High, Medium, Low. Critical and High are ticked by default. Only the ticked levels are imported; secret-scanning alerts are not filtered by severity.
  3. Select Sync Now. The button reads Syncing... and a progress line says security alerts are being synced from GitHub. When it finishes, the sync history below records how many items were created, split into Dependabot risks, new secret signals and code-scanning risks, or the error that stopped the sync.
  4. Select Review in the security signal inbox → to open /incidents/signals and decide the new secret-scanning signals.

Once the connector has synced, the sync history shows Last successful sync: with the date and time of the last completed sync, and it still does after a reload. Only a connector that has never synced reads No sync history yet. The list of individual runs is kept for this visit only; the audit log records every sync.

Each risk created this way is owned by you. It lands in the Security Vulnerabilities risk category, with its impact taken from the alert's severity. A Dependabot risk's likelihood follows the CVSS score (a standard 0–10 vulnerability score) where GitHub gives one; a code-scanning risk starts with a low likelihood. Adjust both in Risks once someone has assessed the alert.

Disconnect the connector

  1. In the Disconnect connector card, read what disconnecting does: it deletes the stored GitHub configuration and credentials, and the sync schedules and mappings that use it. Records already imported stay in Aegis.
  2. Select Disconnect. A confirmation dialog asks you to confirm.
  3. Confirm with Disconnect. Aegis removes the configuration and returns you to /connectors. You can configure the connector again later.

Tips and limits

Where this connects

Imported risks are worked in Risks; signals in Incidents. Sync schedules and the general connector lifecycle are covered in Connectors; the issue-tracker counterpart is Jira.