AlgoSec Ansible documentation!¶

AlgoSec Ansible Role¶

Ansible role to DevOps-ify network security management, leveraging AlgoSec’s business-driven security policy management solution

Documentation available online at: http://algosec-ansible-role.readthedocs.io/en/latest/

Requirements¶

This module is supported and fully tested under python2.7 and python3.6.

All modules of this role require environment:

pip install algosec --upgrade
pip install ansible marshmallow urllib3

Installation¶

The Ansible role can be installed directly from Ansible Galaxy by running:

ansible-galaxy install algosec.algosec

If the ansible-galaxy command-line tool is not available (usually shipped with Ansible), or you prefer to download the role package directly, navigate to the Ansible Galaxy role page and hit “Download”.

Alternately, you can directly navigate to our GitHub repository.

Usage¶

Once installed, you can start using the modules included in this role in your ansible playbooks.

To quickly get up and running a simple example you can follow these steps:

Download and unzip locally the examples folder by clicking here.
Update authentication credentials in vars/algosec-secrets.yml.
Update your AlgoSec server IP in inventory.ini.
Update the arguments of the relevant modules in one of the playbooks (files with the yml extension).
Run ansible-playbook -i inventory.ini <playbook-filename>.yml.
You’ve made it!

Documentation¶

Documentation available online at: https://algosec-ansible-role.readthedocs.io/en/latest/

How to build doc’s locally?¶

Using Docker, running from one folder outside of the project:

$ docker run -it -v $PWD/ansible-role-algosec/:/documents/ ivanbojer/spinx-with-rtd
$ cd docs
$ make html

Using Spinx:

$ cd docs
$ make html

Then see the docs/_build folder created for the html files.

License¶

MIT (see full license here)

Author Information¶

AlgoSec Official Website https://www.algosec.com/

Development¶

To kickoff local development, just use pipenv:

pipenv install

And to use the newly installed virtual environment just run:

pipenv shell

Modules list¶

algosec_define_application_flows¶

New in version 0.3.0.

Synopsis
Requirements
Options
Return Values
Examples
Example For Application Flows JSON File

Synopsis ¶

Update application flows of an AlgoSec BusinessFlow application to match a requested configuration.
Create, modify or delete application flows if needed.
Apply the changes in BusinessFlow to automatically create a FireFlow change request.
Optionally make sure that all defined flow pass the flow connectivity check on BusinessFlow

Requirements ¶

algosec can be obtained from PyPi https://pypi.python.org/pypi/algosec

Options ¶

parameter	required	default	comments
ip_address	yes		IP address (or hostname) of the AlgoSec server.
user	yes		Username credentials to use for auth.
password	yes		Password credentials to use for auth.
certify_ssl	no	False	Set whether or not to validate the AlgoSec server SSL certificate. This flag might be set to False only in testing environments. It is highly unrecommended to set it to False in production environments.
app_name	yes		BusinessFlow Application to update.
app_flows	yes		Dictionary of application flows to be applied. The configuration can be also provided from a JSON file. Please usage examples in the `Examples`_ section.
check_connectivity	no	false	Assert that all flows pass flow connectivity check on BusinessFlow. If any of the unchanged flows are not passing connectivity test, fail and report their names.

Return Values ¶

name	description	returned	type	sample
app_name	The BusinessFlow application for which flows were defined.	always	string	PayrollApp
deleted_flows	Number of flows deleted.	always	int
created_flows	Number of flows created.	always	int
modified_flows	Number of flows modified.	always	int
unchanged_flows	Number of flows left unchanged.	always	int
blocked_flows	List of flow names that failed connectivity check.	only when connectivity check fails, when check_connectivity flag in on.	list	["flow1", "flow2", "flow3"]

Examples ¶

---
- name: Update application flows of an AlgoSec BusinessFlow application
  hosts: algosec-server
  gather_facts: False

  roles:
    - role: algosec.algosec

  tasks:
  - name: Grab AlgoSec credentials from ansible-vault
    include_vars: 'algosec-secrets.yml'
    no_log: 'yes'

  - name: Set App flows on ABF using JSON configuration loaded from file
    # We use delegation to use the local python interpreter (and virtualenv if enabled)
    delegate_to: localhost
    vars:
      flows_data: "{{ lookup('file','vars/application-flows.json')|from_json }}"

    algosec_define_application_flows:
      ip_address: "{{ ip_address }}"
      user: "{{ username }}"
      password: "{{ password }}"
      app_name: "{{ item.app_name}}"
      app_flows: "{{item.app_flows}}"
    with_items: "{{ flows_data.applications }}"

Example For Application Flows JSON File ¶

