Discovery for Web Application Security (ASM) Management

Overview

This document describes the use of the Device Discovery and Import Controller task API. This task can discover and import BIG-IP device configurations in the BIG-IQ system. The parameters shown in the examples demonstrate the use of this task to discover the Web Application Security module.

REST Endpoint: /mgmt/cm/global/tasks/device-discovery-import-controller

Requests

POST /mgmt/cm/global/tasks/device-discovery-import-controller

Request Parameters

Name Type Required Description
operationalMode string False Specifies whether the new device is being imported or existing devices are being re-imported.
deviceDetails array_of_objects False List of devices and their import details.
     deviceReference reference False Device reference to re-import already imported device’s configurations.
          link string False URI link of the reference.
     newDevice object False Device details to import a new device.
          address string False IP address of the device to be imported.
          httpsPort number False HTTPS port number to import a new device.
          userName string False User name to authenticate device for import.
          password string False Password to authenticate device for import.
          clusterName string False Name of the HA cluster to which the device belongs.
          useBigiqSync boolean False Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment.
          deployWhenDscChangesPending boolean False Deploy when there are pending DSC changes on BIG-IP.
     moduleList array_of_objects False List of modules to import.
          module string False Module name to import for the device.
          properties object False Additional properties provided for the import..
               cm:access:import-shared boolean False When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’.
     messages array_of_objects False List of messages gathered during different stages of the device import.
conflictPolicy string False Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects.
deviceConflictPolicy string False Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects.
snapshotWorkingConfig boolean False Snapshot of the working configuration for all devices, before the import.
accessGroupName string False Access group name to import Access configuration for devices.
name string False Name of the task.
errorMessage string False Error message describing details of the task failure.
description string False Description of the task.
status string False Current status of task.

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
operationalMode string Specifies whether the new device is being imported or existing devices are being re-imported..
deviceDetails array_of_objects List of devices and their import details.
     deviceReference reference Device reference to re-import already imported device’s configurations.
          link string URI link of the reference.
     newDevice object Device details to import a new device.
          address string IP address of the device to be imported.
          httpsPort number HTTPS port number to import a new device.
          userName string User name to authenticate device for import.
          password string Password to authenticate device for import.
          clusterName string Name of the HA cluster to which the device belongs.
          useBigiqSync boolean Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment.
          deployWhenDscChangesPending boolean Deploy when there are pending DSC changes on BIG-IP.
     moduleList array_of_objects List of modules to import.
          module string Module name to import for the device.
          status string Device import status.
          errorMsg string Error message if device import failed.
          startTime string Start time of module import for the device.
          endTime string End time of module import for the device.
          properties object Additional properties provided for the import..
               cm:access:import-shared boolean When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’.
          taskReference reference Task reference.
               link string URI link of the reference.
          snapshotWorkingConfig boolean Snapshot module’s working configuration before import.
     deviceStatus string Import status of the device.
     trustTaskReference reference Device trust establishment task reference.
          link string URI link of the reference.
     superDiscoveryTaskReference reference Config discovery task reference.
          link string URI link of the reference.
     superImportTaskReference reference Configuration import task reference.
          link string URI link of the reference.
     messages array_of_objects List of messages gathered during different stages of the device import.
          msgType string Message severity level.
          msg string Message details.
conflictPolicy string Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects.
deviceConflictPolicy string Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects.
snapshotWorkingConfig boolean Snapshot of the working configuration for all devices, before the import.
accessGroupName string Access group name to import Access configuration for devices.
currentStep string Current import step.
startDateTime string Start date and time of task.
name string Name of the task.
errorMessage string Error message describing details of the task failure.
description string Description of the task.
endDateTime string End date and time of task.
status string Current status of task.

Error Response

HTTP/1.1 400 Bad Request

This response status is related to an error during a POST method. A detailed error message displays in the response.

HTTP/1.1 401 Unauthorized

This response occurs when access is denied due to invalid credentials or insufficient permissions.

Permissions

Role Allow
Trust_Discovery_Import Yes
Device_Viewer No
device_manager No

