elastic / elastic/integrations

[Slack] New users data stream for entity support

Open
#18,882 2 comments 0 reactions 1 assignee Claimed by @chemamartinez View on GitHub
enhancement Integration:slack Team:Security-Service Integrations
Dominant language
Handlebars
Stars
333
Forks
647
Avg merge
3d 4h
Merged PRs (30d)
209

Description

## Description

The Slack integration currently collects audit logs via the `audit` data stream, capturing
point-in-time security events. It does not provide an entity inventory.

This issue tracks the addition of a new `users` data stream to the Slack integration. The goal
is to collect Slack Enterprise Grid user records as entity assets, enabling ECS
`user.entity.*` field population for use in Elastic Security's entity analytics workflows.

## Scope

The new data stream targets Slack Enterprise Grid organisations. It is intentionally scoped
to user entities only.

## Endpoint selection

Two Slack API endpoints are candidates for user inventory collection:

| Capability | `users.list` | `admin.users.list` |
|---|---|---|
| Plan requirement | Any (Free, Business+, Enterprise) | Enterprise Grid only |
| Token type | Bot or User token | User token (`xoxp-`) only |
| Required scope | `users:read`, `users:read.email` | `admin.users:read` |
| Rate limit | Tier 2 (20 req/min) | Tier 4 (100 req/min) |
| `date_created` | No | Yes (Unix timestamp) |
| `deactivated_ts` | No (boolean `deleted` only) | Yes (Unix timestamp) |
| `workspaces[]` | Indirect, requires org token | Yes, explicit array |
| `has_sso` | No | Yes |
| `has_2fa` | Yes, plus `two_factor_type` | Yes |
| Full profile (title, phone, timezone) | Yes | No |
| Pagination cursor location | `response_metadata.next_cursor` | `next_cursor` (top-level) |

**Decision: `admin.users.list`** The Slack integration already requires Enterprise Grid
for the `audit` stream, so no new plan requirement is introduced. The Tier 4 rate limit
(5× faster than `users.list`) is meaningful for large orgs. It also provides `date_created`,
`deactivated_ts`, `workspaces[]`, and `has_sso`, which are directly relevant to entity
lifecycle and relationship mapping. Profile fields available via `users.list` (title, phone,
timezone) are not required for the ECS entity fields in scope.

## Endpoints

The new data stream hits the following Slack API endpoints:

- `GET https://slack.com/api/admin.users.list` as primary source; cursor-paginated user
roster. Returns `next_cursor` at the top level of the response (not inside
`response_metadata`).
- `GET https://slack.com/api/usergroups.list?include_users=true`; it fetched once per
collection cycle to resolve group membership. Returns all usergroups with flat member ID
arrays; no pagination.

## Authentication

An org-level user token (`xoxp-`) is required, with the following scopes:

- `admin.users:read` — access to `admin.users.list`
- `usergroups:read` — access to `usergroups.list`

The same token type is already required by the `audit` data stream (`auditlogs:read` scope).
Both scope sets can be granted on a single Slack app token, or configured separately per
data stream — this is an open decision (see below).

## Collection behaviour

- **Interval:** Default `24h` (full org snapshot once daily, configurable)
- **Page size:** Up to 1000 users per request (Slack maximum)
- **Group membership:** `usergroups.list` is called once at the start of each collection
cycle. The CEL program holds the group-to-members mapping in state and enriches each user
record with their group names before emitting events.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.