> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Integration

> Monitor audit logs from GitHub organizations for security and compliance

The GitHub integration enables monitoring of audit logs from your GitHub organizations, providing visibility into repository activities, security events, and administrative actions.

## Overview

The GitHub integration collects audit log events from GitHub organizations, allowing you to track user activities, security events, repository changes, and administrative actions. All events are tagged with `wazuh.integration.name: github` for filtering and analysis.

Reference: `plugins/main/common/wazuh-modules.ts:134`

## Key Features

* Real-time audit log monitoring
* Organization-wide event collection
* Repository activity tracking
* User action monitoring
* Security event detection
* Compliance audit trails
* Administrative action logging
* Access control monitoring

## Data Source Configuration

The GitHub data source uses the following configuration:

```typescript theme={null}
const GITHUB_GROUP_KEY = 'wazuh.integration.name';
const GITHUB_GROUP_VALUE = 'github';
```

Reference: `plugins/main/public/components/common/data-source/pattern/events/github/github-data-source.ts:5`

## Collected Events

The GitHub integration monitors various types of events:

### Repository Events

* Repository creation, deletion, and archiving
* Branch creation and deletion
* Tag creation and deletion
* Repository visibility changes (public/private)
* Repository transfers
* Repository settings modifications
* Collaborator additions and removals

### Code and Content Events

* Push events
* Pull request activities
* Issue creation and modifications
* Release publishing
* Deployment events
* Wiki page changes
* File uploads and downloads

### Security Events

* Secret scanning alerts
* Dependabot alerts
* Code scanning alerts
* Security policy changes
* Two-factor authentication changes
* SSH key additions and removals
* Personal access token usage
* OAuth application authorizations

### Access and Authentication

* User login events
* Failed login attempts
* Organization membership changes
* Team membership modifications
* Permission changes
* Access token creation and revocation
* Deploy key additions

### Administrative Events

* Organization settings changes
* Billing information updates
* Webhook configuration changes
* GitHub Actions workflow modifications
* Secret and variable management
* Runner registration and removal
* Organization policy changes

### Compliance Events

* Data exports
* GDPR data requests
* Audit log exports
* Enterprise policy enforcement
* IP allow list changes

## Setup and Configuration

### Prerequisites

* GitHub organization (audit logs not available for personal accounts)
* Organization owner or admin privileges
* GitHub Enterprise Cloud (for streaming audit logs) or GitHub Enterprise Server
* Wazuh manager with GitHub module enabled
* Personal access token or GitHub App

### Configuration Steps

1. **Create Personal Access Token**

   * Log in to GitHub
   * Go to Settings > Developer settings > Personal access tokens
   * Click "Generate new token (classic)" or "Fine-grained tokens"
   * For classic token:
     * Name: "Wazuh GitHub Integration"
     * Scopes: `admin:org` (read org audit log)
   * For fine-grained token:
     * Repository access: Select organizations
     * Permissions: Organization > Administration (read)
   * Generate and copy the token

2. **Alternative: Create GitHub App** (Recommended for production)

   * Go to Organization Settings > Developer settings > GitHub Apps
   * Click "New GitHub App"
   * Configure:
     * Name: "Wazuh Integration"
     * Homepage URL: Your Wazuh dashboard URL
     * Webhook: Disable (not needed for audit logs)
     * Permissions:
       * Organization: Administration (read)
     * Install the app to your organization
     * Generate and download private key

3. **Configure Wazuh Manager**

   Edit `/var/ossec/etc/ossec.conf`:

   **Using Personal Access Token:**

   ```xml theme={null}
   <wodle name="github">
     <disabled>no</disabled>
     <interval>5m</interval>
     <time_delay>30s</time_delay>
     <curl_max_size>1M</curl_max_size>
     <api_auth>
       <org_name>your-organization</org_name>
       <api_token>your-personal-access-token</api_token>
     </api_auth>
   </wodle>
   ```

   **Using GitHub App:**

   ```xml theme={null}
   <wodle name="github">
     <disabled>no</disabled>
     <interval>5m</interval>
     <api_auth>
       <org_name>your-organization</org_name>
       <app_id>your-app-id</app_id>
       <app_private_key_path>/path/to/private-key.pem</app_private_key_path>
     </api_auth>
   </wodle>
   ```

4. **Multiple Organizations** (Optional)

   Monitor multiple GitHub organizations:

   ```xml theme={null}
   <wodle name="github">
     <disabled>no</disabled>
     <interval>5m</interval>
     <api_auth>
       <org_name>organization-1</org_name>
       <api_token>token-1</api_token>
     </api_auth>
     <api_auth>
       <org_name>organization-2</org_name>
       <api_token>token-2</api_token>
     </api_auth>
   </wodle>
   ```

5. **Verify Configuration**

   * Restart Wazuh manager: `systemctl restart wazuh-manager`
   * Check logs: `tail -f /var/ossec/logs/ossec.log`
   * Look for successful GitHub API connections
   * Verify events appear in Wazuh Dashboard

## Event Fields

GitHub audit log events typically include:

* `data.github.actor` - User who performed the action
* `data.github.action` - Action performed
* `data.github.org` - Organization name
* `data.github.repo` - Repository name (if applicable)
* `data.github.created_at` - Event timestamp
* `data.github.actor_location.country_code` - User location
* `data.github.user_agent` - Client user agent
* `data.github.transport_protocol_name` - Protocol used (web, ssh, http)

## Filtering Events

Filter GitHub events in the dashboard:

```kuery theme={null}
wazuh.integration.name: "github"
```

Additional filters:

* By organization: `data.github.org: "my-org"`
* By actor: `data.github.actor: "username"`
* By action: `data.github.action: "repo.create"`
* By repository: `data.github.repo: "my-org/my-repo"`

