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.

BusinessFlow API Client¶

class algosec.api_clients.business_flow.BusinessFlowAPIClient(server_ip, user, password, algobot_login_user, algobot_login_password, user_email='created_by_algobot@algosec.com', afa_sess_id=None, verify_ssl=True, session_adapter=<class 'algosec.helpers.AlgoSecServersHTTPAdapter'>)[source]¶

BusinessFlow RESTful API client.

Used by initiating and calling its public methods or by sending custom calls using the session property. Client implementation is strictly based on AlgoSec’s official API guide. 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.business_flow 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.business_flow import BusinessFlowAPIClient
client = BusinessFlowAPIClient(ip, username, password)
response = client.session.get(
    "{}/name/{}".format(client.applications_base_url, application_name)
)

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. verify_ssl (bool) – Turn on/off the connection’s SSL certificate verification. Defaults to True.

api_base_url¶

Return the base url for all API calls.

Type:	str

applications_base_url¶

Return the base url for all application related API calls.

Type:	str

apply_application_draft(app_revision_id)[source]¶

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

Parameters:	app_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

business_flow_base_url¶

Return the base url for BusinessFlow.

Type:	str

create_application_flow(app_revision_id, requested_flow)[source]¶

Create an application flow.

Creates network services that were defined in the flow but are not currently exist on ABF.

Parameters:	app_revision_id (int) – The application revision id as defined on ABF to create this flow on requested_flow (algosec.models.RequestedFlow) – The flow to be created
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\|list) – 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 created 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:	`AlgoSecAPIError` – If the flow deletion failed. `EmptyFlowSearch` – If no flow matching that name could be found.
Returns:	None

get_abf_application_dashboard_url(application_revision_id)[source]¶

Return URL for the application dashboard.

This is the applications’s dashboard on AlgoSec BusinessFlow and it can be viewed in the browser.

Parameters:	application_revision_id – The application revision ID to return the dashboard URL for.
Returns:	URL for the application dashboard on the AlgoSec BusinessFlow. An Example would look like that: https://10.0.0.12/BusinessFlow/#application/293/dashboard
Return type:	str

get_application_by_name(app_name)[source]¶

Return the latest revision 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:	Json of the latest application revision.
Return type:	dict

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_associated_applications(network_item)[source]¶

Return all applications containing network objects related to IP addresses.

Parameters:	network_item (str) – The network address or network object to search associated applications for
Raises:	`AlgoSecAPIError` – If error occurred while trying to fetch associated applications.
Returns:	List of dictionaries each representing an associated application.
Return type:	list

get_associated_applications_ui_query(queried_ip_address)[source]¶

Return URL that can be used in the browser to view the associated applications query.

Parameters:	queried_ip_address – The IP address we wish to find associated applications for.
Returns:	URL for ssociated applications query that can be viewed in the browser.
Return type:	str

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

static is_application_critical(application_json)[source]¶

Return True if the application’s json has the critical label set.

Parameters:	application_json – The application Json as returned from AlgoSec BusinessFlow APIs.
Returns:	True if the application is marked as a critical application
Return type:	bool

network_objects_base_url¶

Return the base url for all objects related API calls.

Type:	str

network_services_base_url¶

Return the base url for all services related API calls.

Type:	str

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_clients.firewall_analyzer.FirewallAnalyzerAPIClient(server_ip, user, password, algobot_login_user, algobot_login_password, user_email='created_by_algobot@algosec.com', afa_sess_id=None, verify_ssl=True, session_adapter=<class 'algosec.helpers.AlgoSecServersHTTPAdapter'>)[source]¶

FirewallAnalyzer SOAP API client.

Used by initiating and calling its public methods or by sending custom calls using the client property. Client implementation is strictly based on AlgoSec’s official API guide.

Example

Using the public methods to send an API call:

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

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. verify_ssl (bool) – Turn on/off the connection’s SSL certificate verification. Defaults to True.

afa_session_id_getter¶: Getter to afa session id. Initiates Client if necessary. In case Client Initiation fails for some reason, afa session id might be none. :return: afa session id.

execute_traffic_simulation_query(source, destination, service, target=None, application=None)[source]¶

Return results and browser URL for a traffic simulation query.

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) target (str) – Name of a device or a group the query should run on. With the default None value, the query will run on the entire network and all permitted devices for the user. application (str) – Name of the network application to include in the query.
Raises:	`AlgoSecAPIError` – If any error occurred while executing the traffic simulation query.
Returns:	A dict mapping the results to their values. For example: { ‘result’: DeviceAllowanceState.ALLOWED, ‘query_url’: ‘https://local.algosec.com/fa/query/results/#/work/ALL_FIREWALLS_query-1543622562206/’ }
Return type:	dict

run_traffic_simulation_query(source, destination, service)[source]¶

Run a traffic simulation query.

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_clients.fire_flow.FireFlowAPIClient(server_ip, user, password, algobot_login_user, algobot_login_password, user_email='created_by_algobot@algosec.com', afa_sess_id=None, verify_ssl=True, session_adapter=<class 'algosec.helpers.AlgoSecServersHTTPAdapter'>)[source]¶

FireFlow SOAP API client.

Used by initiating and calling its public methods or by sending custom calls using the client property. Client implementation is strictly based on AlgoSec’s official API guide.

Example

Using the public methods to send an API call:

from algosec.api_clients.fire_flow import FireFlowAPIClient
client = FireFlowAPIClient(ip, username, password)
change_request = client.get_change_request_by_id(change_request_id)

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. verify_ssl (bool) – Turn on/off the connection’s SSL certificate verification. Defaults to True.

create_change_request(subject, requestor_name, email, traffic_lines, description='', template='Basic Change Traffic Request')[source]¶

Create a new change request.

Parameters:	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. traffic_lines (list[algosec.models.ChangeRequestTrafficLine]) – List of traffic lines each describing its sources, destinations and services. 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

BLOCK¶: 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.

It is used to represent a new flow that is about to be created.

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 (list) – 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_content¶

The content of the response that caused the error. If it is a JSON, a JSON will be stored and not the raw content. Will be None if is not passed.

Type:	dict\|str

status_code¶

The status code of the response of the failed API call. (Optional)

Type:	int

Keyword Arguments:
	response – The response object that caused the error. (Optional) response_content (dict) – The content of the response of the failed API call. (Optional) status_code (int) – The status code of the response of the failed API call. (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.UnauthorizedUserException(message='', extra_details='')[source]¶: a class to differ an exception caused by permissions issue

exception algosec.errors.UnrecognizedAllowanceState(*args, **kwargs)[source]¶: Raised when parsing unknown device allowance state strings.