GET /mgmt/cm/global/tasks/device-discovery-import-controller/<id>

Request Parameters

None

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
operationalMode string Specifies whether the new device is being imported or existing devices are being re-imported..
deviceDetails array_of_objects List of devices and their import details.
     deviceReference reference Device reference to re-import already imported device’s configurations.
          link string URI link of the reference.
     newDevice object Device details to import a new device.
          address string IP address of the device to be imported.
          httpsPort number HTTPS port number to import a new device.
          userName string User name to authenticate device for import.
          password string Password to authenticate device for import.
          clusterName string Name of the HA cluster to which the device belongs.
          useBigiqSync boolean Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment.
          deployWhenDscChangesPending boolean Deploy when there are pending DSC changes on BIG-IP.
     moduleList array_of_objects List of modules to import.
          module string Module name to import for the device.
          status string Device import status.
          errorMsg string Error message if device import failed.
          startTime string Start time of module import for the device.
          endTime string End time of module import for the device.
          properties object Additional properties provided for the import..
               cm:access:import-shared boolean When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’.
          taskReference reference Task reference.
               link string URI link of the reference.
          snapshotWorkingConfig boolean Snapshot module’s working configuration before import.
     deviceStatus string Import status of the device.
     trustTaskReference reference Device trust establishment task reference.
          link string URI link of the reference.
     superDiscoveryTaskReference reference Config discovery task reference.
          link string URI link of the reference.
     superImportTaskReference reference Configuration import task reference.
          link string URI link of the reference.
     messages array_of_objects List of messages gathered during different stages of the device import.
          msgType string Message severity level.
          msg string Message details.
conflictPolicy string Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects.
deviceConflictPolicy string Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects.
snapshotWorkingConfig boolean Snapshot of the working configuration for all devices, before the import.
accessGroupName string Access group name to import Access configuration for devices.
currentStep string Current import step.
startDateTime string Start date and time of task.
name string Name of the task.
errorMessage string Error message describing details of the task failure.
description string Description of the task.
endDateTime string End date and time of task.
status string Current status of task.

Error Response

HTTP/1.1 400 Bad Request

This response status is related to an error during a GET method. A detailed error message displays in the response.

HTTP/1.1 401 Unauthorized

This response occurs when access is denied due to invalid credentials or insufficient permissions.

Permissions

Role Allow
Trust_Discovery_Import Yes
Device_Viewer Yes
device_manager Yes

DELETE /mgmt/cm/global/tasks/device-discovery-import-controller/<id>

Request Parameters

None

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
operationalMode string Specifies whether the new device is being imported or existing devices are being re-imported..
deviceDetails array_of_objects List of devices and their import details.
     deviceReference reference Device reference to re-import already imported device’s configurations.
          link string URI link of the reference.
     newDevice object Device details to import a new device.
          address string IP address of the device to be imported.
          httpsPort number HTTPS port number to import a new device.
          userName string User name to authenticate device for import.
          password string Password to authenticate device for import.
          clusterName string Name of the HA cluster to which the device belongs.
          useBigiqSync boolean Instead of using the BIG-IP cluster sync to synchronize cluster devices configuration, use BIG-IQ to push changes to cluster devices during deployment.
          deployWhenDscChangesPending boolean Deploy when there are pending DSC changes on BIG-IP.
     moduleList array_of_objects List of modules to import.
          module string Module name to import for the device.
          status string Device import status.
          errorMsg string Error message if device import failed.
          startTime string Start time of module import for the device.
          endTime string End time of module import for the device.
          properties object Additional properties provided for the import..
               cm:access:import-shared boolean When creating an Access Group, the first device in the list can be set to import shared-config for the Access Group. The property name is ‘cm:access:import-shared’.
          taskReference reference Task reference.
               link string URI link of the reference.
          snapshotWorkingConfig boolean Snapshot module’s working configuration before import.
     deviceStatus string Import status of the device.
     trustTaskReference reference Device trust establishment task reference.
          link string URI link of the reference.
     superDiscoveryTaskReference reference Config discovery task reference.
          link string URI link of the reference.
     superImportTaskReference reference Configuration import task reference.
          link string URI link of the reference.
     messages array_of_objects List of messages gathered during different stages of the device import.
          msgType string Message severity level.
          msg string Message details.
