GitHub

Integrate GitHub with AirMDR to investigate repository activities, monitor security-relevant events, and enrich investigations with repository metadata.

Purpose

The GitHub integration allows AirMDR to:

• Access repository metadata and content information.
• Enrich investigations with GitHub repository context.
• Monitor repository-related security events.
• Support investigations involving source code repositories and development workflows

Method 1: Fine-Grained Personal Access Token (Recommended)

Method 2: Personal Access Token (Classic)

Pre-requisites

Set up a new GitHub account:

• Create a new GitHub account, to avoid an outage to existing organization GitHub users, as a new PAT will be generated.

Mandatory Organization Invite to new users to join GitHub

• Ensure the new user is invited to the organization. The new user must accept the invitation only to join the organization and the relevant team.

Authentication Methods

AirMDR supports the following authentication methods:

Method	Recommended	Description
Fine-Grained Personal Access Token	✅ Yes	Provides repository-level access with least-privilege permissions.
Personal Access Token (Classic)	Supported	Legacy method with broader repository permissions.

Fine-Grained Personal Access Token

Fine-Grained Tokens provide enhanced security through repository-level scoping and granular permissions.

1. Verify Organization Settings

   1. An organization administrator must enable Fine-Grained Personal Access Tokens.
   2. Navigate to Organization → Settings → Third-party Access → Personal access tokens → Settings.
   3. Configure Fine-grained tokens:
      • Enable Allow access via fine-grained personal access tokens
      • Click Save.
        If Require administrator approval is enabled, generated tokens must be approved by an organization administrator before they can be used.

2. Create a Dedicated GitHub Service Account (Optional)

   To avoid interruptions caused by user departures or account changes:

   1. Create a dedicated GitHub user account.
   2. Add the account to your GitHub organization.
   3. Use this account exclusively for AirMDR integrations.
3. Navigate to Fine-Grained Token Creation

   1. Navigate to GitHub → Developer Settings.
   2. Select the Personal access tokens drop-down in the left navigation pane.
   3. Click “Fine-grained tokens” → Generate new token.
4. Configure Basic Token Details & Select Resource Owner and Configure Repository Access

   1. Provide:

      Field	Value (Unique name)
      Token Name	AirMDR Integration
      Description	AirMDR GitHub Integration

   2. Under Resource Owner.
   3. Select your GitHub Organization.
      Example: Resource Owner: MyOrganization
      This ensures the token is scoped to organization repositories.

   4. Select the Expiration as per organizational policy.
      The token will expire on the selected date.

   5. Option A: Choose “All Repositories”.
      Recommended as AirMDR can investigate all repositories.

      (Or)
      Option B: Selected Repositories.
      Recommended for least-privilege deployments.

5. Configure Required Permissions

   1. Under Repository Permissions, configure:

      Permission	Access
      Metadata	Read-only
      Contents	Read-only

   2. Metadata permission is automatically selected and required by GitHub.
   3. No additional permissions are required.
6. Generate Token

   1. Click Generate Token, and Copy the Token immediately.

   Once created, copy and store it in password manager or any relevant vault securely (you won’t be able to see it again).

   If administrator approval is required:

   • Submit the token request to the organization administrator.
   • Wait for approval before configuring AirMDR.

Generate GitHub Personal Access Token (PAT)

GitHub PAT increases Security, Fine-Grained Permissions, and fulfills the GitHub compliance policy for HTTPS Authentication.

1. Access GitHub

   1. Login with GitHub with new user credentials.
   2. Navigate to GitHub → Profile (Top right corner) → Settings → Developer Settings.
2. Generate a Personal Access Token

   1. Select the Personal access tokens drop-down in the left navigation pane.
   2. Click Tokens (classic).
   3. Click “Generate new token” and select “Generate new token (classic)”.
   4. Provide a Token name (descriptive name, For Example: “AirMDR Integration”).
   5. Select Expiration:
      • Choose a token lifespan or set it to “Never Expiration”.
   6. Set Permissions:
      • Choose scopes and define the following permissions:
        • repo (Full control of private repositories)
        • read:org (Read-only access to organization, teams, and membership)
        • read:user (Read-only access to profile information)
   7. Generate and Copy the Token:
      Once created, copy and store it securely (you won’t be able to see it again).

