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

# Github (NHI)

### Overview

Owned by Agent / AI Team for enablement today. IntPlat is the point-of-contact for connection and scope questions.

The GitHub (Graph) integration gives Lumos read-only visibility into the non-human identities, credentials, and automation surfaces inside your GitHub organization. Once connected, the Lumos NHI Security Analysis agent automatically scans these resources and surfaces security findings — each with severity, supporting evidence, and a recommended remediation — so your team can act without digging through GitHub's settings.

This integration uses two GitHub authentication methods together: a GitHub OAuth App (for user-context data) and a GitHub App (for org-scoped resources). Setup typically takes a few minutes, and the agent produces its first findings on the initial sync.

### What Lumos Does

Only Security Agents can use the findings from connecting this integration today.

Lumos agents will identify and analyze risks across your entire environment:

**Identities and membership**

* Organization members and their org-level roles (owner, member, billing manager)
* Outside collaborators (can be excluded via the *Exclude Outside Collaborators* setting)
* Machine users (non-human accounts used for automation)
* SAML identities mapped to GitHub accounts, when the *Use SAML Identities* setting is enabled and your org has SAML SSO configured

**Credentials and tokens**

* Personal Access Tokens issued at the organization level (classic and fine-grained), including scopes and expiry
* OAuth Apps with access to the organization and the tokens they hold
* GitHub Apps installed in the organization, including their granted permissions and installation scope
* Deploy keys configured on repositories
* SSH keys attached to user accounts
* GPG keys attached to user accounts

**Automation and CI/CD**

* Self-hosted runners registered at the organization and repository level
* GitHub Actions configuration on repositories
* Repository and organization Actions secrets (inventory and last-updated metadata; values are never read)
* Environments and their protection rules

**Configuration**

* Repository administration settings
* Organization administration settings
* Repository and organization webhooks, including endpoint targets and whether a webhook secret is set

**Enterprise scope (optional)**

* If you provide an *Enterprise Slug*, the analysis is scoped to that GitHub Enterprise account

### What the NHI Security Analysis agent looks for

After the first sync, the agent automatically reviews the synced data and produces findings such as:

* Personal Access Tokens that are over-scoped, never expire, or haven't been used in a long time
* Deploy keys that grant write access, are orphaned, or shouldn't exist on the repository
* GitHub Apps installed with admin-level scopes whose owners have left the organization
* OAuth tokens still issued to third-party apps that are no longer in active use
* Machine users with privileged scopes and no clear owner
* Webhooks with no secret configured or pointed at unexpected endpoints
* Self-hosted runners that are unowned or attached at an unexpectedly broad scope
* Compound-risk patterns — for example, a long-lived organization-admin PAT held by a machine user that has no matching SAML identity

Each finding includes a severity rating, the specific evidence behind it, and a recommended next step.

### Required scopes and permissions

Lumos connects via two GitHub apps. The minimum scopes and permissions for each are listed below — these are all read-only.

**GitHub App — Required Permissions**

| Category | Permission | Access |
| :- | :- | :- |
| Repository | Actions | Read-only |
| Repository | Administration | Read-only |
| Repository | Environments | Read-only |
| Repository | Secrets | Read-only |
| Repository | Webhooks | Read-only |
| Organization | Administration | Read-only |
| Organization | Members | Read-only |
| Organization | Personal access tokens | Read-only |
| Organization | Secrets | Read-only |
| Organization | Self-hosted runners | Read-only |
| Organization | Webhooks | Read-only |
| Account | Git SSH keys | Read-only |
| Account | Git SSH | Read-Only |
| Account | GPG Keys | Read-Only |
| Enterprise | Audit Log | Read-Only |
| Enterprise | Custom Properti | esRead Only |

Note, providing additional scopes will let the Agent investigate and raise more issues. The full list of scopes recommended by Lumos are:

* **Repository permissions**
  * Actions, Administration, Code scanning alerts, Codespaces, Environments, Metadata, Repository security advisories, Secret scanning alerts, Secrets, Webhooks
* **Organization permissions**
  * Administration, Custom organization roles, Custom properties, Custom repository roles, Events, Members, Models, Organization codespaces, Organization innersource vulnerabilities, Personal access tokens, Projects, Secrets, Self-hosted runners, Webhooks
* **Account permissions**
  * GPG keys, Git SSH keys, SSH signing keys
