Reading GitHub repositories, pull requests and security alerts

Once the MiraShield GitHub App is installed on your organization, MiraShield can read more than its configuration checks: whether each repository protects its main branch and requires reviews, whether every pull request merged in the last 90 days was approved by somebody other than its author, and what security alerts are open. It is read-only, it uses the GitHub App you already installed, and the only thing kept is the installation's id. Secret values from secret scanning are never stored.

Before you start

• Install the MiraShield GitHub App on your organization first (see "Connecting a cloud account or code repository"). Personal accounts are not supported, because organization-wide alert lists only exist for organizations.
• The App needs these read-only permissions: Administration, Pull requests, Dependabot alerts, Code scanning alerts and Secret scanning alerts. If the App was installed before they were added, GitHub asks an organization owner to accept the update: on GitHub, open the organization's Settings, then GitHub Apps under Third-party Access, and click Configure next to MiraShield, where GitHub shows the request to review and accept. Nothing changes, and nothing breaks, until you do.
• A permission that has not been granted is reported as unreadable, never as clean.

How to set it up

1. Open Settings, then Connectors, and click "Add a connector".
2. Pick "GitHub".
3. Click "Also read security alerts and pull requests" next to your organization's name. MiraShield looks up your installation, gets a short-lived token and lists one repository to prove the access, and connects only if that works.
4. Run Scan now, or wait for the nightly scan.

What it reports

• Per repository: whether the default branch is protected and requires reviews, whether secret scanning is on, and whether Dependabot alerts are on.
• Per merged pull request: whether somebody other than the author approved it before it merged, whether the author only approved their own, and whether it links to a ticket.
• Every open Dependabot, code scanning and secret scanning alert as a finding with its severity, and a separate finding when a critical one has been open more than 15 days or a high one more than 30.

Things worth knowing

• Your GitHub plan decides what GitHub will answer. On the Free plan, GitHub refuses to say whether a private repository has branch protection (it asks you to upgrade), so that shows as unknown, not as off. Code scanning and secret scanning alerts on private repositories also need GitHub's paid security features; with none running there is nothing to report, which is not the same as being secure.
• The first scan of a busy organization can take several minutes, because MiraShield reads each merged pull request's reviews one at a time to stay within GitHub's limits. Later scans only read what is new.
• If GitHub's rate limit is reached, the scan stops, says what it could not read, and leaves existing findings open instead of closing them.
• If your organization has one member, every merged pull request will be reported as not approved by somebody else, because GitHub does not let people approve their own pull requests. The findings are accurate; they just cannot be cleared by one person.