conflictPolicy string Conflict policy for shared objects. For Access, a shared import will Accept/USE_BIGIP for all shared and device-specific objects.
deviceConflictPolicy string Conflict policy for device-specific objects. For Access, a device-specific import will Accept/USE_BIGIP for all device-specific objects.
snapshotWorkingConfig boolean Snapshot of the working configuration for all devices, before the import.
accessGroupName string Access group name to import Access configuration for devices.
currentStep string Current import step.
startDateTime string Start date and time of task.
name string Name of the task.
errorMessage string Error message describing details of the task failure.
description string Description of the task.
endDateTime string End date and time of task.
status string Current status of task.

Error Response

HTTP/1.1 400 Bad Request

This response status is related to an error during a DELETE method. A detailed error message displays in the response.

HTTP/1.1 401 Unauthorized

This response occurs when access is denied due to invalid credentials or insufficient permissions.

Permissions

Role Allow
Trust_Discovery_Import Yes
Device_Viewer No
device_manager No

Examples

Create Device Discovery and Import Task

POST /mgmt/cm/global/tasks/device-discovery-import-controller
{
    "operationalMode": "NEW_DEVICE",
    "deviceDetails": [{
        "newDevice": {
            "address": "10.241.102.232",
            "httpsPort": 443,
            "userName": "admin",
            "password": "admin"
        },
        "moduleList": [
        {
            "module": "adc_core"
        },
        {
            "module": "asm"
        },
        {
            "module": "security_shared"
        }],
        "messages": [{
        }]
    }],
    "conflictPolicy": "USE_BIGIP",
    "deviceConflictPolicy": "USE_BIGIP",
    "snapshotWorkingConfig": true,
    "name": "task_for_xyz",
    "description": "This task is to accomplish xyz."
}

Response

HTTP/1.1 200 OK
{
    "operationalMode": "NEW_DEVICE",
    "deviceDetails": [
        {
            "newDevice": {
                "address": "10.241.102.232",
                "httpsPort": 443,
                "userName": "admin",
                "password": "39wEC7+dnG9BKlkuQl671toNDTvRuK/4L4CwVpgR4Qc="
            },
            "moduleList": [
                {
                    "module": "adc_core"
                },
                {
                    "module": "asm"
                },
                {
                    "module": "security_shared"
                }
            ],
            "messages": [
                {}
            ]
        }
    ],
    "conflictPolicy": "USE_BIGIP",
    "deviceConflictPolicy": "USE_BIGIP",
    "snapshotWorkingConfig": true,
    "id": "a83d1e27-98d5-467f-bba5-d1bfe34d52cd",
    "status": "STARTED",
    "name": "task_for_xyz",
    "description": "This task is to accomplish xyz.",
    "userReference": {
        "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "identityReferences": [
        {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
        }
    ],
    "ownerMachineId": "bdbd9f5b-9df1-4630-a743-d692b4d523d9",
    "taskWorkerGeneration": 1,
    "generation": 1,
    "lastUpdateMicros": 1524472514307620,
    "kind": "cm:global:tasks:device-discovery-import-controller:discoveryandimportcontrollertaskitemstate",
    "selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/a83d1e27-98d5-467f-bba5-d1bfe34d52cd"
}

Get Device Discovery and Import Task

GET /mgmt/cm/global/tasks/device-discovery-import-controller/<id>

Response