3. Securely share GitHub PAT

    Share the token via a secured method to the AirMDR operations team or self-configure in the AirMDR Integrations Dashboard.

Integration Credential Requirements

Use the following values in the AirMDR integration configuration screen:

AirMDR Field	Description	Fine-Grained Token Method	Classic Token Method	Where to Obtain
Personal Access Token	GitHub authentication token used by AirMDR to access repository information	Generated Fine-Grained Personal Access Token	Generated Personal Access Token (Classic)	GitHub → Settings → Developer Settings → Personal Access Tokens
Authentication Type	Token-based authentication	Fine-Grained PAT	Classic PAT	GitHub
Repository Access	Scope of repositories AirMDR can access	All repositories or selected repositories	Determined by token scopes	GitHub Token Configuration
Required Permissions	Minimum permissions required by AirMDR	Metadata (Read-only), Contents (Read-only)	repo, read:org	GitHub Token Permissions

Fine-Grained Token Requirements (Recommended)

Setting	Required Value
Resource Owner	Your GitHub Organization
Repository Access	All repositories or selected repositories
Metadata Permission	Read-only
Contents Permission	Read-only
Administrator Approval	Required if enforced by organization policy

Important:
AirMDR recommends using Fine-Grained Personal Access Tokens whenever possible, as they provide enhanced security through repository-level access control and least-privilege permissions.

Classic Token Requirements (Legacy)

Scope	Access Level
repo	Required
read:org	Required

Example AirMDR Configuration

Field	Example Value
Integration Name	GitHub Production
Personal Access Token	github_pat_xxxxxxxxxxxxxxxxx
Status	Enabled

GitHub displays the Personal Access Token only once during creation. Store it securely before proceeding with the AirMDR configuration.

GitHub Integration - Authentication Architecture

GitHub Credential Reference Table

AirMDR Field	Required	Description	Where to Obtain
Auth_token	Yes	GitHub Personal Access Token used to authenticate AirMDR with GitHub. Supports both Fine-Grained Personal Access Tokens and Personal Access Tokens (Classic).	GitHub → Settings → Developer Settings → Personal Access Tokens
Remote Agent	No	Remote Agent used when GitHub is accessed through a private network or restricted environment. Select an existing AirMDR Remote Agent if required.	AirMDR Remote Agent Configuration
Expiry	Recommended	Expiration date of the generated GitHub Personal Access Token. Used for credential lifecycle management and renewal tracking.	Defined during GitHub token creation

Validate Connectivity

Use the following command to verify connectivity and token authentication:

Sample Request

curl -H “Authorization: Bearer <GITHUB_PERSONAL_ACCESS_TOKEN>” \

-H “Accept: application/vnd.github+json” \

https://api.github.com/user

Successful Response

“login”: “github-user”,

“id”: 12345678,

“type”: “User”

Verify Repository Access

curl -H “Authorization: Bearer <GITHUB_PERSONAL_ACCESS_TOKEN>” \

-H “Accept: application/vnd.github+json” \

https://api.github.com/user/repos

If you receive a 401 Unauthorized error, verify that the token is valid and has not expired.
If you receive a 403 Forbidden error, verify that the required repository permissions have been granted and, for Fine-Grained Tokens, ensure the token has been approved by your GitHub organization administrator.

Configure GitHub in AirMDR Integrations Dashboard

1. Navigate to AirMDR, provide the credentials and click Login
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
3. Use the search option, enter the keyword “GitHub”, select the Connections tab, and click + Create button.
4. Enter an unique name to the Instance (e.g., your org name-GitHub) to easily identify the user connection by AirMDR.
5. Enter the application credentials like Auth_token in the Authentication Details field params, and click Save.

Skills provided by this Integration

Skill ID	Purpose
Get repository events from github	Get list of github repository events for the given organization
Get user actions in github	Retrieve a list of actions performed by a specified user on a given GitHub instance. The output includes events such as push, pull, commit, and other user-generated actions.
GitHub Repository Events for Detections	Retrieve a list of events from a GitHub repository for detection purposes. The output includes events such as push, pull request, commit, and other repository-generated activities.
GitHub Audit Log Events for Detections	Retrieve audit log events from a GitHub organization for detection purposes. The output includes events such as member additions, permission changes, repository modifications, and other organization-level audit activities. Requires GitHub Enterprise Cloud license.

