Assets_query

Table of Contents

Client

class Assets_query.Client

A client object representing ‘Assets_query’ Service:

import almdrlib

client = almdrlib.client('assets_query')

Available methods:

asset_group(**kwargs)

Creates, renames, updates, or deletes an asset-group asset. On deletion, deletes any references in linked groups. If a linked group has only a single reference in it, and would be emptied as a result it will also be deleted. On rename, linked groups (that reference the renamed group) also have their reference updated.

Request Syntax

response = client.asset_group(
    account_id='string'
    data='dict'
    return_all_properties='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • data (dict) –

  • return_all_properties (boolean) –

    When true, causes the inclusion of all asset properties in the response. By default, the assets in the response only includes summary properties.

    Default: False

Return type

dict

Returns

Response Syntax

{
    'dry_run': 'False|True',
    'operations': [
        {
            'code': 'integer',
            'name': 'string',
            'operation': 'string'
        }
    ]
}

Response Definitions

  • dry_run (boolean) –

  • operations (list) –

    • (dict) –

      • code (integer) –

      • name (string) –

      • operation (string) –

asset_type_schema(**kwargs)

fetch the schema of an asset type

Request Syntax

response = client.asset_type_schema(
    asset_type='string'
)
Parameters

asset_type (string) – [REQUIRED]

Return type

dict

Returns

Response Syntax

{}

Response Definitions

asset_types_schemas(**kwargs)

Fetches the "schema" for asset types. The schema describes the structure for asset types.

Request Syntax

response = client.asset_types_schemas(
    fields='string'
    filter='string'
    format='list'|'topology'
)
Parameters

  • fields (string) – A csv string of the fields that should be returned for an asset type. Note: if the asset type does not contain that field it will not be in the return value.

  • filter (string) – Filters that asset types must match to be included eg. groupable, taggable, vulnerable, etc…

  • format (string) –

    Returns the asset types as a list of schema objects (list) or as a list of topological schemas

    Valid values: list, topology

Return type

dict

Returns

Response Syntax

{
    'assetTypes': 'dict|list',
    'count': 'number'
}

Response Definitions

  • assetTypes (dict) –

  • count (number) –

config_topology(**kwargs)

Retrieve the given deployment’s configuration topology. Each row in the assets response is a set of related region, vpc, and subnet asset strings that can be cross-referenced as JSON keys in the data map.

Request Syntax

response = client.config_topology(
    account_id='string'
    deployment_id='string'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • deployment_id (string) –

    [REQUIRED]

    The ID of the deployment source as represented in the deployments service (uppercase UUID).

Return type

dict

Returns

Response Syntax

{
    'topology': {
        'assets': [
            'string'
        ],
        'data': {},
        'rows': 'integer'
    }
}

Response Definitions

  • topology (dict) –

    • assets (list) –

      An array of list of asset keys for each subnet in the deployment. Contains the keys for the subnet itself, its vpc and its region.

      • (string) –

    • data (dict) –

      A map containing all referenced asset objects in assets keyed by asset key.

    • rows (integer) –

      Number of assets.

dispose_conclude_remediations(**kwargs)

dispose_remediations disposes the vulnerability instances ("vinstances") associated with a set of remediations or vulnerabilities (by ID). A set of remediation-items is created, 1 per deployment/remediation_id/vulnerability_id, with the state set to "disposed" and all vulnerability instances associated to that "remediation_id" or "vulnerability_id" on assets described by the given "filters" have their "disposed" property set to true.

Note that, if the "expires" property is set on a "disposed" remediation-item, that item will be undisposed when the "expires" timestamp is in the past, and all associated vulnerability instances will have their "disposed" property set back to false.

conclude_remediations concludes the vulnerability instances ("vinstances") associated with a set of remediations or vulnerabilities (by ID). A set of remediation-items is created, 1 per deployment/remediation_id/vulnerability_id, with the state set to "concluded" and all vulnerability instances associated to that "remediation_id" or "vulnerability_id" on assets described by the given "filters" have their "concluded" property set to true.

Note that once all associated vulnerabilities are resolved, "concluded" remediation-items will be cleared from the system (resolved). Any matching vulnerability instance that is created or modified after the "concluded" remediation-item’s modified_on timestamp will be unconcluded (their "concluded" property will be set to false). If all existing vulnerability instances are newer than the remediation-item, then the remediation-item will be cleared (deleted).

Request Syntax

response = client.dispose_conclude_remediations(
    account_id='string'
    data='dict'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • data (dict) –

Return type

dict

Returns

Response Syntax

'dict'

Response Definitions

find_asset(**kwargs)

Finds an asset quickly using known identifiers. The query string parameters for different find operations are grouped together:

To find a collector by type and UUID, specify the following query parameters:

  • collector_type (default: any)

  • return_type (default: collector)

  • uuid

To find a host by its associated appliance UUID and host parameters, specify the following query parameters:

  • collector_type (must be set to appliance)

  • ip_address

  • uuid

To get the metadata for a host, specify the following query parameters:

  • collector_type (default: any)

  • return_type (must be set to host_metadata)

  • uuid

To find a host by network UUID and host parameters, specify the following query parameters:

  • ip_address

  • network_uuid

  • return_type (must be set to host)

Request Syntax

response = client.find_asset(
    account_id='string'
    collector_type='string'
    ip_address='string'
    network_uuid='string'
    return_type='collector'|'host_metadata'|'host'
    uuid='string'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • collector_type (string) –

    Type of collector to find by UUID. A comma-separated list of values can be provided and each type will be checked. any will only be expanded if it is the only type provided. Allowed values:

    • any

    • agent

    • appliance

    • collector

    • remote-source

  • ip_address (string) – The IP address of the host to find, in text representation. Must be used in conjunction with the collector_type=appliance parameter.

  • network_uuid (string) – The value of the network_uuid property on the network/vpc/vnet asset that contains the host to find.

  • return_type (string) –

    The return for this find operation. The default is collector, and note that host and host_metadata are not compatible with the collector_type=collector, because it has no associated host.

    Valid values: collector, host_metadata, host

  • uuid (string) – The UUID of the collector asset

Return type

dict

Returns

Response Syntax

{
    'deployment_id': 'string',
    'host_key': 'string',
    'key': 'string',
    'type': 'string'
}

Response Definitions

  • deployment_id (string) –

    Deployment ID

  • host_key (string) –

  • key (string) –

  • type (string) –

find_assets(**kwargs)

Finds a list of assets quickly using known identifiers. This endpoint is limited to specific asset types, currently: agents, appliances, hosts and remote sources. If the asset is found, the response will contain the asset details, keyed by the identifiers in the request parameters. If the asset is not found, the response will contain a null value, keyed by the identifiers in the request parameters.

Collector results are keyed by the uuid property in the request parameters.

When a host is found by appliance, results are keyed by the uuid and ip_address request parameters, separated by ,.

When a host is found by network, results are keyed by the network_uuid and ip_address request parameters, separated by ,.

Request Syntax

response = client.find_assets(
    account_id='string'
    parameters=[
        {
            'collector_type': 'string',
            'ip_address': 'string',
            'network_uuid': 'string',
            'return_type': 'collector'|'host_metadata'|'host',
            'uuid': 'string'
        }
    ]
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • parameters (list) –

    The list of request objects, each containing parameters of a find asset operation (see description for full details).

    • (dict) –

      A complete set of find asset parameters (see description for full details).

      • collector_type (string) –

        Type of collector to find by UUID. A comma-separated list of values can be provided and each type will be checked. any will only be expanded if it is the only type provided. Allowed values:

        • any

        • agent

        • appliance

        • collector

        • remote-source

      • ip_address (string) –

        The IP address of the host to find, in text representation. Must be used in conjunction with the collector_type=appliance parameter.

      • network_uuid (string) –

        The value of the network_uuid property on the network/vpc/vnet asset that contains the host to find.

      • return_type (string) –

        The return for this find operation. The default is collector, and note that host and host_metadata are not compatible with the collector_type=collector, because it has no associated host.

        Valid values: collector, host_metadata, host

      • uuid (string) –

        The UUID of the collector asset

Return type

dict

Returns

Response Syntax

{
    'assets': {
        '{key}': {
            'deployment_id': 'string',
            'host_key': 'string',
            'key': 'string',
            'type': 'string'
        }
    }
}

Response Definitions

  • assets (dict) –

    • {key} (dict) –

      • deployment_id (string) –

        Deployment ID

      • host_key (string) –

      • key (string) –

      • type (string) –

get_asset_details(**kwargs)

Fetches details and elaborations about individual assets and their surroundings, such as complete asset details or an asset’s network neighborhood or connectivity. The query string parameters for different details operations are grouped together:

To get details of an asset by type, key, deployment, and region, specify the following query parameters:

  • type (must be host)

  • key

  • deployment

  • region

To get details of an asset by type and deployment, specify the following query parameters:

  • type (must be deployment)

  • deployment

To get details of an asset by appliance_uuid and ip_address, specify the following query parameters:

  • appliance_uuid

  • ip_address

  • port (optional, always provide if available)

To get details of an asset by type and uuid, specify the following query parameters:

  • type (default: any)

  • uuid

To get details of an asset by deployment, ip addresses and network, specify the following query parameters:

  • deployment

  • ip_address

  • network

To get details of an asset by user_id, specify the following query parameters:

  • user_id (note that this query will execute an exact match and will not normalize the input while searching)

To get details of an asset by deployment and user_id, specify the following query parameters:

  • deployment

  • user_id (note that this query will execute an exact match and will not normalize the input while searching)

To get details of an asset by user_name, specify the following query parameters:

  • user_name (note that this query will execute an exact match and will not normalize the input while searching)

To get details of an asset by deployment and user_id, specify the following query parameters:

  • deployment

  • user_name (note that this query will execute an exact match and will not normalize the input while searching)

Note that when calling this endpoint with query options deployment, network and ip_address set, if a host is found, any subnet that the host isn’t related to but it could be (the IP address matches the subnet mask) the additional unrelated subnet(s) will be returned under the subnet key in the response.

Request Syntax

response = client.get_asset_details(
    account_id='string'
    appliance_uuid='string'
    deployment='string'
    ip_address='string'
    key='string'
    network='string'
    port='string'
    region='string'
    type='string'
    user_id='string'
    user_name='string'
    uuid='string'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • appliance_uuid (string) – The UUID of the appliance protecting the host to elaborate, which will be the source of any IDS events generated for the host. The appliance UUID is the UUID issued to the appliance agent and contained in its agent certificate.

  • deployment (string) – The native AWS account ID or Azure subscription ID (prefixed by kind), or the internal deployment UUID. Deployment is either the deployment’s Alert Logic UUID, or the native deployment ID prefixed by kind (either aws: or azure:). The expected value is either aws:{AWSAccountId} or azure:{AzureSubscriptionId} (e.g., aws:1234567890 or azure:713CEFBB-E37E-4119-A1AA-458840BFD878).

  • ip_address (string) – A CSV of the IP address(es) of the target protected host. The IP address is the target IP, i.e. the IP of a protected asset (being defined as any IP address in the set of protected subnets, itself known as “home net”). If more than one IP address is given, all of them must be target IPs of the protected asset.

  • key (string) – The native AWS ID (prefixed by kind) or the full asset key of the target asset. Key is either a full asset key, or must be prefixed by id:, followed by the asset’s native ID (e.g. instance ID of a host in AWS). Initially, the expected value is id:AWSInstanceId, e.g. id:i-0fa67ce21528409bc. *Note: If you use id:AWSInstanceId then region must be defined as region ID id:AWSRegionId*

  • network (string) – The network asset key, e.g. a vpc key: /aws/us-east-1/vpc/vpc-12345678.

  • port (string) – The TCP or UDP port on the target protected host

  • region (string) – The AWS region ID (prefixed by kind) or the full asset key. Region is either a full asset key, or must be prefixed by id:, followed by the asset’s native ID (e.g., region ID in AWS). Initially, the expected value is id:AWSRegionId, e.g., id:us-east-2.

  • type (string) –

    The asset type(s) to look up, separated by commas. Note that multiple values are only supported by some flavors (see description) — sometimes only host or deployment are acceptable.

    When passing the uuid parameter, the order provided is the order that the types will be looked up; if you set agent/appliance prior to host, the host will be detailed as a related asset to the associated agent/appliance asset.

    Allowed values:

    • any

    • deployment

    • agent

    • appliance

    • collector

    • host

    • remote-source

  • user_id (string) – The user ID of the user asset being elaborated.

  • user_name (string) – The user name of the user asset being elaborated.

  • uuid (string) – The UUID of the asset type being elaborated. The host UUID for a host is the UUID issued to its associated agent or appliance, and contained in its agent certificate.

Return type

dict

Returns

Response Syntax

{
    'deployment': {},
    'key': 'string',
    'type': 'string',
    '{type}': {
        '{key}': {
            'asset': {},
            'related': {}
        }
    }
}

Response Definitions

  • deployment (dict) –

  • key (string) –

  • type (string) –

  • {type} (dict) –

    • {key} (dict) –

      • asset (dict) –

      • related (dict) –

get_asset_details_post(**kwargs)

Fetches details and elaborations about individual assets and their surroundings, such as complete asset details or an asset’s network neighborhood or connectivity. The request body json for different details operations are grouped together:

To get details of an asset by type, key, deployment, and region, specify the following request body fields:

  • type (must be host)

  • key

  • deployment

  • region

To get details of an asset by type and deployment, specify the following request body fields:

  • type (must be deployment)

  • deployment

To get details of an asset by appliance_uuid and ip_address, specify the following request body fields:

  • appliance_uuid

  • ip_address

  • port (optional, always provide if available)

To get details of an asset by type and uuid, specify the following request body fields:

  • type (default: any)

  • uuid

To get details of an asset by deployment, ip address and network, specify the following request body fields:

  • deployment

  • ip_address

  • network

To get details of an asset by user_id, specify the following request body fields:

  • user_id (note that this query will execute an exact match and will not normalize the input while searching)

To get details of an asset by deployment and user_id, specify the following request body fields:

  • deployment

  • user_id (note that this query will execute an exact match and will not normalize the input while searching)

To get details of an asset by user_name, specify the following request body fields:

  • user_name (note that this query will execute an exact match and will not normalize the input while searching)

To get details of an asset by deployment and user_id, specify the following request body fields:

  • deployment

  • user_name (note that this query will execute an exact match and will not normalize the input while searching)

Note that when calling this endpoint with query options deployment, network and ip_address set, if a host is found, any subnet that the host isn’t related to but it could be (the IP address matches the subnet mask) the additional unrelated subnet(s) will be returned under the subnet key in the response.

Request Syntax

response = client.get_asset_details_post(
    account_id='string'
    data='dict'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • data (dict) –

Return type

dict

Returns

Response Syntax

{
    'deployment': {},
    'key': 'string',
    'type': 'string',
    '{type}': {
        '{key}': {
            'asset': {},
            'related': {}
        }
    }
}

Response Definitions

  • deployment (dict) –

  • key (string) –

  • type (string) –

  • {type} (dict) –

    • {key} (dict) –

      • asset (dict) –

      • related (dict) –

get_deployment_exposures_summary(**kwargs)

Get a summary of exposures by asset type for the given account and deployment ID.

Request Syntax

response = client.get_deployment_exposures_summary(
    account_id='string'
    asset_type='string'
    deployment_id='string'
    disposed='true'|'false'|'all'
    filter=[
        'None'
    ]
    scope='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • asset_type (string) –

    [REQUIRED]

    A valid asset type, e.g. deployment, vpc, host.

  • deployment_id (string) –

    [REQUIRED]

    The ID of the deployment source as represented in the deployments service (uppercase UUID).

  • disposed (string) –

    Filters remediations included in the summary based on the state of vulnerabilities. Possible values are:

    • true - only disposed

    • false - only not disposed

    • all - both

    Valid values: true, false, all

    Default: false

  • filter (list) – Filters that assets/vulnerabilities must match to be included in the exposures summary. filters can be chained together (applied using AND). Generally, any remediation filters should work, but category and severity are the most likely useful filters for this view.

  • scope (boolean) –

    Whether to apply scope when gathering assets to include in the report.

    Default: True

Return type

dict

Returns

Response Syntax

{
    'exposures': [
        'None'
    ],
    'summary': {
        'all': 'integer',
        'high': 'integer',
        'info': 'integer',
        'low': 'integer',
        'medium': 'integer'
    }
}

Response Definitions

  • exposures (list) –

    Array of summarized exposures objects.

  • summary (dict) –

    • all (integer) –

    • high (integer) –

    • info (integer) –

    • low (integer) –

    • medium (integer) –

get_exposures_summary(**kwargs)

Get a summary of exposures by asset type for the given account, across all deployments.

Request Syntax

response = client.get_exposures_summary(
    account_id='string'
    asset_type='string'
    disposed='true'|'false'|'all'
    filter=[
        'None'
    ]
    scope='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • asset_type (string) –

    [REQUIRED]

    A valid asset type, e.g. deployment, vpc, host.

  • disposed (string) –

    Filters remediations included in the summary based on the state of vulnerabilities. Possible values are:

    • true - only disposed

    • false - only not disposed

    • all - both

    Valid values: true, false, all

    Default: false

  • filter (list) –

    Filters that assets/vulnerabilities must match to be included in the exposures summary. filters can be chained together (applied using AND). Generally, any remediation filters should work, but category and severity are the most likely useful filters for this view.

  • scope (boolean) –

    Whether to apply scope when gathering assets to include in the report.

    Default: True

Return type

dict

Returns

Response Syntax

{
    'exposures': [
        'None'
    ],
    'summary': {
        'all': 'integer',
        'high': 'integer',
        'info': 'integer',
        'low': 'integer',
        'medium': 'integer'
    }
}

Response Definitions

  • exposures (list) –

    Array of summarized exposures objects.

  • summary (dict) –

    • all (integer) –

    • high (integer) –

    • info (integer) –

    • low (integer) –

    • medium (integer) –

get_tags_summary(**kwargs)

Get a summary of all tags, with normalized keys, across all deployments. This endpoint should be preferred for use-cases that span deployments, like asset groups.

Request Syntax

response = client.get_tags_summary(
    account_id='string'
    include_tagged_assets='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • include_tagged_assets (boolean) –

    When true, causes the inclusion of tagged assets in the result. The single-column rows become two-column rows and the data map includes tagged assets with keys in the form deployment_id:type:key.

    Default: False

Return type

dict

Returns

Response Syntax

{
    'tags': [
        {
            'deployment_id': 'string',
            'key': 'string',
            'tags': {},
            'type': 'string'
        }
    ]
}

Response Definitions

  • tags (list) –

    Array of summarized tags objects.

    • (dict) –

      • deployment_id (string) –

        Deployment ID

      • key (string) –

        Asset Key

      • tags (dict) –

        Object containing the tag name as keys and their descriptions as values.

      • type (string) –

        Asset Type

get_tags_summary_deprecated(**kwargs)

Get a summary of all tags in a deployment. Returns a list of (minimal) assets with their tags.

Request Syntax

response = client.get_tags_summary_deprecated(
    account_id='string'
    deployment_id='string'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • deployment_id (string) –

    [REQUIRED]

    The ID of the deployment source as represented in the deployments service (uppercase UUID).

Return type

dict

Returns

Response Syntax

{
    'tags': [
        {
            'deployment_id': 'string',
            'key': 'string',
            'tags': {},
            'type': 'string'
        }
    ]
}

Response Definitions

  • tags (list) –

    Array of summarized tags objects.

    • (dict) –

      • deployment_id (string) –

        Deployment ID

      • key (string) –

        Asset Key

      • tags (dict) –

        Object containing the tag name as keys and their descriptions as values.

      • type (string) –

        Asset Type

list_asset_groups(**kwargs)

Disclaimer: This endpoint is currently under development. The request parameters, response format or the endpoint itself may be changed or removed at any time without notice.

List asset groups for given account.

Request Syntax

response = client.list_asset_groups(
    account_id='string'
    return_all_properties='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • return_all_properties (boolean) –

    When true, causes the inclusion of all asset properties in the response. By default, the assets in the response only includes summary properties.

    Default: False

Return type

dict

Returns

Response Syntax

{
    'count': 'integer',
    'groups': [
        {
            'membership_counts': {
                'all': 'integer'
            }
        }
    ]
}

Response Definitions

  • count (integer) –

    The count of groups in the response.

  • groups (list) –

    An array group objects. Each element in the array is an asset group.

    • (dict) –

      Group object.

      • membership_counts (dict) –

        An object of counts keyed by asset type, as well as an all sum of the counts for all types.

        • all (integer) –

          A sum of all asset type counts.

overview_topology(**kwargs)

Render overview topology data for the given account and deployment.

Request Syntax

response = client.overview_topology(
    account_id='string'
    category='string'
    deployment_id='string'
    disposed='true'|'false'|'all'
    extras='string'
    scope='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • category (string) – When computing threatiness, only include vulnerabilities related to assets if those vulnerabilities include the given category.

  • deployment_id (string) –

    [REQUIRED]

    The ID of the deployment source as represented in the deployments service (uppercase UUID).

  • disposed (string) –

    Filters remediations included in the summary based on the state of vulnerabilities. Possible values are:

    • true - only disposed

    • false - only not disposed

    • all - both

    Valid values: true, false, all

    Default: false

  • extras (string) – A comma-delimited list of asset types to fetch in addition to the base topology.

  • scope (boolean) –

    Whether to apply scope when gathering assets to include in the report.

    Default: True

Return type

dict

Returns

Response Syntax

{
    'topology': {
        'asset_counts_by_type': {
            'host': {
                'agent': 'integer',
                'all': 'integer',
                'appliance': 'integer',
                'running': 'integer'
            },
            'subnet': {
                'all': 'integer',
                'security': 'integer',
                'standard': 'integer'
            }
        },
        'assets': [
            'None'
        ],
        'data': {},
        'extras': 'string',
        'rows': 'integer'
    }
}

Response Definitions

  • topology (dict) –

    • asset_counts_by_type (dict) –

      A map of asset counts by asset type. The special key all is always present and includes the counts of all assets. Note that while the value for most asset types is an integer, some asset types (such as host) contain an object with further broken down counts. In that case, the special sub-property all is always present, and will contain the total number of all assets of that type.

      • host (dict) –

        The host count data, keyed by host properties.

        • agent (integer) –

          The total count of all hosts that have the alertlogic_agent property set, which indicates that the host has an Alert Logic agent installed on it.

        • all (integer) –

          The total count of all unique host assets in the response.

        • appliance (integer) –

          The total count of all hosts that have the alertlogic_appliance property set, which indicates that the host is an Alert Logic appliance.

        • running (integer) –

          The total count of all running hosts in the response (excluding appliances). This is extrapolated from the state property of each host. Assets are considered “running” if their state is equal to running, succeeded, or ok.

      • subnet (dict) –

        The subnet count data, keyed by subnet properties.

        • all (integer) –

          The total count of all unique subnet assets in the response.

        • security (integer) –

          The total count of all subnet that have the alertlogic_security property set, which indicates that the subnet is an Alert Logic security subnet (which contains Alert Logic appliances).

        • standard (integer) –

          The total count of all subnet that do not have the alertlogic_security property set, which indicates that the subnet is a standard customer subnet.

    • assets (list) –

      An array of arrays of asset references. Each element in the array is an array of asset references (that can be resolved by looking up the reference in the topology.data object) that describe relationship sequences: region, vpc, subnet, host. Partial rows contain null entries.

    • data (dict) –

      An object containing all of the asset details for asset references in the topology.assets and topology.extras properties. The object keys are asset references produced by colon-joining asset type and asset key, e.g., region:/aws/us-east-1.

    • extras (string) –

      An array of arrays of asset references. Each element in the array is an array of asset references (that can be resolved by looking up the reference in the topology.data object) that describe relationship sequences: host, <extra>. The first element is always a host reference, and the second entry is a reference to an extra asset related to that host.

    • rows (integer) –

      The count of rows in the topology.assets array.

preview_topology(**kwargs)

Disclaimer: This endpoint is currently under development. The request parameters, response format or the endpoint itself may be changed or removed at any time without notice.

Render asset group topology data for the given account. The asset group can be defined by either a list of scopes that include/exclude assets, or a union or intersection of the set of assets in a list of existing nested groups. The response body shares the same format for both types of asset groups.

In either case, a return_asset_types property can be provided that limits the previewed asset group results to the types in the list and all topological ancestor types of the listed types. Although the preview can be limited using the return_asset_types property, the actual asset group that is created using the other parameters will not have be limited to that list of types.

Note that some assets in the topology.data object contain references to non-topologically related assets in the asset model that may be filtered on. For example, a host asset 814C2911-09BB-1005-9916-7831C1BAC182:host:/aws/us-east-1/host/web-1a-1 might contain an image property with an array of keys, like /aws/us-east-1/image/ami-1. These properties indicate that the assets can be filtered (via include/exclude in scopes), for example, placing the filter host.image:/aws/us-east-1/image/ami-1 in the include of an asset-group scope would result in all hosts related to that image being included in the asset-group. These related assets are also included in the topology.data object, and can be found by constructing their data key, e.g., 814C2911-09BB-1005-9916-7831C1BAC182:image:/aws/us-east-1/image/ami-1. Here are the non-topological filters by asset type:

Asset Type

Filter Label

Note

cloud-trail

s3-bucket

external-dns-name

deployment

external-dns-name

region

external-dns-name

vpc

external-dns-name

host

external-dns-name

load-balancer

external-ip

deployment

external-ip

region

external-ip

vpc

external-ip

host

external-ip

load-balancer

host

application

applications are not in the data object

host

auto-scaling-group

host

image

host

instance-profile

host

launch-config

host

load-balancer

host

sg

instance-profile

role

load-balancer

subnet

load-balancer

sg

role

s3-bucket

user

group

volume

host

Request Syntax

response = client.preview_topology(
    account_id='string'
    groups=[
        'None'
    ]
    groups_match='all'|'any'
    return_asset_types=[
        'string'
    ]
    scopes=[
        {
            'asset_types': [
                'None'
            ],
            'exclude': [
                'None'
            ],
            'include': [
                'None'
            ]
        }
    ]
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • groups (list) – A list of nested groups that make up the group. These groups can have disjoint or intersecting sets of assets. The groups can also include other groups with nested groups.

  • groups_match (string) –

    The criteria for inclusion of nested group assets in the previewed group. If the value is any, any asset in ANY of the nested groups will be included in the previewed group. If the value is all, any asset in common to ALL of the nested groups will be included in the previewed group.

    Valid values: all, any

  • return_asset_types (list) –

    A list of groupable asset types that limits the exploration of the asset model. The types specified in this list, as well as their topological ancestor types, are the only ones that will be returned in the resulting topology.assets rows.

    • (string) –

  • scopes (list) –

    The list of request scopes, each containing a scope definition that will be ORed together.

    • (dict) –

      • asset_types (list) –

        A list of asset types that determines the assets included in the individual scope. If an asset would be included in multiple scopes, the scopes’ allowed asset types are unioned together.

      • exclude (list) –

        A list of scope filters, ANDed together, that determine if an asset should NOT be included in the resulting asset group.

      • include (list) –

        A list of scope filters, ANDed together, that determine if an asset should be included in the resulting asset group.

Return type

dict

Returns

Response Syntax

{
    'topology': {
        'assets': [
            'None'
        ],
        'data': {},
        'rows': 'integer'
    }
}

Response Definitions

  • topology (dict) –

    The primary key of the API response.

    • assets (list) –

      An array of arrays of asset references. Each element in the array is an array of asset references (that can be resolved by looking up the reference in the topology.data object) that describe topological relationship sequences. Note that all groupable assets are returned in the rows, but the topology.data object must be consulted for each asset to determine its inclusion or exclusion from the group. Intermediate topology assets do not have their own row in the result (a VPC with subnets would not have an entry, but a VPC without subnets would have an entry).

    • data (dict) –

      An object containing all of the asset details for asset references in the topology.assets. The object keys are asset references produced by colon-joining deployment ID, asset type and asset key, e.g., 814C2911-09BB-1005-9916-7831C1BAC182:region:/aws/us-east-1.

      All assets are decorated with a few additional properties:

      1. A group_membership property that must be consulted to determine membership in the group. Possible values are described below:

      EXPLICIT_IN - The asset is included in the group by scope definition. This status is returned for the first assets in the asset topology that match all of the inclusion filters for scope in scoped groups, and the only IN membership type for groups with nested groups.

      INHERIT_IN - The asset is included in the group by scope definition. This status is returned for any topological successor asset of an asset with the EXPLICIT_IN group membership that meets the exclusion criteria. This membership type is not returned for assets in a group with nested groups.

      CONTAINS - The asset does not meet the full criteria for inclusion in the group, but contains at least one successor asset in the group.

      CAN_CONTAIN - The asset does not meet the full criteria for inclusion in the group. The scope definition does allow this asset to potentially include future successors in the group.

      EXPLICIT_EXCLUDED - The asset is excluded from the group by scope definition. This status is returned for the first assets in the asset topology that match any exclusion filters for scope in scoped groups.

      INHERIT_EXCLUDED - The asset is excluded from the group by scope definition. This status is returned for any topological successor asset of an asset with the EXPLICIT_EXCLUDED group membership. This membership type is not returned for assets in a group with nested groups.

      NOT_IN - The asset does not meet all criteria for inclusion in the group by scope definition, but is not explicitly excluded.

      1. A membership_counts object containing keys of asset types and an object value of in and not_in counts for topological child types. If an asset has no topological children but is of a type that could have topological children (e.g. a region that currently does not have any declared vpcs yet), the membership_counts object may be an empty object {}.

    • rows (integer) –

      The count of rows in the topology.assets array.

query_assets(**kwargs)

Return a list of related assets.

Request Syntax

response = client.query_assets(
    account_id='string'
    asset_types='string'
    filter={}
    filter_relationships={}
    include_alertlogic_security='False|True'
    qfields='string'
    query_format='v1'|'v2'
    reduce='False|True'
    return_count='False|True'
    return_types='string'
    scope='False|True'
    topo_chain='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • asset_types (string) – A query string parameter representing the types of assets to retrieve, as described in Typed queries. tag asset type is handled specially and, if used, may only be the last asset type.]

  • filter (dict) – Filters and variables, as described in Filtering assets.

  • filter_relationships (dict) – A constraint on the existence of a relationship between the given asset types. The lefthand asset_type must be present in the asset_types parameter. If set to true, only rows with an asset of the given asset_type that is related to one or more assets of the related_asset_type will be returned. If set to false, only rows with an asset of the given asset_type that is not related to one or more assets of the related_asset_type will be returned.

  • include_alertlogic_security (boolean) –

    Flag that determines whether to include hosts with the alertlogic_security property set to true (that is, hosts that are Alert Logic appliances) when scope is set to true. By default, these appliances are not returned in query results when scope is set to true. If include_alertlogic_security is set to true and scope is set to true, then the default behavior will be overridden, and Alert Logic appliance hosts will be included in scope (if they are in scope).

    Default: False

  • qfields (string) – Optional comma-separated list of fields to be returned as part of the objects. key, type and deployment_id are always returned. Both &qfields=object.field and &qfields=field are acceptable; in the latter case all objects will be filtered.

  • query_format (string) –

    A query string parameter that defines what query syntax is used. (default: v1)

    Valid values: v1, v2

  • reduce (boolean) – Callers should pass reduce=true to reduce repeated assets in the return data when possible. (default: false)

  • return_count (boolean) – Execute the query and return a single matching row count instead of the assets data itself. (default: false)

  • return_types (string) – A query string parameter representing the names of assets in asset_types to retrieve. The types are a comma-separated list of asset names that must be a subset of the names in asset_types. When return_types is provided, only the specified subset of asset_types is returned in each row. For example, if asset_types is h:host,s:subnet,v:vpc and return_types is h,s, assets will query for rows matching host,subnet,vpc but will only return the first two columns of each row in the result. This can be used to require relationships and provide filters around them without actually requiring that the data be returned.

  • scope (boolean) –

    Flag that determines whether to apply deployment scope when gathering assets for the query. If set to true, only assets in the deployment scope will be returned in the query results.

    Default: False

  • topo_chain (boolean) –

    Flag designed to modify the behavior of the Assets Query finder. If set to true (default), it will find the assets by its topological path (deployment -> region -> vpc -> …). If set to false, it will retrieve all matching assets regardless of their topology path. Note that topo_chain=false may include assets with broken path to the response (e.g. a host without a relationship to a subnet).

    Default: True

Return type

dict

Returns

Response Syntax

{
    'assets': [
        [
            {
                'account_id': 'string',
                'created_on': 'number',
                'deployment_id': 'string',
                'key': 'string',
                'modified_on': 'number',
                'name': 'string',
                'type': 'string',
                'version': 'number'
            }
        ]
    ],
    'rows': 'integer'
}

Response Definitions

  • assets (list) –

    • (list) –

      • (dict) –

        • account_id (string) –

          AIMS account ID

        • created_on (number) –

          Milliseconds since Unix Epoch

        • deployment_id (string) –

          Deployment ID

        • key (string) –

          Asset Key

        • modified_on (number) –

          Milliseconds since Unix Epoch

        • name (string) –

          Asset Name

        • type (string) –

          Asset Type

        • version (number) –

          Object Version

  • rows (integer) –

query_deployment_assets(**kwargs)

Return a list of related assets in a single deployment.

Request Syntax

response = client.query_deployment_assets(
    account_id='string'
    asset_types='string'
    deployment_id='string'
    filter={}
    filter_relationships={}
    include_alertlogic_security='False|True'
    qfields='string'
    query_format='v1'|'v2'
    reduce='False|True'
    return_count='False|True'
    return_types='string'
    scope='False|True'
    topo_chain='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • asset_types (string) –

    A query string parameter representing the types of assets to retrieve, as described in Typed queries. tag asset type is handled specially and, if used, may only be the last asset type.]

  • deployment_id (string) –

    [REQUIRED]

    The ID of the deployment source as represented in the deployments service (uppercase UUID).

  • filter (dict) –

    Filters and variables, as described in Filtering assets.

  • filter_relationships (dict) – A constraint on the existence of a relationship between the given asset types. The lefthand asset_type must be present in the asset_types parameter. If set to true, only rows with an asset of the given asset_type that is related to one or more assets of the related_asset_type will be returned. If set to false, only rows with an asset of the given asset_type that is not related to one or more assets of the related_asset_type will be returned.

  • include_alertlogic_security (boolean) –

    Flag that determines whether to include hosts with the alertlogic_security property set to true (that is, hosts that are Alert Logic appliances) when scope is set to true. By default, these appliances are not returned in query results when scope is set to true. If include_alertlogic_security is set to true and scope is set to true, then the default behavior will be overridden, and Alert Logic appliance hosts will be included in scope (if they are in scope).

    Default: False

  • qfields (string) – Optional comma-separated list of fields to be returned as part of the objects. key, type and deployment_id are always returned. Both &qfields=object.field and &qfields=field are acceptable; in the latter case all objects will be filtered.

  • query_format (string) –

    A query string parameter that defines what query syntax is used. (default: v1)

    Valid values: v1, v2

  • reduce (boolean) – Callers should pass reduce=true to reduce repeated assets in the return data when possible. (default: false)

  • return_count (boolean) – Execute the query and return a single matching row count instead of the assets data itself. (default: false)

  • return_types (string) – A query string parameter representing the names of assets in asset_types to retrieve. The types are a comma-separated list of asset names that must be a subset of the names in asset_types. When return_types is provided, only the specified subset of asset_types is returned in each row. For example, if asset_types is h:host,s:subnet,v:vpc and return_types is h,s, assets will query for rows matching host,subnet,vpc but will only return the first two columns of each row in the result. This can be used to require relationships and provide filters around them without actually requiring that the data be returned.

  • scope (boolean) –

    Flag that determines whether to apply deployment scope when gathering assets for the query. If set to true, only assets in the deployment scope will be returned in the query results.

    Default: False

  • topo_chain (boolean) –

    Flag designed to modify the behavior of the Assets Query finder. If set to true (default), it will find the assets by its topological path (deployment -> region -> vpc -> …). If set to false, it will retrieve all matching assets regardless of their topology path. Note that topo_chain=false may include assets with broken path to the response (e.g. a host without a relationship to a subnet).

    Default: True

Return type

dict

Returns

Response Syntax

{
    'assets': [
        [
            {
                'account_id': 'string',
                'created_on': 'number',
                'deployment_id': 'string',
                'key': 'string',
                'modified_on': 'number',
                'name': 'string',
                'type': 'string',
                'version': 'number'
            }
        ]
    ],
    'rows': 'integer'
}

Response Definitions

  • assets (list) –

    • (list) –

      • (dict) –

        • account_id (string) –

          AIMS account ID

        • created_on (number) –

          Milliseconds since Unix Epoch

        • deployment_id (string) –

          Deployment ID

        • key (string) –

          Asset Key

        • modified_on (number) –

          Milliseconds since Unix Epoch

        • name (string) –

          Asset Name

        • type (string) –

          Asset Type

        • version (number) –

          Object Version

  • rows (integer) –

query_exposures(**kwargs)

Groups vulnerabilities for an account by exposure (by default), remediation, or vulnerable asset. In combination with filtering, it’s easy to view vulnerabilities across your account in the manner most appropriate.

Note: exposures uses a threatiness property which is an internal measurement used for relative comparison and is not considered useful to customers.

Vulnerabilities can be filtered using the filter parameter in the query string. The filter param can be used multiple times. The remediation filters documented above are allowed.

Request Syntax

response = client.query_exposures(
    account_id='string'
    concluded='true'|'false'|'all'
    details='False|True'
    disposed='true'|'false'|'all'
    filter=[
        'None'
    ]
    group='asset'|'exposure'|'remediation'
    include_exposures='False|True'
    include_filters='False|True'
    include_remediation_items='False|True'
    include_remediations='False|True'
    limit='integer'
    scope='False|True'
    sort='asset_count'|'exposures_count'|'severity'|'threatiness'|'vinstances_count'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • concluded (string) –

    Filters remediations included in the summary based on the state of vulnerabilities. Possible values are:

    • true - only concluded

    • false - only not concluded

    • all - both

    Valid values: true, false, all

    Default: false

  • details (boolean) –

    Controls whether vinstances are returned in the response body. Only valid if group is not asset.

    Default: False

  • disposed (string) –

    Filters remediations included in the summary based on the state of vulnerabilities. Possible values are:

    • true - only disposed

    • false - only not disposed

    • all - both

    Valid values: true, false, all

    Default: false

  • filter (list) –

    A filter to apply to the assets for which remediations and vulnerabilities are being requested. Multiple filter parameters may be supplied. The section on remediation filters above covers them in detail. Note: hosts may be used as filters (e.g. filter=host:/aws/us-east-1/host/i-1234567), which will restrict the scope of the remediations return to just the single host key provided. However, hosts will not be returned as filters in remediations responses (returning all hosts as filters would be untenable in a deployment of significant size).

  • group (string) –

    The object type to arrange the vulnerabilities in the response by. Allowed values are:

    • asset: group vulnerabilities by vulnerable asset

    • exposure: group vulnerabilities by exposure

    • remediation: group vulnerabilities by remediation

    Valid values: asset, exposure, remediation

    Default: remediation

  • include_exposures (boolean) –

    Controls whether exposures are returned in the response body. Only valid if group is exposure or asset.

    Default: True

  • include_filters (boolean) –

    Controls whether filters are returned.

    Default: True

  • include_remediation_items (boolean) –

    Controls whether remediation_items are returned in the response body.

    Default: False

  • include_remediations (boolean) –

    Controls whether remediations are returned.

    Default: True

  • limit (integer) – If given, limit the returned results to the first N items. The summary and filters, if returned, will be computed exclusively from the limited results (not the full result set). Note that it limits the number of exposures/remediations returned, but that the summary counts are generated based on the full data set before applying the limit.

  • scope (boolean) –

    Whether to apply scope when gathering assets to include in the report.

    Default: True

  • sort (string) –

    Controls how to order the exposures/remediations. Must be a CSV of at least one of the allowed values. Note that asset_count will not work with group=asset.

    Valid values: asset_count, exposures_count, severity, threatiness, vinstances_count

    Default: severity,threatiness

Return type

dict

Returns

Response Syntax

{
    'exposures': {
        'assets': [
            {}
        ],
        'rows': 'integer'
    },
    'exposures_count': 'integer',
    'filters': [
        {}
    ],
    'remediations': {
        'assets': [
            {}
        ],
        'rows': 'integer'
    },
    'summary': {
        'severities': {
            'high': 'integer',
            'info': 'integer',
            'low': 'integer',
            'medium': 'integer'
        }
    }
}

Response Definitions

  • exposures (dict) –

    In the response when group is exposures or not set.

    • assets (list) –

      List of exposures assets.

      • (dict) –

    • rows (integer) –

      Count of exposures assets returned.

  • exposures_count (integer) –

    Count of exposures. Not present when group is not exposures.

  • filters (list) –

    • (dict) –

      Filter item.

  • remediations (dict) –

    In the response when group is remediations.

    • assets (list) –

      List of remediation assets.

      • (dict) –

    • rows (integer) –

      Count of remediation assets returned.

  • summary (dict) –

    • severities (dict) –

      • high (integer) –

      • info (integer) –

      • low (integer) –

      • medium (integer) –

query_exposures_post(**kwargs)

Groups vulnerabilities for an account by exposure (by default), remediation, or vulnerable asset. In combination with filtering, it’s easy to view vulnerabilities across your account in the manner most appropriate.

Note: exposures uses a threatiness property which is an internal measurement used for relative comparison and is not considered useful for external purposes.

Vulnerabilities can be filtered using the filter parameter in the query string. The filter param can be used multiple times. The remediation filters documented above are allowed.

Request Syntax

response = client.query_exposures_post(
    account_id='string'
    concluded='true'|'false'|'all'
    details='False|True'
    disposed='true'|'false'|'all'
    filters=[
        'string'
    ]
    group='asset'|'exposure'|'remediation'
    include_exposures='False|True'
    include_remediation_items='False|True'
    included_filters='False|True'
    included_remediations='False|True'
    limit='integer'
    scope='False|True'
    sort='asset_count'|'exposures_count'|'severity'|'threatiness'|'vinstances_count'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • concluded (string) –

    Filters remediations included in the summary based on the state of vulnerabilities. Possible values are:

    • true - only concluded

    • false - only not concluded

    • all - both

    Valid values: true, false, all

    Default: false

  • details (boolean) –

    Controls whether vinstances are returned in the response body. Only valid if group is not asset.

    Default: False

  • disposed (string) –

    Filters remediations included in the summary based on the state of vulnerabilities. Possible values are:

    • true - only disposed

    • false - only not disposed

    • all - both

    Valid values: true, false, all

    Default: false

  • filters (list) –

    A filter to apply to the assets for which remediations and vulnerabilities are being requested. Multiple filter parameters may be supplied. The section on remediation filters above covers them in detail. Note: hosts may be used as filters (e.g. filter=host:/aws/us-east-1/host/i-1234567), which will restrict the scope of the remediations return to just the single host key provided. However, hosts will not be returned as filters in remediations responses (returning all hosts as filters would be untenable in a deployment of significant size).

    • (string) –

  • group (string) –

    The object type to arrange the vulnerabilities in the response by. Allowed values are:

    • asset: group vulnerabilities by vulnerable asset

    • exposure: group vulnerabilities by exposure

    • remediation: group vulnerabilities by remediation

    Valid values: asset, exposure, remediation

    Default: remediation

  • include_exposures (boolean) –

    Controls whether exposures are returned in the response body. Only valid if group is exposure or asset.

    Default: True

  • include_remediation_items (boolean) –

    Controls whether remediation_items are returned in the response body.

    Default: False

  • included_filters (boolean) –

    Controls whether filters are returned.

    Default: True

  • included_remediations (boolean) –

    Controls whether remediations are returned.

    Default: True

  • limit (integer) – If given, limit the returned results to the first N items. The summary and filters, if returned, will be computed exclusively from the limited results (not the full result set). Note that it limits the number of exposures/remediations returned, but that the summary counts are generated based on the full data set before applying the limit.

  • scope (boolean) –

    Whether to apply scope when gathering assets to include in the report.

    Default: True

  • sort (string) –

    Controls how to order the exposures/remediations. Must be a CSV of at least one of the allowed values. Note that asset_count will not work with group=asset.

    Valid values: asset_count, exposures_count, severity, threatiness, vinstances_count

    Default: severity,threatiness

Return type

dict

Returns

Response Syntax

{
    'exposures': {
        'assets': [
            {}
        ],
        'rows': 'integer'
    },
    'exposures_count': 'integer',
    'filters': [
        {}
    ],
    'remediations': {
        'assets': [
            {}
        ],
        'rows': 'integer'
    },
    'summary': {
        'severities': {
            'high': 'integer',
            'info': 'integer',
            'low': 'integer',
            'medium': 'integer'
        }
    }
}

Response Definitions

  • exposures (dict) –

    In the response when group is exposures or not set.

    • assets (list) –

      List of exposures assets.

      • (dict) –

    • rows (integer) –

      Count of exposures assets returned.

  • exposures_count (integer) –

    Count of exposures. Not present when group is not exposures.

  • filters (list) –

    • (dict) –

      Filter item.

  • remediations (dict) –

    In the response when group is remediations.

    • assets (list) –

      List of remediation assets.

      • (dict) –

    • rows (integer) –

      Count of remediation assets returned.

  • summary (dict) –

    • severities (dict) –

      • high (integer) –

      • info (integer) –

      • low (integer) –

      • medium (integer) –

query_remediation_items(**kwargs)

Gets a list of remediation-items and an aggregation of filters associated with those remediation items. Filters similar to those in the Query Assets endpoint can be used with an item named remediation-item. The filters field in the output is the union of all filters fields in all the returned remediation items.

Note that the returned remediation-item can also be filtered by various direct properties:

  • audit_id: If the audit_ids param is passed, return only remediation-items that match one of the given audit_ids.

  • deployment_id: If the deployment_ids param is passed, return only remediation-items that match one of the given deployment_ids.

  • remediation_id: If the remediation_ids param is passed, return only remediation-items that match one of the given remediation_ids.

  • item_id: If the remediation_item_ids param is passed, return only remediation-items that match one of the given item_ids.

  • vulnerability_id: If the vulnerability_ids param is passed, return only remediation-items that match one of the given vulnerability_ids.

  • The associated remediation_item_id is rendered on vinstances. Note: details=true is required to see vinstances on exposures.

Request Syntax

response = client.query_remediation_items(
    account_id='string'
    audit_ids='string'
    deployment_ids='string'
    details='False|True'
    filter=[
        'None'
    ]
    group_by_audit_id='False|True'
    include_exposures='False|True'
    include_filters='False|True'
    remediation_ids='string'
    remediation_item_ids='string'
    state='string'
    vulnerability_ids='string'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • audit_ids (string) – A comma-separated list of audit_ids.

  • deployment_ids (string) – A comma-separated list of deployment IDs.

  • details (boolean) –

    Controls whether vinstances are returned in the response (inside each exposure in the exposures property of each remediation-item. In order to work, include_exposures must be set to true.

    Default: False

  • filter (list) –

    A filter to apply to the remediation-items in the account. Multiple filter parameters may be supplied. These filters are matched against the filters property of the remediation-item asset; all given filters must match). Note that the category filter is applied to exposures associated with each remediation-item, not applied to the remediation-item asset directly; the remediation-item will be included in the result if the combined categories of all exposures attached to the remediation-item match the category filter. See the section on remediation filters which covers filters in detail.

  • group_by_audit_id (boolean) –

    Group returned remediation-items by their audit_id and unique vulnerability_id/remediation_id. That is, if multiple remediation-items were disposed or concluded in a single request across distinct deployment_ids and filters sets, display these as a single record. Note that when this option is set to true, the following changes are applied to the response elements:

    • All unique deployment_id attributes are stored in a deployment_ids array.

    • All item_id attributes are stored in an item_ids array.

    • All key attributes are stored in a keys array.

    • categories is rendered as the union of all the categories for all the remediation-items in each group.

    • filters is rendered as the union of all the filters for all the remediation-items in each group.

    • exposures from all remediation-items are appended together.

    • asset_count, exposures_count, severities, and vinstances_count are all summed across all grouped remediation-items.

    Default: False

  • include_exposures (boolean) –

    Controls whether exposures are returned in each remediation-item in the response.

    Default: True

  • include_filters (boolean) –

    Controls whether filters are returned.

    Default: True

  • remediation_ids (string) – A comma-separated list of remediation IDs.

  • remediation_item_ids (string) – A comma-separated list of remediation-item IDs.

  • state (string) – A comma-separated list of remediation-item states. If provided, only include remediation-items in any of the given states in the response.

  • vulnerability_ids (string) – A comma-separated list of vulnerability IDs.

Return type

dict

Returns

Response Syntax

{
    'filters': [
        'None'
    ],
    'remediation-items': {
        'assets': {
            'asset_count': 'integer',
            'exposures': [
                {
                    'asset_count': 'integer',
                    'vinstances': [
                        'None'
                    ],
                    'vinstances_count': 'integer',
                    'vulnerability_id': 'string'
                }
            ],
            'filters': [
                'None'
            ],
            'remediation': {},
            'remediation_id': 'string',
            'vinstances_count': 'integer',
            'vulnerability': {}
        }
    },
    'rows': 'integer',
    'summary': {
        'severities': {}
    }
}

Response Definitions

  • filters (list) –

    An array of filter strings. This is the union of all filters in the remediation-items returned in the remediation-items.assets field. See the filters documentation.

  • remediation-items (dict) –

    An object containing the remediation-items in the response and their count.

    • assets (dict) –

      A list of objects representing remediation-item assets. Each asset represents a single remediation-item.

      • asset_count (integer) –

        The number of unique assets with an exposure associated to the remediation-item.

      • exposures (list) –

        A list of exposures associated to the remediation-item by remediation ID or vulnerability ID.

        • (dict) –

          • asset_count (integer) –

            The number of unique assets with an exposure associated to the exposure.

          • vinstances (list) –

            A list of vinstance objects associated to the exposure which describe the vulnerable asset. Only present when the details query parameter is set to true.

          • vinstances_count (integer) –

            The total number of vulnerable assets associated to the exposure.

          • vulnerability_id (string) –

            The vulnerability ID of the exposure.

      • filters (list) –

        An array of filter strings applied to the remediation-item. See the filters documentation.

      • remediation (dict) –

        The remediation that the remediation-item is associated to. This is present regardless of whether the remediation-item disposes exposures by remediation ID or vulnerability ID.

      • remediation_id (string) –

        The remediation ID that the remediation-item is associated to. This is only present if the remediation-item disposes exposures by remediation ID.

      • vinstances_count (integer) –

        The total number of vulnerable assets associated to the remediation-item.

      • vulnerability (dict) –

        The vulnerability that the remediation-item is associated to. This is only present if the remediation-item disposes exposures by vulnerability ID.

  • rows (integer) –

    The number of rows in the assets list.

  • summary (dict) –

    A summary of the exposures included in the response

    • severities (dict) –

      A summary of the total count of all exposures (vinstances) in all remediation-items returned in the response, counted by severity (the all sub-property contains the full count of all the other severities combined)

query_topology(**kwargs)

Query given deployment assets topology.

Request Syntax

response = client.query_topology(
    account_id='string'
    deployment_id='string'
    disposed='true'|'false'|'all'
    extras='string'
    include_filters='False|True'
    include_remediations='False|True'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • deployment_id (string) –

    [REQUIRED]

    The ID of the deployment source as represented in the deployments service (uppercase UUID).

  • disposed (string) –

    Filters remediations included in the summary based on the state of vulnerabilities. Possible values are:

    • true - only disposed

    • false - only not disposed

    • all - both

    Valid values: true, false, all

    Default: false

  • extras (string) – A comma-delimited list of asset types to fetch in addition to the base topology.

  • include_filters (boolean) –

    Controls whether filters are returned.

    Default: True

  • include_remediations (boolean) –

    Controls whether remediations are returned.

    Default: True

Return type

dict

Returns

Response Syntax

{
    'extras': {},
    'topology': {
        'assets': [
            'None'
        ]
    }
}

Response Definitions

  • extras (dict) –

    Extra assets are returned here if extras query param was set and such assets were found.

  • topology (dict) –

    • assets (list) –

      An array of assets objects containing key, type, created_on, threatiness and threatiness_level.

undispose_remediations(**kwargs)

Undispose (or unconclude) the given remediation-item(s) in the given deployment(s). The remediation-items, if they exist, are deleted immediately. Any vulnerability instances that were concluded or disposed by the remediation-item will be accordingly unconcluded and undisposed (that is, their concluded and disposed properties will be set to false). Note that if deployment_ids query parameter is not set, the remediation item(s) will be removed from all deployments where they exist.

Note that exactly one of remediation_item_ids or audit_ids may be provided. If audit_ids is passed, all remediation-items with any of the given audit_ids will be undisposed/unconcluded. Additionally, if audit_ids is passed, either remediation_ids or vulnerability_ids may be passed. If one of those is also given, remediation-items with one of the given audit_ids and one of the given remediation_ids or vulnerability_ids will be undisposed/unconcluded.

Request Syntax

response = client.undispose_remediations(
    account_id='string'
    audit_ids='string'
    deployment_ids='string'
    remediation_ids='string'
    remediation_item_ids='string'
    vulnerability_ids='string'
)
Parameters

  • account_id (string) –

    [REQUIRED]

    The AIMS account ID whose assets are being accessed. Only valid account IDs are acceptable. Invalid account IDs result in an HTTP 404 Not Found or HTTP 403 Forbidden, depending on the client’s access level.

  • audit_ids (string) – A comma-separated list of audit_ids.

  • deployment_ids (string) – A comma-separated list of deployment IDs.

  • remediation_ids (string) – A comma-separated list of remediation IDs.

  • remediation_item_ids (string) – A comma-separated list of remediation-item IDs.

  • vulnerability_ids (string) – A comma-separated list of vulnerability IDs.

Returns

None