Integ 2887/deprecate v1 apis

CHANGELOG.md

@@ -9,6 +9,28 @@
  how a consumer would use the library or CLI tool (e.g. adding unit tests, updating documentation, etc) are not captured
  here.
 
+## Unreleased
+
+### Added
+
+- `watchlists.v2` methods are added to the SDK, for parity with the API.
+- New CLI watchlist commands `list-excluded-actors` and `list-included-actors` to replace the deprecated `list-excluded-users` and `list-included-users`.
+
+### Updated
+
+- The CLI's `watchlists` commands now use the v2 watchlist API. These commands correctly use `actor_id` instead of `user_id`. While the previous user_id parameters will still work for now, we recommend that users switch as soon as possible to using actor_id instead.
+
+### Fixed
+
+- A bug where the api endpoint used to download audit log events was incorrect.
+
+### Deprecated
+
+- Devices methods in the SDK and CLI are deprecated. Use the Agents methods instead.
+- Risk Profiles methods in the SDK and CLI, already deprecated, are more clearly marked.
+- The SDK's `watchlists.v1` methods are deprecated.
+- The CLI's watchlist group `list-excluded-users` and `list-included-users` commands are deprecated. Use `list-excluded-actors` and `list-included-actors` instead.
+
 ## 2.2.4 - 2025-03-11
 
 ### Added

docs/cli/index.md

@@ -28,15 +28,18 @@ The following subcommand groups are available under the `incydr` command:
 * [Actors](cmds/actors.md)
 * [Agents](cmds/agents.md)
 * [Alert Rules](cmds/alert_rules.md)
-* [Alerts (Deprecated)](cmds/alerts.md)
 * [Audit Log](cmds/audit_log.md)
 * [Cases](cmds/cases.md)
 * [Departments](cmds/departments.md)
-* [Devices](cmds/devices.md)
 * [Directory Groups](cmds/directory_groups.md)
 * [File Events](cmds/file_events.md)
-* [Risk Profiles](cmds/risk_profiles.md)
 * [Sessions](cmds/sessions.md)
 * [Trusted Activities](cmds/trusted_activities.md)
 * [Users](cmds/users.md)
 * [Watchlists](cmds/watchlists.md)
+
+Deprecated command groups:
+
+* [Alerts (Deprecated)](cmds/alerts.md)
+* [Devices (Deprecated)](cmds/devices.md)
+* [Risk Profiles (Deprecated)](cmds/risk_profiles.md)

docs/sdk/clients/devices.md

@@ -1,4 +1,4 @@
-# Devices
+# Devices (Deprecated)
 
 ::: _incydr_sdk.devices.client.DevicesV1
     :docstring:

docs/sdk/clients/risk_profiles.md

@@ -1,4 +1,4 @@
-# Risk Profiles
+# Risk Profiles (Deprecated)
 
 ::: _incydr_sdk.risk_profiles.client.RiskProfilesV1
     :docstring:

docs/sdk/clients/watchlists.md

@@ -1,5 +1,9 @@
 # Watchlists
 
+::: _incydr_sdk.watchlists.client.WatchlistsV2
+    :docstring:
+    :members:
+
 ::: _incydr_sdk.watchlists.client.WatchlistsV1
     :docstring:
     :members:

docs/sdk/enums.md

