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
orHTTP 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.
filter
s can be chained together (applied usingAND
). Currently the only supported filter isassessment_spec.spec_id
. Each filter is a colon-separated pair oftype
(e.g.,assessment_spec.spec_id
) andvalue
(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, thecollector
type.Note that specifying
disposed
orconcluded
query parameters astrue
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
orHTTP 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 concludedfalse
- only not concludedall
- 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 disposedfalse
- only not disposedall
- both
Valid values:
true
,false
,all
Default:
false
filter (string) – Filters assets must match to be included in the report.
filter
s can be chained together (applied usingAND
). Each filter is a colon-separated pair oftype
(e.g.,deployment
) andvalue
(e.g.,DEADBEEF-0000-0000-0000-000000000001
). The currently supported filter types arecategory
,deployment
,deployment_type
,health_level
,protection_policy_id
. and any others returned in thefilters
API response (see examples below). Note that adeployment
filter must be applied to allow other filters to be included. Note that even ifcategory
is not provided, requests will look up vulnerabilities ascategory:configuration,connection
, any additionalcategory
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 adeployment
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
, andunhealthiness
).list (list) –
An array of objects in the report. Each object contains keys of the given URL’s
asset_type
(except in the case ofnetwork
, in which case the key isvpc
) whose value is the asset key which may be looked up in theassets
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 exposureexposure
theexposure
key referenced from the top-levelassets
object,which contains the detailed exposure information.
exposures_by_remediation
- an object keyed by remediations referenced from the top-levelassets
object. Each value is an array ofexposure
keys referenced from the top-levelassets
object.exposures_count
- the number of exposures in the entry.remediations
- an array of remediation keys referenced from the top-levelassets
objectremediations_count
- the number of remediations in the entry.remediation_filters
- a list offilter
s to pass to the remediations API to view full remediation details)health_level
unhealthiness
asset_count
(only included for thenetwork
/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
orconcluded
query parameters astrue
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
orHTTP 403 Forbidden
, depending on the client’s access level.filter (string) – Filters assets must match to be included in the report.
filter
s can be chained together (applied usingAND
). Each filter is a colon-separated pair oftype
(e.g.,deployment
) andvalue
(e.g.,DEADBEEF-0000-0000-0000-000000000001
). The currently supported filter types arecategory
,deployment
,deployment_type
,health_level
,protection_policy_id
. and any others returned in thefilters
API response (see examples below). Note that adeployment
filter must be applied to allow other filters to be included. Note that even ifcategory
is not provided, requests will look up vulnerabilities ascategory:configuration,connection
, any additionalcategory
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
orHTTP 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 disposedfalse
- only not disposedall
- both
Valid values:
true
,false
,all
filter (list) – Filters that assets/vulnerabilities must match to be included in the exposures summary.
filter
s can be chained together (applied usingAND
). Generally, any remediation filters should work, butcategory
andseverity
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
andvpc
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
orHTTP 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 disposedfalse
- only not disposedall
- both
Valid values:
true
,false
,all
filter (list) –
Filters that assets/vulnerabilities must match to be included in the exposures summary.
filter
s can be chained together (applied usingAND
). Generally, any remediation filters should work, butcategory
andseverity
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
andvpc
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
) oroverall
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
andvpc
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
orHTTP 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 disposedfalse
- only not disposedall
- both
Valid values:
true
,false
,all
filter (list) –
Filters that assets/vulnerabilities must match to be included in the exposures summary.
filter
s can be chained together (applied usingAND
). Generally, any remediation filters should work, butcategory
andseverity
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
andvpc
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
) oroverall
type of reported scores.Valid values:
deployment
,host
,overall