HTTP/1.1 200 OK
{
    "operationalMode": "NEW_DEVICE | EXISTING_DEVICE",
    "deviceDetails": [{
        "deviceReference": {
            "link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
        },
        "newDevice": {
            "address": "11.111.111.111",
            "httpsPort": 443,
            "userName": "admin",
            "password": "password",
            "clusterName": "cluster_1_data_center_1",
            "useBigiqSync": false,
            "deployWhenDscChangesPending": false
        },
        "moduleList": [{
            "module": "adc_core",
            "status": "STARTED",
            "errorMsg": "Failed importing adc_core for device 11.111.111.111. Something bad happened.",
            "startTime": "2018-01-30T21:37:10.104-0800",
            "endTime": "2018-01-30T21:38:07.104-0800",
            "properties": {
                "cmAccessImportShared": true
            },
            "taskReference": {
                "link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
            },
            "snapshotWorkingConfig": true
        }],
        "deviceStatus": "IMPORT_STAGE",
        "trustTaskReference": {
            "link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
        },
        "superDiscoveryTaskReference": {
            "link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
        },
        "superImportTaskReference": {
            "link": "https://localhost/mgmt/shared/foo/bar/844dcf8a-4d03-48e4-bb94-bb22a4bc2436"
        },
        "messages": [{
            "msgType": "INFO",
            "msg": "Importing adc_core for device 11.111.111.111."
        }]
    }],
    "conflictPolicy": "USE_BIGIP",
    "deviceConflictPolicy": "USE_BIGIP",
    "snapshotWorkingConfig": true,
    "accessGroupName": "DataCenter_1_AccessGroup",
    "currentStep": "IMPORT_DEVICES",
    "startDateTime": "2018-02-01T19:44:17.804-0800",
    "name": "task_for_xyz",
    "errorMessage": "Something bad happened at step 5.",
    "description": "This task is to accomplish xyz.",
    "endDateTime": "2018-02-01T19:44:17.804-0800",
    "status": "STARTED"
}

Delete Device Discovery and Import Task

DELETE /mgmt/cm/global/tasks/device-discovery-import-controller/<id>

Response

HTTP/1.1 200 OK
{
    "conflictPolicy": "USE_BIGIP",
    "currentStep": "DONE",
    "description": "This task is to accomplish xyz.",
    "deviceConflictPolicy": "USE_BIGIP",
    "deviceDetails": [
        {
            "deviceReference": {
                "link": "https://localhost/mgmt/cm/system/machineid-resolver/e9339a51-8d01-4c6e-bf6a-be2f850c0f62"
            },
            "newDevice": {
                "address": "10.241.102.232",
                "httpsPort": 443,
                "userName": "admin",
                "password": "39wEC7+dnG9BKlkuQl671toNDTvRuK/4L4CwVpgR4Qc="
            },
            "moduleList": [
                {
                    "module": "adc_core"
                },
                {
                    "module": "security_shared"
                },
                {
                    "module": "asm"
                }
            ],
            "deviceStatus": "FINISHED",
            "trustTaskReference": {
                "link": "https://localhost/mgmt/cm/global/tasks/device-trust/455b9c49-938b-4d63-9bf1-6cc6e69dbf40"
            },
            "superDiscoveryTaskReference": {
                "link": "https://localhost/mgmt/cm/global/tasks/device-discovery/c2d324ce-21a1-4db1-a652-670133528bc3"
            },
            "superImportTaskReference": {
                "link": "https://localhost/mgmt/cm/global/tasks/device-import/e09aa0f2-524d-4e47-bfca-33c87a40ca5d"
            }
        }
    ],
    "endDateTime": "2018-04-23T01:37:32.887-0700",
    "generation": 10,
    "id": "a83d1e27-98d5-467f-bba5-d1bfe34d52cd",
    "identityReferences": [
        {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
        }
    ],
    "kind": "cm:global:tasks:device-discovery-import-controller:discoveryandimportcontrollertaskitemstate",
    "lastUpdateMicros": 1524472652938156,
    "name": "task_for_xyz",
    "operationalMode": "NEW_DEVICE",
    "ownerMachineId": "bdbd9f5b-9df1-4630-a743-d692b4d523d9",
    "selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/a83d1e27-98d5-467f-bba5-d1bfe34d52cd",
    "snapshotWorkingConfig": true,
    "startDateTime": "2018-04-23T01:35:14.324-0700",
    "status": "FINISHED",
    "userReference": {
        "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "username": "admin"
}