Feature/bulk alert update (#275)

* wip

* Add commands

* CL

* Adjust help message for bulk gen templ

* Make help text generic

* conform help gen messag

* show command inc note

* bump py42

* optimize

* WIP

* test show

* Test update state

* Finish testing

* Correct CL

* add to cl

* Style

* optionally include observations

* rm dup line

* drop s

Author: Juliya Smith

CHANGELOG.md

@@ -12,6 +12,22 @@ how a consumer would use the library (e.g. adding unit tests, updating documenta
 
 ### Added
 
+- New command `code42 alerts show` that displays information about a single alert.
+
+- New command `code42 alerts update` that can update an alert's state or note.
+
+- New command `code42 alerts bulk generate-tempate` for generating CSV templates for bulk
+  commands.
+
+- New command `code42 alerts bulk update` for bulk updating alerts.
+
+### Changed
+
+- `code42 alerts search` now includes the alert ID in its table output.
+
+- `code42 alerts search` table output now refers to the alert state as `state` instead of
+    `status`.
+
 - `code42 cases file-events bulk` with sub-commands:
     - `generate-template`: that creates the file template. And parameters:
         - `cmd`: with options `add` and `remove`.

setup.py

@@ -38,7 +38,7 @@
         "keyring==18.0.1",
         "keyrings.alt==3.2.0",
         "pandas>=1.1.3",
-        "py42>=1.11.1",
+        "py42>=1.14.1",
     ],
     extras_require={
         "dev": [

src/code42cli/cmds/alerts.py

@@ -1,23 +1,29 @@
 import click
 import py42.sdk.queries.alerts.filters as f
 from c42eventextractor.extractors import AlertExtractor
+from py42.exceptions import Py42NotFoundError
 from py42.sdk.queries.alerts.filters import AlertState
 from py42.sdk.queries.alerts.filters import RuleType
 from py42.sdk.queries.alerts.filters import Severity
+from py42.util import format_dict
 
-import code42cli.click_ext.groups
 import code42cli.cmds.search.extraction as ext
 import code42cli.cmds.search.options as searchopt
 import code42cli.errors as errors
 import code42cli.options as opt
+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.search import SendToCommand
 from code42cli.cmds.search.cursor_store import AlertCursorStore
 from code42cli.cmds.search.extraction import handle_no_events
 from code42cli.cmds.search.options import server_options
 from code42cli.date_helper import convert_datetime_to_timestamp
 from code42cli.date_helper import limit_date_range
+from code42cli.file_readers import read_csv_arg
 from code42cli.options import format_option
 from code42cli.output_formats import JsonOutputFormat
+from code42cli.output_formats import OutputFormat
 from code42cli.output_formats import OutputFormatter
 
 
@@ -39,7 +45,7 @@
     callback=searchopt.is_in_filter(f.Severity),
     help="Filter alerts by severity. Defaults to returning all severities.",
 )
-state_option = click.option(
+filter_state_option = click.option(
     "--state",
     multiple=True,
     type=click.Choice(AlertState.choices()),
@@ -134,14 +140,22 @@
     help="The output format of the result. Defaults to json format.",
     default=JsonOutputFormat.RAW,
 )
+alert_id_arg = click.argument("alert-id")
+note_option = click.option("--note", help="A note to attach to the alert.")
+update_state_option = click.option(
+    "--state",
+    help="The state to give to the alert.",
+    type=click.Choice(AlertState.choices()),
+)
 
 
-def _get_search_default_header():
+def _get_default_output_header():
     return {
+        "id": "Id",
         "name": "RuleName",
         "actor": "Username",
         "createdAt": "ObservedDate",
-        "state": "Status",
+        "state": "State",
         "severity": "Severity",
         "description": "Description",
     }
@@ -155,7 +169,7 @@ def search_options(f):
     return f
 
 
-def alert_options(f):
+def filter_options(f):
     f = actor_option(f)
     f = actor_contains_option(f)
     f = exclude_actor_option(f)
@@ -168,11 +182,11 @@ def alert_options(f):
     f = exclude_rule_type_option(f)
     f = description_option(f)
     f = severity_option(f)
-    f = state_option(f)
+    f = filter_state_option(f)
     return f
 
 
-@click.group(cls=code42cli.click_ext.groups.OrderedGroup)
+@click.group(cls=OrderedGroup)
 @opt.sdk_options(hidden=True)
 def alerts(state):
     """Get and send alert data."""
@@ -203,7 +217,7 @@ def _call_extractor(
 
 
 @alerts.command()
-@alert_options
+@filter_options
 @search_options
 @click.option(
     "--or-query", is_flag=True, cls=searchopt.AdvancedQueryAndSavedSearchIncompatible
@@ -225,11 +239,11 @@ def search(
     use_checkpoint,
     or_query,
     include_all,
-    **kwargs
+    **kwargs,
 ):
     """Search for alerts."""
     output_header = ext.try_get_default_header(
-        include_all, _get_search_default_header(), format
+        include_all, _get_default_output_header(), format
     )
     formatter = OutputFormatter(format, output_header)
     cursor = _get_alert_cursor_store(cli_state.profile.name) if use_checkpoint else None
@@ -246,7 +260,7 @@ def search(
 
 
 @alerts.command(cls=SendToCommand)
-@alert_options
+@filter_options
 @search_options
 @click.option(
     "--or-query", is_flag=True, cls=searchopt.AdvancedQueryAndSavedSearchIncompatible
@@ -283,3 +297,87 @@ def _get_alert_extractor(sdk, handlers):
 
 def _get_alert_cursor_store(profile_name):
     return AlertCursorStore(profile_name)
+
+
+@alerts.command()
+@opt.sdk_options()
+@alert_id_arg
+@click.option(
+    "--include-observations", is_flag=True, help="View observations of the alert."
+)
+def show(state, alert_id, include_observations):
+    """Display the details of a single alert."""
+    formatter = OutputFormatter(OutputFormat.TABLE, _get_default_output_header())
+
+    try:
+        response = state.sdk.alerts.get_details(alert_id)
+    except Py42NotFoundError:
+        raise errors.Code42CLIError(f"No alert found with ID '{alert_id}'.")
+
+    alert = response["alerts"][0]
+    formatter.echo_formatted_list([alert])
+
+    # Show note details
+    note = alert.get("note")
+    if note:
+        click.echo("\nNote:\n")
+        click.echo(format_dict(note))
+
+    if include_observations:
+        observations = alert.get("observations")
+        if observations:
+            click.echo("\nObservations:\n")
+            click.echo(format_dict(observations))
+        else:
+            click.echo("\nNo observations found.")
+
+
+@alerts.command()
+@opt.sdk_options()
+@alert_id_arg
+@update_state_option
+@note_option
+def update(cli_state, alert_id, state, note):
+    """Update alert information."""
+    _update_alert(cli_state.sdk, alert_id, state, note)
+
+
+@alerts.group(cls=OrderedGroup)
+@opt.sdk_options(hidden=True)
+def bulk(state):
+    """Tools for executing bulk alert actions."""
+    pass
+
+
+UPDATE_ALERT_CSV_HEADERS = ["id", "state", "note"]
+update_alerts_generate_template = generate_template_cmd_factory(
+    group_name=ALERTS_KEYWORD,
+    commands_dict={"update": UPDATE_ALERT_CSV_HEADERS},
+    help_message="Generate the CSV template needed for bulk alert commands.",
+)
+bulk.add_command(update_alerts_generate_template)
+
+
+@bulk.command(
+    name="update",
+    help=f"Bulk update alerts using a CSV file with format: {','.join(UPDATE_ALERT_CSV_HEADERS)}",
+)
+@opt.sdk_options()
+@read_csv_arg(headers=UPDATE_ALERT_CSV_HEADERS)
+def bulk_update(cli_state, csv_rows):
+    """Bulk update alerts."""
+    sdk = cli_state.sdk
+
+    def handle_row(id, state, note):
+        _update_alert(sdk, id, state, note)
+
+    run_bulk_process(
+        handle_row, csv_rows, progress_label="Updating alerts:",
+    )
+
+
+def _update_alert(sdk, alert_id, alert_state, note):
+    if alert_state:
+        sdk.alerts.update_state(alert_state, [alert_id], note=note)
+    elif note:
+        sdk.alerts.update_note(alert_id, note)