api_client module

Copyright 2023 Sophos Ltd. All rights reserved. Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class api_client.APIClient(username, password, hostname, port, verify)[source]

Bases: object

Class for making the requests to the firewall XML API.

get_tag(xml_tag: str, timeout: int = 30, output_format: str = 'dict')[source]

Execute a get for a specified XML tag.

Parameters:

  • xml_tag (str) – XML tag for the request

  • timeout (int) – Request timeout in seconds. Defaults to 30 seconds.

  • output_format (str) – Output format. Valid options are “dict” or “xml”. Defaults to dict.

get_tag_with_filter(xml_tag: str, key: str, value: str, operator: str = 'like', timeout: int = 30, output_format: str = <class 'dict'>)[source]

Execute a get for a specified XML tag with filter criteria.

Parameters:

  • xml_tag (str) – XML tag for the request.

  • key (str) – Search key

  • value (str) – Search value

  • operator (str, optional) – Operator for search (“=”,”!=”,”like”). Defaults to “like”.

  • timeout (int) – Request timeout in seconds. Defaults to 30 seconds.

  • output_format (str) – Output format. Valid options are “dict” or “xml”. Defaults to dict.

login(output_format)[source]

Test login credentials.

Parameters:

output_format (str) – Output format. Valid options are “dict” or “xml”. Defaults to dict.

remove(xml_tag: str, name: str, key: str = 'Name', timeout: int = 30, output_format: str = 'dict')[source]

Remove an object from the firewall.

Parameters:

  • xml_tag (str) – The XML tag indicating the type of object to be removed.

  • name (str) – The name of the object to be removed.

  • key (str) – The primary XML key that is used to look up the object. Defaults to Name.

  • timeout (int) – Request timeout in seconds. Defaults to 30 seconds.

  • output_format (str) – Output format. Valid options are “dict” or “xml”. Defaults to dict.

submit_template(filename: str, template_vars: dict, template_dir: str = None, timeout: int = 30, debug: bool = False) → dict[source]

Submits XML payload stored as a Jinja2 file

Parameters:

  • filename (str) – Jinja2 template filename. Place in “templates” directory or configure template_dir.

  • template_vars (dict) – Dictionary of variables to inject into the template. Username and password are passed in by default.

  • template_dir (str) – Directory to look for templates. Default is “./templates”.

  • timeout (int) – Request timeout in seconds. Defaults to 30 seconds.

  • debug (bool, optional) – Enable debug mode to display XML payload. Defaults to False.

Returns:

dict

submit_xml(template_data: str, template_vars: dict = None, set_operation: str = 'add', timeout: int = 30, debug: bool = False) → dict[source]

Submits XML payload as a string to the API.

Parameters:

  • template_data (str) – A string containing the XML payload. Variables can be optionally passed in the string using Jinja2 (ex. {{ some_var }})

  • template_vars (dict, optional) – Dictionary of variables to inject into the XML string.

  • set_operation (str) – Specify ‘add’ or ‘update’ set operation. Default is add. Specify None to exclude the set operation XML block.

  • timeout (int) – Request timeout in seconds. Defaults to 30 seconds.

Returns:

dict

update(xml_tag: str, update_params: dict, name: str = None, lookup_key: str = 'Name', output_format: str = 'dict', timeout: int = 30, debug: bool = False)[source]

Update an existing object on the firewall.

Parameters:

  • xml_tag (str) – The XML tag indicating the type of object to be updated.

  • update_params (dict) – Keys/values to be updated. Keys must match an existing XML key.

  • name (str, optional) – The name of the object to be updated, if applicable.

  • lookup_key (str, optional) – The XML key name to look up the name of the object. Default is “Name”.

  • output_format (str) – Output format. Valid options are “dict” or “xml”. Defaults to dict.

  • timeout (int) – Request timeout in seconds. Defaults to 30 seconds.

  • debug (bool) – Displays the XML payload that was submitted

validate_arg(arg_name, arg_value, valid_choices)[source]
exception api_client.SophosFirewallAPIError[source]

Bases: Exception

Error raised when an API operation fails

exception api_client.SophosFirewallAuthFailure[source]

Bases: Exception

Error raised when authentication to firewall fails

exception api_client.SophosFirewallInvalidArgument[source]

Bases: Exception

Error raised when an invalid argument is specified

exception api_client.SophosFirewallOperatorError[source]

Bases: Exception

Error raised when an invalid operator is specified

exception api_client.SophosFirewallZeroRecords[source]

Bases: Exception

Error raised when a get request returns zero records