Add legal hold membership to device reporting

CHANGELOG.md

@@ -8,6 +8,41 @@ 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.
 
+## 1.3.1 - 2021-02-25
+
+### Changed
+
+- Command options for `profile update`:
+    - `-n` `--name` is not required, and if omitted will use the default profile.
+    - `-s` `--server` and `-u` `--username` are not required and can be updated independently now.
+    - Example: `code42 profile update -s 1.2.3.4:1234`
+
+## 1.3.0 - 2021-02-11
+
+### Fixed
+
+- Issue where `code42 alert-rules bulk add` would show as successful when adding users to a non-existent alert rule.
+
+### Added
+
+- New choice `TLS-TCP` for `--protocol` option used by `send-to` commands:
+    - `code42 security-data send-to`
+    - `code42 alerts send-to`
+    - `code42 audit-logs send-to`
+  for more securely transporting data. Included are new flags:
+    - `--certs`
+    - `--ignore-cert-validation`
+
+### Changed
+
+- The error text in cases command when:
+    - `cases create` sets a name that already exists in the system.
+    - `cases create` sets a description that has more than 250 characters.
+    - `cases update` sets a description that has more than 250 characters.
+    - `cases file-events add` is performed on an already closed case.
+    - `cases file-events add` sets an event id that is already added to the case.
+    - `cases file-events remove` is performed on an already closed case.
+
 ## 1.2.0 - 2021-01-25
 
 ### Added
@@ -71,6 +106,12 @@ how a consumer would use the library (e.g. adding unit tests, updating documenta
 - Now, when adding a cloud alias to a detection list user, such as during `departing-employee add`, it will remove the existing cloud alias if one exists.
     - Before, it would error and the cloud alias would not get added.
 
+### Added
+
+- `code42 devices list` option:
+    - `--include-legal-hold-membership` prints the legal hold matter name and ID for any active device on legal hold
+    - `--include-total-storage` prints the backup archive count and total storage
+
 ## 1.0.0 - 2020-08-31
 
 ### Fixed

src/code42cli/cmds/devices.py

@@ -1,8 +1,11 @@
 from datetime import date
 
 import click
+import numpy as np
 from pandas import concat
 from pandas import DataFrame
+from pandas import json_normalize
+from pandas import Series
 from pandas import to_datetime
 from py42 import exceptions
 from py42.exceptions import Py42NotFoundError
@@ -244,6 +247,22 @@ def _get_device_info(sdk, device_guid):
     is_flag=True,
     help="Include device settings in output.",
 )
+@click.option(
+    "--include-legal-hold-membership",
+    required=False,
+    type=bool,
+    default=False,
+    is_flag=True,
+    help="Include legal hold membership in output.",
+)
+@click.option(
+    "--include-total-storage",
+    required=False,
+    type=bool,
+    default=False,
+    is_flag=True,
+    help="Include backup archive count and total storage in output.",
+)
 @click.option(
     "--exclude-most-recently-connected",
     type=int,
@@ -285,6 +304,8 @@ def list_devices(
     include_backup_usage,
     include_usernames,
     include_settings,
+    include_legal_hold_membership,
+    include_total_storage,
     exclude_most_recently_connected,
     last_connected_after,
     last_connected_before,
@@ -309,7 +330,11 @@ def list_devices(
         "userUid",
     ]
     df = _get_device_dataframe(
-        state.sdk, columns, active, org_uid, include_backup_usage
+        state.sdk,
+        columns,
+        active,
+        org_uid,
+        (include_backup_usage or include_total_storage),
     )
     if last_connected_after:
         df = df.loc[to_datetime(df.lastConnected) > last_connected_after]
@@ -326,17 +351,57 @@ def list_devices(
             .head(exclude_most_recently_connected)
         )
         df = df.drop(most_recent.index)
+    if include_total_storage:
+        df = _add_storage_totals_to_dataframe(df, include_backup_usage)
     if include_settings:
         df = _add_settings_to_dataframe(state.sdk, df)
     if include_usernames:
         df = _add_usernames_to_device_dataframe(state.sdk, df)
+    if include_legal_hold_membership:
+        df = _add_legal_hold_membership_to_device_dataframe(state.sdk, df)
     if df.empty:
         click.echo("No results found.")
     else:
         formatter = DataFrameOutputFormatter(format)
         formatter.echo_formatted_dataframe(df)
 
 
+def _add_legal_hold_membership_to_device_dataframe(sdk, df):
+    columns = ["legalHold.legalHoldUid", "legalHold.name", "user.userUid"]
+
+    legal_hold_member_dataframe = (
+        json_normalize(list(_get_all_active_hold_memberships(sdk)))[columns]
+        .groupby(["user.userUid"])
+        .agg(",".join)
+        .rename(
+            {
+                "legalHold.legalHoldUid": "legalHoldUid",
+                "legalHold.name": "legalHoldName",
+            },
+            axis=1,
+        )
+    )
+    df = df.merge(
+        legal_hold_member_dataframe,
+        how="left",
+        left_on="userUid",
+        right_on="user.userUid",
+    )
+
+    df.loc[df["status"] == "Deactivated", ["legalHoldUid", "legalHoldName"]] = np.nan
+
+    return df
+
+
+def _get_all_active_hold_memberships(sdk):
+    for page in sdk.legalhold.get_all_matters(active=True):
+        for matter in page["legalHolds"]:
+            for _page in sdk.legalhold.get_all_matter_custodians(
+                legal_hold_uid=matter["legalHoldUid"], active=True
+            ):
+                yield from _page["legalHoldMemberships"]
+
+
 def _get_device_dataframe(
     sdk, columns, active=None, org_uid=None, include_backup_usage=False
 ):
@@ -392,6 +457,26 @@ def _add_usernames_to_device_dataframe(sdk, device_dataframe):
     return device_dataframe.merge(users_dataframe, how="left", on="userUid")
 
 
+def _add_storage_totals_to_dataframe(df, include_backup_usage):
+    df[["archiveCount", "totalStorageBytes"]] = df["backupUsage"].apply(
+        _break_backup_usage_into_total_storage
+    )
+
+    if not include_backup_usage:
+        df = df.drop("backupUsage", axis=1)
+    return df
+
+
+def _break_backup_usage_into_total_storage(backup_usage):
+    total_storage = 0
+    archive_count = 0
+    for archive in backup_usage:
+        if archive["archiveFormat"] != "ARCHIVE_V2":
+            archive_count += 1
+            total_storage += archive["archiveBytes"]
+    return Series([archive_count, total_storage])
+
+
 @devices.command()
 @active_option
 @inactive_option