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
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.Verify Organization Settings
- An organization administrator must enable Fine-Grained Personal Access Tokens.
- Navigate to Organization → Settings → Third-party Access → Personal access tokens → Settings.
- 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.
Create a Dedicated GitHub Service Account (Optional)
To avoid interruptions caused by user departures or account changes:
- Create a dedicated GitHub user account.
- Add the account to your GitHub organization.
- Use this account exclusively for AirMDR integrations.
Navigate to Fine-Grained Token Creation
- Navigate to GitHub → Developer Settings.
- Select the Personal access tokens drop-down in the left navigation pane.
- Click “Fine-grained tokens” → Generate new token.
Configure Basic Token Details & Select Resource Owner and Configure Repository Access
- Provide:
Field Value (Unique name) Token Name AirMDR Integration Description AirMDR GitHub Integration - Under Resource Owner.
- Select your GitHub Organization.
Example:Resource Owner: MyOrganizationThis ensures the token is scoped to organization repositories. - Select the Expiration as per organizational policy.
The token will expire on the selected date.
- Option A: Choose “All Repositories”.
Recommended as AirMDR can investigate all repositories.
Option B: Selected Repositories.Recommended for least-privilege deployments.
Configure Required Permissions
- Under Repository Permissions, configure:
Permission Access Metadata Read-only Contents Read-only - Metadata permission is automatically selected and required by GitHub.
- No additional permissions are required.
Generate GitHub Personal Access Token (PAT)
GitHub PAT increases Security, Fine-Grained Permissions, and fulfills the GitHub compliance policy for HTTPS Authentication.Access GitHub
- Login with GitHub with new user credentials.
- Navigate to GitHub → Profile (Top right corner) → Settings → Developer Settings.
Generate a Personal Access Token
- Select the Personal access tokens drop-down in the left navigation pane.
- Click Tokens (classic).
- Click “Generate new token” and select “Generate new token (classic)”.
- Provide a Token name (descriptive name, For Example: “AirMDR Integration”).
- Select Expiration:
- Choose a token lifespan or set it to “Never Expiration”.
- 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)
- Choose scopes and define the following permissions:
- Generate and Copy the Token:
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
Sample Request
curl -H “Authorization: Bearer <GITHUB_PERSONAL_ACCESS_TOKEN>” \-H “Accept: application/vnd.github+json” \https://api.github.com/user
Successful Response
Successful Response
“login”: “github-user”,“id”: 12345678,“type”: “User”
Verify Repository Access
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
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
- Navigate to AirMDR, provide the credentials and click Login
- Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
- Use the search option, enter the keyword “GitHub”, select the Connections tab, and click + Create button.
- Enter an unique name to the Instance (e.g.,
your org name-GitHub) to easily identify the user connection by AirMDR. - Enter the application credentials like
Auth_tokenin 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. |
Additional Information
🧰 Error Handling
🧰 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
🔄 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
- Personal Access Token usage
- Repository access events
- Authentication attempts
- Organization-level permission changes
- Token approval activities (Fine-Grained Tokens)
- API authentication events
- Repository access records
- Security and audit events
| 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
🛑 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
👉 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.
| 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
🛑 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 ExchangedThe integration may access the following information based on the permissions granted to the Personal Access Token:
Security Controls
Encryption
Network Requirements
GitHub API EndpointThe integration communicates with GitHub using the GitHub REST API:
| 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 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. |
| 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 |
| Component | Port | Protocol |
|---|---|---|
| GitHub API | 443 | HTTPS |
| AirMDR Platform | 443 | HTTPS |
https://api.github.comAccess 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.