Sophos XG Firewall : How to use API

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:

  • 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 curlSophos 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.
UsageAttribute – 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.
UsageAttribute – N/A
Attribute Value – N/A
ExamplePlease 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’>
DescriptionSpecify the encrypted password in this tag.
UsageAttribute – N/A
Attribute Value – N/A
ExamplePlease 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.
UsageAttribute – 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.
UsageAttribute – 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’.
UsageAttribute – 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.
UsageAttribute – name, criteria
Attribute Value – name = “Name”, criteria = [“=”,”!=”,”like”]
ExamplePlease refer to the example above.
Tag Name<remove>
Description It is used to delete data.
UsageAttribute – 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.
UsageAttribute – 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.
UsageAttribute – code
Attribute Value – code value.
Example<Response APIVersion="1500.2">
     <Login>
          <status>Authetication Successful</status>
     </Login>
     <IPHost transactionid="">
          <Status code="502">Operation failed. Entity having same name already exists</Status>
     </IPHost>
</Response>

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.
203Operation successful but few configurations could not be applied. Please contact Support.
204-210Operation partially failed.
211-215 Warning messages will be displayed. For more information, refer to the section “Status Message Information” on each page.
216Operation Successful. For more information, refer to the section “Status Message Information” on each page.
500Operation could not be performed on Entity.
501Configuration parameters validation failed.
502Operation failed. Entity having same name already exists.
503Operation failed. Entity having same parameter details already exists.
504-510Operation failed. Deleting entity referred by another entity.
511-520Operation failed. Please contact Support.
521XML Request not compatible with current API version.
522-525Maximum limit reached for entity.
526Record does not exist.
528Trying to update default entities which are not editable.
529Invalid XML request for entity/entities.
530API Version not supported for specific entity.
541-590Operation failed. For more information, refer to the section “Status Message Information” on each page.
599Not having privilege to add/modify configuration.

Be the first to comment

Leave a Reply

Your email address will not be published.


*