API Clients

Welcome! This page explain the best way to use algosec API clients. We’ll start with a short brief description of the module and its constitutions followed by in-depth explanation and exploration of each of the API Clients.

API clients for the following AlgoSec services: BusinessFlow, FireFlow and FirewallAnalyzer.

The clients are intended to be imported, initiated and used in any python code. Clients implementation is based on AlgoSec’s official API guide. Clients require three arguments to be initiated:

  • AlgoSec server IP
  • username
  • password
  • verify_ssl (optional)

Examples

Once initiated, the client is used by calling any of its public functions:

from algosec.api_clients import FirewallAnalyzerAPIClient
client = FirewallAnalyzerAPIClient(ip, username, password)
query_result = client.run_traffic_simulation_query(
    source,
    dest,
    service
)

If the API call you were looking for is not yet implemented, you can send authenticated custom API call to the server using the client’s session property. Please see specific API Client documentations to find out how.

BusinessFlow API Client

class algosec.api_client.BusinessFlowAPIClient(server_ip, user, password, verify_ssl=True)[source]

BusinessFlow RESTful API client.

Used by calling its public methods or by sending custom calls using the session property. To ease the usability for custom API calls, a bunch of base urls were added as properties to this class (see example below).

Examples

Using the public methods to send an API call:

from algosec.api_clients import BusinessFlowAPIClient
client = BusinessFlowAPIClient(ip, username, password)
application_revision_id = client.get_application_revision_id_by_name("ApplicationName")

Sending a custom API Call:

from algosec.api_clients import BusinessFlowAPIClient
client = BusinessFlowAPIClient(ip, username, password)
response = client.session.get(
    "{}/name/{}".format(client.applications_base_url, application_name)
)
api_base_url

str – Return the base url for all API calls.

applications_base_url

str – Return the base url for all application related API calls.

apply_application_draft(revision_id)[source]

Apply an application draft and automatically create a FireFlow change request.

Parameters:revision_id (int|str) – The revision ID of the application to apply the draft for.
Raises:AlgoSecAPIError – If error occurred while trying to apply the application draft.
Returns:The API call response.
Return type:requests.models.Response
create_application_flow(app_revision_id, requested_flow, retry_for_missing_services=True)[source]

Create an application flow.

Parameters:
  • app_revision_id (str) – The application revision id as defined on ABF to create this flow on
  • requested_flow (algosec.models.RequestedFlow) – The flow to be created
  • retry_for_missing_services (bool) –
Raises:

AlgoSecAPIError – If application flow creation failed.

Returns:

An Application object as defined in the API Guide.

Return type:

dict

create_missing_network_objects(all_network_objects)[source]

Create network objects if they are not already defined on the server.

Parameters:all_network_objects (collections.Iterable[str]) – List of the network objects to create if missing from the server.
Raises:AlgoSecAPIError – If the one of the network objects creation failed.
Returns:List of the created network objects.
Return type:list[dict]

Note

If one of the given objects is not a valid IP address or subnet string, the object won’t be created.

create_network_object(type, content, name)[source]

Create a new network object.

Parameters:
  • type (algosec.models.NetworkObjectType) – The network object type
  • content (str) –

    Define the newly created network object. Content depend upon the selected type:

    • HOST: Content is the IP address of the object.
    • RANGE: Content is IP range or CIDR.
    • GROUP: Content is a list of ExistingNetworkObject or
      NewNetworkObject objects as defined in the API Guide.
    • ABSTRACT: Content is None or an empty string.
  • name (str) – Name of the new network object
Raises:

AlgoSecAPIError – If the network object creation failed.

Returns:

The newly create ExistingNetworkObject object.

Return type:

dict

create_network_service(service_name, content, custom_fields=None)[source]

Create a network service.

Parameters:
  • service_name (str) – The service object’s service_name
  • content (list[(str,int)]) – List of (port, proto) pairs defining the services
  • custom_fields – The custom fields to include for the object.
Raises:

AlgoSecAPIError – If network service creation failed.

Returns:

The created NetworkService object as defined in the API Guide.

Return type:

dict

delete_flow_by_id(app_revision_id, flow_id)[source]

Delete an application flow given its id.

Parameters:
  • app_revision_id (int|str) – The revision ID of the application to delete the flow from.
  • flow_id (int|str) – The ID of the flow to delete.
Raises:

AlgoSecAPIError – If the flow deletion failed.

Returns:

None

delete_flow_by_name(app_revision_id, flow_name)[source]

Delete an application flow given its name.

Parameters:
  • app_revision_id (int|str) – The revision ID of the application to delete the flow from.
  • flow_name (str) – The name of the flow to delete.
Raises:
Returns:

None

get_application_flows(app_revision_id)[source]

Return all flows of the application revision.

Note

Only flows with flowType of APPLICATION_FLOW are returned. The rest of the flows (e.g shared flows) are filtered out.

Parameters:app_revision_id (str|int) – The ID of the application revision to fetch the flows for
Raises:AlgoSecAPIError – If application flows list could not be fetched.
Returns:List of Flow objects as defined in the API Guide.
Return type:list[dict]
get_application_revision_id_by_name(app_name)[source]

