Exposure Management - CrowdStrike/falconpy GitHub Wiki

CrowdStrike Falcon CrowdStrike Subreddit

Using the Exposure Management service collection

Uber class support Service class support Documentation Version Page Updated

Table of Contents

Operation ID Description
aggregate_external_assets
PEP8 aggregate_assets
Returns external assets aggregates.
blob_download_external_assets
PEP8 download_assets
Download the entire contents of the blob. The relative link to this endpoint is returned in the GET /entities/external-assets/v1 request.
blob_preview_external_assets
PEP8 preview_assets
Download a preview of the blob. The relative link to this endpoint is returned in the GET /entities/external-assets/v1 request.
get_external_assets
PEP8 get_assets
Get details on external assets by providing one or more IDs.
delete_external_assets
PEP8 delete_assets
Delete multiple external assets.
patch_external_assets
PEP8 update_assets
Update the details of external assets.
query_external_assets
PEP8 query_assets
Get a list of external asset IDs that match the provided filter conditions. Use these IDs with the /entities/external-assets/v1 endpoints

Passing credentials

WARNING

client_id and client_secret are keyword arguments that contain your CrowdStrike API credentials. Please note that all examples below do not hard code these values. (These values are ingested as strings.)

CrowdStrike does not recommend hard coding API credentials or customer identifiers within source code.

aggregate_external_assets

Returns external assets aggregates.

PEP8 method name

aggregate_assets

Endpoint

Method Route
POST /fem/aggregates/external-assets/v1

Required Scope

assets:read

Content-Type

  • Consumes: application/json
  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
body Service Class Support Uber Class Support body dictionary Full body payload as a dictionary. Not required when using other keywords.
date_ranges Service Class Support No Uber Class Support body list of dictionaries Applies to date_range aggregations.

Example:
[
  {
    "from": "2016-05-28T09:00:31Z",
    "to": "2016-05-30T09:00:31Z"
  },
  {
    "from": "2016-06-01T09:00:31Z",
    "to": "2016-06-10T09:00:31Z"
  }
]
exclude Service Class Support No Uber Class Support body string Elements to exclude.
field Service Class Support No Uber Class Support body string The field on which to compute the aggregation.
filter Service Class Support No Uber Class Support body string FQL syntax formatted string to use to filter the results.
from Service Class Support No Uber Class Support body integer Starting position.
include Service Class Support No Uber Class Support body string Elements to include.
interval Service Class Support No Uber Class Support body string Time interval for date histogram aggregations. Valid values include:
  • year
  • month
  • week
  • day
  • hour
  • minute
max_doc_count Service Class Support No Uber Class Support body integer Only return buckets if values are less than or equal to the value here.
min_doc_count Service Class Support No Uber Class Support body integer Only return buckets if values are greater than or equal to the value here.
missing Service Class Support No Uber Class Support body string Missing is the value to be used when the aggregation field is missing from the object. In other words, the missing parameter defines how documents that are missing a value should be treated. By default they will be ignored, but it is also possible to treat them as if they had a value.
name Service Class Support No Uber Class Support body string Name of the aggregate query, as chosen by the user. Used to identify the results returned to you.
q Service Class Support No Uber Class Support body string Full text search across all metadata fields.
ranges Service Class Support No Uber Class Support body list of dictionaries Applies to range aggregations. Ranges values will depend on field.

For example, if max_severity is used, ranges might look like:
[
  {
    "From": 0,
    "To": 70
  },
  {
    "From": 70,
    "To": 100
  }
]
size Service Class Support No Uber Class Support body integer The max number of term buckets to be returned.
sub_aggregates Service Class Support No Uber Class Support body list of dictionaries A nested aggregation, such as:
[
  {
    "name": "max_first_behavior",
    "type": "max",
    "field": "first_behavior"
  }
]

There is a maximum of 3 nested aggregations per request.
sort Service Class Support No Uber Class Support body string FQL syntax string to sort bucket results.
  • _count - sort by document count
  • _term - sort by the string value alphabetically
Supports asc and desc using | format.

