ScanScheduler Service (2.0)

Download OpenAPI specification:Download

Alert Logic Support: support@alertlogic.com

Advanced Scan Scheduling API

Authentication

X-AIMS-Auth-Token

AIMS Authentication Token

Security Scheme Type API Key
Header parameter name: X-AIMS-Auth-Token

Scans Control

Allows to expedite scan for the selected assets at a given level of topology

Expedites scan for all the scannable targets that are descendants of a given level of the topology (for example all hosts belonging to a given subnet). Please note this operation will override all the Scan Schedules that targets belong to. In case when targets are explicitly excluded from scan functionality they will NOT be scanned unless force=true parameter has been set to true.

Scan Now functionality moves the list of targets and their descendants to the top of the scan queue, raising their scan priority, immediately marking them as due to be scanned. It does not mean selected targets will be all scanned at once, since scanning process is dependent on available resources in the form of Scan Appliances deployed within the protected networks. In automatic deployment mode Alert Logic will address the demand by spinning-up additional Scan Appliances adhering to the designated settings, while in manual mode it is the responsibility of the user to provide the sufficient number of active Scan Appliances to execute scans.

All the targets marked as due to be scanned will remain in such state until they have been scanned or scan requests have been cancelled.

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
query Parameters
force
boolean or null
Default: false

Allows to override the exclusion rules applied to selected targets. Otherwise exclusion rules take precedence over expedited scan.

Request Body schema: application/json
type
required
string
Enum: "asset" "cidr" "ip_address" "ip_range" "tag"

Indicates the concrete type of ScanScopeItem's object

asset_type
string
Enum: "deployment" "region" "network" "vpc" "subnet" "host" "external-ip" "external-dns-name" "agent"

Specifies the type of the asset added to the scan scope.

Following asset types are supported:

  • deployment
  • region
  • network
  • vpc (alias of the network type)
  • subnet
  • host
  • external-ip
  • external-dns-name
  • agent
key
required
string

Responses

Request samples

Content type
application/json
{
  • "type": "asset",
  • "asset_type": "subnet",
  • "key": "/aws/us-east-1/subnet/sub-03acf31d311531"
}

Stops scans for selected list of assets

All scan jobs currently running against targets that are within the scope defined by the ScanScopeItem object, will be terminated. Targets will not be re-enqueued until the next scan SLA period defined by scan_frequency parameter of a schedule that contains each of the targets.

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
Request Body schema: application/json
type
required
string
Enum: "asset" "cidr" "ip_address" "ip_range" "tag"

Indicates the concrete type of ScanScopeItem's object

asset_type
string
Enum: "deployment" "region" "network" "vpc" "subnet" "host" "external-ip" "external-dns-name" "agent"

Specifies the type of the asset added to the scan scope.

Following asset types are supported:

  • deployment
  • region
  • network
  • vpc (alias of the network type)
  • subnet
  • host
  • external-ip
  • external-dns-name
  • agent
key
required
string

Responses

Request samples

Content type
application/json
{
  • "type": "asset",
  • "asset_type": "subnet",
  • "key": "/aws/us-east-1/subnet/sub-03acf31d311531"
}

Stops a selected scan schedule

All scan jobs currently running against targets that are within the scope defined by the selected schedule, will be terminated. Targets will not be re-enqueued until the next scan SLA period defined by scan_frequency parameter of the schedule.

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
id
required
string <uuid>

Responses

IP Address Validation

Validates a list of supplied free form IP Addresses,

This Post request does not specify the scan type and uses a default value (vulnerability). So in this case, the validator only works for the following types of scanning: vulnerability and discovery.

Validates a list of supplied strings that represent IP Addresses, checking for their correctness, as well as their alignment with the deployment's protection scope. This API always returns 200 OK status and provides the results of validation using three arrays with respective status (valid/invalid/out_of_scope).

In response API will cast valid IP Addresses into instatiations of ScanScopeItem classes and those that are present in the valid list can be subsequently used in the Scan Schedule's Scope definition.

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "10.0.0.1",
  • "10.0.1.0/24",
  • "10.0.0.1 - 10.0.0.100",
  • "10.0..0",
  • "19216810",
  • "192.168.1.300",
  • "some non ip address string"
]

Response samples

Content type
application/json
{
  • "valid": [
    ],
  • "invalid": [
    ],
  • "out_of_scope": [
    ]
}

Validates a list of supplied free form IP Addresses,

