ASM Policy Analyzer

Overview

The ASM Policy Analyzer API can be used to create or retrieve a task which generates a security suggestion report. The policy analyzer can be run on a policy imported from a BIG-IP which is being managed by BIG-IQ or a policy created in the BIG-IQ. It can not be run on a parent policy. Some security suggestions can be specified to be omitted from the suggestions list.

The ASM Policy Analyzer is the main API that can be called by a user to analyze a security policy, the reference of the policy is required at the time of posting to it. The policy analyzer calculates a security score and suggestions. After the policy analyzer task has completed, you can use the ASM Policy Analyzer Suggestions API and the ASM Policy Analyzer Rules API to get the policy analyzer results which can be reported to the user. The policy analyzer can be rerun after changing the policy configuration to check for improvement of the configuration.

REST Endpoint: /mgmt/cm/asm/tasks/policy-analyzer

Requests

POST /mgmt/cm/asm/tasks/policy-analyzer

Send a POST request to the tasks/policy-analyzer endpoint to initiate a policy analyzer task. Only one task can run at the same time, per policy.

Request Parameters

Name Type Required Description
currentStep string True Current step of the policy analyzer task. This value can be “INIT” to start the task.
ignoredSuggestions object False An array of URLs that list reference links to the suggestions to be omitted from analyzing the policy. These suggestions are ignored when calculating the score. It can be an empty list. The provided suggestions references must exist on the BIG-IQ for this policy, which means that ignoredSuggestions is not applicable for the first request, because there won’t be any suggestions existing on the BIG-IQ to ignore. You can send an ignoredSuggestions list in the subsequent calls by choosing from previously generated suggestions of the policy.
     link string False URL of an ignored suggestion
policyReference object True A reference link to an ASM policy existing on the BIG-IQ for which the policy analyzer can run. The policy must already exist on the BIG-IQ. It can not be a parent policy.
     link string True URL of policy for which policy analyzer report can run.

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
currentStep string An enumeration value indicating the current step of the policy analyzer task. Possible values: “INIT”, “READ_RULES”, “VALIDATE_RULES”, “WRITE_SUGGGESTIONS”, “PATCH_SCORE_AND_CATEGORIES”, “RETURN_SUGGESTIONS”, or “DONE”.
id string UUID identifying the policy analyzer task. This can be the value used for task-id in a request for a specific task.
ignoredSuggestions object An array of URLs for reference links to suggestions which can be omitted from the policy analysis. The suggestions provided must exist on the BIG-IQ for this policy.
     link string URL of ignored suggestions. These are the same as were passed in ignoredSuggestions of the POST request body.
policyReference object A reference link to an ASM policy existing on the BIG-IQ for which the policy analysis can be run.
     link string URL of policy for which a policy analysis can run.
selfLink string A URL to the task’s endpoint. You can poll for the state of this task by sending GET requests to this URL.
status string The status of the policy analyzer task. The value can be “STARTED” when the task has started.
userReference object A reference link to the user of this API.
     link string URL of the user of this API

Permissions

Role Allow
Web Application Security Manager Yes
Web Application Security Editor Yes
Web Application Security Viewer Yes
Web Application Security Deployer Yes

Note that the JSON in the body of the response can include the task’s id and an initial status of “STARTED”. All operations involve starting the task using a POST, after which you should send GET requests to the task’s endpoint, specified by taskId and selfLink, and poll for the task’s status until the task completes.

GET /mgmt/cm/asm/tasks/policy-analyzer/{task-id}

Send a GET request to the tasks/policy-analyzer/{task-id} endpoint to query the status of the policy analyzer task. You can poll for the task’s completion by sending GET requests using task’s selfLink or taskId. Eventually, after the task completes, the value of status can become “FINISHED” and the value of currentStep becomes “DONE” . After the task is completed the body of the response can contain suggestionsReference, which is a link to get security score, category details and reference link to security suggestions for the policy specified by the value of policyReference.

Request Parameters

None

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
currentStep string Current step indicating the status of the policy analyzer task. Eventually this value can be “DONE” when the task is finished. Possible value: “INIT”, “READ_RULES”, “VALIDATE_RULES”, “WRITE_SUGGGESTIONS”, “PATCH_SCORE_AND_CATEGORIES”, “RETURN_SUGGESTIONS”, or “DONE”.
endDateTime string Time when the task ended. For example: “2020-10-26T20:35:55.209-0700”
id string UUID identifying the task in the request
identityReferences object A list of user identities that initiated the task.
     link string URL of identity reference
ignoredSuggestions object An array of URLs for reference links to suggestions which can be omitted in the report. While calculating the score these suggestions are ignored. It can be an empty list. The provided suggestion references must exist on the BIG-IQ for this policy. The value is the same list of ignored suggestions in the policy analyzer task’s POST request body.
     link string URL of ignored suggestion
response object Gives the reference used by the ASM Policy Analyzer Suggestions API. The response object for the task, message, and suggestionsReference are shown in the response only after the value of`status` is “FINISHED”.
     message string Indicates whether the task has finished successfully or not. For example: “Successfully analyzed the policy”.
     suggestionsReference object Link to security suggestion references for this policy.
          link string URL of suggestion
