elastic / elastic/integrations
[Slack] New users data stream for entity support
- 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
Assessment
This issue has not been assessed yet.