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:
- 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: AlgoSecAPIError
– If the flow deletion failed.EmptyFlowSearch
– If no flow matching that name could be found.
Returns: None
-
get_application_flows
(app_revision_id)[source]¶ Return all flows of the application revision.
Note
Only flows with
flowType
ofAPPLICATION_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 failedEmptyFlowSearch
– 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:
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.
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
- It is used to represent a new flow that is about to be created.
- 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.
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.