Validates a list of supplied strings that represent IP Addresses, checking for their correctness, as well as their alignment with the deployment's protection scope.

Depending on the value of the parameter {type_of_scan} different validation will be performed:

  • vulnerability/discovery/abs - IP address or range will be validated against network CIDR ranges that are in scope of the deployment. Additionally, IP addresses will be checked if they belong to the list of restricted private IPv4 ranges, as defined in the following IANA document

  • external - external IP addresses are not being compared with deployment's CIDR ranges, as all external assets are assumed to be within the scope of protection. Additionally, IP addresses will be checked if they don't belong to the restricted private IP ranges defined in the following IANA document

Note: By default the parameter will be set to vulnerability

This API always returns 200 OK status and provides the results of validation using three arrays with respective status (valid/invalid/out_of_scope).

In response API will cast valid IP Addresses into instatiations of ScanScopeItem classes and those that are present in the valid list can be subsequently used in the Scan Schedule's Scope definition.

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
type_of_scan
required
string or null
Default: "vulnerability"
Enum: "vulnerability" "external" "discovery" "abs"

Validation for different types of scan occurs in different ways.

Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "10.0.0.1",
  • "10.0.1.0/24",
  • "10.0.0.1 - 10.0.0.100",
  • "10.0..0",
  • "19216810",
  • "192.168.1.300",
  • "some non ip address string"
]

Response samples

Content type
application/json
{
  • "valid": [
    ],
  • "invalid": [
    ],
  • "out_of_scope": [
    ]
}

Time Zones

Returns a list of supported timezones

Lists supported timezones that can be used in ScanWindow definition

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Scheduling

Returns a list of scan schedules

Lists scan schedules that belong to a particular deployment

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
query Parameters
return_fields
Array of strings
Items Enum: "id" "name" "enabled" "scan_frequency" "scan_window" "scope"

Allows to specify fields of Schedule objects that will be returned by the API. Please note id is a default field and is always returned. If no return_fields parameter is specified the entire Schedule object will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a scan schedule

Create new Scan Schedule for a given deployment

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
Request Body schema: application/json
name
string
enabled
boolean
Default: true

Specifies whether the schedule is active or not.

type_of_scan
string
Enum: "vulnerability" "external" "discovery" "abs"

Specifies which type of scan the schedule should apply to. There are 4 types of scans

  • vulnerability - internal network scan. Requires an appliance to be deployed within a customer's network. Primary target are assets of host type that are in the scope of the schedule and within the scope of protection of the deployment.
  • external - external network scan. Does not require appliances to be deployed, as it is performed from within Alert Logic network against external assets. Primary target are assets of external-ip and external-dns-name types that are in the scope of the schedule and within the scope of protection of the deployment.
  • discovery - internal host-lookup scan. Requires an appliance to be deployed within a customer's network. Specific only to datacenter type of deployment, where cloud API cannot be used to enumerate assets. Used primarily to find active hosts in networks that are in the scope of protection of the deployment. Primary target are assets of network or vpc type.
  • abs - agent-based scan. The agent-based scan upgrade improves the efficiency, accuracy, and usability of Alert Logic vulnerability scanning features. Leverages the vulnerability assessment coverage of authenticated network scanning without the need to manage credentials and with a reduction in network traffic and impact. The agent-based scan requires a host to have an MDR agent installed. Primary target for agent-based scan are assets of agent type. Note an agent requires a parent host asset to be associated with it.
timezone
string or null

Name of the timezone that should be used for the ScanSchedule object. The list of all supported timezones can be obtained with /scheduler/v2/timezones API. Accepted values are derived from Timezone.tz_name field. Please note Daylight Saving Time will be observed and applied automatically, depending on a specified value.

This field is optional with null value defaulting to UTC time zone.

scan_frequency
string
Enum: "automatic" "daily" "weekly" "fortnightly" "monthly" "quarterly" "once"

Specifies the SLA period of how frequently consecutive scans should target individual targets within the deployment. Depending on characteristicts of the workload or its compliance and security requirements, different targets (e.g. hosts, external ip addresses, networks) of a certain scanning scope (e.g. hosts within certain subnets or belonging to certain CIDR ranges) may require different frequency of scans.

By setting scan_frequency to weekly, Alert Logic will aim to scan each target within the scope of a Scan Schedule once every 7 days (168 hours), adhering to the date/time constraints specified by scan_windows parameter.

By setting scan_frequency to fortnightly, Alert Logic will aim to scan each target within the scope of a Scan Schedule every other week (i.e. once every 14 days), adhering to the date/time constraints specified by scan_windows parameter.

