Skip to content

Commit 7258218

Browse files
tora-kozicannie-payseur
tora-kozic
and
annie-payseur
authored
Chore/add user guides (#326)
* trust user guide * adding trust user guides * user guides * adding user guides * user guides * user guides * PR feedback * PR feedback * PR feedback * Update trustedactivities.md Updates to phrasing for brevity, clarity and style. The "Note" section within "Update a Trusted Activity" appeared to be entirely in a code block, which didn't seem right. * Update users.md Updates to phrasing for clarity, brevity, and style. * style * format note block * tiny wording adjustments * /s Co-authored-by: annie-payseur <52421911+annie-payseur@users.noreply.github.com>
1 parent 3427396 commit 7258218

File tree

9 files changed

+430
-38
lines changed

9 files changed

+430
-38
lines changed

‎docs/guides.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,12 @@
22

33
* [Get started with the Code42 command-line interface (CLI)](userguides/gettingstarted.md)
44
* [Configure a profile](userguides/profile.md)
5-
* [Ingest file events or alerts into a SIEM](userguides/siemexample.md)
5+
* [Ingest Data into a SIEM](userguides/siemexample.md)
66
* [Manage detection list users](userguides/detectionlists.md)
77
* [Manage legal hold users](userguides/legalhold.md)
88
* [Clean up your environment by deactivating devices](userguides/deactivatedevices.md)
99
* [Write custom extension scripts using the Code42 CLI and py42](userguides/extensions.md)
10+
* [Manage Users](userguides/users.md)
11+
* [Configure Trusted Activities](userguides/trustedactivities.md)
12+
* [Configure Alert Rules](userguides/alertrules.md)
13+
* [Add and Manage Cases](userguides/cases.md)

‎docs/userguides/alertrules.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Add Users to Alert Rules
2+
3+
Once you [create an alert rule in the Code42 console](https://support.code42.com/Administrator/Cloud/Code42_console_reference/Alert_rule_settings_reference), you can use the CLI `alert-rules` commands to add and remove users from your existing alert rules.
4+
5+
To see a list of all the users currently in your organization:
6+
- Export a list from the [Users action menu](https://support.code42.com/Administrator/Cloud/Code42_console_reference/Users_reference#Action_menu).
7+
- Use the [CLI users commands](./users.md).
8+
9+
## View Existing Alert Rules
10+
11+
You'll need the ID of an alert rule to add or remove a user.
12+
13+
To view a list of all alert rules currently created for your organization, including the rule ID, use the following command:
14+
```bash
15+
code42 alert-rules list
16+
```
17+
18+
Once you've identified the rule ID, view the details of the alert rule as follows:
19+
```bash
20+
code42 alert-rules show <rule-ID>
21+
```
22+
23+
#### Example output
24+
Example output for a single alert rule in default JSON format.
25+
```json
26+
{
27+
"type$": "ENDPOINT_EXFILTRATION_RULE_DETAILS_RESPONSE",
28+
"rules": [
29+
{
30+
"type$": "ENDPOINT_EXFILTRATION_RULE_DETAILS",
31+
"tenantId": "c4e43418-07d9-4a9f-a138-29f39a124d33",
32+
"name": "My Rule",
33+
"description": "this is your rule!",
34+
"severity": "HIGH",
35+
"isEnabled": false,
36+
"fileBelongsTo": {
37+
"type$": "FILE_BELONGS_TO",
38+
"usersToAlertOn": "ALL_USERS"
39+
},
40+
"notificationConfig": {
41+
"type$": "NOTIFICATION_CONFIG",
42+
"enabled": false
43+
},
44+
"fileCategoryWatch": {
45+
"type$": "FILE_CATEGORY_WATCH",
46+
"watchAllFiles": true
47+
},
48+
"ruleSource": "Alerting",
49+
"fileSizeAndCount": {
50+
"type$": "FILE_SIZE_AND_COUNT",
51+
"fileCountGreaterThan": 2,
52+
"totalSizeGreaterThanInBytes": 200,
53+
"operator": "AND"
54+
},
55+
"fileActivityIs": {
56+
"type$": "FILE_ACTIVITY",
57+
"syncedToCloudService": {
58+
"type$": "SYNCED_TO_CLOUD_SERVICE",
59+
"watchBox": false,
60+
"watchBoxDrive": false,
61+
"watchDropBox": false,
62+
"watchGoogleBackupAndSync": false,
63+
"watchAppleIcLoud": false,
64+
"watchMicrosoftOneDrive": false
65+
},
66+
"uploadedOnRemovableMedia": true,
67+
"readByBrowserOrOther": true
68+
},
69+
"timeWindow": 15,
70+
"id": "404ff012-fa2f-4acf-ae6d-107eabf7f24c",
71+
"createdAt": "2021-04-27T01:55:36.4204590Z",
72+
"createdBy": "sean.cassidy@example.com",
73+
"modifiedAt": "2021-09-03T01:46:13.2902310Z",
74+
"modifiedBy": "sean.cassidy@example.com",
75+
"isSystem": false
76+
}
77+
]
78+
}
79+
```
80+
81+
## Add a User to an Alert Rule
82+
83+
You can manage the users who are associated with an alert rule once you know the rule's `rule_id` and the user's `username`.
84+
85+
To add a single user to your alert rule, use the following command:
86+
```bash
87+
code42 alert-rules add-user --rule-id <rule-id> -u sean.cassidy@example.com
88+
```
89+
90+
Alternatively, to add multiple users to your alert rule, fill out the `add` CSV file template, then use the `bulk add` command with the CSV file path.
91+
```bash
92+
code42 alert-rules bulk add users.csv
93+
```
94+
95+
You can remove single or multiple users from alert rules similarly using the `remove-user` and `bulk remove` commands.
96+
97+
98+
## Get CSV Template
99+
100+
The following command will generate a CSV template to either add or remove users from multiple alert rules at once. The CSV file will be saved to the current working directory.
101+
```bash
102+
code42 alert-rules bulk generate-template [add|remove]
103+
```
104+
105+
You can then fill out and use each of the CSV templates with their respective bulk commands.
106+
```bash
107+
code42 alert-rules bulk [add|remove] /Users/my_user/bulk-command.csv
108+
```
109+
110+
Learn more about the [Alert Rules](../commands/alertrules.md) commands.

‎docs/userguides/cases.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Add and Manage Cases
2+
3+
To create a new case, only the name is required. Other attributes are optional and can be provided through the available flags.
4+
5+
The following command creates a case with the `subject` and `assignee` user indicated by their respective UIDs.
6+
```bash
7+
code42 cases create My-Case --subject 123 --assignee 456 --description "Sample case"
8+
```
9+
10+
## Update a Case
11+
12+
To further update or view the details of your case, you'll need the case's unique number, which is assigned upon creation. To get this number, you can use the `list` command to view all cases, with optional filter values.
13+
14+
To print to the console all open cases created in the last 30 days:
15+
```bash
16+
code42 cases list --begin-create-time 30d --status OPEN
17+
```
18+
19+
#### Example Output
20+
Example output for a single case in JSON format.
21+
```json
22+
{
23+
"number": 42,
24+
"name": "My-Case",
25+
"createdAt": "2021-9-17T18:29:53.375136Z",
26+
"updatedAt": "2021-9-17T18:29:53.375136Z",
27+
"description": "Sample case",
28+
"findings": "",
29+
"subject": "123",
30+
"subjectUsername": "sean.cassidy@example.com",
31+
"status": "OPEN",
32+
"assignee": "456",
33+
"assigneeUsername": "elvis.presley@example.com",
34+
"createdByUserUid": "789",
35+
"createdByUsername": "andy.warhol@example.com",
36+
"lastModifiedByUserUid": "789",
37+
"lastModifiedByUsername": "andy.warhol@example.com"
38+
}
39+
```
40+
41+
Once you've identified your case's number, you can view further details on the case, or update its attributes.
42+
43+
The following command will print all details of your case.
44+
```bash
45+
code42 cases show 42
46+
```
47+
48+
If you've finished your investigation and you'd like to close your case, you can update the status of the case. Similarly, other attributes of the case can be updated using the optional flags.
49+
```bash
50+
code42 cases update 42 --status CLOSED
51+
```
52+
53+
## Get CSV Template
54+
55+
The following command will generate a CSV template to either add or remove file events from multiple cases at once. The csv file will be saved to the current working directory.
56+
```bash
57+
code42 cases file-events bulk generate-template [add|remove]
58+
```
59+
60+
You can then fill out and use each of the CSV templates with their respective bulk commands.
61+
```bash
62+
code42 cases file-events bulk [add|remove] bulk-command.csv
63+
```
64+
65+
## Manage File Exposure Events Associated with a Case
66+
67+
The following example command can be used to view all the file exposure events currently associated with a case, indicated here by case number `42`.
68+
```bash
69+
code42 cases file-events list 42
70+
```
71+
72+
Use the `file-events add` command to associate a single file event, referred to by event ID, to a case.
73+
74+
Below is an example command to associate some event with ID `event_abc` with case number `42`.
75+
```bash
76+
code42 cases file-events add 42 event_abc
77+
```
78+
79+
To associate multiple file events with one or more cases at once, enter the case and file event information into the `file-events add` CSV file template, then use the `bulk add` command with the CSV file path. For example:
80+
```bash
81+
code42 cases file-events bulk add my_new_cases.csv
82+
```
83+
84+
Similarly, the `file-events remove` and `file-events bulk remove` commands can be used to remove a file event from a case.
85+
86+
## Export Case Details
87+
88+
You can use the CLI to export the details of a case into a PDF.
89+
90+
The following example command will download the details from case number `42` and save a PDF with the name `42_case_summary.pdf` to the provided path. If a path is not provided, it will be saved to the current working directory.
91+
92+
```bash
93+
code42 cases export 42 --path /Users/my_user/cases/
94+
```
95+
96+
Learn more about the [Managing Cases](../commands/cases.md).

‎docs/userguides/deactivatedevices.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,5 @@ code42 devices list --active \
9595
This lists all devices that have not connected within a year _and_
9696
are not a user's most-recently-connected device, and then attempts
9797
to deactivate them.
98+
99+
Learn more about [Managing Devices](../commands/devices.md).

‎docs/userguides/detectionlists.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22

33
Use the `departing-employee` commands to add employees to or remove employees from the Departing Employees list. Use the `high-risk-employee` commands to add employees to or remove employees from the High Risk list, or update risk tags for those users.
44

5-
To see a list of all the users currently in your organization, you can export a list from the
6-
[Users action menu](https://support.code42.com/Administrator/Cloud/Administration_console_reference/Users_reference#Action_menu).
5+
To see a list of all the users currently in your organization:
6+
- Export a list from the [Users action menu](https://support.code42.com/Administrator/Cloud/Code42_console_reference/Users_reference#Action_menu).
7+
- Use the [CLI users commands](./users.md).
78

89
## Get CSV template
910
To add multiple users to the Departing Employees list:

‎docs/userguides/legalhold.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@
22

33
Once you [create a legal hold matter in the Code42 console](https://support.code42.com/Administrator/Cloud/Configuring/Create_a_legal_hold_matter#Step_1:_Create_a_matter), you can use the Code42 CLI to add or release custodians from the matter.
44

5+
To see a list of all the users currently in your organization:
6+
- Export a list from the [Users action menu](https://support.code42.com/Administrator/Cloud/Code42_console_reference/Users_reference#Action_menu).
7+
- Use the [CLI users commands](./users.md).
8+
59
Use the `legal-hold` commands to manage legal hold custodians.
6-
- To see a list of all the users currently in your organization, you can export a list from the [Users action menu](https://support.code42.com/Administrator/Cloud/Code42_console_reference/Users_reference#Action_menu).
710
- To view a list of legal hold matters for your organization, including the matter ID, use the following command:
811
`code42 legal-hold list`
912
- To see a list of all the custodians currently associated with a legal hold matter, enter `code42 legal-hold show <matterID>`.

‎docs/userguides/siemexample.md‎

Lines changed: 70 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,30 @@ First install and configure the Code42 CLI following the instructions in
1414
[Getting Started](gettingstarted.md).
1515

1616
## Run queries
17-
You can get file events in either a JSON or CEF format for use by your SIEM tool. Alerts data is available in JSON format. You can query the data as a
18-
scheduled job or run ad-hoc queries. Learn more about [searching](../commands/securitydata.md) using the CLI.
17+
You can get file events in either a JSON or CEF format for use by your SIEM tool. Alerts data and audit logs are available in JSON format. You can query the data as a
18+
scheduled job or run ad-hoc queries.
19+
20+
Learn more about searching [File Events](../commands/securitydata.md), [Alerts](../commands/alerts.md), and [Audit Logs](../commands/auditlogs.md) using the CLI.
1921

2022
### Run a query as a scheduled job
2123

2224
Use your favorite scheduling tool, such as cron or Windows Task Scheduler, to run a query on a regular basis. Specify
23-
the profile to use by including `--profile`. An example using the `send-to` command to forward only the new file event data since the previous request to an external syslog server:
25+
the profile to use by including `--profile`.
26+
27+
#### File Exposure Events
28+
An example using the `send-to` command to forward only the new file event data since the previous request to an external syslog server:
2429
```bash
2530
code42 security-data send-to syslog.example.com:514 -p UDP --profile profile1 -c syslog_sender
2631
```
27-
32+
#### Alerts
2833
An example to send to the syslog server only the new alerts that meet the filter criteria since the previous request:
2934
```bash
30-
code42 alerts send-to syslog.example.com:514 -p UDP --profile profile1 --rule-name “Source code exfiltration” --state OPEN -i
35+
code42 alerts send-to syslog.example.com:514 -p UDP --profile profile1 --rule-name "Source code exfiltration" --state OPEN -i
36+
```
37+
#### Audit Logs
38+
An example to send to the syslog server only the audit log events that meet the filter criteria from the last 30 days.
39+
```bash
40+
code42 audit-logs send-to syslog.example.com:514 -p UDP --profile profile1 --actor-username 'sean.cassidy@example.com' -b 30d
3141
```
3242

3343
As a best practice, use a separate profile when executing a scheduled task. Using separate profiles can help prevent accidental updates to your stored checkpoints, for example, by adding `--use-checkpoint` to adhoc queries.
@@ -36,6 +46,8 @@ As a best practice, use a separate profile when executing a scheduled task. Usin
3646

3747
Examples of ad-hoc queries you can run are as follows.
3848

49+
#### File Exposure Events
50+
3951
Print file events since March 5 for a user in raw JSON format:
4052
```bash
4153
code42 security-data search -f RAW-JSON -b 2020-03-05 --c42-username 'sean.cassidy@example.com'
@@ -51,11 +63,18 @@ March 5:
5163
```bash
5264
code42 security-data search -f RAW-JSON -b 2020-03-05 -t ApplicationRead --c42-username 'sean.cassidy@example.com' > /Users/sangita.maskey/Downloads/c42cli_output.txt
5365
```
54-
66+
#### Alerts
5567
Print alerts since May 5 where a file's cloud share permissions changed:
5668
```bash
5769
code42 alerts print -b 2020-05-05 --rule-type FedCloudSharePermissions
5870
```
71+
#### Audit Logs
72+
Print audit log events since June 5 which affected a certain user:
73+
```bash
74+
code42 audit-logs search -b 2021-06-05 --affected-username 'sean.cassidy@examply.com'
75+
```
76+
77+
#### Example Outputs
5978

6079
Example output for a single file exposure event (in default JSON format):
6180

@@ -97,36 +116,53 @@ Example output for a single file exposure event (in default JSON format):
97116
Example output for a single alert (in default JSON format):
98117

99118
```json
100-
{"type$": "ALERT_DETAILS",
101-
"tenantId": "c4b5e830-824a-40a3-a6d9-345664cfbb33",
102-
"type": "FED_CLOUD_SHARE_PERMISSIONS",
103-
"name": "Cloud Share",
104-
"description": "Alert Rule for data exfiltration via Cloud Share",
105-
"actor": "leland.stewart@example.com",
106-
"target": "N/A",
107-
"severity": "HIGH",
108-
"ruleId": "408eb1ae-587e-421a-9444-f75d5399eacb",
109-
"ruleSource": "Alerting",
110-
"id": "7d936d0d-e783-4b24-817d-f19f625e0965",
111-
"createdAt": "2020-05-22T09:47:33.8863230Z",
112-
"state": "OPEN",
113-
"observations": [{"type$": "OBSERVATION",
114-
"id": "4bc378e6-bfbd-40f0-9572-6ed605ea9f6c",
115-
"observedAt": "2020-05-22T09:40:00.0000000Z",
116-
"type": "FedCloudSharePermissions",
117-
"data": {"type$": "OBSERVED_CLOUD_SHARE_ACTIVITY",
118-
"id": "4bc378e6-bfbd-40f0-9572-6ed605ea9f6c",
119-
"sources": ["GoogleDrive"],
120-
"exposureTypes": ["PublicLinkShare"],
121-
"firstActivityAt": "2020-05-22T09:40:00.0000000Z",
122-
"lastActivityAt": "2020-05-22T09:45:00.0000000Z",
123-
"fileCount": 1,
124-
"totalFileSize": 6025,
125-
"fileCategories": [{"type$": "OBSERVED_FILE_CATEGORY", "category": "Document", "fileCount": 1, "totalFileSize": 6025, "isSignificant": false}],
126-
"files": [{"type$": "OBSERVED_FILE", "eventId": "1hHdK6Qe6hez4vNCtS-UimDf-sbaFd-D7_3_baac33d0-a1d3-4e0a-9957-25632819eda7", "name": "1590140395_Longfellow_Cloud_Arch_Redesign.drawio", "category": "Document", "size": 6025}],
127-
"outsideTrustedDomainsEmailsCount": 0, "outsideTrustedDomainsTotalDomainCount": 0, "outsideTrustedDomainsTotalDomainCountTruncated": false}}]}
119+
{
120+
"type$": "ALERT_DETAILS",
121+
"tenantId": "c4b5e830-824a-40a3-a6d9-345664cfbb33",
122+
"type": "FED_CLOUD_SHARE_PERMISSIONS",
123+
"name": "Cloud Share",
124+
"description": "Alert Rule for data exfiltration via Cloud Share",
125+
"actor": "leland.stewart@example.com",
126+
"target": "N/A",
127+
"severity": "HIGH",
128+
"ruleId": "408eb1ae-587e-421a-9444-f75d5399eacb",
129+
"ruleSource": "Alerting",
130+
"id": "7d936d0d-e783-4b24-817d-f19f625e0965",
131+
"createdAt": "2020-05-22T09:47:33.8863230Z",
132+
"state": "OPEN",
133+
"observations": [{"type$": "OBSERVATION",
134+
"id": "4bc378e6-bfbd-40f0-9572-6ed605ea9f6c",
135+
"observedAt": "2020-05-22T09:40:00.0000000Z",
136+
"type": "FedCloudSharePermissions",
137+
"data": {
138+
"type$": "OBSERVED_CLOUD_SHARE_ACTIVITY",
139+
"id": "4bc378e6-bfbd-40f0-9572-6ed605ea9f6c",
140+
"sources": ["GoogleDrive"],
141+
"exposureTypes": ["PublicLinkShare"],
142+
"firstActivityAt": "2020-05-22T09:40:00.0000000Z",
143+
"lastActivityAt": "2020-05-22T09:45:00.0000000Z",
144+
"fileCount": 1,
145+
"totalFileSize": 6025,
146+
"fileCategories": [{"type$": "OBSERVED_FILE_CATEGORY", "category": "Document", "fileCount": 1, "totalFileSize": 6025, "isSignificant": false}],
147+
"files": [{"type$": "OBSERVED_FILE", "eventId": "1hHdK6Qe6hez4vNCtS-UimDf-sbaFd-D7_3_baac33d0-a1d3-4e0a-9957-25632819eda7", "name": "1590140395_Longfellow_Cloud_Arch_Redesign.drawio", "category": "Document", "size": 6025}],
148+
"outsideTrustedDomainsEmailsCount": 0, "outsideTrustedDomainsTotalDomainCount": 0, "outsideTrustedDomainsTotalDomainCountTruncated": false}}]
149+
}
128150
```
129151

152+
Example output for a single audit log event (in default JSON format):
153+
```json
154+
{
155+
"type$": "audit_log::logged_in/1",
156+
"actorId": "1015070955620029617",
157+
"actorName": "sean.cassidy@example.com",
158+
"actorAgent": "py42 1.17.0 python 3.7.10",
159+
"actorIpAddress": "67.220.16.122",
160+
"timestamp": "2021-08-30T16:16:19.165Z",
161+
"actorType": "USER"
162+
}
163+
```
164+
165+
130166
## CEF Mapping
131167

132168
The following tables map the file event data from the Code42 CLI to common event format (CEF).

0 commit comments

Comments
 (0)