To view the details of Input Parameters and Output for the respective skills

• Go to AirMDR → GitHub Integration page.
• Select the Skills tab and click on the required listed skills.

Additional Information

🧰 Error Handling

Error	Possible Cause	Resolution
Invalid credentials provided	The Personal Access Token is incorrect, malformed, or was copied incorrectly.	Verify the token value and update the Auth_token field with a valid GitHub Personal Access Token.
Authentication failed (401 Unauthorized)	The token has expired, been revoked, or is no longer valid.	Generate a new Personal Access Token in GitHub and update the integration configuration.
Access forbidden (403 Forbidden)	The token does not have the required repository permissions or has not been approved by the organization administrator.	Verify token permissions. For Fine-Grained Tokens, ensure Metadata (Read-only) and Contents (Read-only) permissions are granted and administrator approval has been completed if required.
Repository access denied	The selected repositories are not included in the token scope.	Update the token configuration to include the required repositories or select All repositories during token creation.
Organization access restricted	Fine-Grained Personal Access Tokens are disabled for the GitHub organization.	Ask a GitHub organization administrator to enable Fine-Grained Personal Access Tokens in organization settings.
Token approval pending	The organization requires administrator approval before a Fine-Grained Token can be used.	Contact the GitHub organization administrator and request approval for the token.
Connection test failed	Network connectivity issues between AirMDR and GitHub API.	Verify internet access, firewall rules, proxy settings, and GitHub API availability.
API rate limit exceeded	Too many GitHub API requests have been made within a short period.	Wait for the rate limit window to reset or use a dedicated service account with appropriate usage limits.
Remote Agent unavailable	The selected Remote Agent is offline or unreachable.	Verify that the Remote Agent is running and connected to AirMDR before retrying the integration.
Token expired	The configured token has reached its expiration date.	Generate a new token in GitHub and update the Auth_tokenfield in AirMDR.

🔄 Monitoring & Logs

The GitHub integration does not generate logs within GitHub specifically for AirMDR connectivity. However, administrators can monitor integration health, token usage, and API access through both AirMDR and GitHub audit logs.

AirMDR Monitoring

After configuring the integration, administrators can monitor:

• Integration connection status
• Authentication validation results
• Repository data synchronization status
• Integration execution history
• Error and connectivity notifications

GitHub Audit Logs

For GitHub Organizations, audit logs can be used to track:

• Personal Access Token usage
• Repository access events
• Authentication attempts
• Organization-level permission changes
• Token approval activities (Fine-Grained Tokens)

Verify Token Activity

You can verify that the token is actively being used by reviewing:

• API authentication events
• Repository access records
• Security and audit events

Common Indicators of a Healthy Integration

Check	Expected Result
Connection Status	Connected
Authentication Test	Successful
Repository Access	Accessible
Token Status	Active
Integration Health	Healthy
Synchronization	Successful

If authentication or synchronization issues occur, review the AirMDR integration status first, then verify token validity, repository permissions, and organization approval settings within GitHub.

🛑 Security & Access Best Practices

Follow these recommendations to ensure a secure and reliable GitHub integration with AirMDR.

✅ Do’s

Best Practice	Description
Use Fine-Grained Personal Access Tokens	Prefer Fine-Grained Tokens over Classic Tokens to enforce least-privilege access.
Create a Dedicated Service Account	Use a dedicated GitHub account for AirMDR integrations to avoid disruptions caused by employee account changes.
Grant Minimum Required Permissions	Assign only the permissions required by AirMDR (Metadata: Read-only, Contents: Read-only).
Restrict Repository Access	Limit token access to specific repositories whenever possible.
Rotate Tokens Regularly	Periodically regenerate and update tokens according to your organization’s security policy.
Set Token Expiration Dates	Configure expiration dates to reduce the risk of long-lived credentials.
Monitor Audit Logs	Regularly review GitHub audit logs for token usage and repository access activities.
Securely Store Tokens	Store tokens in approved secrets management systems and avoid exposing them in documentation or source code.
Review Token Permissions Periodically	Conduct regular access reviews to ensure permissions remain appropriate.
Enable Administrator Approval	Use token approval workflows where supported to improve governance and oversight.