Return the latest revision id of an application by its name.

Parameters:app_name (str) – The application name to look for.
Raises:AlgoSecAPIError – If no application matching the given name was found.
Returns:The latest application revision ID.
Return type:int
get_flow_by_name(app_revision_id, flow_name)[source]

Return application flow by its name

Parameters:
  • app_revision_id (int|str) – The application revision ID to fetch the flow from.
  • flow_name (str) – The name of the flow to fetch.
Raises:
  • AlgoSecAPIError – If fetching the full list of flows for the application revision failed
  • EmptyFlowSearch – If no flow matching that name could be found
Returns:

Flow object as defined in the API Guide.

Return type:

dict

get_flow_connectivity(app_revision_id, flow_id)[source]

Return a flow connectivity object for a flow given its ID.

Parameters:
  • app_revision_id (int|str) – The ID of the application revision to lookup the flow in.
  • flow_id (int|str) – The ID of the flow to fetch FlowConnectivity for.
Raises:

AlgoSecAPIError – If error occurred while fetching the flow connectivity object.

Returns:

FlowConnectivity object as defined in the API Guide.

Return type:

dict

get_network_object_by_name(object_name)[source]

Return a network object by its name.

Parameters:object_name (str) – The object name to be searched.
Raises:AlgoSecAPIError – If no network object matching the given name could be found.
Returns:The NetworkObject object matching the name lookup.
Return type:dict
get_network_service_by_name(service_name)[source]

Get a network service object by its name.

Parameters:service_name (str) – The name of the service.
Raises:AlgoSecAPIError – If no such network service could be found by name.
Returns:NetworkObject as defined on the API Guide.
Return type:dict
is_flow_contained_in_app(app_revision_id, requested_flow)[source]

Return True if a certain RequestedFlow is already contained in a given application.

If the requested_flow is already contained within one of the existing application flows, return True.

Parameters:requested_flow (algosec.models.RequestedFlow) – The definition of the flow to check containment for.
Raises:AlgoSecAPIError – If error occurred while fetching the application flows.
Returns:True if this flow definition is contained within another existing flow in the application.
Return type:bool
network_objects_base_url

str – Return the base url for all objects related API calls.

network_services_base_url

str – Return the base url for all services related API calls.

search_network_objects(ip_or_subnet, search_type)[source]

Return network objects related to a given IP or subnet.

Parameters:
  • ip_or_subnet (str) – The IP address or hostname of the object, or a subnet. (e.g: 192.1.1.1, 192.168.0.0/16)
  • search_type (algosec.models.NetworkObjectSearchTypes) –

    The enum for search type to perform. Could be one of :

    • INTERSECT - Search objects which their definition intersect with the given IP or subnet.
    • CONTAINED - Search for objects which the given IP or subnet is contained in.
    • CONTAINING - Search for objects contained within the given IP or subnet.
    • EXACT - Search the object which is defined exactly by (and only by) the given IP or subnet.
Raises:

AlgoSecAPIError – If an error occurred during the object search.

Returns:

List of network objects matching the given obj and search type.

Each of the objects is a NetworkObject as defined in the API Guide.

Return type:

list[dict]

FirewallAnalyzer API Client

class algosec.api_client.FirewallAnalyzerAPIClient(server_ip, user, password, verify_ssl=True)[source]

FirewallAnalyzer SOAP API client.

Parameters:
  • server_ip (str) – IP address of the AlgoSec server.
  • user (str) – Username used to log in to AlgoSec.
  • password (str) – The user’s password, similar to the one used to log in to the UI.

Used by calling its public methods or by sending custom calls using the client property.

Example

Using the public methods to send an API call:

from algosec.api_clients import FirewallAnalyzerAPIClient
client = FirewallAnalyzerAPIClient(ip, username, password)
query_result = client.run_traffic_simulation_query(
    source,
    dest,
    service
)
run_traffic_simulation_query(source, destination, service)[source]

Run a traffic simulation query and return its results.

Parameters:
  • source (str) – Source of the simulated traffic. (e.g. IPs, subnet or an object name)
  • destination (str) – Destination of the simulated traffic. (e.g. IPs, subnet or an object name)
  • service (str) – Service of the simulated traffic (e.g: tcp/200, http)
Raises:

AlgoSecAPIError – If any error occurred while executing the traffic simulation query.

Returns:

Traffic simulation query result.

Return type:

algosec.models.DeviceAllowanceState

FireFlow API Client

class algosec.api_client.FireFlowAPIClient(server_ip, user, password, verify_ssl=True)[source]

FireFlow SOAP API client.

Parameters:
  • server_ip (str) – IP address of the AlgoSec server.
  • user (str) – Username used to log in to AlgoSec.
  • password (str) – The user’s password, similar to the one used to log in to the UI.

Used by calling its public methods or by sending custom calls using the client property.

Example

Using the public methods to send an API call:

