Overview
This article will describes the steps how to use Sophos XG’s firewall.
The article incudes the following sections :
What to do
- Enable API
- Download the API help
- List of tags used in API
- How to use API
- Status code and description
What to do
Enable the API
- Go to Authentication > User to create a new user for API call. The user will need to be Administrator and its profile will require read/write permission. This API user is optional, its purpose is to lock the user down to certain rights in the XG, you can always use the Admin account.
- As an example, we configured this apiuser to have read/write permissions to the User configuration.
- Go to Backup & Firmware > API to enable the API Configuration and input the IP addresses you will make the call from in the Allowed IP Address field.
- This IP address needs to be in a zone that has access to the HTTPS Admin Services, if not, it needs a Local Service ACL Exception Rule.
- Go to Administrator > Device Access to verify its associated Zone or to create a Local Service ACL Exception Rule.
Download the API Help
Refer to the API documentation on how to format the XML request which is available in XG Firewall documentation, different versions have different API documentation. For example, below is how to find the API for XG v17.5:
- Open XG Firewall documentation
- Select the Sophos Firewall OS version 17.5
- Scroll down
- Click on API Help to download it, then click on index.html to open it.
- Once opened, it looks like this. it includes XML tags, status codes used in the API and how to format the XML requests for all XG components organized the same way as in the XG’s GUI.
Now you can make the API request to the XG using a browser or any remote application that support API like curl. Sophos XG Firewall: How to use API to import web exceptions is an example.
Note: Make sure you pass the certificate error if using a self signed certificate.
List of tags used in API
- XML tags are used for applying the configurations on the appliance.
| Tag Name | <Request> |
| Description | It is used for sending XML Request. To apply any configuration this tag is necessary. API Version also needs to be specified for configurations to be applied successfully. |
| Usage | Attribute – APIVersion Attribute Value – Version of API used. For example: “1500.2” |
| Example | <Request APIVersion=”1500.2”> <Login> <Username>admin</Username> <Password passwordform=”encrypt”>8b1e6eb1b182b1806390ffefc99753fc</Password> </Login> </Request> |
| Tag Name | <Login> |
| Description | It is used for Authentication. |
| Usage | Attribute – N/A Attribute Value – N/A |
| Example | Please refer to the example above. |
| Tag Name | <username> |
| Description | Specify the username in this tag |
| Usage | Attribute – N/A Attribute Value – N/A |
| Example | Please refer to the example above. |
| Tag Name | <Password passwordfrom = ‘encpryt’> |
| Description | Specify the encrypted password in this tag. |
| Usage | Attribute – N/A Attribute Value – N/A |
| Example | Please refer to the example above. |
| Tag Name | <Set> |
| Description | It is used to inform that the request is to be served as Add/Update depending on the Attribute value. Note: If,no “operation” attribute/value is defined in the tag, then Add operation will be performed followed by Update. |
| Usage | Attribute – operation Attribute Value – Add/Update |
| Example | <Request> <Login> <Username>admin</Username> <Password passwordform=”encrypt”>8b1e6eb1b182b1806390ffefc99753fc</Password> </Login> <Set operation=”add”> <IPHost> <Name>CustomIPHostTypeIPV4</Name> <IPFamily>IPv4</IPFamily> <HostType>IP</HostType> <IPAddress>1.1.1.1</IPAddress> </IPHost> </Set> </Request> |
| Tag Name | <Get> |
| Description | It is used to inform that the request needs to be served for retrieving data of the entity specified. |
| Usage | Attribute – N/A Attribute Value – N/A |
| Example | <Request> <Login> <Username>admin</Username> <Password passwordform=”encrypt”>8b1e6eb1b182b1806390ffefc99753fc</Password> </Login> <Get> <IPHost></IPHost> </Get> </Request> |
| Tag Name | <filter> |
| Description | It is used for retrieving entity data based on the criteria specified in the <Key> tag. It is only applicable for entity ‘Name’. |
| Usage | Attribute – N/A Attribute Value – N/A |
| Example | <Request> <Login> <Username>admin</Username> <Password passwordform=”encrypt”>8b1e6eb1b182b1806390ffefc99753fc</Password> </Login> <Get> <IPHost> <Filter> <key name=”Name” criteria=”like”>CustomIPHostTypeIPV4</key> </Filter> </IPHost> </Get> </Request> |
| Tag Name | <Key> |
| Description | It is used within the <Filter> tag to specify the filter key and Filter criteria. |
| Usage | Attribute – name, criteria Attribute Value – name = “Name”, criteria = [“=”,”!=”,”like”] |
| Example | Please refer to the example above. |
| Tag Name | <remove> |
| Description | It is used to delete data. |
| Usage | Attribute – N/A Attribute Value – N/A |
| Example | <Request> <Login> <Username>admin</Username> <Password passwordform=”encrypt”>8b1e6eb1b182b1806390ffefc99753fc</Password> </Login> <Remove> <IPHost> <Name>CustomIPHostTypeIPV4</Name> </IPHost> </Remove> </Request> |
| Tag Name | <response> |
| Description | Response of any request will be displayed in this tag. |
| Usage | Attribute – APIVersion Attribute Value – Same value as specified in the XML Request or if it is not specified then active firmware API Version will be considered. |
| Example | <Response APIVersion=”1500.2″> <Login> <status>Authetication Successful</status> </Login> <IPHost transactionid=””> <Status code=”502″>Message.IPHostRecordExists</Status> </IPHost> </Response> |
| Tag Name | <Status> |
| Description | It is a part of the <Response> tag and it indicates the configuration status based on the code. |
| Usage | Attribute – code Attribute Value – code value. |
| Example | <Response APIVersion="1500.2"> |
How to use API
Please use the link below to use API:
https://<Sophos IP>:<port>/webconsole/APIController?reqxml=<Add the XML request here>
Note: The port mentioned in the URL above should be the same as the port that is configured in the Admin Console HTTPS Port from System > Administration > Admin Settings.
Example:
Set request :
https://<Sophos IP>:<port>/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Set> <IPHost transactionid=""><Name>ip2</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress>2.2.2.9</IPAddress></IPHost> </Set></Request>
Get Request :
https://<Sophos IP>:<port>/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Get> <IPHost></IPHost> </Get></Request>
Status code and description
When XML response is received, it contains a status code with the description about the success/failure of the operation.
| Status | Message |
| 200 | Configuration applied successfully. |
| 201 | Operation partially successful. |
| 203 | Operation successful but few configurations could not be applied. Please contact Support. |
| 204-210 | Operation partially failed. |
| 211-215 | Warning messages will be displayed. For more information, refer to the section “Status Message Information” on each page. |
| 216 | Operation Successful. For more information, refer to the section “Status Message Information” on each page. |
| 500 | Operation could not be performed on Entity. |
| 501 | Configuration parameters validation failed. |
| 502 | Operation failed. Entity having same name already exists. |
| 503 | Operation failed. Entity having same parameter details already exists. |
| 504-510 | Operation failed. Deleting entity referred by another entity. |
| 511-520 | Operation failed. Please contact Support. |
| 521 | XML Request not compatible with current API version. |
| 522-525 | Maximum limit reached for entity. |
| 526 | Record does not exist. |
| 528 | Trying to update default entities which are not editable. |
| 529 | Invalid XML request for entity/entities. |
| 530 | API Version not supported for specific entity. |
| 541-590 | Operation failed. For more information, refer to the section “Status Message Information” on each page. |
| 599 | Not having privilege to add/modify configuration. |
Leave a Reply