Feature/watchlists (#414)

* adding watchlists

CHANGELOG.md

@@ -8,6 +8,32 @@ 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` and `UserRiskProfile` clients
+  - These features replace the `DetectionLists` client as well as its `DepartingEmployee` and `HighRiskEmployee` services.  All related classes and methods have been marked as deprecated and will raise deprecation warnings.
+  - `Watchlists` client includes the following methods:
+    - `get()`
+    - `delete()`
+    - `get_all()`
+    - `create()`
+    - `get_all_included_users()`
+    - `add_included_users_by_watchlist_id()`
+    - `add_included_users_by_watchlist_type()`
+    - `delete_included_users_by_watchlist_id()`
+    - `delete_included_users_by_watchlist_type()`
+    - `get_all_watchlist_members()`
+    - `get_watchlist_member()`
+  - `UserRiskProfile` client includes the following methods:
+    - `get_by_id()`
+    - `get_by_username()`
+    - `update()`
+    - `get_page()`
+    - `get_all()`
+    - `add_cloud_aliases()`
+    - `delete_cloud_aliases()`
+
 ## 1.22.0 - 2022-04-01
 
 ### Added

CONTRIBUTING.md

@@ -47,11 +47,13 @@ eval "$(pyenv virtualenv-init -)"
 Then, create your virtual environment.
 
 ```bash
-pyenv install 3.6.14
-pyenv virtualenv 3.6.14 py42
+pyenv install 3.9.10
+pyenv virtualenv 3.9.10 py42
 pyenv activate py42
 ```
 
+**Note**: Py42 for end users supports Pythons versions <3.6 and <4 - However due to some of the build dependencies, you'll need a version >=3.7 for your virtual environment.  Use `pyenv --versions` to see all versions available for install. There are some known issues installing python 3.6 with pyenv on certain OS.
+
 If running into issues on Big Sur(Version 11) while installing python 3.6 the below may work
 
 ```bash
@@ -184,12 +186,14 @@ To simply test that the documentation build without errors, you can run:
 tox -e docs
 ```
 
+Note that the `myst-parser` dependency that contributes to building the docs requires python 3.7+.
+
 #### Running the docs locally
 
 To build and run the documentation locally, run the following from the `docs` directory:
 
 ```bash
-pip install sphinx myst_parser sphinx_rtd_theme
+pip install sphinx myst-parser sphinx_rtd_theme
 make html
 ```
 

docs/conf.py

@@ -66,6 +66,9 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+# generate header anchors
+myst_heading_anchors = 4
+
 
 # -- Options for HTML output -------------------------------------------------
 

docs/guides.md

@@ -18,6 +18,8 @@
     Backup Sets <userguides/backupsets>
     userguides/cases
     userguides/trustedactivities
+    userguides/userriskprofile
+    userguides/watchlists
 ```
 
 * [Getting Started](userguides/gettingstarted.md)
@@ -31,3 +33,5 @@
 * [Backup Sets](userguides/backupsets.md)
 * [Cases](userguides/cases.md)
 * [Trust Settings](userguides/trustedactivities.md)
+* [User Risk Profiles](userguides/userriskprofile.md)
+* [Watchlists](userguides/watchlists.md)

docs/methoddocs/constants.md

@@ -35,3 +35,9 @@
     :members:
     :show-inheritance:
 ```
+
+```{eval-rst}
+.. autoclass:: py42.constants.WatchlistType
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/detectionlists.md

@@ -1,5 +1,7 @@
 # Detection Lists
 
+**Detection lists have been deprecated. Use [Watchlists](watchlists.md) instead.**
+
 ```{eval-rst}
 .. autoclass:: py42.clients.detectionlists.DetectionListsClient
     :members:

docs/methoddocs/userriskprofile.md

@@ -0,0 +1,7 @@
+# User Risk Profiles
+
+```{eval-rst}
+.. autoclass:: py42.clients.userriskprofile.UserRiskProfileClient
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/watchlists.md

@@ -0,0 +1,13 @@
+# Watchlists
+
+```{eval-rst}
+.. autoclass:: py42.clients.watchlists.WatchlistType
+    :members:
+    :show-inheritance:
+```
+
+```{eval-rst}
+.. autoclass:: py42.clients.watchlists.WatchlistsClient
+    :members:
+    :show-inheritance:
+```

docs/methods.md

@@ -47,7 +47,9 @@ Explore the complete public documentation for `py42` below.
 * [Shared Query Filters](methoddocs/sharedqueryfilters.md)
 * [Trusted Activities](methoddocs/trustedactivities.md)
 * [Users](methoddocs/users.md)
+* [User Risk Profiles](methoddocs/userriskprofile.md)
 * [Util](methoddocs/util.md)
+* [Watchlists](methoddocs/watchlists.md)
 
 ```{eval-rst}
 .. automodule:: py42.sdk

docs/userguides/cases.md

@@ -27,7 +27,7 @@ from py42.constants import CaseStatus
 response = sdk.cases.update(case_number, status=CaseStatus.CLOSED)
 ```
 
-Case statuses can be set to either `OPEN` or `CLOSED`.  Constants for these statuses are available at [Case Status](../methoddocs/constants.html#py42.constants.CaseStatus)
+Case statuses can be set to either `OPEN` or `CLOSED`.  Constants for these statuses are available at [Case Status](https://py42docs.code42.com/en/stable/methoddocs/constants.html#py42.constants.CaseStatus).
 
 ## View Details for all OPEN Cases
 

docs/userguides/departingemployee.md

@@ -37,4 +37,4 @@ sdk.detectionlists.departing_employee.remove(user_id)
 ```
 
 For complete details, see
- [Departing Employee](../methoddocs/detectionlists.html#departing-employee).
+ [Departing Employee](../methoddocs/detectionlists.md#departing-employees).

docs/userguides/highriskemployee.md

@@ -50,7 +50,7 @@ response = sdk.detectionlists.add_user_risk_tags(user_id, tag_list)
 response = sdk.detectionlists.remove_user_risk_tags(user_id, tag_list)
 ```
 
-Constants for Risk tags are available at [Risk Tags](../methoddocs/constants.html#py42.constants.RiskTags)
+Constants for Risk tags are available at [Risk Tags](https://py42docs.code42.com/en/stable/methoddocs/constants.html#py42.constants.RiskTags)
 
 For complete details, see
- [High Risk Employee](../methoddocs/detectionlists.html#high-risk-employee).
+ [High Risk Employee](../methoddocs/detectionlists.md#high-risk-employee).

docs/userguides/trustedactivities.md

@@ -11,7 +11,7 @@ from py42.constants import TrustedActivityType
 
 response = sdk.trustedactivities.create(TrustedActivityType.DOMAIN, "test-domain.com")
 ```
-Constants for the each type of trusted activity are available at [Trusted Activity Type](../methoddocs/constants.html#py42.constants.TrustedActivityType)
+Constants for the each type of trusted activity are available at [Trusted Activity Type](https://py42docs.code42.com/en/stable/methoddocs/constants.html#py42.constants.TrustedActivityType)
 
 
 Once you've created a trusted activity, or if you're working with an existing one, you can use the trusted activity's `resourceId` to view details about it.

docs/userguides/userriskprofile.md

@@ -0,0 +1,58 @@
+# User Risk Profile
+
+A user risk profile is created for each user.  Use py42 to manage these user risk profiles.
+
+## Update a User Risk Profile
+
+Determine the user ID to manage a user's risk profile.  For example, the following code uses the `get_username()` method to find the ID of a user with the username `test.user@code42.com`.
+
+```python
+response = sdk.userriskprofile.get_username()
+
+user_id = response.data["userId"]
+```
+
+Use the user ID with the `update()` method to manage a user risk profiles' `startDate`, `endDate`, and `notes` fields.
+
+The `startDate` and `endDate` arguments expect a format of `YYYY-MM-DD` or a `datetime` object.
+
+The following code updates the departure date of the user risk profile to March 1st, 2025:
+
+```python
+# update the user risk profile
+sdk.userriskprofile.update(user_id, end_date="2025-03-01", notes="Updated the departure date.")
+
+# view updated user details
+py42.util.print_response(sdk.userriskprofile.get(user_id))
+```
+
+If you want to clear a field, provide an empty string to the corresponding argument.
+
+For example, the following code will clear the `endDate` and `notes` fields:
+
+```python
+# clear fields on the user risk profile
+sdk.userriskprofile.update(user_id, end_date="", notes="")
+```
+
+## Manage Cloud Aliases
+
+Each user risk profile starts with a default alias of their code42 username and can have one additional cloud alias.
+Use the `UserRiskProfileClient` to manage these aliases.
+
+Use `add_cloud_aliases()` to assign additional cloud aliases to a user:
+
+```python
+user_id = "test-user-123"
+cloud_aliases = "test-user@email.com"
+sdk.userriskprofile.add_cloud_aliases(user_id, cloud_aliases)
+
+# view updated user cloud aliases
+py42.util.print_response(sdk.userriskprofile.get(user_id))
+```
+
+Remove cloud aliases in a similar manner using the `delete_cloud_aliases()` method. Provide a list of values to add or remove multiple aliases at once.
+
+```python
+sdk.userriskprofile.delete_cloud_aliases(user_id, ["test-user@email.com", "username@email.com"])
+```

docs/userguides/watchlists.md

@@ -0,0 +1,69 @@
+# Watchlists
+
+Use py42 to create and manage watchlists.
+
+Watchlists have replaced the Departing Employees and High Risk Employees detections lists. See the [Code42 support documentation](https://support.code42.com/Incydr/Admin/Monitoring_and_managing/Manage_watchlists) on managing watchlists for more information.
+
+## Create a Watchlist
+
+```python
+from py42.constants import WatchlistType
+
+watchlist = sdk.watchlists.create(WatchlistType.DEPARTING)
+
+# store the id of the new watchlist
+watchlist_id = watchlist.data["watchlistId"]
+```
+
+Watchlist types are available as constants in the [WatchlistType](https://py42docs.code42.com/en/stable/methoddocs/constants.html#py42.constants.WatchlistType) class.
+
+## View Watchlist Details
+
+There are several methods to view different details about watchlists.
+
+```python
+import py42.util
+
+# Get information on all current watchlists
+response = sdk.watchlists.get_all()
+
+# print all information to the console
+for page in response:
+    py42.util.print_response(page)
+```
+
+Once you have the watchlist's ID, use the following methods to see more details:
+
+```python
+# To get watchlist details
+sdk.watchlists.get(watchlist_id)
+
+# To see all included users
+sdk.watchlists.get_all_included_users(watchlist_id)
+```
+
+## Manage Users on Watchlists
+
+Use the `included_users` methods to manage individual users who are explicitly included on watchlists.
+
+Py42 allows you to reference a watchlist either by its ID or by its type. If adding individual users to a watchlist with the `add_included_users_by_watchlist_type()` method, py42 will create the watchlist for you if it doesn't already exist.
+
+For example, the following code demonstrates two methods to add users to the Departing watchlist:
+
+```python
+user_ids = ["test-user-123", "test-user-456"]
+
+# METHOD 1: add by watchlist id
+sdk.watchlists.add_included_users_by_watchlist_id(user_ids, watchlist_id)
+
+# METHOD 2: add by watchlist type
+from py42.constants import WatchlistType
+
+# this method will create the DEPARTING watchlist for you if it doesn't already exist
+sdk.watchlists.add_included_users_by_watchlist_type(user_ids, WatchlistType.DEPARTING)
+
+# View your updated watchlist users
+sdk.watchlists.get_all_included_users(watchlist_id)
+```
+
+The `delete_included_users_by_watchlist_id()` and `delete_included_users_by_watchlist_type()` methods can be used similarly to remove users from a watchlist.

src/py42/clients/__init__.py

@@ -12,5 +12,7 @@
         "cases",
         "loginconfig",
         "trustedactivities",
+        "userriskprofile",
+        "watchlists",
     ],
 )