Remediations

Table of Contents

Client

class Remediations.Client

A client object representing ‘Remediations’ Service:

import almdrlib

client = almdrlib.client('remediations')

Available methods:

get_assessment_specs(**kwargs)

This endpoint will return all assessment-spec assets, the assets that were evaluated as part of that assessment spec, and the vulnerabilities found.

Request Syntax

response = client.get_assessment_specs(
    account_id='string'
    deployment_id='string'
    filter=[
        '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.

  • deployment_id (string) –

    [REQUIRED]

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

  • filter (list) – Filters assets must match to be included in the assessment specs result. filters can be chained together (applied using AND). Currently the only supported filter is assessment_spec.spec_id. Each filter is a colon-separated pair of type (e.g., assessment_spec.spec_id) and value (e.g., /alertlogic/fusionvm/internal) Since this filter supports negation (e.g. assessment_spec.spec_id:!/alertlogic/fusionvm/internal) you can exclude a spec_id, or exclusively get one (e.g. assessment_spec.spec_id:/alertlogic/fusionvm/internal). You can also use a regex pattern (e.g. assessment_spec.spec_id:~/cis/.*).

Return type

dict

Returns

Response Syntax

{
    'assessment-specs': [
        {}
    ],
    'filters': [
        'string'
    ],
    'summary': {}
}

Response Definitions

  • assessment-specs (list) –

    • (dict) –

  • filters (list) –

    • (string) –

  • summary (dict) –

get_collection_health(**kwargs)

This endpoint will return collection health information for the given asset type (agent, appliance, collector, host, subnet, network, or vpc). By default, the endpoint summarizes the health of assets of the given asset type across all deployments, but supports filtration by deployment ID, deployment type, protection level (protection_policy_id), and vulnerability category, as well as evaluating assets in scope (default) or not.

Note that host health only includes non-agent, non-appliance hosts in its results.

Note that the protection level filter, protection_policy_id, requires a policy ID from the policies service. If given, only assets in the protection scope of that policy will be used to generate the collection health information. The protection scope is not taken into account for all asset types, notably, the collector type.

Note that specifying disposed or concluded query parameters as true will hide undisposed or unconcluded remediations on affected assets. The unhealthiness calculation will reflect these remediation options and may make a healthy asset appear unhealthy or vice-versa. These options should be used with care when determining the health of an asset.

Request Syntax

response = client.get_collection_health(
    account_id='string'
    asset_type='string'
    concluded='true'|'false'|'all'
    disposed='true'|'false'|'all'
    filter='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.

  • asset_type (string) –

    [REQUIRED]

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

  • 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

  • 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 (string) – Filters assets must match to be included in the report. filters can be chained together (applied using AND). Each filter is a colon-separated pair of type (e.g., deployment) and value (e.g., DEADBEEF-0000-0000-0000-000000000001). The currently supported filter types are category, deployment, deployment_type, health_level, protection_policy_id. and any others returned in the filters API response (see examples below). Note that a deployment filter must be applied to allow other filters to be included. Note that even if category is not provided, requests will look up vulnerabilities as category:configuration,connection, any additional category filter included in the request will work as an “AND” operation. Since this filter supports negation (e.g. category:!configuration) you can exclude a category, or exclusively get one (e.g. category:connection). Only configuration and connection vulnerabilities are considered in collection health, even if you filter category` it beyond that.

  • scope (boolean) –

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

    Default: True

Return type

dict

Returns

Response Syntax

{
    'assets': {},
    'filters': {},
    'list': [
        {}
    ]
}

Response Definitions

  • assets (dict) –

    An object whose keys are all asset keys, e.g., 6AF0EAB2-C331-4FBC-B91F-81CEB69D48FA:agent:/agent/DA663430-E658-4F53-932E-DACBFFDE3DE2. Note that if a deployment filter is given, the deployment ID will not be included, e.g. agent:/agent/DA663430-E658-4F53-932E-DACBFFDE3DE2. In either case, the value at each key is the asset object with its key summary properties included.

  • filters (dict) –

    An object whose keys are all filters, e.g., deployment_type:datacenter. The value at each key is an object containing information about the results that would be returned if the filter were applied (count, health_level, and unhealthiness).

  • list (list) –

    An array of objects in the report. Each object contains keys of the given URL’s asset_type (except in the case of network, in which case the key is vpc) whose value is the asset key which may be looked up in the assets key of the main response JSON (see above) to get the full asset details. Additional keys in the object include:

    • Associated assets (e.g., deployment, host, image, region)

    • exposures - an array of objects with 2 properties:

      • asset_count: The number of assets affected by the given exposure

      • exposurethe exposure key referenced from the top-level assets object,

        which contains the detailed exposure information.

    • exposures_by_remediation - an object keyed by remediations referenced from the top-level assets object. Each value is an array of exposure keys referenced from the top-level assets object.

    • exposures_count - the number of exposures in the entry.

    • remediations - an array of remediation keys referenced from the top-level assets object

    • remediations_count - the number of remediations in the entry.

    • remediation_filters - a list of filters to pass to the remediations API to view full remediation details)

    • health_level

    • unhealthiness

    • asset_count (only included for the network/vpc/subnet asset types)

    • (dict) –

get_collection_health_summary(**kwargs)

This endpoint will return a summary of collection health by asset type (agent, appliance, network). The summary is a count of total/protected (as applicable) assets of the given type, as well as a breakdown of the counts of each by health_level. By default, the endpoint summarizes the health of all deployments, but supports filtration by deployment ID, deployment type, and protection level (protection_policy_id), as well as evaluating assets in scope (default) or not.

Note that the protection level filter, protection_policy_id, requires a policy ID from the policies service. If given, only assets in the protection scope of that policy will be used to generate the summary.

Note that specifying disposed or concluded query parameters as true will hide undisposed or unconcluded remediations on affected assets. The unhealthiness calculation will reflect these remediation options and may make a healthy asset appear unhealthy or vice-versa. These options should be used with care when determining the health of an asset.

Request Syntax

response = client.get_collection_health_summary(
    account_id='string'
    filter='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.

  • filter (string) – Filters assets must match to be included in the report. filters can be chained together (applied using AND). Each filter is a colon-separated pair of type (e.g., deployment) and value (e.g., DEADBEEF-0000-0000-0000-000000000001). The currently supported filter types are category, deployment, deployment_type, health_level, protection_policy_id. and any others returned in the filters API response (see examples below). Note that a deployment filter must be applied to allow other filters to be included. Note that even if category is not provided, requests will look up vulnerabilities as category:configuration,connection, any additional category filter included in the request will work as an “AND” operation. Since this filter supports negation (e.g. category:!configuration) you can exclude a category, or exclusively get one (e.g. category:connection). Only configuration and connection vulnerabilities are considered in collection health, even if you filter category` it beyond that.

  • scope (boolean) –

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

    Default: True

Return type

dict

Returns

Response Syntax

{
    'agents': {
        'coverage': {
            'protected': 'integer',
            'total': 'integer'
        },
        'health': {
            'scores': [
                {
                    'count': 'integer',
                    'health_level': '0'|'2',
                    'unhealthiness': 'number'
                }
            ]
        }
    },
    'appliances': {
        'coverage': {
            'total': 'integer'
        },
        'health': {
            'scores': [
                {
                    'count': 'integer',
                    'health_level': '0'|'2',
                    'unhealthiness': 'number'
                }
            ]
        }
    },
    'collectors': {
        'coverage': {
            'total': 'integer'
        },
        'health': {
            'scores': [
                {
                    'count': 'integer',
                    'health_level': '0'|'2',
                    'unhealthiness': 'number'
                }
            ]
        }
    },
    'networks': {
        'coverage': {
            'protected': 'integer',
            'total': 'integer'
        },
        'health': {
            'scores': [
                {
                    'count': 'integer',
                    'health_level': '0'|'2',
                    'unhealthiness': 'number'
                }
            ]
        }
    }
}

Response Definitions

  • agents (dict) –

    Top-level object containing agent health summary

    • coverage (dict) –

      Agent health coverage

      • protected (integer) –

        Total number of protected agents matching the given scope and filter(s)

      • total (integer) –

        Total number of agents matching the given scope and filter(s)

    • health (dict) –

      Agent health coverage

      • scores (list) –

        Agent health scores

        • (dict) –

          • count (integer) –

            Count of agents with the given health_level in the object

          • health_level (integer) –

            Health level of agents in the object

            Valid values: 0, 2

          • unhealthiness (number) –

            Unhealthiness score of agents in the object

  • appliances (dict) –

    Top-level object containing appliance health summary

    • coverage (dict) –

      Appliance health coverage

      • total (integer) –

        Total number of appliances matching the given scope and filter(s)

    • health (dict) –

      Appliance health coverage

      • scores (list) –

        Appliance health scores

        • (dict) –

          • count (integer) –

            Count of appliances with the given health_level in the object

          • health_level (integer) –

            Health level of appliances in the object

            Valid values: 0, 2

          • unhealthiness (number) –

            Unhealthiness score of appliances in the object

  • collectors (dict) –

    Top-level object containing collector health summary

    • coverage (dict) –

      Collector health coverage

      • total (integer) –

        Total number of collectors matching the given scope and filter(s)

    • health (dict) –

      Collector health coverage

      • scores (list) –

        Collector health scores

        • (dict) –

          • count (integer) –

            Count of collectors with the given health_level in the object

          • health_level (integer) –

            Health level of collectors in the object

            Valid values: 0, 2

          • unhealthiness (number) –

            Unhealthiness score of collectors in the object

  • networks (dict) –

    Top-level object containing network health summary

    • coverage (dict) –

      Network health coverage

      • protected (integer) –

        Total number of protected networks matching the given scope and filter(s)

      • total (integer) –

        Total number of networks matching the given scope and filter(s)

    • health (dict) –

      Network health coverage

      • scores (list) –

        Network health scores

        • (dict) –

          • count (integer) –

            Count of networks with the given health_level in the object

          • health_level (integer) –

            Health level of networks in the object

            Valid values: 0, 2

          • unhealthiness (number) –

            Unhealthiness score of networks in the object

get_current_scores(**kwargs)

This endpoint will return all current asset scores for given account’s deployments and VPCs in a summary format.

Request Syntax

response = client.get_current_scores(
    account_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.

  • 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

  • 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

list

Returns

Response Syntax

[
    {
        'account_id': 'string',
        'cidr_ranges': [
            'None'
        ],
        'deployment_id': 'string',
        'key': 'string',
        'name': 'string',
        'network_uuid': 'string',
        'p90_severity': 'integer',
        'raw_severity': 'integer',
        'score_type': 'tri',
        'severity': 'integer',
        'type': 'deployment'|'host',
        'value': 'number'
    }
]

Response Definitions

  • (dict) –

    Top-level object containing the asset scores fields.

    • account_id (string) –

      Account ID asset belongs to.

    • cidr_ranges (list) –

      Array of strings representing Classless Inter-Domain Routing (CIDR) IPs ranges. Only on vpc summary types.

    • deployment_id (string) –

      The Deployment ID the asset belongs to.

    • key (string) –

      Asset key.

    • name (string) –

      The Asset name.

    • network_uuid (string) –

      The VPC network UUID. Only on vpc summary types.

    • p90_severity (integer) –

      The 90th percentile of the threat severity.

    • raw_severity (integer) –

      The raw value of the threat severity.

    • score_type (string) –

      The score type.

      Valid values: tri

    • severity (integer) –

      Threat severity.

    • type (string) –

      Asset type (deployment, vpc) of reported scores.

      Valid values: deployment, host

    • value (number) –

      The current score value.

get_risk_summary(**kwargs)

This endpoint will return the risk summary of given score type for also given account. The only score type supported is TRI (Threat Risk Index). This endpoint returns the risk summary scores for deployment and vpc asset types.

The response report provides daily threat risk index (TRI) scores summary of given account’s environment, including the overall TRI score (see response entry example with "type": "overall").

Request Syntax

response = client.get_risk_summary(
    account_id='string'
    disposed='true'|'false'|'all'
    filter=[
        'None'
    ]
    scope='False|True'
    score_type='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.

  • 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

  • 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

  • score_type (string) –

    [REQUIRED]

    A valid score type. Currently the only supported type is tri.

Return type

list

Returns

Response Syntax

[
    {
        'account_id': 'string',
        'cidr_ranges': [
            'None'
        ],
        'deployment_id': 'string',
        'key': 'string',
        'name': 'string',
        'network_uuid': 'string',
        'relative_severity': 'integer',
        'risk_level': 'integer',
        'tri': 'number',
        'tri_asset_count': 'integer',
        'tri_last_updated': 'integer',
        'tri_pctile_all': 'number',
        'tri_pctile_segment': 'number',
        'tri_severity': 'integer',
        'tri_trend_13w': 'number',
        'tri_trend_1w': 'number',
        'tri_trend_4w': 'number',
        'type': 'deployment'|'host'|'overall'
    }
]

Response Definitions

  • (dict) –

    Top-level object containing the asset risk summary fields.

    • account_id (string) –

      Account ID asset belongs to.

    • cidr_ranges (list) –

      Array of strings representing Classless Inter-Domain Routing (CIDR) IPs ranges. Only on vpc summary types.

    • deployment_id (string) –

      The Deployment ID the asset belongs to. Present in all types, except overall.

    • key (string) –

      Asset key or predefined “overall”.

    • name (string) –

      Asset name or predefined “Overall by deployment”.

    • network_uuid (string) –

      The VPC network UUID. Only on vpc summary types.

    • relative_severity (integer) –

      Threat relative severity. Only on deployment and vpc summary types.

    • risk_level (integer) –

      Threat risk level.

    • tri (number) –

      Current TRI score.

    • tri_asset_count (integer) –

      Number of assets with TRI score associated to response type.

    • tri_last_updated (integer) –

      Last time TRI score was updated (0 if never updated).

    • tri_pctile_all (number) –

      TRI percentile all.

    • tri_pctile_segment (number) –

      TRI percentile segment.

    • tri_severity (integer) –

      TRI severity level.

    • tri_trend_13w (number) –

      TRI 13 week trend.

    • tri_trend_1w (number) –

      TRI week trend.

    • tri_trend_4w (number) –

      TRI month trend.

    • type (string) –

      Asset type (deployment, vpc) or overall type of reported scores.

      Valid values: deployment, host, overall

get_risk_summary_by_asset_type(**kwargs)

This endpoint will return the risk summary of given score type for given account and asset type. The only score type supported is TRI (Threat Risk Index).

The response report provides daily threat risk index (TRI) scores of given account’s asset type, including the overall TRI score. Note that only deployment and vpc are supported as asset type URL param.

Request Syntax

response = client.get_risk_summary_by_asset_type(
    account_id='string'
    asset_type='string'
    disposed='true'|'false'|'all'
    filter=[
        'None'
    ]
    scope='False|True'
    score_type='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.

  • 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

  • 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

  • score_type (string) –

    [REQUIRED]

    A valid score type. Currently the only supported type is tri.

Return type

list

Returns

Response Syntax

[
    {
        'account_id': 'string',
        'cidr_ranges': [
            'None'
        ],
        'deployment_id': 'string',
        'key': 'string',
        'name': 'string',
        'network_uuid': 'string',
        'relative_severity': 'integer',
        'risk_level': 'integer',
        'tri': 'number',
        'tri_asset_count': 'integer',
        'tri_last_updated': 'integer',
        'tri_pctile_all': 'number',
        'tri_pctile_segment': 'number',
        'tri_severity': 'integer',
        'tri_trend_13w': 'number',
        'tri_trend_1w': 'number',
        'tri_trend_4w': 'number',
        'type': 'deployment'|'host'|'overall'
    }
]

Response Definitions

  • (dict) –

    Top-level object containing the asset risk summary fields.

    • account_id (string) –

      Account ID asset belongs to.

    • cidr_ranges (list) –

      Array of strings representing Classless Inter-Domain Routing (CIDR) IPs ranges. Only on vpc summary types.

    • deployment_id (string) –

      The Deployment ID the asset belongs to. Present in all types, except overall.

    • key (string) –

      Asset key or predefined “overall”.

    • name (string) –

      Asset name or predefined “Overall by deployment”.

    • network_uuid (string) –

      The VPC network UUID. Only on vpc summary types.

    • relative_severity (integer) –

      Threat relative severity. Only on deployment and vpc summary types.

    • risk_level (integer) –

      Threat risk level.

    • tri (number) –

      Current TRI score.

    • tri_asset_count (integer) –

      Number of assets with TRI score associated to response type.

    • tri_last_updated (integer) –

      Last time TRI score was updated (0 if never updated).

    • tri_pctile_all (number) –

      TRI percentile all.

    • tri_pctile_segment (number) –

      TRI percentile segment.

    • tri_severity (integer) –

      TRI severity level.

    • tri_trend_13w (number) –

      TRI 13 week trend.

    • tri_trend_1w (number) –

      TRI week trend.

    • tri_trend_4w (number) –

      TRI month trend.

    • type (string) –

      Asset type (deployment, vpc) or overall type of reported scores.

      Valid values: deployment, host, overall