policyReference object A reference link to an ASM policy existing on the BIG-IQ for which the policy analysis can run.
     link string URL of policy for which policy analyzer can run.
status string The current status of the policy analyzer task. Eventually this value can be “FINISHED” when the task has completed successfully and the user can get reference to the suggestions in the response.
startDateTime string Time when the task started. For example: “2020-10-26T20:35:11.221-0700”
username string Name of the user. For example “admin”.
userReference object A reference link to a user.

Permissions

Role Allow
Web Application Security Manager Yes
Web Application Security Editor Yes
Web Application Security Viewer Yes
Web Application Security Deployer Yes

Examples

POST to create a policy analyzer task

The following example sends a POST request to create a policy analyzer task.

POST https://<BIG-IQ>/mgmt/cm/asm/tasks/policy-analyzer

The JSON in the body of the POST can look similar to the following example.

{
    "policyReference": {
            "link": "https://localhost/mgmt/cm/asm/working-config/policies/6c6ef0a0-d6ca-31b3-887a-5bfe5001a7e4"
    },
    "ignoredSuggestions": [
            "https://localhost/mgmt/cm/asm/reports/analyzer/config-analyzer-suggestions/6c6ef0a0-d6ca-31b3-887a-5bfe5001a7e4/suggestions/f33ba15e-ffa5-310e-873b-f3842afb46a6"
    ],
    "currentStep": "INIT"
}

Response

The JSON in the response to the POST can look similar to the following. In the following example, the identifier of the policy analyzer task, “86873b8c-fc90-45f9-88a5-d7dfa64a37b5”, is returned in id and selfLink.

HTTP/1.1 200 OK

{
    "currentStep": "INIT",
    "policyReference": {
            "link": "https://localhost/mgmt/cm/asm/working-config/policies/6c6ef0a0-d6ca-31b3-887a-5bfe5001a7e4"
    },
    "ignoredSuggestions": [
            "https://localhost/mgmt/cm/asm/reports/analyzer/config-analyzer-suggestions/6c6ef0a0-d6ca-31b3-887a-5bfe5001a7e4/suggestions/f33ba15e-ffa5-310e-873b-f3842afb46a6"
    ],
    "id": "86873b8c-fc90-45f9-88a5-d7dfa64a37b5",
    "status": "STARTED",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }],
    "ownerMachineId": "1754be01-cb27-4c7c-8063-81c08d7ebfec",
    "taskWorkerGeneration": 1,
    "generation": 1,
    "lastUpdateMicros": 1611733414191356,
    "kind": "cm:asm:tasks:policy-analyzer:asmpolicyanalyzertaskstate",
    "selfLink": "https://localhost/mgmt/cm/asm/tasks/policy-analyzer/86873b8c-fc90-45f9-88a5-d7dfa64a37b5"
}

You can send a repeated GET requests to the selfLink to check whether the task has completed.

GET to check if task has completed

The following example sends a GET request to the tasks/policy-analyzer/{task-id} to check if the policy analyzer has completed. In the following example, the value of the {task-id} placeholder is “86873b8c-fc90-45f9-88a5-d7dfa64a37b5”.

GET https://<BIG-IQ>/mgmt/cm/asm/tasks/policy-analyzer/86873b8c-fc90-45f9-88a5-d7dfa64a37b5

Response

The JSON in the response to the GET can look similar to the following. The value of status becomes “FINISHED” and the value of currentStep becomes “DONE” when task is completed. After the task is completed the body of the response can contain suggestionsReference, which is a link to security suggestions for the policy specified by the value of policyReference.

HTTP/1.1 200 OK

{
    "id": "86873b8c-fc90-45f9-88a5-d7dfa64a37b5",
    "kind": "cm:asm:tasks:policy-analyzer:asmpolicyanalyzertaskstate",
    "status": "FINISHED",
    "response": {
            "message": "Succesfully analyzed the policy",
            "suggestionsReference": {
                    "link": "https://localhost/mgmt/cm/asm/reports/analyzer/config-analyzer-suggestions/6c6ef0a0-d6ca-31b3-887a-5bfe5001a7e4"
            }
    },
    "selfLink": "https://localhost/mgmt/cm/asm/tasks/policy-analyzer/86873b8c-fc90-45f9-88a5-d7dfa64a37b5",
    "username": "admin",
    "generation": 8,
    "currentStep": "DONE",
    "endDateTime": "2021-01-26T23:45:14.807-0800",
    "startDateTime": "2021-01-26T23:43:35.097-0800",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "ownerMachineId": "1754be01-cb27-4c7c-8063-81c08d7ebfec",
    "policyReference": {
            "link": "https://localhost/mgmt/cm/asm/working-config/policies/6c6ef0a0-d6ca-31b3-887a-5bfe5001a7e4"
    },
    "lastUpdateMicros": 1611733514885735,
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }]
}

After the policy analyzer task has completed, you can use the suggestionsReference and the ASM Policy Analyzer Suggestions API to send a GET request for the policy analyzer results.