{
  "applications": [
    {
      "app_name": "TEST",
      "app_flows": {
        "flow1": {
          "sources": ["HR Payroll server", "192.168.0.0/16"],
          "destinations": ["16.47.71.62"],
          "services": ["HTTPS"]
        },
        "flow2": {
          "sources": ["10.0.0.1"],
          "destinations": ["10.0.0.2"],
          "services": ["udp/501"]
        },
        "flow3": {
          "sources": ["1.2.3.4"],
          "destinations": ["3.4.5.6"],
          "services": ["SSH"]
        }
      }
    },
    {
      "app_name": "ANOTHER-APP",
      "app_flows": {
        "new-flow": {
          "sources": ["1.2.3.4"],
          "destinations": ["3.4.5.6"],
          "services": ["SSH"]
        }
      }
    }
  ]
}

algosec_add_single_application_flow¶

New in version 0.1.0.

Synopsis
Requirements
Options
Examples

Synopsis ¶

Create a new application flow on AlgoSec BusinessFlow.
Creation is skipped if the requested flow is a contained in one of the existing flows of the relevant application.

Requirements ¶

algosec can be obtained from PyPi https://pypi.python.org/pypi/algosec

Options ¶

parameter	required	default	comments
ip_address	yes		IP address (or hostname) of the AlgoSec server.
user	yes		Username credentials to use for auth.
password	yes		Password credentials to use for auth.
certify_ssl	no	False	Set whether or not to validate the AlgoSec server SSL certificate. This flag might be set to False only in testing environments. It is highly unrecommended to set it to False in production environments.
app_name	yes		BusinessFlow Application to add the flow to.
name	yes		Name for the flow to be created
sources	yes		Comma separated list of IPs or ABF network objects of traffic sources for the flow
destinations	yes		Comma separated list of IPs or ABF network objects of traffic destinations for the flow
services	yes		Comma separated list of traffic services to allow in the flow. Services can be as defined on AlgoSec BusinessFlow or in a proto/port format (only UDP and TCP are supported as proto. e.g. tcp/50).
users	no		Comma separated list of users the flow is relevant to.
network_applications	no		Comma separated list of network application names the flow is relevant to.
comment	no	Flow created by AlgoSecAnsible	Comment to attach to the flow
apply_draft	no	True	Apply the AlgoSec BusinessFlow application draft. Applying the application draft should be done after every batch of flow updates as each draft application may take a few minutes to execute. If you have more than one abf_flow_update module usage in your ansible playbook, it is recommended to set the "apply_draft" to False to all module calls but the last one (that should be True). Make sure that this module is called with "apply_draft" set to True at the last time it is used in an Ansible playbook.

Examples ¶

algosec_provision_network_connectivity¶

New in version 0.1.0.

Synopsis
Requirements
Options
Examples
Return Values

Synopsis ¶

Provision network connectivity by creating a change request in AlgoSec FireFlow.
No change request is created if traffic is already provisioned correctly.

Requirements ¶

algosec can be obtained from PyPi https://pypi.python.org/pypi/algosec

Options ¶

parameter	required	default	comments
ip_address	yes		IP address (or hostname) of the AlgoSec server.
user	yes		Username credentials to use for auth.
password	yes		Password credentials to use for auth.
certify_ssl	no	False	Set whether or not to validate the AlgoSec server SSL certificate. This flag might be set to False only in testing environments. It is highly unrecommended to set it to False in production environments.
requestor	yes		The first and last name of the requestor.
email	yes		The email address of the requestor.
traffic_lines	yes		List of dictionaries, each define a traffic lines that should be added into the change request. Each traffic_line dict object should contain the following keys: action, sources, destinationsand services. action - Boolean. True to allow traffic or False to drop it. sources - list of IP addresses or BusinessFlow objects destinations - list of IP addresses or BusinessFlow objects services - list of services of the traffic to allow. Accepted services are as defined on AlgoSec BusinessFlow or by port/proto format (e.g. tcp/50,udp/100,ssh). Please usage examples in the `Examples`_ section.
template	no	None	Full name of the template to use for the newly created change request.

Examples ¶

---
- name: Create Traffic Change Request if needed
  hosts: algosec-server
  gather_facts: False

  roles:
    - role: algosec.algosec

  tasks:
  - name: Grab the credentials from ansible-vault
    include_vars: 'algosec-secrets.yml'
    no_log: 'yes'

  - name: Create Traffic Change Request
    # We use delegation to use the local python interpreter (and virtualenv if enabled)
    delegate_to: localhost
    algosec_provision_network_connectivity:
      ip_address: "{{ ip_address }}"
      user: "{{ username }}"
      password: "{{ password }}"

      requestor: Almog Cohen
      email: almog@email.com
      traffic_lines:
        # This is an 'allow' traffic line
        - action: true
          sources: ["192.168.12.12", "123.123.132.123"]
          destinations: ["16.47.71.62", "234.234.234.234"]
          services: ["HTTPS", "http", "tcp/80", "tcp/51"]
        # This is a drop traffic line
        - action: false
          sources: ["10.0.0.1"]
          destinations: ["10.0.1.0"]
          services: ["HTTPS"]

    register: result

  - name: Print the test results
    debug: var=result

