Version 1.0.9 - New Discover service collection operations

CHANGELOG.md

@@ -1,3 +1,18 @@
+# Version 1.0.9
+## Added features and functionality
++ Added: New Discover service collection endpoints, matching Service Class operations and unit testing.
+    * New method: _`get_accounts`_
+    * New method: _`get_logins`_
+    * New method: _`query_accounts`_
+    * New method: _`query_logins`_
+    - `discover.py`
+    - `tests/test_discover.py`
+## Other
++ Fixed: Docstring typo for the `ProvisionAWSAccounts` operation within the Cloud Connect AWS Service Class.
+    - `cloud_connect_aws.py`
++ Fixed: Docstring typo for the `combinedQueryVulnerabilities` operation within the Spotlight Vulnerabilities Service Class. Closes #608.
+    - `spotlight_vulnerabilities.py`
+
 # Version 1.0.8
 ## Added features and functionality
 + Added: Spotlight Evaluation Logic Service Class, related service collection endpoints and related unit tests.

src/falconpy/_endpoint/_discover.py

@@ -37,6 +37,26 @@
 """
 
 _discover_endpoints = [
+  [
+    "get_accounts",
+    "GET",
+    "/discover/entities/accounts/v1",
+    "Get details on accounts by providing one or more IDs.",
+    "discover",
+    [
+      {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "collectionFormat": "multi",
+        "description": "One or more account IDs (max: 100). Find account IDs with GET `/discover/queries/accounts/v1`",
+        "name": "ids",
+        "in": "query",
+        "required": True
+      }
+    ]
+  ],
   [
     "get_hosts",
     "GET",
@@ -57,6 +77,62 @@
       }
     ]
   ],
+  [
+    "get_logins",
+    "GET",
+    "/discover/entities/logins/v1",
+    "Get details on logins by providing one or more IDs.",
+    "discover",
+    [
+      {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "collectionFormat": "multi",
+        "description": "One or more login IDs (max: 100). Find login IDs with GET `/discover/queries/logins/v1`",
+        "name": "ids",
+        "in": "query",
+        "required": True
+      }
+    ]
+  ],
+  [
+    "query_accounts",
+    "GET",
+    "/discover/queries/accounts/v1",
+    "Search for accounts in your environment by providing an FQL (Falcon Query Language) filter and paging details. Returns a set of account IDs which match the filter criteria.",
+    "discover",
+    [
+      {
+        "minimum": 0,
+        "type": "integer",
+        "description": "An offset used with the `limit` parameter to manage pagination of results. On your first request, don’t provide an `offset`. On subsequent requests, provide the `offset` from the previous response to continue from that place in the results.",
+        "name": "offset",
+        "in": "query"
+      },
+      {
+        "maximum": 100,
+        "minimum": 1,
+        "type": "integer",
+        "description": "The number of account IDs to return in this response (min: 1, max: 100, default: 100). Use with the `offset` parameter to manage pagination of results.",
+        "name": "limit",
+        "in": "query"
+      },
+      {
+        "type": "string",
+        "description": "Sort accounts by their properties. A single sort field is allowed. Common sort options include:\n\n<ul><li>username|asc</li><li>last_failed_login_timestamp|desc</li></ul>",
+        "name": "sort",
+        "in": "query"
+      },
+      {
+        "type": "string",
+        "description": "Filter accounts using an FQL query. Common filter options include:\n\n<ul><li>account_type:'Local'</li><li>admin_privileges:'Yes'</li><li>first_seen_timestamp:<'now-7d'</li><li>last_successful_login_type:'Terminal server'</li></ul>",
+        "name": "filter",
+        "in": "query"
+      }
+    ]
+  ],
   [
     "query_hosts",
     "GET",
@@ -68,9 +144,43 @@
       {
         "minimum": 0,
         "type": "integer",
-        "description": "An offset used with the `limit` parameter to manage pagination of results. "
-        "On your first request, don’t provide an `offset`. On subsequent requests, provide the `offset` "
-        "from the previous response to continue from that place in the results.",
+        "description": "An offset used with the `limit` parameter to manage pagination of results. On your first request, don’t provide an `offset`. On subsequent requests, provide the `offset` from the previous response to continue from that place in the results.",
+        "name": "offset",
+        "in": "query"
+      },
+      {
+        "maximum": 100,
+        "minimum": 1,
+        "type": "integer",
+        "description": "The number of asset IDs to return in this response (min: 1, max: 100, default: 100). Use with the `offset` parameter to manage pagination of results.",
+        "name": "limit",
+        "in": "query"
+      },
+      {
+        "type": "string",
+        "description": "Sort assets by their properties. A single sort field is allowed. Common sort options include:\n\n<ul><li>hostname|asc</li><li>product_type_desc|desc</li></ul>",
+        "name": "sort",
+        "in": "query"
+      },
+      {
+        "type": "string",
+        "description": "Filter assets using an FQL query. Common filter options include:\n\n<ul><li>entity_type:'managed'</li><li>product_type_desc:'Workstation'</li><li>platform_name:'Windows'</li><li>last_seen_timestamp:>'now-7d'</li></ul>",
+        "name": "filter",
+        "in": "query"
+      }
+    ]
+  ],
+  [
+    "query_logins",
+    "GET",
+    "/discover/queries/logins/v1",
+    "Search for logins in your environment by providing an FQL (Falcon Query Language) filter and paging details. Returns a set of login IDs which match the filter criteria.",
+    "discover",
+    [
+      {
+        "minimum": 0,
+        "type": "integer",
+        "description": "An offset used with the `limit` parameter to manage pagination of results. On your first request, don’t provide an `offset`. On subsequent requests, provide the `offset` from the previous response to continue from that place in the results.",
         "name": "offset",
         "in": "query"
       },

src/falconpy/_version.py

@@ -35,7 +35,7 @@
 
 For more information, please refer to <https://unlicense.org>
 """
