Technical Tip: Automating FortiWeb script creation and application using the REST API

Description

This article explains how to automate the creation and application of FortiWeb scripts using the REST API.

The script content and the scripting configuration object are handled through separate API operations.

Scope

FortiWeb.

Solution

API workflow:

Use the following sequence to automate a FortiWeb script:

1. Validate and update the script content using the 'policy.scripting.text' endpoint.

2. Verify the response from the API call.

3. Apply the scripting configuration using the 'server-policy/scripting' endpoint.
   
   

Validate and update the script content:

Send a PUT request to the following endpoint:

PUT /api/v2.0/policy/policy.scripting.text?name=<script_name>&vdom=<vdom>

For example:

PUT /api/v2.0/policy/policy.scripting.text?name=API_TEST&vdom=root

Use the 'text' parameter to provide the script content.

{
    "data": {
        "text": "when RULE_INIT {\n    debug(\"Hello\")\n}"
    }
}

A successful response is returned as follows:

{
    "results": {
        "result": "OK"
    }
}

A successful response indicates that the script content was accepted without a syntax error.


Apply the scripting configuration:

After the script content has been successfully validated, apply the scripting configuration using the following endpoint.

PUT /api/v2.0/cmdb/server-policy/scripting?meky=<script_name>

For example:

PUT /api/v2.0/cmdb/server-policy/scripting?meky=API_TEST

The scripting configuration can then reference the script by name.

{
    "data": {
        "name": "API_TEST",
        "scripting-name": "API_TEST"
    }
}

API error handling:

A '500 Internal Server Error' with the following response can occur when the scripting configuration references a script that has not been successfully created or validated:

{
    "results": {
        "errcode": -90,
        "message": "CLI parsing error."
    }
}

The 'policy.scripting.text' API must therefore be called before creating or applying the corresponding scripting configuration.

The current implementation can also return an unknown error when the submitted script contains a syntax error. The exact syntax error is not necessarily returned by the API.

For automation, treat the response from the 'policy.scripting.text' operation as the validation result before proceeding with the scripting configuration operation.

Automation sequence:

The recommended API sequence is as follows:

Send the following with the script content: 

'PUT /api/v2.0/policy/policy.scripting.text?name=<script_name>&vdom=<vdom>' 

Verify that the response contains:

 "result":"OK".

If the validation is successful, send the following to apply the scripting configuration:

 PUT /api/v2.0/cmdb/server-policy/scripting?meky=<script_name> 

Reference the same script name in the 'scripting-name' attribute of the scripting configuration.

This sequence separates script content validation from the application of the scripting configuration and can be used when automating FortiWeb scripting through the REST API.