Return Values ¶

name	description	returned	type	sample
change_request_url	URL for the change request ticket on the AlgoSec server.	success	string	https://local.algosec.com/FireFlow/Ticket/Display.html?id=4447

Examples¶

algosec_define_application_flows¶

Match the application flows of an AlgoSec BusinessFlow application to a requested configuration

---
- name: Update application flows of an AlgoSec BusinessFlow application
  hosts: algosec-server
  gather_facts: False

  roles:
    - role: algosec.algosec

  tasks:
  - name: Grab AlgoSec credentials from ansible-vault
    include_vars: 'algosec-secrets.yml'
    no_log: 'yes'

  - name: Set App flows on ABF using JSON configuration loaded from file
    # We use delegation to use the local python interpreter (and virtualenv if enabled)
    delegate_to: localhost
    vars:
      flows_data: "{{ lookup('file','vars/application-flows.json')|from_json }}"

    algosec_define_application_flows:
      ip_address: "{{ ip_address }}"
      user: "{{ username }}"
      password: "{{ password }}"
      app_name: "{{ item.app_name}}"
      app_flows: "{{item.app_flows}}"
    with_items: "{{ flows_data.applications }}"

Example For Application Flows JSON File¶

{
  "applications": [
    {
      "app_name": "TEST",
      "app_flows": {
        "flow1": {
          "sources": ["HR Payroll server", "192.168.0.0/16"],
          "destinations": ["16.47.71.62"],
          "services": ["HTTPS"]
        },
        "flow2": {
          "sources": ["10.0.0.1"],
          "destinations": ["10.0.0.2"],
          "services": ["udp/501"]
        },
        "flow3": {
          "sources": ["1.2.3.4"],
          "destinations": ["3.4.5.6"],
          "services": ["SSH"]
        }
      }
    },
    {
      "app_name": "ANOTHER-APP",
      "app_flows": {
        "new-flow": {
          "sources": ["1.2.3.4"],
          "destinations": ["3.4.5.6"],
          "services": ["SSH"]
        }
      }
    }
  ]
}

algosec_add_single_application_flow¶

Create new Application Flows on AlgoSec BusinessFlow

---
- name: Create a flow on an AlsogsecBusinessFlow App
  hosts: algosec-server
  gather_facts: False

  roles:
    - role: algosec.algosec

  tasks:
  - name: Grab the credentials from ansible-vault
    include_vars: 'algosec-secrets.yml'
    no_log: 'yes'

  - name: Create the flow on ABF
    # We use delegation to use the local python interpreter (and virtualenv if enabled)
    delegate_to: localhost
    algosec_add_single_application_flow:
      ip_address: "{{ ip_address }}"
      user: "{{ username }}"
      password: "{{ password }}"

      app_name: Payroll
      name: payroll-server-auth
      sources: ["192.168.12.12"]
      destinations: ["16.47.71.62", "16.47.71.63"]
      services: ["HTTPS", "tcp/23"]

algosec_provision_network_connectivity¶

Check and create traffic change requests with AlgoSec FireFlow.

---
- name: Create Traffic Change Request if needed
  hosts: algosec-server
  gather_facts: False

  roles:
    - role: algosec.algosec

  tasks:
  - name: Grab the credentials from ansible-vault
    include_vars: 'algosec-secrets.yml'
    no_log: 'yes'

  - name: Create Traffic Change Request
    # We use delegation to use the local python interpreter (and virtualenv if enabled)
    delegate_to: localhost
    algosec_provision_network_connectivity:
      ip_address: "{{ ip_address }}"
      user: "{{ username }}"
      password: "{{ password }}"

      requestor: Almog Cohen
      email: almog@email.com
      traffic_lines:
        # This is an 'allow' traffic line
        - action: true
          sources: ["192.168.12.12", "123.123.132.123"]
          destinations: ["16.47.71.62", "234.234.234.234"]
          services: ["HTTPS", "http", "tcp/80", "tcp/51"]
        # This is a drop traffic line
        - action: false
          sources: ["10.0.0.1"]
          destinations: ["10.0.1.0"]
          services: ["HTTPS"]

    register: result

  - name: Print the test results
    debug: var=result

License¶

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute and/or sublicense, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Support¶

This template/solution is released under an as-is, best effort, support policy. These scripts should be seen as community supported and AlgoSec. will contribute our expertise as and when possible. We do not provide technical support or help in using or troubleshooting the components of the project through our normal support options such as AlgoSec support teams and backline support options. The underlying product used by the scripts or templates are still supported, but the support is only for the product functionality and not for help in deploying or using the template or script itself.

Unless explicitly tagged, all projects or work posted in our GitHub repository or sites other than our official Downloads page are provided under the best effort policy.

Search Page