Example: _count|desc
time_zone Service Class Support No Uber Class Support body string Time zone for bucket results.
type Service Class Support No Uber Class Support body string Type of aggregation. Valid values include:
  • date_histogram - Aggregates counts on a specified time interval. Requires use of “interval” field.
  • date_range - Aggregates counts on custom defined date range buckets. Can include multiple ranges. (Similar to time series, but the bucket sizes are variable). Date formats to follow ISO 8601.
  • terms - Buckets alerts by the value of a specified field. For example, if field used is scenario, then alerts will be bucketed by the various alert scenario names.
  • range - Buckets alerts by specified (numeric) ranges of a specified field. For example, if doing a range aggregation on the max_severity field, the alerts will be counted by the specified ranges of severity.
  • cardinality - Returns the count of distinct values in a specified field.
  • max - Returns the maximum value of a specified field.
  • min - Returns the minimum value of a specified field.
  • avg - Returns the average value of the specified field.
  • sum - Returns the total sum of all values for the specified field.
  • percentiles - Returns the following percentiles for the specified field: 1, 5, 25, 50, 75, 95, 99.

Usage

Service class example (PEP8 syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )
date_range = {
    "from": "string",
    "to": "string"
}

search_range = {
    "From": integer,
    "To": integer
}

response = falcon.aggregate_assets(date_ranges=[date_range],
                                   exclude="string",
                                   field="string",
                                   filter="string",
                                   from=integer,
                                   include="string",
                                   interval="string",
                                   max_doc_count=integer,
                                   min_doc_count=integer,
                                   missing="string",
                                   name="string",
                                   q="string",
                                   ranges=[search_range],
                                   size=integer,
                                   sort="string",
                                   time_zone="string",
                                   type="string"
                                   )
print(response)
Service class example (Operation ID syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )
date_range = {
    "from": "string",
    "to": "string"
}

search_range = {
    "From": integer,
    "To": integer
}

response = falcon.aggregate_external_assets(date_ranges=[date_range],
                                            exclude="string",
                                            field="string",
                                            filter="string",
                                            from=integer,
                                            include="string",
                                            interval="string",
                                            max_doc_count=integer,
                                            min_doc_count=integer,
                                            missing="string",
                                            name="string",
                                            q="string",
                                            ranges=[search_range],
                                            size=integer,
                                            sort="string",
                                            time_zone="string",
                                            type="string"
                                            )
print(response)
Uber class example
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

body_payload = [{
    "date_ranges": [
        {
            "from": "string",
            "to": "string"
        }
    ],
    "exclude": "string",
    "field": "string",
    "filter": "string",
    "from": integer,
    "include": "string",
    "interval": "string",
    "max_doc_count": integer,
    "min_doc_count": integer,
    "missing": "string",
    "name": "string",
    "q": "string",
    "ranges": [
        {
            "From": integer,
            "To": integer
        }
    ],
    "size": integer,
    "sort": "string",
    "sub_aggregates": []
    "time_zone": "string",
    "type": "string"
}]

response = falcon.command("aggregate_external_assets", body=body_payload)

print(response)

Back to Table of Contents

blob_download_external_assets

Download the entire contents of the blob. The relative link to this endpoint is returned in the get_external_assets request.

PEP8 method name

download_assets

Endpoint

Method Route
GET /fem/entities/blobs-download/v1

Required Scope

assets:read

Content-Type

  • Produces: application/octet-stream

Keyword Arguments

Name Service Uber Type Data type Description
assetId Service Class Support Uber Class Support query string The Asset ID
hash Service Class Support Uber Class Support query string The File Hash
parameters Service Class Support Uber Class Support query dictionary Full query string parameters payload as a dictionary. Not required when using other keywords.

Usage

