Skip to content

Commit 8a0eace

Browse files
tora-kozictora-kozic
authored
Add v2 file events (#382)
* Add v2 file events * check for profile setting in get_saved_search_option callback * use boolean options for profile settings * update changelog * fix build * Use risk.Severity.not_eq(NO_RISK_INDICATED) for --include-non-exposure option * pr feedback
1 parent ac60fa5 commit 8a0eace

File tree

16 files changed

+669
-96
lines changed

16 files changed

+669
-96
lines changed

‎CHANGELOG.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
The intended audience of this file is for py42 consumers -- as such, changes that don't affect
99
how a consumer would use the library (e.g. adding unit tests, updating documentation, etc) are not captured here.
1010

11+
## Unreleased
12+
13+
### Added
14+
- Support for the V2 file event data model.
15+
- V1 file event APIs were marked deprecated in May 2022 and will be no longer be supported after May 2023.
16+
- Use the `--use-v2-file-events True` option with the `code42 profile create` or `code42 profile update` commands to enable your code42 CLI profile to use the latest V2 file event data model.
17+
- See the [V2 File Events User Guide](https://clidocs.code42.com/en/latest/userguides/siemexample.html) for more information.
18+
19+
### Changed
20+
- The `--disable-ssl-errors` options for the `code42 profile create` and `code42 profile update` commands is no longer a flag and now takes a boolean `True/False` arg.
1121
## 1.14.5 - 2022-08-01
1222

1323
### Added

‎docs/commands/securitydata.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
*************
2+
Security Data
3+
*************
4+
5+
.. warning:: V1 file events, saved searches, and queries are **deprecated**.
6+
7+
See more information in the `Enable V2 File Events User Guide <../userguides/v2apis.html>`_.
8+
19
.. click:: code42cli.cmds.securitydata:security_data
210
:prog: security-data
311
:nested: full

‎docs/guides.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
99
Get started with the Code42 command-line interface (CLI) <userguides/gettingstarted.md>
1010
Configure a profile <userguides/profile.md>
11+
Enable V2 File Events <userguides/v2apis.md>
1112
Ingest data into a SIEM <userguides/siemexample.md>
1213
Manage legal hold users <userguides/legalhold.md>
1314
Clean up your environment by deactivating devices <userguides/deactivatedevices.md>
@@ -23,6 +24,7 @@
2324

2425
* [Get started with the Code42 command-line interface (CLI)](userguides/gettingstarted.md)
2526
* [Configure a profile](userguides/profile.md)
27+
* [Enable V2 File Events](userguides/v2apis.md)
2628
* [Ingest data into a SIEM](userguides/siemexample.md)
2729
* [Manage legal hold users](userguides/legalhold.md)
2830
* [Clean up your environment by deactivating devices](userguides/deactivatedevices.md)

‎docs/userguides/v2apis.md

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# V2 File Events
2+
3+
```{eval-rst}
4+
.. warning:: V1 file events, saved searches, and queries are **deprecated**.
5+
```
6+
7+
For details on the updated File Event Model, see the V2 File Events API documentation on the [Developer Portal](https://developer.code42.com/api/#tag/File-Events).
8+
9+
V1 file event APIs were marked deprecated in May 2022 and will be no longer be supported after May 2023.
10+
11+
Use the `--use-v2-file-events True` option with the `code42 profile create` or `code42 profile update` commands to enable your code42 CLI profile to use the latest V2 file event data model.
12+
13+
Use `code42 profile show` to check the status of this setting on your profile:
14+
```bash
15+
% code42 profile update --use-v2-file-events
16+
17+
% code42 profile show
18+
19+
test-user-profile:
20+
* username = [email protected]
21+
* authority url = https://console.core-int.cloud.code42.com
22+
* ignore-ssl-errors = False
23+
* use-v2-file-events = True
24+
25+
```
26+
27+
For details on setting up a profile, see the [profile set up user guide](./profile.md).
28+
29+
Enabling this setting will use the V2 data model for querying searches and saved searches with all `code security-data` commands.
30+
The response shape for these events has changed from V1 and contains various field remappings, renamings, additions and removals. Column names will also be different when using the `Table` format for outputting events.
31+
32+
### V2 File Event Data Example ###
33+
34+
Below is an example of the new file event data model:
35+
36+
```json
37+
{
38+
"@timestamp": "2022-07-14T16:53:06.112Z",
39+
"event": {
40+
"id": "0_c4e43418-07d9-4a9f-a138-29f39a124d33_1068825680073059134_1068826271084047166_1_EPS",
41+
"inserted": "2022-07-14T16:57:00.913917Z",
42+
"action": "application-read",
43+
"observer": "Endpoint",
44+
"shareType": [],
45+
"ingested": "2022-07-14T16:55:04.723Z",
46+
"relatedEvents": []
47+
},
48+
"user": {
49+
"email": "[email protected]",
50+
"id": "1068824450489230065",
51+
"deviceUid": "1068825680073059134"
52+
},
53+
"file": {
54+
"name": "cat.jpg",
55+
"directory": "C:/Users/John Doe/Downloads/",
56+
"category": "Spreadsheet",
57+
"mimeTypeByBytes": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
58+
"categoryByBytes": "Spreadsheet",
59+
"mimeTypeByExtension": "image/jpeg",
60+
"categoryByExtension": "Image",
61+
"sizeInBytes": 4748,
62+
"owner": "John Doe",
63+
"created": "2022-07-14T16:51:06.186Z",
64+
"modified": "2022-07-14T16:51:07.419Z",
65+
"hash": {
66+
"md5": "8872dfa1c181b823d2c00675ae5926fd",
67+
"sha256": "14d749cce008711b4ad1381d84374539560340622f0e8b9eb2fe3bba77ddbd64",
68+
"md5Error": null,
69+
"sha256Error": null
70+
},
71+
"id": null,
72+
"url": null,
73+
"directoryId": [],
74+
"cloudDriveId": null,
75+
"classifications": []
76+
},
77+
"report": {
78+
"id": null,
79+
"name": null,
80+
"description": null,
81+
"headers": [],
82+
"count": null,
83+
"type": null
84+
},
85+
"source": {
86+
"category": "Device",
87+
"name": "DESKTOP-1",
88+
"domain": "192.168.00.000",
89+
"ip": "50.237.00.00",
90+
"privateIp": [
91+
"192.168.00.000",
92+
"127.0.0.1"
93+
],
94+
"operatingSystem": "Windows 10",
95+
"email": {
96+
"sender": null,
97+
"from": null
98+
},
99+
"removableMedia": {
100+
"vendor": null,
101+
"name": null,
102+
"serialNumber": null,
103+
"capacity": null,
104+
"busType": null,
105+
"mediaName": null,
106+
"volumeName": [],
107+
"partitionId": []
108+
},
109+
"tabs": [],
110+
"domains": []
111+
},
112+
"destination": {
113+
"category": "Cloud Storage",
114+
"name": "Dropbox",
115+
"user": {
116+
"email": []
117+
},
118+
"ip": null,
119+
"privateIp": [],
120+
"operatingSystem": null,
121+
"printJobName": null,
122+
"printerName": null,
123+
"printedFilesBackupPath": null,
124+
"removableMedia": {
125+
"vendor": null,
126+
"name": null,
127+
"serialNumber": null,
128+
"capacity": null,
129+
"busType": null,
130+
"mediaName": null,
131+
"volumeName": [],
132+
"partitionId": []
133+
},
134+
"email": {
135+
"recipients": null,
136+
"subject": null
137+
},
138+
"tabs": [
139+
{
140+
"title": "Files - Dropbox and 1 more page - Profile 1 - Microsoft​ Edge",
141+
"url": "https://www.dropbox.com/home",
142+
"titleError": null,
143+
"urlError": null
144+
}
145+
],
146+
"accountName": null,
147+
"accountType": null,
148+
"domains": [
149+
"dropbox.com"
150+
]
151+
},
152+
"process": {
153+
"executable": "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
154+
"owner": "John doe"
155+
},
156+
"risk": {
157+
"score": 17,
158+
"severity": "CRITICAL",
159+
"indicators": [
160+
{
161+
"name": "First use of destination",
162+
"weight": 3
163+
},
164+
{
165+
"name": "File mismatch",
166+
"weight": 9
167+
},
168+
{
169+
"name": "Spreadsheet",
170+
"weight": 0
171+
},
172+
{
173+
"name": "Remote",
174+
"weight": 0
175+
},
176+
{
177+
"name": "Dropbox upload",
178+
"weight": 5
179+
}
180+
],
181+
"trusted": false,
182+
"trustReason": null
183+
}
184+
}
185+
186+
```

‎setup.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
"keyrings.alt==3.2.0",
4040
"ipython==7.16.3",
4141
"pandas>=1.1.3",
42-
"py42>=1.23.0",
42+
"py42>=1.24.0",
4343
],
4444
extras_require={
4545
"dev": [

‎src/code42cli/cmds/profile.py

Lines changed: 46 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,16 @@ def username_option(required=False):
7070

7171
disable_ssl_option = click.option(
7272
"--disable-ssl-errors",
73-
is_flag=True,
73+
type=click.types.BOOL,
7474
help="For development purposes, do not validate the SSL certificates of Code42 servers. "
75-
"This is not recommended, except for specific scenarios like testing.",
75+
"This is not recommended, except for specific scenarios like testing. Attach this flag to the update command to toggle the setting.",
76+
default=None,
77+
)
78+
79+
use_v2_file_events_option = click.option(
80+
"--use-v2-file-events",
81+
type=click.types.BOOL,
82+
help="Opts to use the V2 file event data model. Attach this flag to the update command to toggle the setting",
7683
default=None,
7784
)
7885

@@ -86,6 +93,7 @@ def show(profile_name):
8693
echo(f"\t* username = {c42profile.username}")
8794
echo(f"\t* authority url = {c42profile.authority_url}")
8895
echo(f"\t* ignore-ssl-errors = {c42profile.ignore_ssl_errors}")
96+
echo(f"\t* use-v2-file-events = {c42profile.use_v2_file_events}")
8997
if cliprofile.get_stored_password(c42profile.name) is not None:
9098
echo("\t* A password is set.")
9199
echo("")
@@ -100,10 +108,22 @@ def show(profile_name):
100108
@totp_option
101109
@yes_option(hidden=True)
102110
@disable_ssl_option
111+
@use_v2_file_events_option
103112
@debug_option
104-
def create(name, server, username, password, disable_ssl_errors, debug, totp):
113+
def create(
114+
name,
115+
server,
116+
username,
117+
password,
118+
disable_ssl_errors,
119+
use_v2_file_events,
120+
debug,
121+
totp,
122+
):
105123
"""Create profile settings. The first profile created will be the default."""
106-
cliprofile.create_profile(name, server, username, disable_ssl_errors)
124+
cliprofile.create_profile(
125+
name, server, username, disable_ssl_errors, use_v2_file_events
126+
)
107127
password = password or _prompt_for_password(name)
108128
if password:
109129
_set_pw(name, password, debug, totp=totp)
@@ -117,18 +137,35 @@ def create(name, server, username, password, disable_ssl_errors, debug, totp):
117137
@password_option
118138
@totp_option
119139
@disable_ssl_option
140+
@use_v2_file_events_option
120141
@debug_option
121-
def update(name, server, username, password, disable_ssl_errors, debug, totp):
142+
def update(
143+
name,
144+
server,
145+
username,
146+
password,
147+
disable_ssl_errors,
148+
use_v2_file_events,
149+
debug,
150+
totp,
151+
):
122152
"""Update an existing profile."""
123153
c42profile = cliprofile.get_profile(name)
124154

125-
if not server and not username and not password and disable_ssl_errors is None:
155+
if (
156+
not server
157+
and not username
158+
and not password
159+
and disable_ssl_errors is None
160+
and use_v2_file_events is None
161+
):
126162
raise click.UsageError(
127-
"Must provide at least one of `--username`, `--server`, `--password`, or "
163+
"Must provide at least one of `--username`, `--server`, `--password`, `--use-v2-file-events` or "
128164
"`--disable-ssl-errors` when updating a profile."
129165
)
130-
131-
cliprofile.update_profile(c42profile.name, server, username, disable_ssl_errors)
166+
cliprofile.update_profile(
167+
c42profile.name, server, username, disable_ssl_errors, use_v2_file_events
168+
)
132169
if not password and not c42profile.has_stored_password:
133170
password = _prompt_for_password(c42profile.name)
134171
if password:

0 commit comments

Comments
 (0)