@@ -124,7 +124,9 @@ Alerts has been replaced by [Sessions](#sessions).
 * **CLOSED**: `"CLOSED"`
 * **OPEN**: `"OPEN"`
 
-## Devices
+## Devices (Deprecated)
+
+Devices has been replaced by [Agents](#agents)
 
 ### Devices Sort Keys
 

docs/sdk/models.md

@@ -124,7 +124,10 @@ Alerts has been replaced by [Sessions](#sessions).
 ::: incydr.models.DepartmentsPage
     :docstring:
 
-## Devices
+## Devices (Deprecated)
+
+Devices has been replaced by [Agents](#agents).
+
 ---
 
 ### `Device` model
@@ -220,7 +223,10 @@ Alerts has been replaced by [Sessions](#sessions).
 :::incydr.models.Role
     :docstring:
 
-## Risk Profiles
+## Risk Profiles (Deprecated)
+
+Risk Profiles have been replaced by [Actors](#actors).
+
 ---
 
 ### `RiskProfile` model
@@ -246,23 +252,51 @@ Alerts has been replaced by [Sessions](#sessions).
 ::: incydr.models.WatchlistsPage
     :docstring:
 
+### `WatchlistActor` model
+
+::: incydr.models.WatchlistActor
+    :docstring:
+
 ### `WatchlistUser` model
 
+WatchlistUser is deprecated. Use WatchlistActor instead.
+
 ::: incydr.models.WatchlistUser
     :docstring:
 
+### `WatchlistMembersListV2` model
+
+::: incydr.models.WatchlistMembersListV2
+    :docstring:
+
 ### `WatchlistMembersList` model
 
+WatchlistMembersList is deprecated. Use WatchlistMembersListV2 instead.
+
 ::: incydr.models.WatchlistMembersList
     :docstring:
 
+### `IncludedActorsList` model
+
+::: incydr.models.IncludedActorsList
+    :docstring:
+
+### `ExcludedActorsList` model
+
+::: incydr.models.ExcludedActorsList
+    :docstring:
+
 ### `IncludedUsersList` model
 
+IncludedUsersList is deprecated. Use IncludedActorsList instead.
+
 ::: incydr.models.IncludedUsersList
     :docstring:
 
 ### `ExcludedUsersList` model
 
+ExcludedUsersList is deprecated. Use ExcludedActorsList instead.
+
 ::: incydr.models.ExcludedUsersList
     :docstring:
 

mkdocs.yml

@@ -43,22 +43,22 @@ nav:
     - Reference:
       - Actors: 'sdk/clients/actors.md'
       - Agents: 'sdk/clients/agents.md'
-      - Alerts (Deprecated): 'sdk/clients/alerts.md'
       - Alert Rules: 'sdk/clients/alert_rules.md'
       - Alert Querying: 'sdk/clients/alert_queries.md'
       - Audit Log: 'sdk/clients/audit_log.md'
       - Cases: 'sdk/clients/cases.md'
       - Customer: 'sdk/clients/customer.md'
       - Departments: 'sdk/clients/departments.md'
-      - Devices: 'sdk/clients/devices.md'
       - Directory Groups: 'sdk/clients/directory_groups.md'
       - File Events: 'sdk/clients/file_events.md'
       - File Event Querying: 'sdk/clients/file_event_queries.md'
-      - Risk Profiles: 'sdk/clients/risk_profiles.md'
       - Sessions: 'sdk/clients/sessions.md'
       - Trusted Activites: 'sdk/clients/trusted_activities.md'
       - Users: 'sdk/clients/users.md'
       - Watchlists: 'sdk/clients/watchlists.md'
+      - Alerts (Deprecated): 'sdk/clients/alerts.md'
+      - Devices (Deprecated): 'sdk/clients/devices.md'
+      - Risk Profiles (Deprecated): 'sdk/clients/risk_profiles.md'
     - Enums: 'sdk/enums.md'
     - Models: 'sdk/models.md'
   - CLI:
@@ -71,19 +71,19 @@ nav:
       - Commands:
         - Actors: 'cli/cmds/actors.md'
         - Agents: 'cli/cmds/agents.md'
-        - Alerts (Deprecated): 'cli/cmds/alerts.md'
         - Alert Rules: 'cli/cmds/alert_rules.md'
         - Audit Log: 'cli/cmds/audit_log.md'
         - Cases: 'cli/cmds/cases.md'
         - Departments: 'cli/cmds/departments.md'
-        - Devices: 'cli/cmds/devices.md'
         - Directory Groups: 'cli/cmds/directory_groups.md'
         - File Events: 'cli/cmds/file_events.md'
-        - Risk Profiles: 'cli/cmds/risk_profiles.md'
         - Sessions: 'cli/cmds/sessions.md'
         - Trusted Activites: 'cli/cmds/trusted_activities.md'
         - Users: 'cli/cmds/users.md'
         - Watchlists: 'cli/cmds/watchlists.md'
+        - Alerts (Deprecated): 'cli/cmds/alerts.md'
+        - Devices (Deprecated): 'cli/cmds/devices.md'
+        - Risk Profiles (Deprecated): 'cli/cmds/risk_profiles.md'
   - Guides:
       - Introduction: 'integration-guides/index.md'
       - Microsoft Sentinel:

src/_incydr_cli/cmds/alerts.py

@@ -47,7 +47,7 @@
 @click.group(cls=IncydrGroup)
 @logging_options
 def alerts():
-    """View and manage alerts."""
+    """DEPRECATED. Use the Sessions command group instead. View and manage alerts."""
     deprecation_warning(DEPRECATION_TEXT)
 
 

src/_incydr_cli/cmds/devices.py

@@ -9,17 +9,23 @@
 from _incydr_cli.cmds.options.output_options import SingleFormat
 from _incydr_cli.cmds.options.output_options import table_format_option
 from _incydr_cli.cmds.options.output_options import TableFormat
+from _incydr_cli.cmds.utils import deprecation_warning
 from _incydr_cli.core import IncydrCommand
 from _incydr_cli.core import IncydrGroup
 from _incydr_sdk.core.client import Client
 from _incydr_sdk.devices.models import Device
 from _incydr_sdk.utils import model_as_card
 
 
+# Deprecated 2025-03
+DEPRECATION_TEXT = "DeprecationWarning: Devices commands are deprecated. Use the 'incydr agents' command group instead."
+
+
 @click.group(cls=IncydrGroup)
 @logging_options
 def devices():
-    """View devices."""
+    """DEPRECATED. Use the agents command group instead. View devices."""
+    deprecation_warning(DEPRECATION_TEXT)
 
 
 @devices.command("list", cls=IncydrCommand)

src/_incydr_cli/cmds/options/utils.py

@@ -1,5 +1,6 @@
 import click
 
+from _incydr_cli.cmds.utils import actor_lookup
 from _incydr_cli.cmds.utils import user_lookup
 from _incydr_sdk.core.client import Client
 
@@ -21,3 +22,12 @@ def user_lookup_callback(ctx, param, value):
     if "@" in str(value):
         return user_lookup(Client(), value)
     return value
+
+
+def actor_lookup_callback(ctx, param, value):
+    if not value:
+        return
+    # only call user_lookup if username to prevent unnecessary client inits with obj()
+    if "@" in str(value):
+        return actor_lookup(Client(), value)
+    return value

src/_incydr_cli/cmds/risk_profiles.py

@@ -29,7 +29,7 @@
 @click.group(cls=IncydrGroup)
 @logging_options
 def risk_profiles():
-    """View and manage risk profiles."""
+    """DEPRECATED. Use the Actors command group instead. View and manage risk profiles."""
     deprecation_warning(DEPRECATION_TEXT)
 
 

src/_incydr_cli/cmds/utils.py

@@ -8,6 +8,8 @@
 from click import echo
 from click import style
 
+from _incydr_sdk.actors.client import ActorNotFoundError
+
 
 def deprecation_warning(text):
     echo(style(text, fg="red"), err=True)
@@ -29,6 +31,22 @@ def user_lookup(client, value):
     return value
 
 
+def actor_lookup(client, value):
+    """
+    Returns the actor ID for a given actor name, or returns the value unchanged if not a username.
+
+    Used with the `actor_lookup_callback` method on user args.
+    """
+    if "@" in str(value):
+        # assume username/email was passed
+        try:
+            return client.actors.v1.get_actor_by_name(value).actor_id
+        except ActorNotFoundError:
+            raise ValueError(f"User with username '{value}' not found.")
+        # else return ID
+    return value
+
+
 class warn_interrupt:
     """A context decorator class used to wrap functions where a keyboard interrupt could potentially
     leave things in a bad state. Warns the user with provided message and exits when wrapped