Service class example (PEP8 syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

with open("some_file.ext", "wb") as save_file:
    save_file.write(falcon.download_assets(assetId="string", hash="string"))
Service class example (Operation ID syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

with open("some_file.ext", "wb") as save_file:
    save_file.write(falcon.download_assets(assetId="string", hash="string"))
Uber class example
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

with open("some_file.ext", "wb") as save_file:
    save_file.write(falcon.command("blob_download_external_assets", assetId="string", hash="string"))

Back to Table of Contents

blob_preview_external_assets

Download a preview of the blob. The relative link to this endpoint is returned in the get_external_assets request.

PEP8 method name

preview_assets

Endpoint

Method Route
GET /fem/entities/blobs-preview/v1

Required Scope

assets:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
assetId Service Class Support Uber Class Support query string The Asset ID
hash Service Class Support Uber Class Support query string The File Hash
parameters Service Class Support Uber Class Support query dictionary Full query string parameters payload as a dictionary. Not required when using other keywords.

Usage

Service class example (PEP8 syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

response = falcon.preview_assets(assetId="string", hash="string")

print(response)
Service class example (Operation ID syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

response = falcon.blob_preview_external_assets(assetId="string", hash="string")

print(response)
Uber class example
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("blob_preview_external_assets", assetId="string", hash="string")

print(response)

Back to Table of Contents

get_external_assets

Get details on external assets by providing one or more IDs.

PEP8 method name

get_assets

Endpoint

Method Route
GET /fem/entities/external-assets/v1

Required Scope

assets:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
ids Service Class Support Uber Class Support query string or list of strings One or more asset IDs (max: 100). Find asset IDs with query_external_assets.
parameters Service Class Support Uber Class Support query dictionary Full query string parameters payload as a dictionary. Not required when using other keywords.

Usage

Service class example (PEP8 syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_assets(ids=id_list)

print(response)
Service class example (Operation ID syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.get_external_assets(ids=id_list)

print(response)
Uber class example
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.command("get_external_assets", ids=id_list)

print(response)

Back to Table of Contents

delete_external_assets

Delete multiple external assets.

PEP8 method name

delete_assets

Endpoint

Method Route
DELETE /fem/entities/external-assets/v1

Required Scope

assets:write

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
body Service Class Support Uber Class Support body dictionaries Full body payload in JSON format.
description Service Class Support No Uber Class Support body string Delete description.
ids Service Class Support Uber Class Support query string or list of strings One or more asset IDs (max: 100). Find asset IDs with query_external_assets.
parameters Service Class Support Uber Class Support query dictionary Full query string parameters payload as a dictionary. Not required when using other keywords.

Usage

Service class example (PEP8 syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.delete_assets(ids=id_list, description="string")

print(response)
Service class example (Operation ID syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

response = falcon.delete_external_assets(ids=id_list, description="string")

print(response)
Uber class example
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

id_list = 'ID1,ID2,ID3'  # Can also pass a list here: ['ID1', 'ID2', 'ID3']

body_payload = {
  "description": "string"
}

response = falcon.command("delete_external_assets", ids=id_list, body=body_payload)

print(response)

Back to Table of Contents

patch_external_assets

Update the details of external assets.

PEP8 method name

update_assets

Endpoint

Method Route
PATCH /fem/entities/external-assets/v1

Required Scope

assets:write

Content-Type

  • Consumes: application/json
  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
action Service Class Support Uber Class Support body string The asset triage action.
assigned_to Service Class Support Uber Class Support body string The user assigned to triage the asset.
body Service Class Support Uber Class Support body dictionary Full body payload as a dictionary. Not required when using other keywords.
cid Service Class Support Uber Class Support body string Asset customer ID.
criticality Service Class Support Uber Class Support body string The criticality level manually assigned to this asset.
criticality_description Service Class Support Uber Class Support body string The criticality description manually assigned to this asset.
description Service Class Support Uber Class Support body string The asset triage description
id Service Class Support Uber Class Support body string The unique ID of the asset.
status Service Class Support Uber Class Support body string The asset triage status.

Usage

Service class example (PEP8 syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

response = falcon.update_assets(action="string",
                                assigned_to="string",
                                cid="string",
                                criticality="string",
                                criticality_description="string",
                                description="string",
                                id="string",
                                status="string"
                                )

print(response)
Service class example (Operation ID syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

response = falcon.patch_external_assets(action="string",
                                        assigned_to="string",
                                        cid="string",
                                        criticality="string",
                                        criticality_description="string",
                                        description="string",
                                        id="string",
                                        status="string"
                                        )

print(response)
Uber class example
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

body_payload = {
  "assets": [
    {
      "cid": "string",
      "criticality": "string",
      "criticality_description": "string",
      "id": "string",
      "triage": {
        "action": "string",
        "assigned_to": "string",
        "description": "string",
        "status": "string"
      }
    }
  ]
}

response = falcon.command("patch_external_assets", body=body_payload)

print(response)

Back to Table of Contents

query_external_assets

Get a list of external asset IDs that match the provided filter conditions. Use these IDs with the GET and PATCH endpoints.

PEP8 method name

query_assets

Endpoint

Method Route
GET /fem/queries/external-assets/v1

Required Scope

assets:read

Content-Type

  • Produces: application/json

Keyword Arguments

Name Service Uber Type Data type Description
filter Service Class Support Uber Class Support query string Filter assets using an FQL query. Common filter options include:
  • asset_type:'ip'
  • last_seen_timestamp:>'now-7d'
All filter fields and operations supports negation (!).
limit Service Class Support Uber Class Support query integer Number of IDs to return.
offset Service Class Support Uber Class Support query string Starting index of result set from which to return IDs.
sort Service Class Support Uber Class Support query string Order by fields.
parameters Service Class Support Uber Class Support query dictionary Full query string parameters payload as a dictionary. Not required when using other keywords.
Available filters (Exact Match)
asset_id asset_type
confidence connectivity_status
criticality criticality_description
criticality_timestamp criticality_username
data_providers discovered_by
dns_domain.fqdn dns_domain.isps
dns_domain.parent_domain dns_domain.resolved_ips
dns_domain.services.applications.category dns_domain.services.applications.cpe
dns_domain.services.applications.name dns_domain.services.applications.vendor
dns_domain.services.applications.version dns_domain.services.cloud_provider
dns_domain.services.cpes dns_domain.services.hosting_provider
dns_domain.services.last_seen dns_domain.services.platform_name
dns_domain.services.port dns_domain.services.protocol
dns_domain.services.protocol_port dns_domain.services.status
dns_domain.services.status_code dns_domain.services.transport
dns_domain.type first_seen
id internet_exposure
ip.asn ip.cloud_vm.description
ip.cloud_vm.instance_id ip.cloud_vm.lifecycle
ip.cloud_vm.mac_address ip.cloud_vm.owner_id
ip.cloud_vm.platform ip.cloud_vm.private_ip
ip.cloud_vm.public_ip ip.cloud_vm.region
ip.cloud_vm.security_groups ip.cloud_vm.source
ip.cloud_vm.status ip.fqdns
ip.ip_address ip.isp
ip.location.area_code ip.location.city
ip.location.country_code ip.location.country_name
ip.location.postal_code ip.location.region_code
ip.location.region_name ip.location.timezone
ip.ptr ip.aid
ip.services.applications.category ip.services.applications.cpe
ip.services.applications.name ip.services.applications.vendor
ip.services.applications.version ip.services.cloud_provider
ip.services.cpes ip.services.first_seen
ip.services.last_seen ip.services.platform_name
ip.services.port ip.services.protocol
ip.services.protocol_port ip.services.status
ip.services.status_code ip.services.transport
last_seen manual
perimeter subsidiaries.id
subsidiaries.name triage.action
triage.assigned_to triage.status
triage.updated_by triage.updated_timestamp
Available filter fields that support wildcard (*)
asset_id asset_type
confidence connectivity_status
criticality criticality_username
data_providers discovered_by
dns_domain.fqdn dns_domain.isps
dns_domain.parent_domain dns_domain.resolved_ips
dns_domain.services.applications.category dns_domain.services.applications.cpe
dns_domain.services.applications.name dns_domain.services.applications.vendor
dns_domain.services.applications.version dns_domain.services.cloud_provider
dns_domain.services.cpes dns_domain.services.hosting_provider
dns_domain.services.id dns_domain.services.platform_name
dns_domain.services.port dns_domain.services.protocol
dns_domain.services.protocol_port dns_domain.services.status
dns_domain.services.status_code dns_domain.services.transport
dns_domain.type id
internet_exposure ip.asn
ip.cloud_vm.instance_id ip.cloud_vm.lifecycle
ip.cloud_vm.mac_address ip.cloud_vm.owner_id
ip.cloud_vm.platform ip.cloud_vm.private_ip
ip.cloud_vm.public_ip ip.cloud_vm.region
ip.cloud_vm.security_groups ip.cloud_vm.source
ip.cloud_vm.status ip.fqdns
ip.ip_address ip.isp
ip.location.area_code ip.location.city
ip.location.country_code ip.location.country_name
ip.location.postal_code ip.location.region_code
ip.location.region_name ip.location.timezone
ip.ptr ip.aid
ip.services.applications.category ip.services.applications.cpe
ip.services.applications.name ip.services.applications.vendor
ip.services.applications.version ip.services.cloud_provider
ip.services.cpes ip.services.platform_name
ip.services.port ip.services.protocol
ip.services.protocol_port ip.services.status
ip.services.status_code ip.services.transport
manual perimeter
subsidiaries.id subsidiaries.name
triage.action triage.assigned_to
triage.status triage.updated_by
Available filter fields that support lists ([v1, v2])
asset_id asset_type
confidence connectivity_status
criticality criticality_username
data_providers discovered_by
dns_domain.fqdn dns_domain.isps
dns_domain.parent_domain dns_domain.services.applications.category
dns_domain.services.applications.cpe dns_domain.services.applications.name
dns_domain.services.applications.vendor dns_domain.services.applications.version
dns_domain.services.cloud_provider dns_domain.services.cpes
dns_domain.services.id dns_domain.services.platform_name
dns_domain.services.port dns_domain.services.protocol
dns_domain.services.protocol_port dns_domain.services.status
dns_domain.services.status_code dns_domain.services.transport
dns_domain.type id
internet_exposure ip.asn
ip.cloud_vm.instance_id ip.cloud_vm.lifecycle
ip.cloud_vm.mac_address ip.cloud_vm.owner_id
ip.cloud_vm.platform ip.cloud_vm.region
ip.cloud_vm.security_groups ip.cloud_vm.source
ip.cloud_vm.status ip.fqdns
ip.isp ip.location.area_code
ip.location.city ip.location.country_code
ip.location.country_name ip.location.postal_code
ip.location.region_code ip.location.region_name
ip.location.timezone ip.ptr
ip.aid ip.services.applications.category
ip.services.applications.cpe ip.services.applications.name
ip.services.applications.vendor ip.services.applications.version
ip.services.cloud_provider ip.services.cpes
ip.services.platform_name ip.services.port
ip.services.protocol ip.services.protocol_port
ip.services.status ip.services.status_code
ip.services.transport manual
perimeter subsidiaries.id
subsidiaries.name triage.action
triage.assigned_to triage.status
triage.updated_by  
Available filter fields that support range comparisons (>, <, >=, <=)
criticality_timestamp dns_domain.resolved_ips
dns_domain.services.first_seen dns_domain.services.last_seen
dns_domain.services.port dns_domain.services.status_code
first_seen ip.cloud_vm.private_ip
ip.cloud_vm.public_ip ip.ip_address
ip.services.first_seen ip.services.last_seen
ip.services.port ip.services.status_code
last_seen triage.updated_timestamp

Usage

Service class example (PEP8 syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

response = falcon.query_assets(offset="string",
                               limit=integer,
                               sort="string",
                               filter="string"
                               )
print(response)
Service class example (Operation ID syntax)
from falconpy import ExposureManagement

falcon = ExposureManagement(client_id=CLIENT_ID,
                            client_secret=CLIENT_SECRET
                            )

response = falcon.query_external_assets(offset="string",
                                        limit=integer,
                                        sort="string",
                                        filter="string"
                                        )
print(response)
Uber class example
from falconpy import APIHarnessV2

falcon = APIHarnessV2(client_id=CLIENT_ID,
                      client_secret=CLIENT_SECRET
                      )

response = falcon.command("query_external_assets",
                          offset="string",
                          limit=integer,
                          sort="string",
                          filter="string"
                          )
print(response)

Back to Table of Contents

⚠️ **GitHub.com Fallback** ⚠️