Configure GitHub for AppFabric
GitHub is a platform and cloud-based service for software development and version control using Git, allowing developers to store and manage their code. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous integration, and wikis for every project.
You can use AWS AppFabric for security to receive audit logs and user data from GitHub, normalize the data into Open Cybersecurity Schema Framework (OCSF) format, and output the data to an Amazon Simple Storage Service (Amazon S3) bucket or an Amazon Data Firehose stream.
AppFabric support for GitHub
AppFabric supports receiving user information and audit logs from GitHub.
Prerequisites
To use AppFabric to transfer audit logs from GitHub to supported destinations, you must meet the following requirements:
-
To access the Audit logs you need to have an enterprise account.
-
To access the Enterprise audit logs you need to have Administrator role for your enterprise account.
-
To get audit logs from organization, you need to be Organization owner.
Rate limit considerations
GitHub imposes rate limits on the GitHub API. For
more information about the GitHub API rate limits, see API Request Limits and Allocations
Data delay considerations
You might see up to a 30-minute delay for an audit event to be delivered to your
destination. This is due to delay in audit events made available by the application
as well as due to precautions taken to reduce data loss. However, this might be
customizable at an account-level. For assistance, contact AWS Support
Connecting AppFabric to your GitHub account
After you create your app bundle within the AppFabric service, you must authorize AppFabric with GitHub. To find the information required to authorize GitHub with AppFabric, use the following steps.
Create an OAuth application
AppFabric integrates with the GitHub using OAuth. Use the following
steps to create an OAuth application in GitHub. For more information,
see Creating
GitHubs Apps
-
Choose your profile photo located in the top-right corner of the page, and then choose Settings.
-
Choose Developer settings in the left navigation pane.
-
Choose OAuth apps in the left navigation pane.
-
Choose New OAuth App.
Note
This button will be labeled Register a new application if you haven't previously created an OAuth app.
-
Enter the name of your app in the Application name text box.
-
Enter the full application instance URL in the Homepage URL text box.
-
(Optional) Enter a description for your app in the Application description text box. Users will see this description.
-
Enter a URL with the following format in the Authorization callback URL text box.
https://<region>.console.aws.amazon.com/appfabric/oauth2In this URL,
<region>is the code for the AWS Region in which you configured your AppFabric app bundle. For example, the code for the US East (N. Virginia) Region isus-east-1. For that Region, the redirect URL ishttps://.us-east-1.console.aws.amazon.com/appfabric/oauth2 -
Choose Enable Device Flow if your OAuth app will use device flow to identify and authorize users. For more information about device flow, see Authorizing OAuth apps
on the GitHub website. -
Choose Register application.
App authorizations
Tenant ID
AppFabric will request your tenant ID. The tenant ID should be provided in either of the following formats:
Enterprise audit log:
Use the enterprise's audit log if you want to know aggregated actions from all of the organizations owned by your enterprise account.
To use the enterprise audit log, the tenant ID is your account's enterprise
ID. You can find your enterprise ID in the address bar of your browser. For
example, exampleenterprisehttps://github.com/settings/enterprises/.examplenterprise
When you specify the tenant ID for enterprise audit log, you must prefix it
with enterprise:. Therefore, specify the previous example as
enterprise:examplenterprise.
Organization audit log:
Use the organization’s audit log as an organization admin if you want to know the actions performed by members of your organization. It includes details such as who performed the action, what the action was, and when it was performed.
To use organization audit log, the tenant ID is your organization ID. You can
find your organization ID in the address bar of your browser. For example,
exampleorganizationhttps://github.com/settings/organizations/.exampleorganization
When you specify the tenant ID for organization audit log, you must prefix it
with organization:. Therefore, specify the previous example as
organization:exampleorganization.
Tenant name
Enter a name that identifies this unique GitHub enterprise or organization. AppFabric uses the tenant name to label the app authorizations and any ingestions created from the app authorization.
Client ID
AppFabric will request a client ID. Use the following steps to find your client ID in GitHub,
-
Choose your profile photo located in the top-right corner of the page, and then choose Settings.
-
Choose Developer settings in the left navigation pane.
-
Choose OAuth apps in the left navigation pane.
-
Choose the specific OAuth app, and then look for the Client ID value.
Client secret
AppFabric will request a client secret. Use the following steps to find your client secret in GitHub.
-
Choose your profile photo located in the top-right corner of the page, and then choose Settings.
-
Choose Developer settings in the left navigation pane.
-
Choose OAuth apps in the left navigation pane.
-
Choose the specific OAuth app, and then look for the Client Secret value. If you are unable to find an existing client secret, then you might need to generate a new one.
Approve authorization
After creating the app authorization in AppFabric, you will receive a pop-up window from GitHub to approve the authorization. To approve the AppFabric authorization, choose Allow.
Make sure that your organizations have granted access