-_VERSION = '1.0.8'
+_VERSION = '1.0.9'
 _MAINTAINER = 'Joshua Hiller'
 _AUTHOR = 'CrowdStrike'
 _AUTHOR_EMAIL = 'falconpy@crowdstrike.com'

src/falconpy/cloud_connect_aws.py

@@ -154,8 +154,6 @@ def provision_aws_accounts(self: object, body: dict, parameters: dict = None, **
         external_id -- AWS cross-account role secret. String.
         iam_role_arn -- ARN used for cross-account role. String.
         id -- AWS account ID. String.
-        mode -- Mode for provisioning. Allowed values are `manual` or `cloudformation`.
-                Defaults to `manual` if not defined.
         parameters -- full parameters payload, not required if mode is provided as a keyword.
         rate_limit_reqs -- Integer.
         rate_limit_time -- Integer.

src/falconpy/discover.py

@@ -53,6 +53,34 @@ class Discover(ServiceClass):
     - a valid token provided by the authentication service class (oauth2.py)
     """
 
+    @force_default(defaults=["parameters"], default_types=["dict"])
+    def get_accounts(self: object, *args, parameters: dict = None, **kwargs) -> dict:
+        """Get details on accounts by providing one or more IDs.
+
+        Find account IDs with `query_accounts`.
+
+        Keyword arguments:
+        ids -- One or more account IDs (max: 100). String or list of strings.
+        parameters - full parameters payload, not required if ids is provided as a keyword.
+
+        Arguments: When not specified, the first argument to this method is assumed to be 'ids'.
+                   All others are ignored.
+
+        Returns: dict object containing API response.
+
+        HTTP Method: GET
+
+        Swagger URL
+        https://assets.falcon.crowdstrike.com/support/api/swagger.html#/discover/get-accounts
+        """
+        return process_service_request(
+            calling_object=self,
+            endpoints=Endpoints,
+            operation_id="get_accounts",
+            keywords=kwargs,
+            params=handle_single_argument(args, parameters, "ids")
+            )
+
     @force_default(defaults=["parameters"], default_types=["dict"])
     def get_hosts(self: object, *args, parameters: dict = None, **kwargs) -> dict:
         """Get details on assets by providing one or more IDs.
@@ -81,6 +109,85 @@ def get_hosts(self: object, *args, parameters: dict = None, **kwargs) -> dict:
             params=handle_single_argument(args, parameters, "ids")
             )
 