* **Enterprise permissions**
  * Custom properties, Enterprise custom organization roles, Enterprise custom properties for organizations, Enterprise innersource vulnerabilities, Enterprise organization installation repositories, Enterprise organization installations, Enterprise people, Enterprise single sign-on, Enterprise teams, Enterprise administration

**GitHub OAuth App — required scopes**

OAuth scopes are requested by Lumos during the authorization flow when the integration is first connected; you do not configure them at app registration in GitHub. The OAuth App only needs to be registered with a Client ID, Client Secret, and the correct Authorization callback URL (see setup below).

Currently required OAuth2 scopes by the integration:

* read:public\_key
* read:gpg\_key
* read:audit\_log
* read:user
* read:org

### Settings reference

| Setting | Default | Description |
| :- | :- | :- |
| Enterprise Slug | empty | The slug at the end of your GitHub Enterprise URL (e.g., `acme-corp` from `github.com/enterprises/acme-corp`). Scopes the analysis to that enterprise. |
| Exclude Outside Collaborators | Off | When enabled, outside collaborators are not synced into this integration. |
| Use SAML Identities | Off | When enabled, user identity data is read from your SAML Identity Provider instead of GitHub profiles. Requires SAML SSO to be configured in your GitHub organization. |

### Setup

You'll register two apps in GitHub and paste their values into the Lumos integration tile.

View a video for this [<u>version</u>](https://drive.google.com/file/d/1raBXI7PWW48KpefgHqRHa2Nrp_xcmZUF/view?usp=sharing) before getting started to get an idea of what is required.

#### Step 1 — Register a GitHub OAuth App

1. Go to [GitHub Developer Settings](https://github.com/settings/developers) and select **OAuth Apps** in the left sidebar.
2. Click **New OAuth App** (or **Register a new application**).
3. Fill in the required details:
   * **Application name** — any descriptive name
   * **Homepage URL** — any valid URL
   * **Authorization callback URL** — `https://app.lumosidentity.com/integrations/ics_oauth2_callback`
4. Click **Register application**.
5. Copy the **Client ID** value and paste it into the *Client ID* field in Lumos.
6. Click **Generate a new client secret**, then copy the secret into the *Client Secret* field in Lumos. Save it immediately — GitHub will not show it again.

#### Step 2 — Register a GitHub App

The GitHub App can be created either with enterprise scope or organization scope. The Enterprise app should be created in enterprise apps if you would like the connector to review all organizations in the Github enterprise. If you would like to scope it to one organization, install the Github application in that organization. Since it gives access to the organizations in the connected enterprise and is managed by the enterprise, not a single account.

1. Go to [GitHub Developer Settings → GitHub Apps](https://github.com/settings/apps) and click **New GitHub App**.
2. Fill in the required details (name, an arbitrary homepage URL).
3. Set the following permissions, all **Read-only**:
   * **Repository permissions:** Actions, Administration, Environments, Secrets, Webhooks
   * **Organization permissions:** Administration, Members, Personal access tokens, Secrets, Self-hosted runners, Webhooks
   * **Account permissions:** Git SSH keys
4. Select that this app can be installed **only on this account**, then create the GitHub App.
5. Under **General → About**, copy the **App ID** and paste it into the *App ID* field in Lumos.
6. Under **General → Private keys**, click **Generate a private key**. A `.pem` file will download. Open it and paste the full contents into the *Private Key* field in Lumos.
7. In the left sidebar, click **Install App**, choose the organization or account to install on, and confirm.
8. After installation, open the installation's settings page. The **Installation ID** is the number at the end of the URL — for example, in `https://github.com/organizations/<org>/settings/installations/<installation_id>`, the trailing number is what you paste into the *Installation ID* field in Lumos.

#### Step 3 — Finish configuring in Lumos

1. Enter your **Enterprise Slug** if you want to scope the analysis to a specific GitHub Enterprise account.
2. (Optional) Toggle **Exclude Outside Collaborators** or **Use SAML Identities** to match how your organization manages identity.
3. Save the integration. Lumos will run an initial sync and the NHI Security Analysis agent will produce its first findings shortly after.

### Notes

* All resources listed above are accessed read-only. Lumos cannot modify GitHub configuration, secrets, tokens, or memberships through this integration.
* Secret values (for Actions secrets, webhook secrets, etc.) are never read. Only their presence and metadata are analyzed.
* This integration sits alongside the Lumos Entra ID (Graph) and AWS IAM Identity Center (Graph) integrations and feeds the same NHI Security Analysis agent.