Skip to content
This repository has been archived by the owner on Jul 18, 2024. It is now read-only.

Latest commit

 

History

History
236 lines (190 loc) · 11.5 KB

jupiterone.md

File metadata and controls

236 lines (190 loc) · 11.5 KB
Raw

GitHub

GitHub + JupiterOne Integration Benefits

GitHub Enterprise Server is now supported

  • Visualize GitHub users, teams, code repositories, pull requests, issues, installed GitHub applications, organizational secrets, repo secrets, repo environments, and environmental secrets in the JupiterOne graph.
  • Map GitHub users to employees in your JupiterOne account.
  • Map GitHub users to development/security trainings.
  • Monitor GitHub software development activities within repositories including changes, reviews and approvals.
  • Monitor changes to GitHub user teams, users, code repositories, and pull requests using JupiterOne alerts.
  • Monitor installations of GitHub Apps using JupiterOne alerts.
  • Monitor and audit outside collaborators on code repositories.

How it Works

  • JupiterOne periodically fetches installed GitHub apps, users, teams, code repositories, and recently created/changed pull requests and issues in those repositories to update the graph.
  • Write JupiterOne queries to review and monitor updates to the graph.
  • Configure alerts to take action when the JupiterOne graph changes.

Note on issues and pull requests:

The integration limits ingestion of pull requests and issues during each execution to 500 of the most recently created/modified since the last execution. This is an accumulative process resulting in existing issues and pull requests which have been ingested, but are not changing, remain in the graph.

Note on secret scanning findings:

Secret scanning findings are by default assigned a critical severity

Requirements

  • JupiterOne requires the JupiterOne GitHub app with read-only permissions be installed in your GitHub Organization account.
  • You must have permission in JupiterOne to install new integrations.
  • If setting up for GitHub Enterprise Server, the URL to your instance is required.
  • Note: GitHub Enterprise Server Versions 3.3.3 and above have been verified as compatible with this integration. Other versions may work but are not fully supported.

Support

If you need help with this integration, please contact JupiterOne Support.

Integration Walk-through

In GitHub

Upon creating a new GitHub integration configuration in JupiterOne, the user is re-directed to GitHub to install the JupiterOne GitHub App. The App will request read-only permissions to support ingestion of entities and relationships.

Repository Permissions

  • Actions: Read-only
  • Administration: Read-only
  • Dependabot alerts: Read-only
  • Discussions: Read-only
  • Environments: Read-only
  • Issues: Read-only (enables both Issues and private-repo PRs)
  • Metadata: Read-only
  • Pages: Read-only
  • Pull requests: Read-only
  • Secrets: Read-only

Organization Permissions

  • Administration: Read-only
  • Members: Read-only
  • Secrets: Read-only
  • Events: Read-only

User Permissions

  • None

Secrets Caveat

Note that the Secrets API does not reveal the values of Secrets - only their names and creation dates.

GitHub References:

In JupiterOne

  1. From the top navigation of the J1 Search homepage, select Integrations.
  2. Scroll to the GitHub integration tile and click it.
  3. Click the Add Configuration button and configure the following settings:
    • Enter the Account Name by which you'd like to identify this GitHub account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when Tag with Account Name is checked.
    • Enter a Description that will further assist your team when identifying the integration instance.
    • Select a Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.
  4. Click Create Configuration once all values are provided.

Hierarchy of Steps

This integration uses many steps to retrieve data. Some of the steps depend on others. If there is a crash or error, it might be helpful to understand the hierarchy of step dependency.

  • The root step is fetch-account. All other steps depend on it.
  • There are four steps that depend only on fetch-account. These are fetch-apps, fetch-repos, fetch-users, and fetch-teams. These could be considered primary steps.
  • Other steps logically require multiple primary steps to complete. Examples include fetch-collaborators, fetch-team-members, and fetch-team-repos.
  • Finally, some sophisticated steps require both primary steps and secondary steps before they can execute. For example, fetch-prs needs both fetch-repos and fetch-collaborators in order to properly label reviewers and approvers.

How to Uninstall

  1. From the top navigation of the J1 Search homepage, select Integrations.
  2. Scroll to the GitHub integration tile and click it.
  3. Identify and click the integration to delete.
  4. Click the trash can icon.
  5. Click the Remove button to delete the integration.

Data Model

Entities

The following entities are created:

Resources Entity _type Entity _class
Account github_account Account
GitHub Code Scanning Alerts github_code_scanning_finding Finding
GitHub Env Secret github_env_secret Secret
GitHub Secret Scanning Alert github_secret_scanning_finding Finding
GitHub Vulnerability Alert github_finding Finding
Github App github_app Application
Github Branch Protection Rule github_branch_protection_rule Rule
Github Environment github_environment Configuration
Github Issue github_issue Issue
Github Org Secret github_org_secret Secret
Github Pull Request github_pullrequest PR
Github Repo github_repo CodeRepo
Github Repo Secret github_repo_secret Secret
Github Team github_team UserGroup
Github User github_user User

Relationships

The following relationships are created:

Source Entity _type Relationship _class Target Entity _type
github_account INSTALLED github_app
github_account HAS github_org_secret
github_account OWNS github_repo
github_account HAS github_team
github_account HAS github_user
github_app OVERRIDES github_branch_protection_rule
github_env_secret OVERRIDES github_org_secret
github_env_secret OVERRIDES github_repo_secret
github_environment HAS github_env_secret
github_pullrequest CONTAINS github_pullrequest
github_repo HAS github_branch_protection_rule
github_repo HAS github_code_scanning_finding
github_repo USES github_env_secret
github_repo HAS github_environment
github_repo HAS github_finding
github_repo HAS github_issue
github_repo USES github_org_secret
github_repo HAS github_pullrequest
github_repo HAS github_repo_secret
github_repo USES github_repo_secret
github_repo HAS github_secret_scanning_finding
github_repo ALLOWS github_team
github_repo ALLOWS github_user
github_repo_secret OVERRIDES github_org_secret
github_team OVERRIDES github_branch_protection_rule
github_team HAS github_user
github_user MANAGES github_account
github_user OVERRIDES github_branch_protection_rule
github_user ASSIGNED github_issue
github_user CREATED github_issue
github_user APPROVED github_pullrequest
github_user OPENED github_pullrequest
github_user REVIEWED github_pullrequest
github_user MANAGES github_team

Mapped Relationships

The following mapped relationships are created:

Source Entity _type Relationship _class Target Entity _type Direction
github_finding IS *cve* FORWARD
github_finding EXPLOITS *cwe* FORWARD
github_issue ASSIGNED *github_user* REVERSE
github_issue CREATED *github_user* REVERSE
github_pullrequest APPROVED *github_user* REVERSE
github_pullrequest OPENED *github_user* REVERSE
github_pullrequest REVIEWED *github_user* REVERSE