❌ Don’ts

Avoid	Reason
Don’t Use Personal User Accounts	Integration failures may occur if the user leaves the organization or changes permissions.
Don’t Grant Unnecessary Permissions	Excessive permissions increase security risks and violate the principle of least privilege.
Don’t Share Tokens Over Email or Chat	Tokens are sensitive credentials and should only be stored in secure locations.
Don’t Commit Tokens to Repositories	Tokens exposed in source code can be abused and may require immediate revocation.
Don’t Disable Token Expiration	Long-lived credentials increase the impact of credential compromise.
Don’t Use Classic Tokens for New Deployments	Fine-Grained Tokens provide better security controls and repository-level access restrictions.
Don’t Ignore Failed Authentication Alerts	Authentication failures may indicate expired, revoked, or compromised tokens.
Don’t Grant Access to All Repositories Unnecessarily	Limit access only to repositories required for AirMDR investigations.
Don’t Reuse Tokens Across Multiple Applications	Use a dedicated token specifically for the AirMDR integration.
Don’t Leave Unused Tokens Active	Revoke unused or obsolete tokens immediately to reduce attack surface.

Security Recommendation

For production environments, AirMDR recommends using a dedicated GitHub service account with a Fine-Grained Personal Access Token, repository-specific access, and read-only permissions to align with security best practices and the principle of least privilege.

👉 Support & Maintenance

• 📧 Contact AirMDR Support through your designated support channel.
• 🔁 Rotate credentials regularly. Regular maintenance of the GitHub integration helps ensure uninterrupted connectivity, secure access, and reliable repository monitoring.

Maintenance Activities

Activity	Recommended Frequency
Verify integration status	Weekly
Review token expiration dates	Monthly
Validate token permissions	Quarterly
Review GitHub audit logs	Monthly
Rotate Personal Access Tokens	As per organizational security policy
Remove unused tokens	Immediately when no longer required
Review repository access scope	Quarterly
Validate Remote Agent connectivity (if used)	Monthly

🛑 Data Flow & Security

The GitHub integration uses a GitHub Personal Access Token (Fine-Grained or Classic) to securely authenticate AirMDR and retrieve repository information required for investigations and enrichment activities.

Data Exchanged

The integration may access the following information based on the permissions granted to the Personal Access Token:

Data Type	Purpose
Repository Metadata	Retrieve repository names, IDs, descriptions, visibility, and ownership details.
Repository Contents	Access repository file and content information for investigation and enrichment workflows.
Organization Information	Retrieve organization-level repository associations and ownership information.
Repository Activity Data	Support security investigations and contextual analysis.

AirMDR only accesses the resources permitted by the configured GitHub Personal Access Token.

Security Controls

Security Control	Description
Token-Based Authentication	AirMDR authenticates using a GitHub Personal Access Token.
Least-Privilege Access	Fine-Grained Tokens allow repository-specific and read-only permissions.
Encrypted Communication	All communication between AirMDR and GitHub APIs occurs over HTTPS/TLS.
Secure Credential Storage	Tokens are stored securely within AirMDR’s credential management framework.
Access Control	Repository access is limited by the permissions configured on the GitHub token.

Encryption

Data State	Protection Method
Data In Transit	TLS 1.2+ / HTTPS
Stored Credentials	Encrypted within AirMDR credential storage mechanisms
API Authentication	GitHub Personal Access Token

Network Requirements

Component	Port	Protocol
GitHub API	443	HTTPS
AirMDR Platform	443	HTTPS

GitHub API Endpoint

The integration communicates with GitHub using the GitHub REST API: https://api.github.com

Access Model

Authentication Method	Supported
Fine-Grained Personal Access Token	Yes
Personal Access Token (Classic)	Yes

Security Recommendation

AirMDR recommends using Fine-Grained Personal Access Tokens with Metadata (Read-only) and Contents (Read-only) permissions to align with the principle of least privilege and minimize security exposure.