Feature/advanced query from file (#161)

* add workflow

* style fix

* point cla action to code42-cla repo

* Add CLA note to contributing guide

* style

* style2

* update changelog

* note checkpoint update in changelog

* style

* make filename argument require `@` prefix

* reword build query exception

Author: timabrmsn

CHANGELOG.md

@@ -12,6 +12,10 @@ how a consumer would use the library (e.g. adding unit tests, updating documenta
 
 ### Changed
 
+- The `--advanced-query` option on `alerts search` and `security-data (search|send-to)` commands has been updated:
+    - It can now accept the query as a JSON string or as the path to a file containing the JSON query.
+    - It can be used with the `--use-checkpoint/-c` option.
+
 - 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.
 

src/code42cli/click_ext/__init__.py

@@ -0,0 +1,110 @@
+import difflib
+import re
+from collections import OrderedDict
+
+import click
+from py42.exceptions import Py42ForbiddenError
+from py42.exceptions import Py42HTTPError
+from py42.exceptions import Py42InvalidRuleOperationError
+from py42.exceptions import Py42LegalHoldNotFoundOrPermissionDeniedError
+from py42.exceptions import Py42UserAlreadyAddedError
+
+from code42cli.errors import Code42CLIError
+from code42cli.errors import LoggedCLIError
+from code42cli.errors import UserDoesNotExistError
+from code42cli.logger import get_main_cli_logger
+
+_DIFFLIB_CUT_OFF = 0.6
+
+
+class ExceptionHandlingGroup(click.Group):
+    """A `click.Group` subclass to add custom exception handling."""
+
+    logger = get_main_cli_logger()
+    _original_args = None
+
+    def make_context(self, info_name, args, parent=None, **extra):
+
+        # grab the original command line arguments for logging purposes
+        self._original_args = " ".join(args)
+
+        return super().make_context(info_name, args, parent=parent, **extra)
+
+    def invoke(self, ctx):
+        try:
+            return super().invoke(ctx)
+
+        except click.UsageError as err:
+            self._suggest_cmd(err)
+
+        except LoggedCLIError:
+            raise
+
+        except Code42CLIError as err:
+            self.logger.log_error(str(err))
+            raise
+
+        except click.ClickException:
+            raise
+
+        except click.exceptions.Exit:
+            raise
+
+        except (
+            UserDoesNotExistError,
+            Py42UserAlreadyAddedError,
+            Py42InvalidRuleOperationError,
+            Py42LegalHoldNotFoundOrPermissionDeniedError,
+        ) as err:
+            self.logger.log_error(err)
+            raise Code42CLIError(str(err))
+
+        except Py42ForbiddenError as err:
+            self.logger.log_verbose_error(self._original_args, err.response.request)
+            raise LoggedCLIError(
+                "You do not have the necessary permissions to perform this task. "
+                "Try using or creating a different profile."
+            )
+
+        except Py42HTTPError as err:
+            self.logger.log_verbose_error(self._original_args, err.response.request)
+            raise LoggedCLIError("Problem making request to server.")
+
+        except OSError:
+            raise
+
+        except Exception:
+            self.logger.log_verbose_error()
+            raise LoggedCLIError("Unknown problem occurred.")
+
+    @staticmethod
+    def _suggest_cmd(usage_err):
+        """Handles fuzzy suggestion of commands that are close to the bad command entered."""
+        if usage_err.message is not None:
+            match = re.match("No such command '(.*)'.", usage_err.message)
+            if match:
+                bad_arg = match.groups()[0]
+                available_commands = list(usage_err.ctx.command.commands.keys())
+                suggested_commands = difflib.get_close_matches(
+                    bad_arg, available_commands, cutoff=_DIFFLIB_CUT_OFF
+                )
+                if not suggested_commands:
+                    raise usage_err
+                usage_err.message = "No such command '{}'. Did you mean {}?".format(
+                    bad_arg, " or ".join(suggested_commands)
+                )
+        raise usage_err
+
+
+class OrderedGroup(click.Group):
+    """A `click.Group` subclass that uses an `OrderedDict` to store commands so the help text lists
+    them in the order they were defined/added to the group.
+    """
+
+    def __init__(self, name=None, commands=None, **attrs):
+        super().__init__(name, commands, **attrs)
+        # the registered subcommands by their exported names.
+        self.commands = commands or OrderedDict()
+
+    def list_commands(self, ctx):
+        return self.commands

src/code42cli/click_ext/groups.py

@@ -0,0 +1,36 @@
+import click
+
+
+def incompatible_with(incompatible_opts):
+    """Factory for creating custom `click.Option` subclasses that enforce incompatibility with the
+    option strings passed to this function.
+    """
+
+    if isinstance(incompatible_opts, str):
+        incompatible_opts = [incompatible_opts]
+
+    class IncompatibleOption(click.Option):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+
+        def handle_parse_result(self, ctx, opts, args):
+            # if None it means we're in autocomplete mode and don't want to validate
+            if ctx.obj is not None:
+                found_incompatible = ", ".join(
+                    [
+                        "--{}".format(opt.replace("_", "-"))
+                        for opt in opts
+                        if opt in incompatible_opts
+                    ]
+                )
+                if self.name in opts and found_incompatible:
+                    name = self.name.replace("_", "-")
+                    raise click.BadOptionUsage(
+                        option_name=self.name,
+                        message="--{} can't be used with: {}".format(
+                            name, found_incompatible
+                        ),
+                    )
+            return super().handle_parse_result(ctx, opts, args)
+
+    return IncompatibleOption

src/code42cli/click_ext/options.py

@@ -0,0 +1,18 @@
+import click
+
+
+class FileOrString(click.File):
+    """Declares a parameter to be a file (if the argument begins with `@`), otherwise accepts it as
+    a string.
+    """
+
+    def __init__(self):
+        super().__init__("r")
+
+    def convert(self, value, param, ctx):
+        if value.startswith("@") or value == "-":
+            value = value.lstrip("@")
+            file = super().convert(value, param, ctx)
+            return file.read()
+        else:
+            return value

src/code42cli/click_ext/types.py

@@ -8,11 +8,11 @@
 from code42cli import PRODUCT_NAME
 from code42cli.bulk import generate_template_cmd_factory
 from code42cli.bulk import run_bulk_process
+from code42cli.click_ext.groups import OrderedGroup
 from code42cli.cmds.shared import get_user_id
 from code42cli.errors import Code42CLIError
 from code42cli.file_readers import read_csv_arg
 from code42cli.options import format_option
-from code42cli.options import OrderedGroup
 from code42cli.options import sdk_options
 from code42cli.output_formats import OutputFormatter
 

src/code42cli/cmds/alert_rules.py

@@ -7,6 +7,7 @@
 from py42.sdk.queries.alerts.filters import RuleType
 from py42.sdk.queries.alerts.filters import Severity
 
+import code42cli.click_ext.groups
 import code42cli.cmds.search.extraction as ext
 import code42cli.cmds.search.options as searchopt
 import code42cli.errors as errors
@@ -155,7 +156,7 @@ def alert_options(f):
     return f
 
 
-@click.group(cls=opt.OrderedGroup)
+@click.group(cls=code42cli.click_ext.groups.OrderedGroup)
 @opt.sdk_options(hidden=True)
 def alerts(state):
     """Tools for getting alert data."""
@@ -177,13 +178,12 @@ def _call_extractor(
     extractor = _get_alert_extractor(cli_state.sdk, handlers)
     extractor.use_or_query = or_query
     if advanced_query:
-        extractor.extract_advanced(advanced_query)
-    else:
-        if begin or end:
-            cli_state.search_filters.append(
-                ext.create_time_range_filter(f.DateObserved, begin, end)
-            )
-        extractor.extract(*cli_state.search_filters)
+        cli_state.search_filters = advanced_query
+    if begin or end:
+        cli_state.search_filters.append(
+            ext.create_time_range_filter(f.DateObserved, begin, end)
+        )
+    extractor.extract(*cli_state.search_filters)
 
 
 @alerts.command()

src/code42cli/cmds/alerts.py

@@ -3,6 +3,7 @@
 
 from code42cli.bulk import generate_template_cmd_factory
 from code42cli.bulk import run_bulk_process
+from code42cli.click_ext.groups import OrderedGroup
 from code42cli.cmds.detectionlists import update_user
 from code42cli.cmds.detectionlists.options import cloud_alias_option
 from code42cli.cmds.detectionlists.options import notes_option
@@ -11,7 +12,6 @@
 from code42cli.errors import Code42CLIError
 from code42cli.file_readers import read_csv_arg
 from code42cli.file_readers import read_flat_file_arg
-from code42cli.options import OrderedGroup
 from code42cli.options import sdk_options
 
 

src/code42cli/cmds/departing_employee.py

@@ -4,6 +4,7 @@
 
 from code42cli.bulk import generate_template_cmd_factory
 from code42cli.bulk import run_bulk_process
+from code42cli.click_ext.groups import OrderedGroup
 from code42cli.cmds.detectionlists import add_risk_tags as _add_risk_tags
 from code42cli.cmds.detectionlists import handle_list_args
 from code42cli.cmds.detectionlists import remove_risk_tags as _remove_risk_tags
@@ -15,7 +16,6 @@
 from code42cli.errors import Code42CLIError
 from code42cli.file_readers import read_csv_arg
 from code42cli.file_readers import read_flat_file_arg
-from code42cli.options import OrderedGroup
 from code42cli.options import sdk_options
 
 risk_tag_option = click.option(

src/code42cli/cmds/high_risk_employee.py

@@ -8,11 +8,11 @@
 
 from code42cli.bulk import generate_template_cmd_factory
 from code42cli.bulk import run_bulk_process
+from code42cli.click_ext.groups import OrderedGroup
 from code42cli.cmds.shared import get_user_id
 from code42cli.errors import UserNotInLegalHoldError
 from code42cli.file_readers import read_csv_arg
 from code42cli.options import format_option
-from code42cli.options import OrderedGroup
 from code42cli.options import sdk_options
 from code42cli.output_formats import OutputFormat
 from code42cli.output_formats import OutputFormatter