Skip to content

Commit a929fc2

Browse files
efd6efd6
authored
entityanalytics_ad: add support for device entities (#14223)
The data stream is split to do this, essentially in the same way that the entityanalytics_okta integration move from v1 to v2 was managed. The pipeline is split into three with calls to a common pipeline. The third, non-user/non-device pipeline is intended to act as a fallback. Currently, the differentiated pipelines are largely identical, but the separation allows easier adjustment in the future.
1 parent 294b2d5 commit a929fc2

File tree

28 files changed

+1502
-278
lines changed

28 files changed

+1502
-278
lines changed

‎packages/entityanalytics_ad/_dev/build/docs/README.md‎

Lines changed: 74 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,18 @@
22

33
This Active Directory Entity Analytics integration allows users to securely stream User Entities data to Elastic Security via the Active Directory LDAP look-ups. When integrated with Elastic Security, this valuable data can be leveraged within Elastic for risk-scoring scenarios (e.g., context enrichments) and detecting advanced analytics (UBA) use cases.
44

5+
## Upgrading to v0.15.0 from v0.14 and lower of the integration
6+
7+
In v0.15.0 of the integration the user and device data was split into separate data streams. The data ingested into your index will be the same but you may need to update device searches if you were using them.
8+
9+
**NOTE**: When you upgrade from a version prior to v0.15.0 you will need to reconfigure the integration and enable it due to internal changes in the package. See [Resolve conflicts](https://www.elastic.co/guide/en/fleet/current/upgrade-integration.html#resolve-conflicts) in the Fleet documentation for details.
10+
511
## Data streams
612

713
The Active Directory Entity Analytics integration collects one type of data: user.
814

915
- **User** is used to retrieve all user entries available from an Active Directory server.
16+
- **Device** is used to retrieve all device logs available from an Active Directory server.
1017

1118
## Requirements
1219

@@ -33,14 +40,78 @@ The Active Directory provider periodically contacts the server, retrieving updat
3340

3441
Fetching and shipping updates occurs in one of two processes: **full synchronizations** and **incremental updates**. Full synchronizations will send the entire list of users in state, along with write markers to indicate the start and end of the synchronization event. Incremental updates will only send data for changed users during that event. Changes on a user can come in many forms, whether it be a change to the user’s metadata, or a user was added or deleted. By default, full synchronizations occur every 24 hours and incremental updates occur every 15 minutes. These intervals may be customized to suit your use case.
3542

43+
## Sample Events
44+
45+
A user document:
46+
47+
```json
48+
{
49+
"@timestamp": "2024-02-05T06:37:40.876026-05:00",
50+
"event": {
51+
"action": "user-discovered",
52+
},
53+
"activedirectory": {
54+
"id": "CN=Guest,CN=Users,DC=testserver,DC=local",
55+
"user": {
56+
"accountExpires": "2185-07-21T23:34:33.709551516Z",
57+
"badPasswordTime": "0",
58+
"badPwdCount": "0",
59+
"cn": "Guest",
60+
"codePage": "0",
61+
"countryCode": "0",
62+
"dSCorePropagationData": [
63+
"2024-01-22T06:37:40Z",
64+
"1601-01-01T00:00:01Z"
65+
],
66+
"description": "Built-in account for guest access to the computer/domain",
67+
"distinguishedName": "CN=Guest,CN=Users,DC=testserver,DC=local",
68+
"instanceType": "4",
69+
"isCriticalSystemObject": true,
70+
"lastLogoff": "0",
71+
"lastLogon": "2185-07-21T23:34:33.709551616Z",
72+
"logonCount": "0",
73+
"memberOf": "CN=Guests,CN=Builtin,DC=testserver,DC=local",
74+
"name": "Guest",
75+
"objectCategory": "CN=Person,CN=Schema,CN=Configuration,DC=testserver,DC=local",
76+
"objectClass": [
77+
"top",
78+
"person",
79+
"organizationalPerson",
80+
"user"
81+
],
82+
"objectGUID": "hSt/40XJQU6cf+J2XoYMHw==",
83+
"objectSid": "AQUAAAAAAAUVAAAA0JU2Fq1k30YZ7UPx9QEAAA==",
84+
"primaryGroupID": "514",
85+
"pwdLastSet": "2185-07-21T23:34:33.709551616Z",
86+
"sAMAccountName": "Guest",
87+
"sAMAccountType": "805306368",
88+
"uSNChanged": "8197",
89+
"uSNCreated": "8197",
90+
"userAccountControl": "66082",
91+
"whenChanged": "2024-01-22T06:36:59Z",
92+
"whenCreated": "2024-01-22T06:36:59Z"
93+
},
94+
"whenChanged": "2024-01-22T06:36:59Z"
95+
},
96+
"user": {
97+
"id": "CN=Guest,CN=Users,DC=testserver,DC=local"
98+
},
99+
"labels": {
100+
"identity_source": "activedirectory-1"
101+
}
102+
}
103+
```
104+
36105
## Logs reference
37106

38107
### User
39108

40109
This is the `User` dataset.
41110

42-
#### Example
111+
{{fields "user"}}
43112

44-
{{event "user"}}
113+
### Device
45114

46-
{{fields "user"}}
115+
This is the `Device` dataset.
116+
117+
{{fields "device"}}

‎packages/entityanalytics_ad/changelog.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
11
# newer versions go on top
2+
- version: "0.16.0"
3+
changes:
4+
- description: Add support for collection device entities.
5+
type: enhancement
6+
link: https://github.com/elastic/integrations/pull/14223
7+
- description: Split data stream by entity type.
8+
type: breaking-change
9+
link: https://github.com/elastic/integrations/pull/14223
210
- version: "0.15.0"
311
changes:
412
- description: ECS version updated to 8.17.0.

‎packages/entityanalytics_ad/data_stream/device/fields/base-fields.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
- name: data_stream.type
2+
external: ecs
3+
- name: data_stream.dataset
4+
external: ecs
5+
- name: data_stream.namespace
6+
external: ecs
7+
- name: event.module
8+
external: ecs
9+
type: constant_keyword
10+
value: entityanalytics_ad
11+
- name: event.dataset
12+
external: ecs
13+
type: constant_keyword
14+
value: entityanalytics_ad.device
15+
- name: '@timestamp'
16+
external: ecs

‎packages/entityanalytics_ad/data_stream/device/fields/beats.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
- name: input.type
2+
type: keyword
3+
description: Type of filebeat input.

‎packages/entityanalytics_ad/data_stream/device/fields/ecs.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
- name: asset
2+
type: group
3+
fields:
4+
- name: category
5+
type: keyword
6+
- name: costCenter
7+
type: keyword
8+
- name: create_date
9+
type: date
10+
- name: id
11+
type: keyword
12+
- name: last_seen
13+
type: date
14+
- name: last_status_change_date
15+
type: date
16+
- name: last_updated
17+
type: date
18+
- name: name
19+
type: keyword
20+
- name: status
21+
type: keyword
22+
- name: type
23+
type: keyword
24+
- name: vendor
25+
type: keyword
26+
- name: labels
27+
type: group
28+
fields:
29+
- name: identity_source
30+
type: keyword
31+
- name: user
32+
type: group
33+
fields:
34+
- name: account
35+
type: group
36+
fields:
37+
- name: activated_date
38+
type: date
39+
- name: change_date
40+
type: date
41+
- name: create_date
42+
type: date
43+
- name: password_change_date
44+
type: date
45+
- name: status
46+
type: group
47+
fields:
48+
- name: deprovisioned
49+
type: boolean
50+
- name: locked_out
51+
type: boolean
52+
- name: password_expired
53+
type: boolean
54+
- name: recovery
55+
type: boolean
56+
- name: suspended
57+
type: boolean
58+
- name: geo
59+
type: group
60+
fields:
61+
- name: city_name
62+
type: keyword
63+
- name: country_iso_code
64+
type: keyword
65+
- name: name
66+
type: keyword
67+
- name: postal_code
68+
type: keyword
69+
- name: region_name
70+
type: keyword
71+
- name: timezone
72+
type: keyword
73+
- name: organization
74+
type: group
75+
fields:
76+
- name: name
77+
type: keyword
78+
- name: profile
79+
type: group
80+
fields:
81+
- name: department
82+
type: keyword
83+
- name: first_name
84+
type: keyword
85+
- name: id
86+
type: keyword
87+
- name: job_title
88+
type: keyword
89+
- name: last_name
90+
type: keyword
91+
- name: manager
92+
type: keyword
93+
- name: mobile_phone
94+
type: keyword
95+
- name: other_identities
96+
type: keyword
97+
- name: primaryPhone
98+
type: keyword
99+
- name: secondEmail
100+
type: keyword
101+
- name: status
102+
type: keyword
103+
- name: type
104+
type: keyword

0 commit comments

Comments
 (0)