appsec-github-watcher

appsec-github-watcher

Description

This repository contains two Go-based applications that work together to help manage GitHub organization security and Slack group memberships:

1. appsec-github-watcher

A web API that monitors GitHub organization membership changes through webhooks and automates security-related tasks:

• GitHub Organization Monitoring: Listens to webhooks for member additions, removals, and invitations
• User Onboarding: Sends welcome emails to new organization members with security best practices and guidelines
• Security Compliance: Helps maintain organizational security standards by ensuring new members receive security guidance

2. appsec-slack-updater

A scheduled job that synchronizes GitHub organization administrators with a Slack usergroup:

• Admin Synchronization: Automatically updates a dedicated Slack usergroup with all GitHub organization admins
• SSO Email Integration: Uses GitHub GraphQL API to retrieve SSO email addresses for mapping between systems

Both applications integrate with GitHub's API (including GraphQL for SSO email retrieval). appsec-slack-updater with Slack's API for usergroup management. The appsec-github-watcher additionally uses Microsoft Graph API for sending welcome emails.

Environment variables required at runtime:

General Configuration

• ENABLE_EMAIL_FUNCTIONALITY - Feature toggle for email functionality. Set to "true", "yes", "1", or "on" to enable welcome emails (optional, default: disabled)

GitHub Application

• GITHUB_WEBHOOK_SECRET_KEY Generated secret we use to verify that the payload is sent from our webhook.
• GITHUB_APP_ID The GitHub App ID used for authentication.
• GITHUB_APP_INSTALLATION_ID The GitHub App installation ID used for authentication.
• GITHUB_APP_PRIVATE_KEY The private key used for GitHub App authentication.
• GITHUB_ORGANIZATION The GitHub organization name to fetch SAML identity information.

Required GitHub App Permissions

• Organization:
  • members: read - To receive webhooks for membership changes and list admins
  • administration: read - To access organization information

Webhook Events

• organization.member_added
• organization.member_removed
• organization.member_invited

Slack Integration

• SLACK_BOT_TOKEN The Bot User OAuth Token for the Slack application. You can obtain this from your Slack App settings under "OAuth & Permissions" > "Bot User OAuth Token".
• SLACK_USER_GROUP_ID The ID of the Slack usergroup to synchronize with GitHub admins (required for slack-updater)

Required Slack Scopes

• usergroups:read - To read the list of users in a user group
• usergroups:write - To update user group memberships
• users:read - To read user information
• users:read.email - To look up users by email address

Azure (for Email Service - only required for github-watcher with email functionality enabled)

• AZURE_APP_CLIENT_ID - Azure AD application client ID
• AZURE_APP_TENANT_ID - Azure AD tenant ID
• AZURE_APP_CLIENT_SECRET - Azure AD client secret
• AZURE_OPENID_CONFIG_TOKEN_ENDPOINT - Azure AD token endpoint (optional, defaults to standard endpoint)
• EMAIL_FROM_ADDRESS - The email address to send welcome emails from (optional, defaults to appsec@nav.no)

Required Microsoft Graph API Permissions

• Mail.Send - To send welcome emails
• User.Read - To read user information

Development Setup

1. Install dependencies: go mod tidy
2. Configure environment variables as listed above
3. Run the GitHub watcher application: go run cmd/appsec-github-watcher/main.go
4. Run the Slack updater application: go run cmd/appsec-slack-updater/main.go
5. Build the Docker image: docker build .

Email Templates

The application uses Go's embed package to include email templates directly in the compiled binary:

• Template files are located in internal/msgraph/templates/
• The welcome email template is in welcome_email.html
• Templates are automatically embedded into the binary at build time - no need to distribute template files separately
• To modify email content, update the HTML template files before building

Testing

Run tests with: go test ./...

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contact

For any questions, issues, or feature requests, please reach out to the AppSec team:

• Internal: Either our slack channel #appsec or contact a team member directly via slack/teams/mail.
• External: Open GitHub Issue

Code generated by GitHub Copilot

This project was developed with the assistance of GitHub Copilot, an AI-powered code completion tool.