Introduction

This article is designed to serve as a technical specification document that captures the exact methodology used to create the connections required to use Device Control functions from within Fusion SOAR. While this is a specific function to focus on, it serves as a methodology that can be replicated to introduce other functions that exist within the Falcon API to Fusion SOAR workflows.

Requirements

CrowdStrike

• CrowdStrike Falcon Fusion SOAR Read/Write Access
• CrowdStrike Falcon Foundry Read/Write Access
• Licensing for CrowdStrike Falcon Foundry – allowing creation of at least 1 app.
• Optional: CrowdStrike Falcon API OpenAPI Specification JSON Document
• Optional: CrowdStrike Development Environment

General

• Optional: Python3 for filtering OpenAPI Specifications

Preparing the Falcon OpenAPI Specification for Foundry

Purpose

The OpenAPI specification document for CrowdStrike contains over 900 functions. Without adjustment, Falcon Foundry fails to ingest the document. There are two approaches to resolving this.

Approach 1

You could manually configure the API without the use of the OpenAPI specification document. This means you will be configuring each part of the API integration manually. This is an acceptable method to use if you’re only planning on using one or two different functions within your integration.

Approach 2

Using the Python script found in this repo (https://github.com/SunnySkye/CrowdStrike/blob/main/OpenAPI-Splitter.py), you can split the OpenAPI specification document down into separate spec files based on each defined endpoint in that specification. So instead of having one big specification document, you have over 30 smaller spec files, one for each endpoint.

Then, you can simply use whichever of the single specification files you need in order to continue your work. In this case, we're only interested in the endpoint that handles USB Device Control, so that is the only specification file we will bother to import into Foundry.

Configuring the API in Foundry

• Within a Foundry application, open the “integrations” section

*Add an API integration, and select “Start from an OpenAPI”

*Upload the file you created with the Python script. If successful, you will see this screen:

There are some further fields to complete, but simply leave them blank and continue. Don’t fill in the client ID or secret here, that is done elsewhere.

Configuring the API function

Introduction

In this section, we are configuring the API function(s) more specifically. For this document, we will be configuring “PATCH /policy/entities/device-control/v1” Click the 3 dots next to the function, and click “edit”.

Generating the schema

Unfortunately, the OpenAPI specification is simply not enough to fully define the query for Foundry. The easiest way to get a starting point schema is to take a sample request from the OpenAPI document page: https://assets.falcon.us-2.crowdstrike.com/support/api/swagger-us2.html#/device-control-policies/updateDeviceControlPolicies, and upload it into the schema generator within Falcon Foundry. Unfortunately, this is not perfect and it can produce a schema that does not provide all the options that are available to the API function. In this instance, it can be valuable to leverage an LLM like ChatGPT to troubleshoot the schema if you’re unfamiliar with how these schemas are structured.

A working schema for the device control policy update function can be found in appendix 4.

Testing

You can use the testing function in Foundry to ensure your schema is working correctly. The way the testing area presents the parameters is identical to how these parameters will be presented within Fusion SOAR.

The schema provided in Appendix 4 presents as follows in testing:

Once you click “Add json.resources”, it expands out as shown:

Not all fields are mandatory. For example, if you add an exception for a USB Device Control policy, you only need to provide the Combined ID.

There is an issue that causes a 400 error, because the “Query time” is not submitting as an integer like it should. Fortunately, this does not prevent the exception from being created.

Sharing to Fusion SOAR

Finally, you can share the API function with Fusion. To do this, simply use the Workflow Share Settings within the function settings as shown below:

Once this is shared, you must deploy your Foundry application. Once deployed, the options will appear in Falcon Fusion.

In order to populate the query, you must ensure that Fusion has a variable that can be inserted that is valid for the query. This can be done by using the SIEM query function within your Fusion workflow. Configuring this query and returning variables is beyond the scope of this document.

#Appendices

Appendix 1: List of tags found in OpenAPI Specification Document

(Do not rely solely on this list, it is for reference purposes only)

ASPM Alerts Falcon Complete Dashboard Overwatch Dashboard api-integrations certificate-based-exclusions cloud-aws-registration cloud-azure-registration cloud-connect-aws cloud-security-assets cloud-snapshots complianceAssessments configuration-assessment configuration-assessment-evaluation-logic container-alerts container-detections container-images container-packages container-vulnerabilities content-update-policies correlation-rules cspg-iacapi cspm-registration custom-ioa custom-storage d4c-registration datascanner delivery-settings deployments detects device-content device-control-policies discover discover-iot downloads-api drift-indicators event schema event-streams exposure-management falcon-container falcon-container-cli falcon-container-image falconx-sandbox field schema filevantage firewall-management firewall-policies foundry-logscale handle host-group host-migration hosts humio-auth-proxy identity-entities identity-protection image-assessment-policies incidents installation-tokens installation-tokens-settings intel intelligence-feeds intelligence-indicator-graph ioa-exclusions ioc iocs kubernetes-protection lookup-files malquery message-center ml-exclusions mobile-enrollment mssp ods prevention-policies quarantine quick-scan quick-scan-pro real-time-response real-time-response-admin real-time-response-audit recon release-notes releases report-executions response-policies runtime-detections sample-uploads scheduled-reports sensor-download sensor-update-policies sensor-usage-api sensor-visibility-exclusions serverless-vulnerabilities spotlight-evaluation-logic spotlight-vulnerabilities unidentified-containers user-management workflows zero-trust-assessment

Appendix 2: OpenAPI Spec Filter Script

This appendix has been removed, the file can be found here: https://github.com/SunnySkye/CrowdStrike/blob/main/OpenAPI-Splitter.py

Appendix 3:

Refer to Appendix 2.

Appendix 4: Device Control Policy Update Schema

"$schema": "http://json-schema.org/draft-07/schema#", "properties": { "meta": { "properties": { "query_time": { "type": "integer", "title": "Query time" } }, "required": [ "query_time" ], "type": "object", "title": "Meta" }, "resources": { "items": { "properties": { "id": { "enum": [ "REDACTED-PolicyID-Goes-Here" ], "type": "string", "title": "ID" }, "settings": { "properties": { "classes": { "items": { "properties": { "action": { "enum": [ "BLOCK_ALL", "FULL_ACCESS" ], "type": "string", "title": "Action" }, "exceptions": { "items": { "properties": { "action": { "enum": [ "BLOCK_ALL", "FULL_ACCESS" ], "type": "string", "title": "Action" }, "combined_id": { "type": "string", "title": "Combined ID" }, "product_id_decimal": { "type": "string", "title": "Product ID decimal" }, "product_name": { "type": "string", "title": "Product name" }, "serial_number": { "type": "string", "title": "Serial number" }, "use_wildcard": { "type": "boolean", "title": "Use wildcard" }, "vendor_id_decimal": { "type": "string", "title": "Vendor ID decimal" }, "vendor_name": { "type": "string", "title": "Vendor name" } }, "required": [ "action" ], "type": "object", "title": "Exceptions" }, "type": "array" }, "id": { "enum": [ "ANY", "IMAGING", "MASS_STORAGE" ], "type": "string", "title": "ID" } }, "required": [ "id", "exceptions" ], "type": "object", "title": "Classes" }, "type": "array" } }, "required": [ "classes" ], "type": "object", "title": "Settings" } }, "required": [ "id", "settings" ], "type": "object", "title": "Resources" }, "type": "array" } }, "required": [ "resources" ], "type": "object", "title": "Device Control Policy PATCH Schema" }