added endpoint information for host tags. added tests

src/falconpy/_endpoint.py

@@ -73,6 +73,7 @@
     ["queryCombinedGroupMembers", "GET", "/devices/combined/host-group-members/v1"],
     ["queryCombinedHostGroups", "GET", "/devices/combined/host-groups/v1"],
     ["PerformActionV2", "POST", "/devices/entities/devices-actions/v2"],
+    ["FalconGroupingTag", "PATCH", "/devices/entities/devices/tags/v1"],
     ["UpdateDeviceTags", "PATCH", "/devices/entities/devices/tags/v1"],
     ["GetDeviceDetails", "GET", "/devices/entities/devices/v1?ids={}"],
     ["performGroupAction", "POST", "/devices/entities/host-group-actions/v1"],

src/falconpy/hosts.py

@@ -67,6 +67,39 @@ def PerformActionV2(self: object, parameters: dict, body: dict, action_name: str
             returned = generate_error_result("Invalid value specified for action_name parameter.")
 
         return returned
+
+    def FalconGroupingTag(self: object, action_name: str ids: [] or str, tags: [] or str) -> dict:
+        """
+        allows for tagging hosts. If the tags are empty
+        """
+        ALLOWED_ACTIONS = ["add", "remove"]
+        # validate action is allowed AND tags is "something"
+        if action_name.lower() in ALLOWED_ACTIONS and tags is not None:
+            FULL_URL = self.base_url + '/devices/entities/devices/tags/v1'
+            HEADERS = self.headers
+            # convert ids/tags to be a list object if not already
+            if isinstance(ids, str):
+                ids = [ids]
+            if isinstance(tags, str):
+                tags = [tags]
+            # tags must start with FalconGroupingTags, users probably won't know this so add it for them
+            patch_tag = []
+            for tag in tags:
+                if tag.startswith("FalconGroupingTags/"):
+                    patch_tag.append(tag)
+                else:
+                    tag_name = "FalconGroupingTags/" + tag
+                    patch_tag.append(tag)
+
+            BODY = {
+                "action": action_name,
+                "devices_ids": ids,
+                "tags": patch_tag
+            }
+            returned = service_request(caller=self, method="PATCH", body=body, headers=HEADERS, verify=self.ssl_verify)
+        else:
+            returned = generate_error_result("Invalid value specified for action_name parameter.")
+        return returned
 
     def GetDeviceDetails(self: object, ids) -> dict:
         """ Get details on one or more hosts by providing agent IDs (AID).

tests/test_hosts.py

@@ -45,6 +45,34 @@ def serviceHosts_QueryDevicesByFilter(self):
     #     else:
     #         return False
 
+    def serviceHosts_addTag(self):
+        id_list = []
+        id_list.append(
+            falcon.GetDeviceDetails(ids=falcon.QueryDevicesByFilter(parameters={"limit":1})["body"]["resources"][0])["body"]["resources"][0]["device_id"]
+        )
+        # test basic, id is a list, single valid tag w/o manipulation
+        if not falcon.FalconGroupingTag(action_name="add", ids=id_list, tags=["FalconGroupingTags/testtag"])["status_code"] in AllowedResponses:
+            return False
+        if not falcon.FalconGroupingTag(action_name="remove", ids=id_list, tags=["FalconGroupingTags/testtag"])["status_code"] in AllowedResponses:
+            return False
+        # id is a list, multiple tags needing manipulation
+        if not falcon.FalconGroupingTag(action_name="add", ids=id_list, tags=["testtag", "tagtest", "anothertag"])["status_code"] in AllowedResponses:
+            return False
+        if not falcon.FalconGroupingTag(action_name="remove", ids=id_list, tags=["testtag", "tagtest", "anothertag"])["status_code"] in AllowedResponses:
+            return False
+        # id is a list, mutliple tags some need manipulation
+        if not falcon.FalconGroupingTag(action_name="add", ids=id_list, tags=["FalconGroupingTags/testtag", "manipulate", "FalconGroupingTags/anothertag"])["status_code"] in AllowedResponses:
+            return False
+        if not falcon.FalconGroupingTag(action_name="remove", ids=id_list, tags=["FalconGroupingTags/testtag", "manipulate", "FalconGroupingTags/anothertag"])["status_code"] in AllowedResponses:
+            return False
+        # id is single string, single valid tag w/o manipulation
+        if not falcon.FalconGroupingTag(action_name="add", ids=id_list[0], tags=["FalconGroupingTags/testtag"])["status_code"] in AllowedResponses:
+            return False
+        if not falcon.FalconGroupingTag(action_name="remove", ids=id_list[0], tags=["FalconGroupingTags/testtag"])["status_code"] in AllowedResponses:
+            return False
+
+        return True
+
     def serviceHosts_PerformActionV2(self):
         id_list = []
         id_list.append(
@@ -87,7 +115,12 @@ def test_QueryDevicesByFilterScroll(self):
 
     def test_QueryDevicesByFilter(self):
         assert self.serviceHosts_QueryDevicesByFilter() == True
+
+    def test_addTag(self):
+        assert self.serviceHosts_addTag() == True
 
+    def test_removeTag(self):
+        assert self.serviceHosts_removeTag() == True
     # def test_GetDeviceDetails(self):
     #     assert self.serviceHosts_GetDeviceDetails() == True