from algosec.api_clients import FireFlowAPIClient
client = FireFlowAPIClient(ip, username, password)
change_request = client.get_change_request_by_id(change_request_id)
create_change_request(action, subject, requestor_name, email, sources, destinations, services, description='', template=None)[source]

Create a new change request.

Parameters:
  • action (algosec.models.ChangeRequestAction) – action requested by this Change Request to allow or drop traffic.
  • subject (str) – The ticket subject, will be shown on FireFlow.
  • requestor_name (str) – The ticket creator name, will be shown on FireFlow.
  • email (str) – The email address of the requestor.
  • sources (list[str]) – List of IP address representing the source of the traffic.
  • destinations (list[str]) – List of IP address representing the destination of the traffic.
  • services (list[str]) – List of services which describe the type of traffic. Each service could be a service name as defined on AlgoSec servers or just a proto/port pair. (e.g. ssh, http, tcp/50, udp/700)
  • description (str) – description for the ticket, will be shown on FireFlow.
  • template (str) – When different than None, this template will be passed on to FireFlow to be used as the template for the new change requets.
Raises:

AlgoSecAPIError – If change request creation failed.

Returns:

The URL for the newley create change request on FireFlow

Return type:

str

get_change_request_by_id(change_request_id)[source]

Get a change request by its ID.

Useful for checking the status of a change request you opened through the API.

Parameters:change_request_id – The ID of the change request to fetch.
Raises:AlgoSecAPIError – If the change request was not found on the server or another error occurred while fetching the change request.
Returns:The change request ticket object.

Models and Constants

Define models and enums used by the API clients.

Note

Most developers will not have to use any of the contents of this module directly.

class algosec.models.ChangeRequestAction[source]

Enum representing a change request expected action.

ALLOW

This enum will mark the change request to allow the requested traffic

DROP

This enum will mark the change request to block the requested traffic

class algosec.models.DeviceAllowanceState[source]

Enum representing different device allowance states as defined on BusinessFlow.

PARTIALLY_BLOCKED
BLOCKED
ALLOWED
NOT_ROUTED
class algosec.models.NetworkObjectSearchTypes[source]

Enum used for search_network_objects()

class algosec.models.NetworkObjectType[source]

Enum representing a NetworkObject type as defined on the API Guide.

Used by various API clients to communicate with the AlgoSec servers.

HOST

Denotes an object that is defined by it’s IP address.

RANGE

Denotes an object that is defined by an IP range or CIDR.

GROUP

Denotes an object that is defined by a list of ExistingNetworkObject or NewNetworkObject objects.

ABSTRACT

Denotes an object that is devoid of any particular definition. Defined with empty content.

class algosec.models.RequestedFlow(name, sources, destinations, network_users, network_applications, network_services, comment, custom_fields=None, type='APPLICATION')[source]

Represents a NewFlow model from the API Guide.

This model is used by the BusinessFlowAPIClient to create and handle different operations regarding new and existing flows.

Examples

  1. It is used to represent a new flow that is about to be created.
  2. It is used to check if any flow definition is already contained within other existing flows.
Parameters:
  • name (str) – The name of the new flow.
  • sources (list[str]) – Sources for the flow.
  • destinations (list[str]) – Destinations for the flow.
  • network_users (list[str]) – Network user names for the flow.
  • network_applications (list[str]) – Names of network application for the flow.
  • network_services (list[str]) – Names of network services names for the flow.
  • comment (str) – Any comment to save alongside the flow.
  • custom_fields – Custom fields for the new flow
  • type (str) – Optional. The type of the flow to create. Default to APPLICATION.
get_json_flow_definition()[source]

Return a dict object representing a NewFlow as expected by the API.

Returns:NewFlow object.
Return type:dict

Exceptions and Errors

Exception and error classes used and thrown by the API clients.

Developers will might use the exceptions and errors in their code while working with the API clients. Each of public methods of the API client document which errors may raise by their use. Then, developers can try-except in their code using the AlgoSec defined errors for better clarity of their code.

exception algosec.errors.AlgoSecAPIError(*args, **kwargs)[source]

Root parent AlgoSec API error subclassed by all other API errors.

response

The response object that caused the error. If it was not passed to the constructor, will be None.

response_json

dict – The JSON of the response that caused the error. Will be None if is not available.

Keyword Arguments:
 
  • response – The response object that caused the error. (Optional)
  • response_json (dict) – The JSON of the response that caused the error. (Optional)
exception algosec.errors.AlgoSecBusinessFlowAPIError(*args, **kwargs)[source]

Raised for any BusinessFlow related API errors.

This error is also subclassed by other more specific BusinessFlow related errors.

exception algosec.errors.AlgoSecLoginError(*args, **kwargs)[source]

Raised when login to AlgoSec API fails

exception algosec.errors.EmptyFlowSearch(*args, **kwargs)[source]

Raised when flow search by exact name fails.

exception algosec.errors.UnrecognizedAllowanceState(*args, **kwargs)[source]

Raised when parsing unknown device allowance state strings.

exception algosec.errors.UnrecognizedServiceString[source]

Raised when parsing invalid network service definition strings