GitHub Integration

​

Overview

​

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

const GITHUB_GROUP_KEY = 'wazuh.integration.name';
const GITHUB_GROUP_VALUE = 'github';

​

Collected 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:
   <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:
   <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:
   <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

• 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

wazuh.integration.name: "github"

• 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

<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

<!-- 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

<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
• Docker Integration
• Office 365 Integration
• System Auditing
• GitHub Audit Log Documentation