Please note when the same host effectively belongs to two distinct Scan Schedules, the higher frequency (e.g. daily over weekly) will be respected for both schedules and union of scan_windows will be considered as time periods when scans will be allowed to occur.

Array of ScanWindowSelectedDaysOfWeek (object) or ScanWindowSelectedDaysOfMonth (object) or ScanWindowContinuousPeriodWeekly (object) or ScanWindowContinuousPeriodMonthly (object) or ScanWindowSpecificDate (object) or ScanWindowContinuousQuarterly (object) or ScanWindowSelectedWeekdayOfMonth (object) or null

Specifies the time periods when the Scan Schedule should be active.

In case when there are no restrictions to the scanning periods and Scan Schedule should be considered as "automatic", scan_windows list should be either an empty list or null. In such case each target in the schedule's scope will be scanned once within the selected SLA period, that is specified by scan_frequency parameter, without date and time restrictions other than availability of appliances within the deployment.

Please note there are four types of scan_windows, defined as following models:

  • ScanWindowSelectedDaysOfWeek
  • ScanWindowSelectedDaysOfMonth
  • ScanWindowContinuousPeriodWeekly
  • ScanWindowContinuousPeriodMonthly
  • ScanWindowSpecificDate
  • ScanWindowContinuousQuarterly
  • `ScanWindowSelectedWeekdayOfMonth'

For details please refer to the documentation of the above models.

object

Specifies what assets are considered to be scanned within designated periods defined by scan_windows parameter, setting the SLA as specified by scan_frequency parameter.

Array of ScanOptionPorts (object) or null

An optional list of Scan Options, that affect the scan configuration. One of the supported options is a list of ports, applicable to vulnerability and external types of scans.

Responses

Request samples

Content type
application/json
{
  • "name": "My Advanced Internal Scan Schedule 01",
  • "enabled": true,
  • "type_of_scan": "vulnerability",
  • "timezone": "Europe/Belfast",
  • "scan_frequency": "weekly",
  • "scan_windows": [
    ],
  • "scan_scope": {
    },
  • "scan_options": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "My Advanced Internal Scan Schedule 01",
  • "default": false,
  • "enabled": true,
  • "type_of_scan": "vulnerability",
  • "timezone": "Europe/Belfast",
  • "scan_frequency": "weekly",
  • "scan_windows": [
    ],
  • "scan_scope": {
    },
  • "scan_options": [
    ],
  • "created": {
    },
  • "modified": {
    }
}

Returns a selected scan schedule

Returns the scan schedule definition for a given id.

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "My Advanced Internal Scan Schedule 01",
  • "default": false,
  • "enabled": true,
  • "type_of_scan": "vulnerability",
  • "timezone": "Europe/Belfast",
  • "scan_frequency": "weekly",
  • "scan_windows": [
    ],
  • "scan_scope": {
    },
  • "scan_options": [
    ],
  • "created": {
    },
  • "modified": {
    }
}

Deletes a selected scan schedule

Deletes Selected Schedule.

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
id
required
string <uuid>

Responses

Updates a selected scan schedule

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "My Advanced Internal Scan Schedule 01",
  • "default": false,
  • "enabled": true,
  • "type_of_scan": "vulnerability",
  • "timezone": "Europe/Belfast",
  • "scan_frequency": "weekly",
  • "scan_windows": [
    ],
  • "scan_scope": {
    },
  • "scan_options": [
    ],
  • "created": {
    },
  • "modified": {
    }
}

Scan Schedule Summary

Returns a summary of the selected schedule

Returns a summary of the selected schedule specified by id.

Authorizations:
path Parameters
account_id
required
string
deployment_id
required
string <uuid>
id
required
string <uuid>
query Parameters
return_fields
Array of strings
Items Enum: "assets_number" "assets_in_sla" "assets_excluded" "assets_to_scan" "assets_being_scanned" "last_scan_date" "next_scan_date" "status"

Allows to specify which of the fields of ScheduleSummary object will be returned by the API. If no return_fields parameter is specified the entire ScheduleSummary object will be returned.

Responses

Response samples

Content type
application/json
{
  • "assets_number": 964,
  • "assets_in_sla": 950,
  • "assets_excluded": 14,
  • "assets_to_scan": 0,
  • "last_scan_date": "2019-08-24T14:15:22Z",
  • "next_scan_date": "2019-08-24T14:15:22Z",
  • "status": "in_progress"
}