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.