slack-audit-log-bot

Slack audit log collection and SSO compliance analysis for Slack Enterprise Grid. Built on the deno-slack-sdk platform.

What it does

• Polls the Slack Audit Logs API on a schedule
• Classifies login events as SAML SSO or suspected password authentication
• Posts Block Kit reports and compliance alerts to a Slack channel
• Tracks security-relevant events (user provisioning, role changes, SSO config changes)
• Supports on-demand manual audit checks via a Slack shortcut

Architecture

triggers/
  scheduled_login_audit.ts    Hourly  -> LoginAuditWorkflow
  scheduled_security_audit.ts Daily   -> SecurityAuditWorkflow
  manual_audit_trigger.ts     Shortcut -> ManualAuditWorkflow

workflows/
  login_audit_workflow.ts     fetch_audit_logs -> analyze_login_events -> post_login_report
  security_audit_workflow.ts  fetch_security_events -> post_security_report
  manual_audit_workflow.ts    OpenForm -> fetch_audit_logs -> analyze_login_events -> post_login_report

functions/
  fetch_audit_logs.ts         Paginated API polling with cursor tracking and rate limiting
  analyze_login_events.ts     Auth method classification (SAML vs password heuristic)
  post_login_report.ts        Block Kit summary + per-user SSO compliance alerts
  fetch_security_events.ts    Polls for security events (provisioning, role changes, SSO)
  post_security_report.ts     Grouped security event digest

datastores/
  poll_cursor.ts              Tracks last-polled timestamp per workflow (avoids re-fetching)
  login_events.ts             Stores classified login events with 30-day TTL

Auth method classification

The bot assumes an SSO-required org. All successful user_login events default to saml. A login is reclassified as password_suspected if:

• The event is user_login_failed (always flagged)
• A user_login_failed for the same user occurred within 5 minutes before a user_login

Flagged logins generate individual SSO Compliance Alert messages in the alert channel.

Security events tracked

Action	Description
user_created	User provisioned
user_deactivated	User deactivated
pref.sso_setting_changed	SSO configuration changed
user_session_reset_by_admin	Admin reset a user session
role_change_to_admin	User promoted to admin
role_change_to_owner	User promoted to owner
role_change_to_regular	User demoted to regular

Prerequisites

• Slack CLI installed and authenticated
• Slack Enterprise Grid org admin access
• A Slack app with a xoxp- user token that has the auditlogs:read scope

Setup

1. Clone and authenticate:

   cd slack-audit-log-bot
   slack auth login

2. Configure environment variables:

   Edit .env with your real values:

   SLACK_AUDIT_TOKEN=xoxp-your-token-here
   ALERT_CHANNEL_ID=C0123456789
   

   The xoxp- token must belong to an Org Owner or Org Admin with auditlogs:read. The channel ID is where reports and alerts will be posted.

3. Run locally:

   slack run

   This starts the app in development mode. Triggers will be created automatically for the dev environment.

4. Create the manual trigger:

   slack trigger create --trigger-def triggers/manual_audit_trigger.ts

   This returns a shortcut URL you can paste into any Slack channel.

Usage

Automated (no action needed)

• Hourly: Login audit runs, posts summary + alerts if password auth is detected
• Daily: Security event digest posts if any provisioning/role/SSO changes occurred

Manual

1. Use the "Run Audit Now" shortcut link in Slack
2. Choose how many hours to look back (default: 24)
3. Report posts to the alert channel

Rate limiting

The bot respects Slack's Tier 3 rate limits (50 requests/min org-wide):

• 1.3 second delay between paginated API calls
• Maximum 20 pages per workflow run (up to 10,000 events)
• Backs off on HTTP 429 and returns partial results

Cursor tracking

Each workflow maintains its own cursor in the poll_cursor datastore. On each run, the bot fetches only events newer than the last successful poll. Manual runs use a time-based lookback and do not update the cursor.

Running tests

slack deno test

Tests cover the auth classification logic: SAML defaults, failed login flagging, correlation windows, cross-user isolation, and metadata extraction.

Deploying to production

slack deploy

Then create triggers for the deployed app:

slack trigger create --trigger-def triggers/scheduled_login_audit.ts
slack trigger create --trigger-def triggers/scheduled_security_audit.ts
slack trigger create --trigger-def triggers/manual_audit_trigger.ts

Project info

• Org: Your Enterprise Grid org ID (set in .env)
• API endpoint: https://api.slack.com/audit/v1/logs
• Runtime: Slack-hosted Deno
• Language: TypeScript