Creating and Configuring a GitHub System of Record

Prerequisites

• A GitHub Personal Access Token, with scopes relevant to the entities that you want to sync into SGNL
  • Basic Scopes: read:org, read:user, user:email, read:enterprise
  • Entity Specific Scopes:
    • Repository: public_repo
    • Organization: admin:org
• Knowledge of your Enterprise Slug, available from Enterprise Settings (Profile –> Enterprise Settings, as an Enterprise Admin) in GitHub and is referenced with the Display Name
• If using GitHub Enterprise Server – the networking and service availability requirements for SGNL’s Adapters to connect to your GitHub Server:
  • Availability of the service on Port 443 from SGNL’s Adapter Service
  • Depending on the entities you need to synchronize from SGNL, there are a range of endpoints SGNL will need access to, i.e.
    • For Secret Scanning Entities: https://HOSTNAME/api/v3/enterprises/ENTERPRISE/secret-scanning/alerts
    • For All Other Entities: http(s)://HOSTNAME/api/graphql

Configuring GitHub

1. Sign-in to GitHub (either Enterprise Cloud or Enterprise Server) and select your profile image from the top-right, then select Settings
2. From the Nav, select Developer settings and then Personal Access Tokens –> Tokens (Classic)

• Note Fine-Grained Access Tokens are currently in Beta and are not supported for production-use of SGNL with GitHub

3. Generate a new token (classic)
4. Set a descriptive note for the token and set an appropriate expiry for your token

• Note SGNL securely encrypts and stores all tokens entered into the product, it is recommended that this token should be entered into SGNL and not stored elsewhere in order to minimize the risk of credential leakage. Consider your use-case, organizational policies, and how you will manage the credential (outside of SGNL) when determining your expiry.

5. Define the necessary scopes, based on your use-case
6. Generate and copy the token, temporarily storing it somewhere secure until you enter it into SGNL in the next steps

Configuring SGNL

1. Login to the SGNL Console
2. From the left menu, select Systems of Record
3. Click “Add System of Record” or “Add”.
4. The SGNL SoR Catalog will show up on the screen:
5. Click on “GitHub” which will open up the New System of Record screen with some configuration options pre-populated from the GitHub SoR template
6. Depending on whether you are using GitHub Enterprise Server or Enterprise Cloud, your Hostname may vary:

• For Enterprise Server: The hostname of your server, e.g. github.wholesalechips.co
• For Enterprise Cloud: The GitHub public API, e.g. api.github.com

7. Select Bearer authentication, and enter Bearer <the personal access token you copied from GitHub>
8. The Adapter Configuration will vary depending on Enterprise Cloud or Enterprise Server,

• For Enterprise Server

{
 "enterpriseSlug": "<your enterprise slug, e.g. wholesalechips>",
 "isEntepriseCloud": false,
 "apiVersion": "v3"
}

• For Enterprise Cloud

{
 "enterpriseSlug": "<your enterprise slug, e.g. wholesalechips>",
 "isEntepriseCloud": true,
 "apiVersion": "v3"
}

9. When you’re happy with the configuration, click Save
10. All entities and relationships are created as defined in the GitHub template. If applicable, you can edit an entity and modify any properties of the entity or the associated attributes. Hover over the entity on the screen above to see the Edit button as shown above
11. You can check the relationships created through the Relationships tab. Additional Relationships can be added (or removed) as needed
12. Note that synchronization is disabled by default when a new System of Record is created. You can choose to enable synchronization on Entities individually. Hover over the entity to see the Enable Sync button, and click on it
13. Repeat for all Entities you want to synchronize to SGNL. Finally, Enable synchronization for the System of Record
14. After some time, SGNL should complete ingesting the data from your GitHub instance into the SGNL graph. The number of objects ingested per entity are displayed on the GitHub screen. You should then be able to construct policies based on your GitHub data and make access evaluation calls to SGNL.
15. Once ingestion is complete and GitHub data is in the SGNL graph, you can use Data Lens to explore the SGNL graph