Community
Questions Library
Docs
Blog
Events
Swag
Github
Slack
JupiterOne
Discussions
Release Notes
Contact Us
GitHub Integration with JupiterOne - AskJ1 Community
<main> <article class="userContent"> <h2 data-id="github-jupiterone-integration-benefits">GitHub + JupiterOne Integration Benefits</h2> <p><strong>GitHub Enterprise Server is now supported</strong></p> <ul><li><p>Visualize GitHub users, teams, code repositories, pull requests, issues,<br> installed GitHub applications, organizational secrets, repo secrets, repo<br> environments, and environmental secrets in the JupiterOne graph.</p></li> <li><p>Map GitHub users to employees in your JupiterOne account.</p></li> <li>Map GitHub users to development/security trainings.</li> <li><p>Monitor Github software development activities within repositories including<br> changes, reviews and approvals.</p></li> <li><p>Monitor changes to GitHub user teams, users, code repositories, and pull<br> requests using JupiterOne alerts.</p></li> <li><p>Monitor installations of GitHub Apps using JupiterOne alerts.</p></li> <li>Monitor and audit outside collaborators on code repositories.</li> </ul><h2 data-id="how-it-works">How it Works</h2> <ul><li><p>JupiterOne periodically fetches installed GitHub <code class="code codeInline" spellcheck="false" tabindex="0">apps</code>, <code class="code codeInline" spellcheck="false" tabindex="0">users</code>, <code class="code codeInline" spellcheck="false" tabindex="0">teams</code>,<br><code class="code codeInline" spellcheck="false" tabindex="0">code repositories</code>, and recently created/changed <code class="code codeInline" spellcheck="false" tabindex="0">pull requests</code> and <code class="code codeInline" spellcheck="false" tabindex="0">issues</code><br> in those repositories to update the graph.</p></li> <li><p>Write JupiterOne queries to review and monitor updates to the graph.</p></li> <li>Configure alerts to take action when the JupiterOne graph changes.</li> </ul><h3 data-id="note-on-issues-and-pull-requests"><strong>Note on <code class="code codeInline" spellcheck="false" tabindex="0">issues</code> and <code class="code codeInline" spellcheck="false" tabindex="0">pull requests</code>:</strong></h3> <p>The integration limits ingestion of <code class="code codeInline" spellcheck="false" tabindex="0">pull requests</code> and <code class="code codeInline" spellcheck="false" tabindex="0">issues</code> during each<br> execution to 500 of the most recently created/modified <em>since the last<br> execution</em>. This is an accumulative process resulting in existing <code class="code codeInline" spellcheck="false" tabindex="0">issues</code> and<br><code class="code codeInline" spellcheck="false" tabindex="0">pull requests</code> which have been ingested, but are not changing, remain in the<br> graph.</p> <h2 data-id="requirements">Requirements</h2> <ul><li><p>JupiterOne requires the JupiterOne GitHub app with read-only permissions be<br> installed in your Github Organization account.</p></li> <li><p>You must have permission in JupiterOne to install new integrations.</p></li> <li>If setting up for GitHub Enterprise Server, the URL to your instance is<br> required.</li> </ul><h2 data-id="support">Support</h2> <p>If you need help with this integration, please contact<br><a rel="nofollow" href="https://support.jupiterone.io">JupiterOne Support</a>.</p> <h2 data-id="integration-walk-through">Integration Walk-through</h2> <h3 data-id="in-github">In GitHub</h3> <p>Upon creating a new GitHub integration configuration in JupiterOne, the user is<br> re-directed to GitHub to install the JupiterOne GitHub App. The App will request<br> read-only permissions to support ingestion of<br><a rel="nofollow" href="#data-model">entities and relationships</a>.</p> <h4 data-id="repository-permissions">Repository Permissions</h4> <ul><li>Actions: Read-only</li> <li>Environments: Read-only</li> <li>Metadata: Read-only</li> <li>Pull requests: Read-only</li> <li>Issues: Read-only (enables both Issues and private-repo PRs)</li> <li><a rel="nofollow" href="#secrets-caveat">Secrets</a>: Read-only</li> <li>Dependabot alerts: Read-only</li> </ul><h4 data-id="organization-permissions">Organization Permissions</h4> <ul><li>Members: Read-only</li> <li>Administration: Read-only</li> <li><a rel="nofollow" href="#secrets-caveat">Secrets</a>: Read-only</li> </ul><h4 data-id="user-permissions">User Permissions</h4> <ul><li>None</li> </ul><h4 data-id="secrets-caveat">Secrets Caveat</h4> <p>Note that the Secrets API does not reveal the values of Secrets - only their<br> names and creation dates.</p> <p>Github References:</p> <ul><li><a rel="nofollow" href="https://developer.github.com/apps/building-github-apps/setting-permissions-for-github-apps/">https://developer.github.com/apps/building-github-apps/setting-permissions-for-github-apps/</a></li> <li><a rel="nofollow" href="https://developer.github.com/v3/apps/permissions/#metadata-permissions">https://developer.github.com/v3/apps/permissions/#metadata-permissions</a></li> <li><a rel="nofollow" href="https://developer.github.com/v3/apps/permissions/#permission-on-contents">https://developer.github.com/v3/apps/permissions/#permission-on-contents</a></li> <li><a rel="nofollow" href="https://docs.github.com/en/rest/reference/actions#secrets">https://docs.github.com/en/rest/reference/actions#secrets</a></li> <li><a rel="nofollow" href="https://docs.github.com/en/rest/reference/permissions-required-for-github-apps#permission-on-secrets">https://docs.github.com/en/rest/reference/permissions-required-for-github-apps#permission-on-secrets</a></li> </ul><h3 data-id="in-jupiterone">In JupiterOne</h3> <ol><li>From the configuration <strong>Gear Icon</strong>, select <strong>Integrations</strong>.</li> <li>Scroll to the <strong>GitHub</strong> integration tile and click it.</li> <li>Click the <strong>Add Configuration</strong> button and configure the following settings: <ul><li>Enter the <strong>Account Name</strong> by which you'd like to identify this GitHub<br> account in JupiterOne. Ingested entities will have this value stored in<br><code class="code codeInline" spellcheck="false" tabindex="0">tag.AccountName</code> when <strong>Tag with Account Name</strong> is checked.</li> <li>Enter a <strong>Description</strong> that will further assist your team when identifying<br> the integration instance.</li> <li>Select a <strong>Polling Interval</strong> that you feel is sufficient for your<br> monitoring needs. You may leave this as <code class="code codeInline" spellcheck="false" tabindex="0">DISABLED</code> and manually execute the<br> integration.</li> </ul></li> <li>Click <strong>Create Configuration</strong> once all values are provided.</li> </ol><h2 data-id="hierarchy-of-steps">Hierarchy of Steps</h2> <p>This integration uses many steps to retrieve data. Some of the steps depend on<br> others. If there is a crash or error, it might be helpful to understand the<br> hierarchy of step dependency.</p> <ul><li>The root step is <code class="code codeInline" spellcheck="false" tabindex="0">fetch-account</code>. All other steps depend on it.</li> <li><p>There are four steps that depend only on <code class="code codeInline" spellcheck="false" tabindex="0">fetch-account</code>. These are<br><code class="code codeInline" spellcheck="false" tabindex="0">fetch-apps</code>, <code class="code codeInline" spellcheck="false" tabindex="0">fetch-repos</code>, <code class="code codeInline" spellcheck="false" tabindex="0">fetch-users</code>, and <code class="code codeInline" spellcheck="false" tabindex="0">fetch-teams</code>. These could be<br> considered primary steps.</p></li> <li><p>Other steps logically require multiple primary steps to complete. Examples<br> include <code class="code codeInline" spellcheck="false" tabindex="0">fetch-collaborators</code>, <code class="code codeInline" spellcheck="false" tabindex="0">fetch-team-members</code>, and <code class="code codeInline" spellcheck="false" tabindex="0">fetch-team-repos</code>.</p></li> <li><p>Finally, some sophisticated steps require both primary steps and secondary<br> steps before they can execute. For example, <code class="code codeInline" spellcheck="false" tabindex="0">fetch-prs</code> needs both<br><code class="code codeInline" spellcheck="false" tabindex="0">fetch-repos</code> and <code class="code codeInline" spellcheck="false" tabindex="0">fetch-collaborators</code> in order to properly label reviewers<br> and approvers.</p></li> </ul><h2 data-id="how-to-uninstall">How to Uninstall</h2> <ol><li>From the configuration <strong>Gear Icon</strong>, select <strong>Integrations</strong>.</li> <li>Scroll to the <strong>GitHub</strong> integration tile and click it.</li> <li>Identify and click the <strong>integration to delete</strong>.</li> <li>Click the <strong>trash can</strong> icon.</li> <li>Click the <strong>Remove</strong> button to delete the integration.</li> </ol><h2 data-id="data-model">Data Model</h2> <h3 data-id="entities">Entities</h3> <p>The following entities are created:</p> <table><thead><tr><th>Resources</th> <th>Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> <th>Entity <code class="code codeInline" spellcheck="false" tabindex="0">_class</code></th> </tr></thead><tbody><tr><td>Account</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_account</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Account</code></td> </tr><tr><td>CVE</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">cve</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Vulnerability</code></td> </tr><tr><td>CWE</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">cwe</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Weakness</code></td> </tr><tr><td>GitHub Env Secret</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_env_secret</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Secret</code></td> </tr><tr><td>GitHub Environment</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_environment</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Configuration</code></td> </tr><tr><td>GitHub Issue</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_issue</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Issue</code></td> </tr><tr><td>GitHub Org Secret</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_org_secret</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Secret</code></td> </tr><tr><td>GitHub Pull Request</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_pullrequest</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">PR</code></td> </tr><tr><td>GitHub Repo Secret</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo_secret</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Secret</code></td> </tr><tr><td>GitHub Team</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_team</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">UserGroup</code></td> </tr><tr><td>GitHub Vulnerability Alerts</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_finding</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Finding</code></td> </tr><tr><td>Github App</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_app</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Application</code></td> </tr><tr><td>Github Repo</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">CodeRepo</code></td> </tr><tr><td>Github User</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">User</code></td> </tr></tbody></table><h3 data-id="relationships">Relationships</h3> <p>The following relationships are created:</p> <table><thead><tr><th>Source Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> <th>Relationship <code class="code codeInline" spellcheck="false" tabindex="0">_class</code></th> <th>Target Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> </tr></thead><tbody><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_account</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_org_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_account</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_team</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_account</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_account</code></td> <td><strong>INSTALLED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_app</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_account</code></td> <td><strong>OWNS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_env_secret</code></td> <td><strong>OVERRIDES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_org_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_env_secret</code></td> <td><strong>OVERRIDES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_environment</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_env_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_finding</code></td> <td><strong>EXPLOITS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">cwe</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_finding</code></td> <td><strong>IS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">cve</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>ALLOWS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_team</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>ALLOWS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_environment</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_finding</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_issue</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_pullrequest</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo_secret</code></td> <td><strong>OVERRIDES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_org_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>USES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_env_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>USES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_org_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo</code></td> <td><strong>USES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_repo_secret</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_team</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> <td><strong>APPROVED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_pullrequest</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> <td><strong>ASSIGNED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_issue</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> <td><strong>CREATED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_issue</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> <td><strong>MANAGES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_account</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> <td><strong>MANAGES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_team</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> <td><strong>OPENED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_pullrequest</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">github_user</code></td> <td><strong>REVIEWED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">github_pullrequest</code></td> </tr></tbody></table> </article> </main>
.png)