Legal hold implementation (#82) (#90)

* Legal hold implementation (#82)

Co-authored-by: Alan Grgic <alan.grgic@code42.com>

* print "No active matter members." instead of "Active matter members:\nNone"

* add comment to clarify None/True state for `active` arg

* changelog periods

* add additionally

* with => will

* move matter_id accessible check to remove_user

* print "No inactive matter members."
fix tests

* Remove extra space

Co-authored-by: Tim Abramson <tim.abramson@code42.com>
Co-authored-by: tim.abramson <tim@abramson.dev>
Co-authored-by: Juliya Smith <juliya.smith@code42.com>

Author: 3 people

.github/workflows/build.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: [2.7, 3.5, 3.6, 3.7, 3.8]
+        python: [3.5, 3.6, 3.7, 3.8]
 
     steps:
       - uses: actions/checkout@v2

CHANGELOG.md

@@ -45,6 +45,20 @@ how a consumer would use the library (e.g. adding unit tests, updating documenta
             - `path`
         - `remove`: that takes a csv file with rule IDs and usernames.
 
+- `code42 legal-hold` commands:
+    - `add-user` with parameters `--matter-id/-m` and `--username/-u`.
+    - `remove-user` with parameters `--matter-id/-m` and `--username/-u`.
+    - `list` prints out existing active legal hold matters.
+    - `show` takes a `matter_id` and prints details of the matter.
+        - optional argument `--include-inactive` additionally prints matter memberships that are no longer active.
+        - optional argument `--include-policy` additionally prints out the matter's backup preservation policy in json form.
+    - `bulk` with subcommands:
+        - `add-user`: that takes a csv file with matter IDs and usernames. 
+        - `remove-user`: that takes a csv file with matter IDs and usernames.
+        - `generate-template`: that creates the file templates. 
+            - `cmd`: with options `add` and `remove`.
+            - `path`
+            
 - Success messages for `profile delete` and `profile update`.
 
 - Additional information in the error log file:

setup.py

@@ -19,9 +19,9 @@
     long_description_content_type="text/markdown",
     packages=find_packages("src"),
     package_dir={"": "src"},
-    python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, <4",
+    python_requires=">3, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, <4",
     install_requires=[
-        "c42eventextractor==0.3.0b1",
+        "c42eventextractor==0.3.1",
         "keyring==18.0.1",
         "keyrings.alt==3.2.0",
         "py42>=1.2.0",
@@ -46,8 +46,6 @@
         "Natural Language :: English",
         "License :: OSI Approved :: MIT License",
         "Programming Language :: Python",
-        "Programming Language :: Python :: 2",
-        "Programming Language :: Python :: 2.7",
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.5",
         "Programming Language :: Python :: 3.6",

src/code42cli/bulk.py

@@ -23,7 +23,7 @@ def generate_template(handler, path=None):
     `handler` only has one parameter that is not `sdk` or `profile`, it will create a blank file. 
     This is useful for commands such as `remove` which only require a list of users.
     """
-    path = path or u"{0}/{1}.csv".format(os.getcwd(), str(handler.__name__))
+    path = path or os.path.join(os.getcwd(), u"{}.csv".format(str(handler.__name__)))
     args = [
         arg
         for arg in inspect.getargspec(handler).args

src/code42cli/cmds/alerts/rules/commands.py

@@ -1,3 +1,6 @@
+import os
+
+from code42cli.commands import Command
 from code42cli import MAIN_COMMAND
 from code42cli.commands import Command, SubcommandLoader
 from code42cli.bulk import generate_template, BulkCommandType
@@ -52,17 +55,21 @@ def _generate_template_file(cmd, path=None):
     """Generates a template file a user would need to fill-in for bulk operating.
 
     Args:
-        cmd (str or unicode): An option from the `BulkCommandType` enum specifying which type of file to
-            generate.
-        path (str or unicode, optional): A path to put the file after it's generated. If None, will use
-            the current working directory. Defaults to None.
+        cmd (str or unicode): An option from the `BulkCommandType` enum specifying which type of 
+            file to generate.
+        path (str or unicode, optional): A path to put the file after it's generated. If None, will 
+            use the current working directory. Defaults to None.
     """
     handler = None
+    filename = u"alert_rule.csv"
     if cmd == BulkCommandType.ADD:
         handler = add_user
+        filename = u"add_users_to_{}".format(filename)
     elif cmd == BulkCommandType.REMOVE:
         handler = remove_user
-
+        filename = u"remove_users_from_{}".format(filename)
+    if not path:
+        path = os.path.join(os.getcwd(), filename)
     generate_template(handler, path)
 
 

src/code42cli/cmds/alerts/rules/user_rule.py

@@ -1,24 +1,24 @@
+from collections import OrderedDict
+
 from py42.exceptions import Py42InternalServerError
 from py42.util import format_json
 
 
 from code42cli.errors import InvalidRuleTypeError
-from code42cli.util import format_to_table, find_format_width
+from code42cli.util import format_to_table, find_format_width, get_user_id
 from code42cli.bulk import run_bulk_process
 from code42cli.file_readers import create_csv_reader
 from code42cli.logger import get_main_cli_logger
-from code42cli.cmds.detectionlists import get_user_id
 from code42cli.cmds.alerts.rules.enums import AlertRuleTypes
 
 
-_HEADER_KEYS_MAP = {
-    u"observerRuleId": u"RuleId",
-    u"name": u"Name",
-    u"severity": u"Severity",
-    u"type": u"Type",
-    u"ruleSource": u"Source",
-    u"isEnabled": u"Enabled",
-}
+_HEADER_KEYS_MAP = OrderedDict()
+_HEADER_KEYS_MAP[u"observerRuleId"] = u"RuleId"
+_HEADER_KEYS_MAP[u"name"] = u"Name"
+_HEADER_KEYS_MAP[u"severity"] = u"Severity"
+_HEADER_KEYS_MAP[u"type"] = u"Type"
+_HEADER_KEYS_MAP[u"ruleSource"] = u"Source"
+_HEADER_KEYS_MAP[u"isEnabled"] = u"Enabled"
 
 
 def add_user(sdk, profile, rule_id, username):

src/code42cli/cmds/detectionlists/__init__.py

@@ -3,9 +3,10 @@
 from code42cli.cmds.detectionlists.commands import DetectionListSubcommandLoader
 from code42cli.bulk import generate_template, run_bulk_process
 from code42cli.file_readers import create_csv_reader, create_flat_file_reader
-from code42cli.errors import UserAlreadyAddedError, UserDoesNotExistError, UnknownRiskTagError
+from code42cli.errors import UserAlreadyAddedError, UnknownRiskTagError
 from code42cli.cmds.detectionlists.enums import DetectionLists, DetectionListUserKeys, RiskTags
 from code42cli.cmds.detectionlists.bulk import BulkDetectionList, BulkHighRiskEmployee
+from code42cli.util import get_user_id
 
 
 def try_handle_user_already_added_error(bad_request_err, username_tried_adding, list_name):
@@ -205,23 +206,6 @@ def load_user_descriptions(argument_collection):
     notes.set_help(u"Notes about the employee.")
 
 
-def get_user_id(sdk, username):
-    """Returns the user's UID (referred to by `user_id` in detection lists). If the user does not 
-    exist, it prints an error and exits.
-    
-    Args:
-        sdk (py42.sdk.SDKClient): The py42 sdk.
-        username (str or unicode): The username of the user to get an ID for.
-    
-    Returns:
-         str: The user ID for the user with the given username.
-    """
-    users = sdk.users.get_by_username(username)[u"users"]
-    if not users:
-        raise UserDoesNotExistError(username)
-    return users[0][u"userUid"]
-
-
 def update_user(sdk, user_id, cloud_alias=None, risk_tag=None, notes=None):
     """Updates a detection list user.
     

src/code42cli/cmds/detectionlists/departing_employee.py

@@ -2,11 +2,11 @@
     DetectionList,
     DetectionListHandlers,
     load_user_descriptions,
-    get_user_id,
     update_user,
     try_handle_user_already_added_error,
     DetectionListSubcommandLoader,
 )
+from code42cli.util import get_user_id
 from code42cli.cmds.detectionlists.enums import DetectionLists
 
 from py42.exceptions import Py42BadRequestError
@@ -48,7 +48,7 @@ def add_departing_employee(
         sdk.detectionlists.departing_employee.add(user_id, departure_date)
         update_user(sdk, user_id, cloud_alias, notes=notes)
     except Py42BadRequestError as err:
-        list_name = DetectionLists.DEPARTING_EMPLOYEE
+        list_name = u"{} list".format(DetectionLists.DEPARTING_EMPLOYEE)
         try_handle_user_already_added_error(err, username, list_name)
         raise
 

src/code42cli/cmds/detectionlists/high_risk_employee.py

@@ -6,14 +6,14 @@
     DetectionList,
     DetectionListHandlers,
     load_user_descriptions,
-    get_user_id,
     update_user,
     try_handle_user_already_added_error,
     add_risk_tags,
     remove_risk_tags,
     load_username_description,
     handle_list_args,
 )
+from code42cli.util import get_user_id
 from code42cli.cmds.detectionlists.enums import DetectionLists, DetectionListUserKeys, RiskTags
 
 
@@ -71,7 +71,7 @@ def add_high_risk_employee(sdk, profile, username, cloud_alias=None, risk_tag=No
         sdk.detectionlists.high_risk_employee.add(user_id)
         update_user(sdk, user_id, cloud_alias, risk_tag, notes)
     except Py42BadRequestError as err:
-        list_name = DetectionLists.HIGH_RISK_EMPLOYEE
+        list_name = u"{} list".format(DetectionLists.HIGH_RISK_EMPLOYEE)
         try_handle_user_already_added_error(err, username, list_name)
         raise
 

src/code42cli/cmds/legal_hold/__init__.py

@@ -0,0 +1,150 @@
+from collections import OrderedDict
+from functools import lru_cache
+from pprint import pprint
+
+from py42.exceptions import Py42ForbiddenError, Py42BadRequestError
+
+
+from code42cli.errors import (
+    UserAlreadyAddedError,
+    UserNotInLegalHoldError,
+    LegalHoldNotFoundOrPermissionDeniedError,
+)
+from code42cli.util import (
+    format_to_table,
+    find_format_width,
+    format_string_list_to_columns,
+    get_user_id,
+)
+from code42cli.bulk import run_bulk_process
+from code42cli.file_readers import create_csv_reader
+from code42cli.logger import get_main_cli_logger
+
+_MATTER_KEYS_MAP = OrderedDict()
+_MATTER_KEYS_MAP[u"legalHoldUid"] = u"Matter ID"
+_MATTER_KEYS_MAP[u"name"] = u"Name"
+_MATTER_KEYS_MAP[u"description"] = u"Description"
+_MATTER_KEYS_MAP[u"creator_username"] = u"Creator"
+_MATTER_KEYS_MAP[u"creationDate"] = u"Creation Date"
+
+logger = get_main_cli_logger()
+
+
+def add_user(sdk, matter_id, username):
+    user_id = get_user_id(sdk, username)
+    matter = _check_matter_is_accessible(sdk, matter_id)
+    try:
+        sdk.legalhold.add_to_matter(user_id, matter_id)
+    except Py42BadRequestError as e:
+        if u"USER_ALREADY_IN_HOLD" in e.response.text:
+            matter_id_and_name_text = u"legal hold matter id={}, name={}".format(
+                matter_id, matter[u"name"]
+            )
+            raise UserAlreadyAddedError(username, matter_id_and_name_text)
+        raise
+
+
+def remove_user(sdk, matter_id, username):
+    _check_matter_is_accessible(sdk, matter_id)
+    membership_id = _get_legal_hold_membership_id_for_user_and_matter(sdk, username, matter_id)
+    sdk.legalhold.remove_from_matter(membership_id)
+
+
+def get_matters(sdk):
+    matters = _get_all_active_matters(sdk)
+    if matters:
+        rows, column_size = find_format_width(matters, _MATTER_KEYS_MAP)
+        format_to_table(rows, column_size)
+
+
+def add_bulk_users(sdk, file_name):
+    reader = create_csv_reader(file_name)
+    run_bulk_process(
+        lambda matter_id, username: add_user(sdk, matter_id, username), reader,
+    )
+
+
+def remove_bulk_users(sdk, file_name):
+    reader = create_csv_reader(file_name)
+    run_bulk_process(
+        lambda matter_id, username: remove_user(sdk, matter_id, username), reader,
+    )
+
+
+def show_matter(sdk, matter_id, include_inactive=False, include_policy=False):
+    matter = _check_matter_is_accessible(sdk, matter_id)
+    matter[u"creator_username"] = matter[u"creator"][u"username"]
+
+    # if `active` is None then all matters (whether active or inactive) are returned. True returns
+    # only those that are active.
+    active = None if include_inactive else True
+    memberships = _get_legal_hold_memberships_for_matter(sdk, matter_id, active=active)
+    active_usernames = [member[u"user"][u"username"] for member in memberships if member[u"active"]]
+    inactive_usernames = [
+        member[u"user"][u"username"] for member in memberships if not member[u"active"]
+    ]
+
+    rows, column_size = find_format_width([matter], _MATTER_KEYS_MAP)
+
+    print(u"")
+    format_to_table(rows, column_size)
+    if active_usernames:
+        print(u"\nActive matter members:\n")
+        format_string_list_to_columns(active_usernames)
+    else:
+        print("\nNo active matter members.\n")
+
+    if include_inactive:
+        if inactive_usernames:
+            print(u"\nInactive matter members:\n")
+            format_string_list_to_columns(inactive_usernames)
+        else:
+            print("No inactive matter members.\n")
+
+    if include_policy:
+        _get_and_print_preservation_policy(sdk, matter[u"holdPolicyUid"])
+        print(u"")
+
+
+def _get_and_print_preservation_policy(sdk, policy_uid):
+    preservation_policy = sdk.legalhold.get_policy_by_uid(policy_uid)
+    print(u"\nPreservation Policy:\n")
+    pprint(preservation_policy._data_root)
+
+
+def _get_legal_hold_membership_id_for_user_and_matter(sdk, username, matter_id):
+    user_id = get_user_id(sdk, username)
+    memberships = _get_legal_hold_memberships_for_matter(sdk, matter_id, active=True)
+    for member in memberships:
+        if member[u"user"][u"userUid"] == user_id:
+            return member[u"legalHoldMembershipUid"]
+    raise UserNotInLegalHoldError(username, matter_id)
+
+
+def _get_legal_hold_memberships_for_matter(sdk, matter_id, active=True):
+    memberships_generator = sdk.legalhold.get_all_matter_custodians(
+        legal_hold_uid=matter_id, active=active
+    )
+    memberships = [
+        member for page in memberships_generator for member in page[u"legalHoldMemberships"]
+    ]
+    return memberships
+
+
+def _get_all_active_matters(sdk):
+    matters_generator = sdk.legalhold.get_all_matters()
+    matters = [
+        matter for page in matters_generator for matter in page[u"legalHolds"] if matter[u"active"]
+    ]
+    for matter in matters:
+        matter[u"creator_username"] = matter[u"creator"][u"username"]
+    return matters
+
+
+@lru_cache(maxsize=None)
+def _check_matter_is_accessible(sdk, matter_id):
+    try:
+        matter = sdk.legalhold.get_matter_by_uid(matter_id)
+        return matter
+    except (Py42BadRequestError, Py42ForbiddenError):
+        raise LegalHoldNotFoundOrPermissionDeniedError(matter_id)