+    @force_default(defaults=["parameters"], default_types=["dict"])
+    def get_logins(self: object, *args, parameters: dict = None, **kwargs) -> dict:
+        """Get details on logins by providing one or more IDs.
+
+        Find login IDs with `query_logins`.
+
+        Keyword arguments:
+        ids -- One or more login IDs (max: 100). String or list of strings.
+        parameters - full parameters payload, not required if ids is provided as a keyword.
+
+        Arguments: When not specified, the first argument to this method is assumed to be 'ids'.
+                   All others are ignored.
+
+        Returns: dict object containing API response.
+
+        HTTP Method: GET
+
+        Swagger URL
+        https://assets.falcon.crowdstrike.com/support/api/swagger.html#/discover/get-logins
+        """
+        return process_service_request(
+            calling_object=self,
+            endpoints=Endpoints,
+            operation_id="get_logins",
+            keywords=kwargs,
+            params=handle_single_argument(args, parameters, "ids")
+            )
+
+    @force_default(defaults=["parameters"], default_types=["dict"])
+    def query_accounts(self: object, parameters: dict = None, **kwargs) -> dict:
+        """Search for accounts in your environment.
+
+        Supports providing a FQL (Falcon Query Language) filter and paging details.
+        Returns a set of account IDs which match the filter criteria.
+
+        Keyword arguments:
+        filter -- The filter expression that should be used to limit the results. FQL syntax.
+                  Available Filters:
+                  id                            last_successful_login_timestamp
+                  cid                           last_successful_login_hostname
+                  user_sid                      last_successful_login_remote_ip
+                  login_domain                  last_successful_login_host_country
+                  account_name                  last_successful_login_host_city
+                  username                      last_failed_login_type
+                  account_type                  last_failed_login_timestamp
+                  admin_privileges              last_failed_login_hostname
+                  first_seen_timestamp          password_last_set_timestamp
+                  last_successful_login_type
+        limit -- The number of account IDs to return in this response. (Max: 100, default: 100)
+                 Use with the offset parameter to manage pagination of results.
+        offset -- An offset used with the limit parameter to manage pagination of results.
+                  On your first request, don’t provide an offset. On subsequent requests,
+                  provide the offset from the previous response to continue from that place
+                  in the results.
+        parameters - full parameters payload, not required if using other keywords.
+        sort -- Sort assets by their properties. A single sort field is allowed.
+                Common sort options include:
+                account_type:'Local'
+                admin_privileges:'Yes'
+                first_seen_timestamp:<'now-7d'
+                last_successful_login_type:'Terminal server'
+
+        This method only supports keywords for providing arguments.
+
+        Returns: dict object containing API response.
+
+        HTTP Method: GET
+
+        Swagger URL
+        https://assets.falcon.crowdstrike.com/support/api/swagger.html#/discover/query-accounts
+        """
+        return process_service_request(
+            calling_object=self,
+            endpoints=Endpoints,
+            operation_id="query_accounts",
+            keywords=kwargs,
+            params=parameters
+            )
+
     @force_default(defaults=["parameters"], default_types=["dict"])
     def query_hosts(self: object, parameters: dict = None, **kwargs) -> dict:
         """Search for assets in your environment.
@@ -141,3 +248,56 @@ def query_hosts(self: object, parameters: dict = None, **kwargs) -> dict:
             keywords=kwargs,
             params=parameters
             )
+
+    @force_default(defaults=["parameters"], default_types=["dict"])
+    def query_logins(self: object, parameters: dict = None, **kwargs) -> dict:
+        """Search for logins in your environment.
+
+        Supports providing a FQL (Falcon Query Language) filter and paging details.
+        Returns a set of asset IDs which match the filter criteria.
+
+        Keyword arguments:
+        filter -- The filter expression that should be used to limit the results. FQL syntax.
+                  Available Filters:
+                  id                  login_timestamp
+                  cid                 login_domain
+                  login_status        admin_privileges
+                  account_id          local_ip
+                  host_id             remote_ip
+                  user_sid            host_country
+                  aid                 host_city
+                  account_name        is_suspicious
+                  username            failure_description
+                  hostname            login_event_count
+                  account_type        aggregation_time_interval
+                  login_type
+        limit -- The number of login IDs to return in this response. (Max: 100, default: 100)
+                 Use with the offset parameter to manage pagination of results.
+        offset -- An offset used with the limit parameter to manage pagination of results.
+                  On your first request, don’t provide an offset. On subsequent requests,
+                  provide the offset from the previous response to continue from that place
+                  in the results.
+        parameters - full parameters payload, not required if using other keywords.
+        sort -- Sort logins by their properties. A single sort field is allowed.
+                Common sort options include:
+                account_type:'Local'
+                login_type:'Interactive'
+                first_seen_timestamp:<'now-7d'
+                admin_privileges:'No'
+
+        This method only supports keywords for providing arguments.
+
+        Returns: dict object containing API response.
+
+        HTTP Method: GET
+
+        Swagger URL
+        https://assets.falcon.crowdstrike.com/support/api/swagger.html#/discover/query-logins
+        """
+        return process_service_request(
+            calling_object=self,
+            endpoints=Endpoints,
+            operation_id="query_logins",
+            keywords=kwargs,
+            params=parameters
+            )

src/falconpy/spotlight_vulnerabilities.py

@@ -68,7 +68,7 @@ def query_vulnerabilities_combined(self: object, parameters: dict = None,  **kwa
         facet -- Select various details blocks to be returned for each vulnerability entry.
                  Supported values:
                  cve_details            host_info
-                 remediation_details
+                 remediation_details    evaluation_logic
         filter -- Filter items using a query in Falcon Query Language (FQL).
                   Wildcards '*' are unsupported.
         limit -- The number of items to return in this response (default: 100, max: 400).

tests/test_discover.py

@@ -24,11 +24,27 @@ def run_all_tests(self):
         if check["status_code"] == 429:
             pytest.skip("Rate limit hit")
         if check["body"]["resources"]:
-            id_list = check["body"]["resources"]
+            hosts_id_list = check["body"]["resources"]
         else:
-            id_list = "1234567890"
+            hosts_id_list = "1234567890"
+        check = falcon.query_accounts(limit=1)
+        if check["status_code"] == 429:
+            pytest.skip("Rate limit hit")
+        if check["body"]["resources"]:
+            accounts_id_list = check["body"]["resources"]
+        else:
+            accounts_id_list = "1234567890"
+        check = falcon.query_logins(limit=1)
+        if check["status_code"] == 429:
+            pytest.skip("Rate limit hit")
+        if check["body"]["resources"]:
+            logins_id_list = check["body"]["resources"]
+        else:
+            logins_id_list = "1234567890"
         tests = {
-            "query_and_get_hosts": falcon.get_hosts(ids=id_list)
+            "query_and_get_accounts": falcon.get_accounts(ids=accounts_id_list),
+            "query_and_get_hosts": falcon.get_hosts(ids=hosts_id_list),
+            "query_and_get_logins": falcon.get_logins(ids=logins_id_list)
         }
         for key in tests:
             if tests[key]["status_code"] not in AllowedResponses: