Feature/watchlists (#367)

* initial watchlists commands

* error handling

* add `bulk generate-template`

* require id or type option on `list-users`

* unused import

* mark departing_employee & high_risk as deprecated

* silence py42 deprecation warnings

* add deprecation_warning util func

* add user-risk-profile updates to `code42 users` cmd group

* fix bulk header names

* watchlists cmd tests

* fix existing alias cmd tests

* rename commands from add>update

* actually use --clear option on risk-profile update cmds

* add append-note logic to bulk risk-profile update

* not handling user_id in csv

* new user risk profile cmd tests

* PR feedback & style

* brackets around user metavar

* documentation updates

* use get_watchlist_members instead of get_included_users

* switch tests to use get_all_watchlist_members

* change list-users > list-members in user guide

* appease flake8

* add --only-included-users option to `list-members` cmd

* move f-string docstrings to help params

* document --only-included-users option

* add > remove in test

* changelog

Author: timabrmsn

CHANGELOG.md

@@ -8,6 +8,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The intended audience of this file is for py42 consumers -- as such, changes that don't affect
 how a consumer would use the library (e.g. adding unit tests, updating documentation, etc) are not captured here.
 
+
+## Unreleased
+
+### Added
+
+- `watchlists` command group for interacting with watchlists.
+  - `watchlists add` for adding users to a watchlist
+  - `watchlists remove` for removing users from a watchlist
+  - `watchlists list` for listing existing watchlists
+  - `watchlists list-members` for listing users who are members of a given watchlist
+  - `watchlist bulk add|remove` for adding/removing multiple users via CSV file
+
+- `users update-start-date` command to add/modify the "start date" property of a User's risk profile.
+- `users update-departure-date` command to add/modify the "end date" property of a User's risk profile.
+- `users update-risk-profile-notes` command to add/modify the "notes" property of a User's risk profile.
+
+### Deprecated
+
+- `departing-employee` and `high-risk-employee` command groups. These actions have been replaced by the `watchlists` command group.
+
 ## 1.13.0 - 2022-04-04
 
 ### Added

docs/commands.md

@@ -10,25 +10,27 @@
     Alerts <commands/alerts.rst>
     Audit Logs <commands/auditlogs.rst>
     Cases <commands/cases.rst>
-    Departing Employee <commands/departingemployee.rst>
     Devices <commands/devices.rst>
-    High Risk Employee <commands/highriskemployee.rst>
     Legal Hold <commands/legalhold.rst>
     Profile <commands/profile.rst>
     Security Data <commands/securitydata.rst>
     Trusted Activities <commands/trustedactivities.rst>
     Users <commands/users.rst>
+    Watchlists <commands/watchlists.rst>
+    (DEPRECATED) Departing Employee <commands/departingemployee.rst>
+    (DEPRECATED) High Risk Employee <commands/highriskemployee.rst>
 ```
 
 * [Alert Rules](commands/alertrules.rst)
 * [Alerts](commands/alerts.rst)
 * [Audit Logs](commands/auditlogs.rst)
 * [Cases](commands/cases.rst)
-* [Departing Employee](commands/departingemployee.rst)
 * [Devices](commands/devices.rst)
-* [High Risk Employee](commands/highriskemployee.rst)
 * [Legal Hold](commands/legalhold.rst)
 * [Profile](commands/profile.rst)
 * [Security Data](commands/securitydata.rst)
 * [Trusted Activities](commands/trustedactivities.rst)
 * [Users](commands/users.rst)
+* [Watchlists](commands/watchlists.rst)
+* [(DEPRECATED) Departing Employee](commands/departingemployee.rst)
+* [(DEPRECATED) High Risk Employee](commands/highriskemployee.rst)

docs/commands/watchlists.rst

@@ -0,0 +1,3 @@
+.. click:: code42cli.cmds.watchlists:watchlists
+  :prog: watchlists
+  :nested: full

docs/guides.md

@@ -9,7 +9,6 @@
     Get started with the Code42 command-line interface (CLI) <userguides/gettingstarted.md>
     Configure a profile <userguides/profile.md>
     Ingest data into a SIEM <userguides/siemexample.md>
-    Manage detection list users <userguides/detectionlists.md>
     Manage legal hold users <userguides/legalhold.md>
     Clean up your environment by deactivating devices <userguides/deactivatedevices.md>
     Write custom extension scripts using the Code42 CLI and Py42 <userguides/extensions.md>
@@ -18,12 +17,13 @@
     Configure alert rules <userguides/alertrules.md>
     Add and manage cases <userguides/cases.md>
     Perform bulk actions <userguides/bulkcommands.md>
+    Manage watchlist members <userguides/watchlists.md>
+    (DEPRECATED) Manage detection list users <userguides/detectionlists.md>
 ```
 
 * [Get started with the Code42 command-line interface (CLI)](userguides/gettingstarted.md)
 * [Configure a profile](userguides/profile.md)
 * [Ingest data into a SIEM](userguides/siemexample.md)
-* [Manage detection list users](userguides/detectionlists.md)
 * [Manage legal hold users](userguides/legalhold.md)
 * [Clean up your environment by deactivating devices](userguides/deactivatedevices.md)
 * [Write custom extension scripts using the Code42 CLI and Py42](userguides/extensions.md)
@@ -32,3 +32,5 @@
 * [Configure alert rules](userguides/alertrules.md)
 * [Add and manage cases](userguides/cases.md)
 * [Perform bulk actions](userguides/bulkcommands.md)
+* [Manage watchlist members](userguides/watchlists.md)
+* [(DEPRECATED) Manage detection list users](userguides/detectionlists.md)

docs/userguides/detectionlists.md

@@ -1,4 +1,14 @@
-# Manage Detection List Users
+# (DEPRECATED) Manage Detection List Users
+
+```{eval-rst}
+.. note::
+
+    Detection Lists have been replaced by Watchlists.
+
+    Functionality for adding users to Departing Employee and High Risk Employee categories has been migrated to the :code:`code42 watchlists` command group.
+
+    Functionality for listing and managing User Risk Profiles (e.g. adding Cloud Aliases, Notes, and Start/End dates to a user profile) has been migrated to the :code:`code42 users` command group.
+```
 
 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.
 

docs/userguides/users.md

@@ -34,6 +34,34 @@ code42 users add-role --username "sean.cassidy@example.com" --role-name "Desktop
 
 Similarly, use the `remove-role` command to remove a role from a user.
 
+## Manage User Risk Profile info
+
+To set a start or end/departure date on a User's profile (useful for users on the "New Hire" and "Departing" Watchlists):
+
+```bash
+code42 users update-start-date 2020-03-10 user@example.com
+
+code42 users update-departure-date 2022-06-20 user@example.com
+```
+
+To clear the value of start_date/end_date on a User's profile, use the `--clear` option to the above commands:
+
+```bash
+code42 users update-departure-date --clear user@example.com
+```
+
+To update a User's Risk Profile notes field:
+
+```bash
+code42 users update-risk-profile-notes user@example.com "New note text"
+```
+
+By default, the note text will overwrite notes are already on the profile. To keep existing note data, use the `--append` option:
+
+```bash
+code42 users update-risk-profile-notes user@example.com "Additional note text" --append
+```
+
 ## Deactivate a User
 
 You can deactivate a user with the following command:
@@ -73,17 +101,18 @@ Alternatively, to move multiple users between organizations, fill out the `move`
 code42 users bulk move bulk-command.csv
 ```
 
-## Get CSV Template
+## Get CSV Template for bulk commands
 
-The following command generates a CSV template to either update users' data, or move users between organizations.  The csv file is saved to the current working directory.
+The following command generates a CSV template for each of the available bulk user commands.  The CSV file is saved to the current working directory.
 ```bash
-code42 trusted-activities bulk generate-template [update|move]
+code42 users bulk generate-template [update|move|add-alias|remove-alias|update-risk-profile]
 ```
 
 Once generated, fill out and use each of the CSV templates with their respective bulk commands.
 ```bash
-code42 trusted-activities bulk [update|move|reactivate|deactivate] bulk-command.csv
+code42 users bulk [update|move|deactivate|reactivate|add-alias|remove-alias|update-risk-profile] bulk-command.csv
 ```
+
 A CSV with a `username` column and a single username on each new line is used for the `reactivate` and `deactivate` bulk commands.  These commands are not available as options for `generate-template`.
 
 Learn more about [Managing Users](../commands/users.md).

docs/userguides/watchlists.md

@@ -0,0 +1,64 @@
+# Manage watchlist members
+
+## List created watchlists
+
+To list all the watchlists active in your Code42 environment, run:
+
+```bash
+code42 watchlists list
+```
+
+##  List all members of a watchlist
+
+You can list watchlists either by their Type:
+
+```bash
+code42 watchlists list-members --watchlist-type DEPARTING_EMPLOYEE
+```
+
+or by their ID (get watchlist IDs from `code42 watchlist list` output):
+
+```bash
+code42 watchlists list-members --watchlist-id 6e6c5acc-2568-4e5f-8324-e73f2811fa7c
+```
+
+A "member" of a watchlist is any user that the watchlist alerting rules apply to. Users can be members of a watchlist
+either by being explicitly added (via console or `code42 watchlists add [USER_ID|USERNAME]`), but they can also be
+implicitly included based on some user profile property (like working in a specific department). To get a list of only
+those "members" who have been explicitly added (and thus can be removed via the `code42 watchlists remove [USER_ID|USERNAME]`
+command), add the `--only-included-users` option to `list-members`.
+
+## Add or remove a single user from watchlist membership
+
+A user can be added to a watchlist using either the watchlist ID or Type, just like listing watchlists, and the user
+can be identified either by their user_id or their username:
+
+```bash
+code42 watchlist add --watchlist-type NEW_EMPLOYEE 9871230
+```
+
+```bash
+code42 watchlist add --watchlist-id 6e6c5acc-2568-4e5f-8324-e73f2811fa7c user@example.com
+```
+
+## Bulk adding/removing users from watchlists
+
+The bulk watchlist commands read input from a CSV file.
+
+Like the individual commands, they can take either a user_id/username or watchlist_id/watchlist_type to identify who
+to add to which watchlist. Because of this flexibility, the CSV does require a header row identifying each column.
+
+You can generate a template CSV with the correct header values using the command:
+
+```bash
+code42 watchlists bulk generate-template [add|remove]
+```
+
+If both username and user_id are provided in the CSV row, the user_id value will take precedence. If watchlist_type and watchlist_id columns
+are both provided, the watchlist_id will take precedence.
+
+## Add Watchlist-related metadata to User's Profile
+
+Some Watchlists store related metadata to the watchlist member on the User Risk Profile. For example, when adding a user
+to the Departing Watchlist in the Code42 admin console, you can specify a "departure date" for the user. These values
+can be set/updated from the CLI under the [Users command group](./users.md#manage-user-risk-profile-info)

src/code42cli/click_ext/groups.py

@@ -17,6 +17,7 @@
 from py42.exceptions import Py42InvalidRuleOperationError
 from py42.exceptions import Py42InvalidUsernameError
 from py42.exceptions import Py42LegalHoldNotFoundOrPermissionDeniedError
+from py42.exceptions import Py42NotFoundError
 from py42.exceptions import Py42OrgNotFoundError
 from py42.exceptions import Py42TrustedActivityConflictError
 from py42.exceptions import Py42TrustedActivityIdNotFound
@@ -25,6 +26,8 @@
 from py42.exceptions import Py42UserAlreadyAddedError
 from py42.exceptions import Py42UsernameMustBeEmailError
 from py42.exceptions import Py42UserNotOnListError
+from py42.exceptions import Py42UserRiskProfileNotFound
+from py42.exceptions import Py42WatchlistNotFound
 
 from code42cli.errors import Code42CLIError
 from code42cli.errors import LoggedCLIError
@@ -90,6 +93,9 @@ def invoke(self, ctx):
             Py42TrustedActivityIdNotFound,
             Py42CloudAliasLimitExceededError,
             Py42CloudAliasCharacterLimitExceededError,
+            Py42UserRiskProfileNotFound,
+            Py42WatchlistNotFound,
+            Py42NotFoundError,
         ) as err:
             msg = err.args[0]
             self.logger.log_error(msg)

src/code42cli/cmds/departing_employee.py

@@ -17,13 +17,16 @@
 from code42cli.file_readers import read_csv_arg
 from code42cli.options import format_option
 from code42cli.options import sdk_options
+from code42cli.util import deprecation_warning
 
 
 def _get_filter_choices():
     filters = DepartingEmployeeFilters.choices()
     return get_choices(filters)
 
 
+DEPRECATION_TEXT = "(DEPRECATED): Use `code42 watchlists` commands instead."
+
 DATE_FORMAT = "%Y-%m-%d"
 filter_option = click.option(
     "--filter",
@@ -34,19 +37,18 @@ def _get_filter_choices():
 )
 
 
-@click.group(cls=OrderedGroup)
+@click.group(cls=OrderedGroup, help=f"{DEPRECATION_TEXT}\n\nAdd and remove employees from the Departing Employees detection list.")
 @sdk_options(hidden=True)
 def departing_employee(state):
-    """Add and remove employees from the Departing Employees detection list."""
     pass
 
 
-@departing_employee.command("list")
+@departing_employee.command("list", help=f"{DEPRECATION_TEXT}\n\nLists the users on the Departing Employees list.")
 @sdk_options()
 @format_option
 @filter_option
 def _list(state, format, filter):
-    """Lists the users on the Departing Employees list."""
+    deprecation_warning(DEPRECATION_TEXT)
     employee_generator = _get_departing_employees(state.sdk, filter)
     list_employees(
         employee_generator,
@@ -55,7 +57,7 @@ def _list(state, format, filter):
     )
 
 
-@departing_employee.command()
+@departing_employee.command(help=f"{DEPRECATION_TEXT}\n\nAdd a user to the Departing Employees detection list.")
 @username_arg
 @click.option(
     "--departure-date",
@@ -66,22 +68,22 @@ def _list(state, format, filter):
 @notes_option
 @sdk_options()
 def add(state, username, cloud_alias, departure_date, notes):
-    """Add a user to the Departing Employees detection list."""
+
+    deprecation_warning(DEPRECATION_TEXT)
     _add_departing_employee(state.sdk, username, cloud_alias, departure_date, notes)
 
 
-@departing_employee.command()
+@departing_employee.command(help=f"{DEPRECATION_TEXT}\n\nRemove a user from the Departing Employees detection list.")
 @username_arg
 @sdk_options()
 def remove(state, username):
-    """Remove a user from the Departing Employees detection list."""
+    deprecation_warning(DEPRECATION_TEXT)
     _remove_departing_employee(state.sdk, username)
 
 
-@departing_employee.group(cls=OrderedGroup)
+@departing_employee.group(cls=OrderedGroup, help=f"{DEPRECATION_TEXT}\n\nTools for executing bulk departing employee actions.")
 @sdk_options(hidden=True)
 def bulk(state):
-    """Tools for executing bulk departing employee actions."""
     pass
 
 
@@ -101,12 +103,13 @@ def bulk(state):
 
 @bulk.command(
     name="add",
-    help="Bulk add users to the departing employees detection list using a CSV file with "
-    f"format: {','.join(DEPARTING_EMPLOYEE_CSV_HEADERS)}.",
+    help=f"{DEPRECATION_TEXT}\n\nBulk add users to the departing employees detection list using "
+    f"a CSV file with format: {','.join(DEPARTING_EMPLOYEE_CSV_HEADERS)}.",
 )
 @read_csv_arg(headers=DEPARTING_EMPLOYEE_CSV_HEADERS)
 @sdk_options()
 def bulk_add(state, csv_rows):
+    deprecation_warning(DEPRECATION_TEXT)
     sdk = state.sdk  # Force initialization of py42 to only happen once.
 
     def handle_row(username, cloud_alias, departure_date, notes):
@@ -131,11 +134,13 @@ def handle_row(username, cloud_alias, departure_date, notes):
 
 @bulk.command(
     name="remove",
-    help=f"Bulk remove users from the departing employees detection list using a CSV file with format {','.join(REMOVE_EMPLOYEE_HEADERS)}.",
+    help=f"{DEPRECATION_TEXT}\n\nBulk remove users from the departing employees detection list "
+    f"using a CSV file with format {','.join(REMOVE_EMPLOYEE_HEADERS)}.",
 )
 @read_csv_arg(headers=REMOVE_EMPLOYEE_HEADERS)
 @sdk_options()
 def bulk_remove(state, csv_rows):
+    deprecation_warning(DEPRECATION_TEXT)
     sdk = state.sdk
 
     def handle_row(username):