Chore/ix feedback (#86)

* address devices IX feedback * address securitydata IX feedback * address file event query IX feedback * nest Filter Classes under File Event Queries header * address archive client IX feedback * address response/exceptions IX feedback * split Response and Exceptions into their own pages * address util IX feedback * util tweak * add direct links to userguides for alerts search and file events search * oops we missed including AlertQuery and Alert filters in the methoddocs * change cloud alias api * change cloud alias api on module * address detectionlists IX feedback * ID > identification number * more IDs > identification numbers * a n * capitalize HRE * indentation * stub tests * indentation * add endpoint clarification for FED events. * fix detectionlists module * detectionlist updates * a touch more legacy Co-authored-by: Alan Grgic <alan.grgic@code42.com>
code42 · Apr 21, 2020 · e6eefde · e6eefde
1 parent 8e2fb9e
commit e6eefde
Show file tree

Hide file tree

Showing 23 changed files with 244 additions and 177 deletions.
diff --git a/docs/methoddocs/alerts.md b/docs/methoddocs/alerts.md
@@ -5,3 +5,60 @@
     :members:
     :show-inheritance:
 ```
+
+```eval_rst
+.. autoclass:: py42.sdk.queries.alerts.alert_query.AlertQuery
+    :members:
+    :show-inheritance:
+```
+
+## Filter Classes
+
+The following classes construct filters for file event queries. Each filter class corresponds to an alert detail.
+Call the appropriate classmethod on your desired filter class with the `value` you want to match and it will return a
+`FilterGroup` object that can be passed to `AlertQuery`'s `all()` or `any()` methods to create complex queries
+that match multiple filter rules.
+
+See [Executing Searches](../userguides/searches.md) for more on building search queries.
+
+```eval_rst
+.. autoclass:: py42.sdk.queries.alerts.filters.alert_filter.DateObserved
+    :members:
+    :inherited-members:
+    :show-inheritance:
+```
+
+```eval_rst
+.. autoclass:: py42.sdk.queries.alerts.filters.alert_filter.Actor
+    :members:
+    :inherited-members:
+    :show-inheritance:
+```
+
+```eval_rst
+.. autoclass:: py42.sdk.queries.alerts.filters.alert_filter.RuleName
+    :members:
+    :inherited-members:
+    :show-inheritance:
+```
+
+```eval_rst
+.. autoclass:: py42.sdk.queries.alerts.filters.alert_filter.Description
+    :members:
+    :inherited-members:
+    :show-inheritance:
+```
+
+```eval_rst
+.. autoclass:: py42.sdk.queries.alerts.filters.alert_filter.Severity
+    :members:
+    :inherited-members:
+    :show-inheritance:
+```
+
+```eval_rst
+.. autoclass:: py42.sdk.queries.alerts.filters.alert_filter.AlertState
+    :members:
+    :inherited-members:
+    :show-inheritance:
+```
diff --git a/docs/methoddocs/detectionlists.md b/docs/methoddocs/detectionlists.md
@@ -6,7 +6,7 @@
     :show-inheritance:
 ```
 
-## Departing Employee
+## Departing Employees
 
 ```eval_rst
 .. autoclass:: py42.clients.detectionlists.departing_employee.DepartingEmployeeClient

diff --git a/docs/methoddocs/exceptions.md b/docs/methoddocs/exceptions.md
@@ -0,0 +1,8 @@
+# Exceptions
+
+```eval_rst
+.. automodule:: py42.exceptions
+    :members:
+    :show-inheritance:
+
+```
diff --git a/docs/methoddocs/filleeventqueries.md b/docs/methoddocs/filleeventqueries.md
@@ -12,25 +12,25 @@
     :show-inheritance:
 ```
 
-# Filter Classes
+## Filter Classes
 
-The following classes construct filters for Forensic Search queries. Each filter class corresponds to a Forensic Search
-event detail. Call the appropriate classmethod on your desired filter class with the `value` you want to match and it
-will return a `FilterGroup` object that can be passed to `FileEventQuery`'s `all()` or `any()` methods to create complex
-queries that match multiple filter rules.
+The following classes construct filters for file event queries. Each filter class corresponds to a file event detail.
+Call the appropriate classmethod on your desired filter class with the `value` you want to match and it will return a
+`FilterGroup` object that can be passed to `FileEventQuery`'s `all()` or `any()` methods to create complex queries
+that match multiple filter rules.
 
 Example:
 
-To search for events concerning a certain set of documents, you can use the `FileName` and `MD5` filter classes to
+To search for events observed for certain set of documents, you can use the `FileName` and `MD5` filter classes to
 construct `FilterGroup`s that will search for matching filenames or (in case someone renamed the sensitive file) the
 known MD5 hashes of the files:
 
     filename_filter = FileName.is_in(['confidential_plans.docx', 'confidential_plan_projections.xlsx'])
     md5_filter = MD5.is_in(['133765f4fff5e3038b9352a4d14e1532', 'ea16f0cbfc76f6eba292871f8a8c794b'])
 
-See [Executing Searches](../userguides/searches.md) for more on crafting search queries.
+See [Executing Searches](../userguides/searches.md) for more on building search queries.
 
-## Event Filters
+### Event Filters
 
 ```eval_rst
 .. autoclass:: py42.sdk.queries.fileevents.filters.event_filter.EventTimestamp
@@ -60,7 +60,7 @@ See [Executing Searches](../userguides/searches.md) for more on crafting search
     :show-inheritance:
 ```
 
-## File Filters
+### File Filters
 
 ```eval_rst
 .. autoclass:: py42.sdk.queries.fileevents.filters.file_filter.FileCategory
@@ -111,7 +111,7 @@ See [Executing Searches](../userguides/searches.md) for more on crafting search
     :show-inheritance:
 ```
 
-## Device Filters
+### Device Filters
 
 ```eval_rst
 .. autoclass:: py42.sdk.queries.fileevents.filters.device_filter.DeviceUsername
@@ -141,7 +141,7 @@ See [Executing Searches](../userguides/searches.md) for more on crafting search
     :show-inheritance:
 ```
 
-## Cloud Filters
+### Cloud Filters
 
 ```eval_rst
 .. autoclass:: py42.sdk.queries.fileevents.filters.cloud_filter.Actor
@@ -178,7 +178,7 @@ See [Executing Searches](../userguides/searches.md) for more on crafting search
     :show-inheritance:
 ```
 
-## Exposure Filters
+### Exposure Filters
 
 ```eval_rst
 .. autoclass:: py42.sdk.queries.fileevents.filters.exposure_filter.ExposureType
@@ -264,7 +264,7 @@ See [Executing Searches](../userguides/searches.md) for more on crafting search
     :show-inheritance:
 ```
 
-## Email Filters
+### Email Filters
 
 ```eval_rst
 .. autoclass:: py42.sdk.queries.fileevents.filters.email_filter.EmailPolicyName

diff --git a/docs/methoddocs/response.md b/docs/methoddocs/response.md
@@ -5,12 +5,3 @@
     :members:
     :show-inheritance:
 ```
-
-# Exceptions
-
-```eval_rst
-.. automodule:: py42.exceptions
-    :members:
-    :show-inheritance:
-
-```
diff --git a/docs/methods.md b/docs/methods.md
@@ -28,6 +28,7 @@ Explore the complete public documentation for `py42` below.
 * [File Event Queries](methoddocs/filleeventqueries.md)
 * [Archive](methoddocs/archive.md)
 * [Response](methoddocs/response.md)
+* [Exceptions](methoddocs/exceptions.md)
 * [Util](methoddocs/util.md)
 
 ```eval_rst

diff --git a/docs/userguides/searches.md b/docs/userguides/searches.md
@@ -3,6 +3,9 @@
 py42 features a powerful, flexible query system for quickly and easily searching file events and alerts.
 This guide explains the syntax for building queries and executing searches.
 
+```eval_rst
+.. _anchor_search_file_events:
+```
 ## Search File Events
 
 First, import the required modules and classes and create the SDK:
@@ -68,9 +71,12 @@ for event in file_events:
     print(event["md5Checksum"])
 ```
 
+```eval_rst
+.. _anchor_search_alerts:
+```
 ## Search Alerts
 
-Alert searches work in a very similar way to file event searches. 
+Alert searches work in a very similar way to file event searches.
 
 To start, import the filters and query object:
 

diff --git a/src/py42/clients/alerts.py b/src/py42/clients/alerts.py
@@ -22,7 +22,8 @@ def search(self, query):
 
         Args:
             query (:class:`py42.sdk.queries.alerts.alert_query.AlertQuery`): An alert query.
-                See `userguides.searches` to learn more about how to construct a query.
+                See the :ref:`Executing Searches User Guide <anchor_search_alerts>` to learn more
+                about how to construct a query.
 
         Returns:
             :class:`py42.response.Py42Response`: A response containing the alerts that match the given
@@ -37,8 +38,9 @@ def get_details(self, alert_ids, tenant_id=None):
         when passed into a search, would result in events that could have triggered the alerts.
 
         Args:
-            alert_ids (iter[str]): The IDs of the alerts for which you want to get details for.
-            tenant_id (str, optional): The tenant ID for the tenant that the alerts belong to.
+            alert_ids (iter[str]): The identification numbers of the alerts for which you want to
+                get details for.
+            tenant_id (str, optional): The unique identifier of the tenant that the alerts belong to.
                 When given None, it uses the currently logged in user's tenant ID. Defaults to
                 None.
 
@@ -56,9 +58,9 @@ def resolve(self, alert_ids, tenant_id=None, reason=None):
         """Resolves the alerts with the given IDs.
 
         Args:
-            alert_ids (iter[str]): The IDs for the alerts to resolve.
-            tenant_id (str, optional): The ID for the tenant that the alerts belong to.
-                When given None, it uses the currently logged in user's tenant ID. Defaults to
+            alert_ids (iter[str]): The identification numbers for the alerts to resolve.
+            tenant_id (str, optional): The unique identifier for the tenant that the alerts belong
+                to. When given None, it uses the currently logged in user's tenant ID. Defaults to
                 None.
             reason (str, optional): The reason the alerts are now resolved. Defaults to None.
 
@@ -77,9 +79,10 @@ def reopen(self, alert_ids, tenant_id=None, reason=None):
         """Reopens the resolved alerts with the given IDs.
 
         Args:
-            alert_ids (iter[str]): The IDs for the alerts to reopen.
-            tenant_id (str, optional): The ID for the tenant that the alerts belong to. When given
-                None, it uses the currently logged in user's tenant ID. Defaults to None.
+            alert_ids (iter[str]): The identification numbers for the alerts to reopen.
+            tenant_id (str, optional): The unique identifier for the tenant that the alerts belong
+                to. When given None, it uses the currently logged in user's tenant ID. Defaults to
+                None.
             reason (str, optional): The reason the alerts are reopened. Defaults to None.
 
         Returns:

diff --git a/src/py42/clients/detectionlists/departing_employee.py b/src/py42/clients/detectionlists/departing_employee.py
@@ -15,13 +15,17 @@ def __init__(self, session, user_context, detection_list_user_client):
         self._detection_list_user_client = detection_list_user_client
 
     def add(self, user_id, departure_date):
-        """Adds a user to Departing Employees, creates the detection list profile if it doesn't
-        exist before adding.
+        """Adds a user to the Departing Employees list. Creates a detection list user profile if one
+         didn't already exist.
         `REST Documentation <https://ecm-east.us.code42.com/svc/swagger/index.html?urls.primaryName=v2#/>`__
 
+        Raises a :class:`Py42BadRequestError` when a user already exists in the Departing Employee
+        detection list.
+
         Args:
-            user_id (str or int): The Code42 userUid of the user, to be added to departing employee.
-            departure_date (date): Date in YYYY-MM-DD format
+            user_id (str or int): The Code42 userUid of the user you want to add to the departing
+                employees list.
+            departure_date (date): Date in YYYY-MM-DD format. Date is treated as UTC.
 
         Returns:
             :class:`py42.response.Py42Response`
@@ -49,7 +53,7 @@ def get(self, user_id):
         return self._session.post(uri, data=json.dumps(data))
 
     def remove(self, user_id):
-        """Removes a user from Departing Employees.
+        """Removes a user from the Departing Employees list.
         `REST Documentation <https://ecm-east.us.code42.com/svc/swagger/index.html?urls.primaryName=v2#/>`__
 
         Args:
@@ -116,8 +120,8 @@ def set_alerts_enabled(self, alerts_enabled=True):
         `REST Documentation <https://ecm-east.us.code42.com/svc/swagger/index.html?urls.primaryName=v2#/>`__
 
         Args:
-            tenant_id (str, optional): The identifier of the Customer tenant. Defaults to None (the
-                tenant_id of SDK authorization user will be used).
+            tenant_id (str, optional): The unique identifier of the customer tenant. Defaults to
+                None (the tenant_id of SDK authorization user will be used).
             alerts_enabled (bool): Set alerting to on (True) or off (False). Defaults to True.
 
         Returns:
@@ -136,7 +140,7 @@ def update_departure_date(
 
         Args:
             user_id (str): The Code42 userUid of the user.
-            departure_date (date): Date in YYYY-MM-DD format.
+            departure_date (date): Date in YYYY-MM-DD format. Date is treated as UTC.
 
         Returns:
             :class:`py42.sdk.response.Py42Response`

diff --git a/src/py42/clients/detectionlists/high_risk_employee.py b/src/py42/clients/detectionlists/high_risk_employee.py
@@ -6,11 +6,7 @@
 
 
 class HighRiskEmployeeClient(BaseClient):
-    """Administrator utility to manage High Risk employees.
-
-    `Support Documentation <https://support.code42.com/Administrator/Cloud/Monitoring_and_managing/Detection_list_management_APIs>`__
-
-    """
+    """A client for interacting with High Risk Employee APIs."""
 
     _api_version = u"v2"
     _uri_prefix = u"/svc/api/{0}".format(_api_version)
@@ -31,15 +27,15 @@ def _add_high_risk_employee(self, tenant_id, user_id):
         return self._session.post(uri, data=json.dumps(data))
 
     def add(self, user_id):
-        """Adds a user to high risk employee detection list.
-
-        A user profile in detection list will be created before adding to High Risk Employee
-        list if it doesn't exist.
+        """Adds a user to the High Risk Employee detection list. Creates a detection list user
+        profile if one didn't already exist.
 
-        Returns failure when a user already exists in the high risk employee detection list.
+        Raises a :class:`Py42BadRequestError` when a user already exists in the High Risk Employee
+        detection list.
 
         Args:
-            user_id (str or int): The Code42 userUid of the user who needs to be added to HRE detection list.
+            user_id (str or int): The Code42 userUid of the user you want to add to the High Risk
+                Employee detection list.
 
         Returns:
             :class:`py42.response.Py42Response`
@@ -52,7 +48,7 @@ def set_alerts_enabled(self, enabled=True):
         """Enable alerts.
 
         Args:
-            enabled (bool): Whether to enable alerts for all users
+            enabled (bool): Whether to enable alerts for all users.
 
         Returns:
             :class:`py42.response.Py42Response`
@@ -62,10 +58,11 @@ def set_alerts_enabled(self, enabled=True):
         return self._session.post(uri, data=json.dumps(data))
 
     def remove(self, user_id):
-        """Remove a user from high risk employee detection list.
+        """Remove a user from the High Risk Employee detection list.
 
         Args:
-            user_id (str or int): The Code42 userUid of the user who needs to be added to HRE detection lists.
+            user_id (str or int): The Code42 userUid of the user you want to add to the High Risk
+                Employee detection list.
 
         Returns:
             :class:`py42.response.Py42Response`
@@ -78,8 +75,8 @@ def get(self, user_id):
         """Get user information.
 
         Args:
-            user_id (str or int): The Code42 userUid of the user has been added to the High Risk Employee
-              detection list.
+            user_id (str or int): The Code42 userUid of the user has been added to the High Risk
+                Employee detection list.
 
         Returns:
             :class:`py42.response.Py42Response`
@@ -112,12 +109,12 @@ def _get_high_risk_employees_page(
         return self._session.post(uri, data=json.dumps(data))
 
     def get_all(self, filter_type=u"OPEN", sort_key=None, sort_direction=None):
-        """Search High Risk employee list. Filter results by filter_type.
+        """Search High Risk Employee list. Filter results by filter_type.
 
         Args:
             filter_type (str): Valid filter types.
             sort_key (str): Sort results based by field.
-            sort_direction (str): "ASC" or "DESC"
+            sort_direction (str): ``ASC`` or ``DESC``
 
         Returns:
             generator: An object that iterates over :class:`py42.response.Py42Response` objects