## Use Cases

### Security Monitoring

* **Access Control**
  * Monitor unauthorized access attempts
  * Track permission changes
  * Identify unusual access patterns
  * Detect compromised accounts

* **Secret Protection**
  * Track secret scanning alerts
  * Monitor secret exposure events
  * Identify hardcoded credentials
  * Alert on secret leaks

* **Code Security**
  * Monitor vulnerability alerts
  * Track security policy violations
  * Identify insecure dependencies
  * Review code scanning findings

### Compliance and Auditing

* **Regulatory Compliance**
  * SOC 2 audit trail requirements
  * ISO 27001 access logging
  * GDPR data access tracking
  * HIPAA audit requirements

* **Change Management**
  * Track production branch changes
  * Monitor deployment events
  * Audit configuration changes
  * Review administrative actions

* **Access Auditing**
  * User access reviews
  * Permission change tracking
  * Third-party app authorization
  * API token usage monitoring

### DevOps Security

* **CI/CD Security**
  * GitHub Actions workflow monitoring
  * Self-hosted runner security
  * Secrets and variables management
  * Deployment approvals tracking

* **Supply Chain Security**
  * Dependency change monitoring
  * Third-party action usage
  * Package publication tracking
  * Container image deployment

### Insider Threat Detection

* Mass repository cloning
* Unusual download activity
* After-hours access
* Bulk permission changes
* Repository data exports
* Organization secret access

## Common Audit Log Actions

### Repository Actions

* `repo.create` - Repository created
* `repo.destroy` - Repository deleted
* `repo.archived` - Repository archived
* `repo.transfer` - Repository transferred
* `repo.access` - Repository accessed

### Security Actions

* `secret_scanning.alert_created` - Secret detected
* `dependabot.alert_created` - Vulnerability found
* `code_scanning.alert_created` - Code issue detected
* `two_factor_authentication.enabled` - 2FA enabled
* `two_factor_authentication.disabled` - 2FA disabled

### Access Actions

* `org.add_member` - Member added to organization
* `org.remove_member` - Member removed
* `team.add_member` - User added to team
* `team.remove_member` - User removed from team
* `oauth_application.create` - OAuth app created

### Administrative Actions

* `org.update_settings` - Organization settings changed
* `repo_secret.create` - Secret created
* `repo_secret.remove` - Secret deleted
* `org_secret.create` - Organization secret created
* `workflow.created` - GitHub Actions workflow created

## Troubleshooting

### Authentication Issues

* **Error: Bad credentials**
  * Verify personal access token is correct
  * Check token hasn't expired
  * Ensure token has `admin:org` scope
  * Confirm token is for the correct organization

* **Error: Not Found**
  * Verify organization name is correct
  * Check user has organization owner/admin privileges
  * Ensure audit log access is available (requires GitHub Enterprise)

### No Events Appearing

* Verify organization has audit log feature (Enterprise plan required)
* Check if events exist in GitHub's audit log UI
* Ensure time\_delay setting allows for event processing
* Review Wazuh logs for API errors
* Confirm network connectivity to GitHub API

### Rate Limiting

* GitHub API has rate limits (5,000 requests/hour for authenticated requests)
* Adjust polling interval to reduce API calls
* Use GitHub App instead of personal token for higher limits
* Monitor `X-RateLimit-Remaining` header in logs

### Missing Specific Event Types

* Verify event type is included in audit log
* Check if feature generating events is enabled
* Ensure user has appropriate permissions
* Review GitHub's audit log documentation for available events

## Security Best Practices

1. **Token Management**
   * Use GitHub Apps instead of personal access tokens
   * Rotate tokens regularly
   * Use fine-grained tokens with minimum permissions
   * Store tokens securely in Wazuh configuration
   * Never commit tokens to repositories

2. **Access Control**
   * Use dedicated service account for integration
   * Apply principle of least privilege
   * Regular access reviews
   * Monitor integration account activity

3. **Monitoring**
   * Alert on critical security events
   * Monitor for secret exposures
   * Track administrative changes
   * Review failed authentication attempts

4. **Compliance**
   * Retain audit logs per policy requirements
   * Regular compliance reviews
   * Document integration configuration
   * Test incident response procedures

## Advanced Configuration

### Event Filtering

Filter events at collection time:

```xml theme={null}
<wodle name="github">
  <disabled>no</disabled>
  <interval>5m</interval>
  <api_auth>
    <org_name>your-org</org_name>
    <api_token>your-token</api_token>
  </api_auth>
  <only_future_events>yes</only_future_events>
  <event_filter>
    <actions>repo.create,repo.destroy,org.add_member</actions>
  </event_filter>
</wodle>
```

### Custom Polling Intervals

Adjust based on organization size and activity:

```xml theme={null}
<!-- High-activity organization -->
<interval>2m</interval>
<time_delay>15s</time_delay>

<!-- Low-activity organization -->
<interval>15m</interval>
<time_delay>1m</time_delay>
```

## GitHub Enterprise Server

For on-premises GitHub Enterprise Server:

```xml theme={null}
<wodle name="github">
  <disabled>no</disabled>
  <interval>5m</interval>
  <api_auth>
    <org_name>your-org</org_name>
    <api_token>your-token</api_token>
    <enterprise_slug>your-enterprise</enterprise_slug>
  </api_auth>
</wodle>
```

## Related Resources

* [Cloud Integrations Overview](/cloud/overview)
* [Docker Integration](/cloud/docker)
* [Office 365 Integration](/cloud/office365)
* [System Auditing](/modules/system-auditing)
* [GitHub Audit Log Documentation](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.