algosec-sdk 1.0.1

data/lib/algosec-sdk/exceptions.rb

@@ -0,0 +1,37 @@
+# (c) Copyright 2018 AlgoSec Systems
+#
+# 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.
+
+# Contains all the custom Exception classes
+module ALGOSEC_SDK
+  # Client configuration is invalid
+  class InvalidClient < StandardError
+  end
+
+  # Could not make request
+  class InvalidRequest < StandardError
+  end
+
+  # 400
+  class BadRequest < StandardError
+  end
+
+  # 401
+  class Unauthorized < StandardError
+  end
+
+  # 404
+  class NotFound < StandardError
+  end
+
+  # Other bad response codes
+  class RequestError < StandardError
+  end
+end

data/lib/algosec-sdk/helpers/business_flow_helper.rb

@@ -0,0 +1,347 @@
+require_relative 'flow_comparisons'
+require 'set'
+require 'ipaddress'
+
+module ALGOSEC_SDK
+  module NetworkObjectType
+    HOST = 'Host'.freeze
+    RANGE = 'Range'.freeze
+    GROUP = 'Group'.freeze
+    ABSTRACT = 'Abstract'.freeze
+  end
+end
+
+module ALGOSEC_SDK
+  module NetworkObjectSearchType
+    INTERSECT = 'INTERSECT'.freeze
+    CONTAINED = 'CONTAINED'.freeze
+    CONTAINING = 'CONTAINING'.freeze
+    EXACT = 'EXACT'.freeze
+  end
+end
+
+module ALGOSEC_SDK
+  # Contains helper methods for BusinessFlow
+  module BusinessFlowHelper
+    # Request login to get session cookie credentials
+    # @raise [RuntimeError] if the request failed
+    # @return [Array<Hash>] flows
+    def login
+      response_handler(rest_post('/BusinessFlow/rest/v1/login'))
+    end
+
+    # Get list of application flows for an application revision id
+    # @param [String, Symbol] app_revision_id
+    # @raise [RuntimeError] if the request failed
+    # @return [Array<Hash>] flows
+    def get_application_flows(app_revision_id)
+      response = rest_get("/BusinessFlow/rest/v1/applications/#{app_revision_id}/flows")
+      flows = response_handler(response)
+      flows.map { |flow| flow['flowType'] == 'APPLICATION_FLOW' ? flow : nil }.compact
+    end
+
+    # Get application flows from the server as a hash from flow name it it's content
+    # @param [String, Symbol] app_revision_id
+    # @raise [RuntimeError] if the request failed
+    # @return [Hash] flows as a hash from name to flow
+    def get_application_flows_hash(app_revision_id)
+      Hash[get_application_flows(app_revision_id).map { |flow| [flow['name'], flow] }]
+    end
+
+    # Delete a specific flow
+    # @param [String] app_revision_id
+    # @param [String] flow_id
+    # @raise [RuntimeError] if the request failed
+    # @return true
+    def delete_flow_by_id(app_revision_id, flow_id)
+      response = rest_delete("/BusinessFlow/rest/v1/applications/#{app_revision_id}/flows/#{flow_id}")
+      response_handler(response)
+      true
+    end
+
+    # Get connectivity status for a flow
+    # @param [String] app_revision_id
+    # @param [String] flow_id
+    # @raise [RuntimeError] if the request failed
+    # @return [String] Connectivity Status dict that contain flowId, queryLink and status keys
+    def get_flow_connectivity(app_revision_id, flow_id)
+      response = rest_post("/BusinessFlow/rest/v1/applications/#{app_revision_id}/flows/#{flow_id}/check_connectivity")
+      response_handler(response)
+    end
+
+    # Create a flow
+    # @param [String] app_revision_id The application revision id to create the flow in
+    # @param [Object] flow_name
+    # @param [Array<String>] sources
+    # @param [Array<String>] destinations
+    # @param [Array<String>] network_users
+    # @param [Array<String>] network_apps
+    # @param [Array<String>] network_services
+    # @param [String] comment
+    # @param [String] type
+    # @raise [RuntimeError] if the request failed
+    # @return Newly created application flow
+    # rubocop:disable Metrics/ParameterLists
+    def create_application_flow(
+      app_revision_id,
+      flow_name,
+      sources,
+      destinations,
+      network_services,
+      network_users,
+      network_apps,
+      comment,
+      type = 'APPLICATION',
+      custom_fields = []
+    )
+      # rubocop:enable Metrics/ParameterLists
+
+      # Create the missing network objects from the sources and destinations
+      create_missing_network_objects(sources + destinations)
+      create_missing_services(network_services)
+
+      get_named_objects = ->(name_list) { name_list.map { |name| { name: name } } }
+
+      new_flow = {
+        name: flow_name,
+        sources: get_named_objects.call(sources),
+        destinations: get_named_objects.call(destinations),
+        users: network_users,
+        network_applications: get_named_objects.call(network_apps),
+        services: get_named_objects.call(network_services),
+        comment: comment,
+        type: type,
+        custom_fields: custom_fields
+      }
+      response = rest_post("/BusinessFlow/rest/v1/applications/#{app_revision_id}/flows/new", body: [new_flow])
+      flows = response_handler(response)
+      # AlgoSec return a list of created flows, we created only one
+      flows[0]
+    end
+
+    # Fetch an application flow by it's name
+    # @param [String] app_revision_id The application revision id to fetch the flow from
+    # @param [Object] flow_name
+    # @raise [RuntimeError] if the request failed
+    # @return The requested flow
+    def get_application_flow_by_name(app_revision_id, flow_name)
+      flows = get_application_flows(app_revision_id)
+      requested_flow = flows.find do |flow|
+        break flow if flow['name'] == flow_name
+      end
+
+      if requested_flow.nil?
+        raise(
+          "Unable to find flow by name. Application revision id: #{app_revision_id}, flow_name: #{flow_name}."
+        )
+      end
+      requested_flow
+    end
+
+    # Get latest application revision id by application name
+    # @param [String, Symbol] app_name
+    # @raise [RuntimeError] if the request failed
+    # @return [Boolean] application revision id
+    def get_app_revision_id_by_name(app_name)
+      response = rest_get("/BusinessFlow/rest/v1/applications/name/#{app_name}")
+      app = response_handler(response)
+      app['revisionID']
+    end
+
+    # Apply application draft
+    # @param [String] app_revision_id
+    # @raise [RuntimeError] if the request failed
+    # @return true
+    def apply_application_draft(app_revision_id)
+      response = rest_post("/BusinessFlow/rest/v1/applications/#{app_revision_id}/apply")
+      response_handler(response)
+      true
+    end
+
+    # Create a new network service
+    # @param [String] service_name
+    # @param content List of lists in the form of (protocol, port)
+    # @raise [RuntimeError] if the request failed
+    # @return true if service created or already exists
+    def create_network_service(service_name, content)
+      content = content.map { |service| { protocol: service[0], port: service[1] } }
+      new_service = { name: service_name, content: content }
+      response = rest_post('/BusinessFlow/rest/v1/network_services/new', body: new_service)
+      response_handler(response)
+      true
+    end
+
+    # Create a new network object
+    # @param [NetworkObjectType] type type of the object to be created
+    # @param [String] content Define the newly created network object. Content depend upon the selected type
+    # @param [String] name Name of the new network object
+    # @raise [RuntimeError] if the request failed
+    # @return Newly created object
+    def create_network_object(type, content, name)
+      new_object = { type: type, name: name, content: content }
+      response = rest_post('/BusinessFlow/rest/v1/network_objects/new', body: new_object)
+      response_handler(response)
+    end
+
+    # Search a network object
+    # @param [String] ip_or_subnet The ip or subnet to search the object with
+    # @param [NetworkObjectSearchType] search_type type of the object search method
+    # @raise [RuntimeError] if theh request failed
+    # @return List of objects from the search result
+    def search_network_object(ip_or_subnet, search_type)
+      response = rest_get(
+        '/BusinessFlow/rest/v1/network_objects/find',
+        query: { address: ip_or_subnet, type: search_type }
+      )
+      response_handler(response)
+    end
+
+    # Return a plan for modifying application flows based on current and newly proposed application flows definition
+    # @param [Array<Hash>] server_app_flows List of app flows currently defined on the server
+    # @param [Array<Hash>] new_app_flows List of network flows hash definitions
+    # @raise [RuntimeError] if the request failed
+    # @return 3 lists of flow names: flows_to_delete, flows_to_create, flows_to_modify
+    def plan_application_flows(server_app_flows, new_app_flows)
+      current_flow_names = Set.new(server_app_flows.keys)
+      new_flow_names = Set.new(new_app_flows.keys)
+      # Calculate the flows_to_delete, flows_to_create and flows_to_modify and unchanging_flows
+      flows_to_delete = current_flow_names - new_flow_names
+      flows_to_create = new_flow_names - current_flow_names
+      flows_to_modify = Set.new((new_flow_names & current_flow_names).map do |flow_name|
+        flow_on_server = server_app_flows[flow_name]
+        new_flow_definition = new_app_flows[flow_name]
+        ALGOSEC_SDK::AreFlowsEqual.flows_equal?(new_flow_definition, flow_on_server) ? nil : flow_name
+      end.compact)
+
+      [flows_to_delete, flows_to_create, flows_to_modify]
+    end
+
+    # Create/modify/delete application2 flows to match a given flow plan returned by 'plan_application_flows'
+    # @param [Integer] app_name The app to create the flows for
+    # @param [Array<Hash>] new_app_flows List of network flows hash definitions
+    # @param [Array<Hash>] flows_from_server List of network flows objects fetched from the server
+    # @param [Array<String>] flows_to_delete List of network flow names for deletion
+    # @param [Array<String>] flows_to_create List of network flow names to create
+    # param [Array<String>] flows_to_modify List of network flow names to delete and re-create with the new definition
+    # @raise [RuntimeError] if any of the requests failed
+    # @return True
+    def implement_app_flows_plan(
+      app_name,
+      new_app_flows,
+      flows_from_server,
+      flows_to_delete,
+      flows_to_create,
+      flows_to_modify
+    )
+      # Get the app revision id
+      app_revision_id = get_app_revision_id_by_name(app_name)
+
+      # This param is used to determine if it is necessary to update the app_revision_id
+      is_draft_revision = false
+
+      # Delete all the flows for deletion and modification
+      (flows_to_delete | flows_to_modify).each do |flow_name_to_delete|
+        delete_flow_by_id(app_revision_id, flows_from_server[flow_name_to_delete]['flowID'])
+        next if is_draft_revision
+        app_revision_id = get_app_revision_id_by_name(app_name)
+        # Refetch the fresh flows from the server, as a new application revision has been created
+        # and it's flow IDs have been change. Only that way we can make sure that the following flow deletions
+        # by name will work as expected
+        flows_from_server = get_application_flows(app_revision_id)
+        is_draft_revision = true
+      end
+      # Create all the new + modified flows
+      (flows_to_create | flows_to_modify).each do |flow_name_to_create|
+        new_flow_data = new_app_flows[flow_name_to_create]
+        create_application_flow(
+          app_revision_id,
+          flow_name_to_create,
+          # Document those key fields somewhere so users know how what is the format of app_flows object
+          # that is provided to this function
+          new_flow_data['sources'],
+          new_flow_data['destinations'],
+          new_flow_data['services'],
+          new_flow_data.fetch('users', []),
+          new_flow_data.fetch('applications', []),
+          new_flow_data.fetch('comment', '')
+        )
+        unless is_draft_revision
+          app_revision_id = get_app_revision_id_by_name(app_name)
+          is_draft_revision = true
+        end
+      end
+
+      apply_application_draft(app_revision_id) if is_draft_revision
+    end
+
+    # Update application flows of an application to match a requested flows configuration.
+    # @param [Integer] app_name The app to create the flows for
+    # @param [Object] new_app_flows Hash of new app flows, pointing from the flow name to the flow definition
+    # @raise [RuntimeError] if the request failed
+    # @return The updated list of flow objects from the server, including their new flowID
+    def define_application_flows(app_name, new_app_flows)
+      flows_from_server = get_application_flows_hash(get_app_revision_id_by_name(app_name))
+      flows_to_delete, flows_to_create, flows_to_modify = plan_application_flows(flows_from_server, new_app_flows)
+      implement_app_flows_plan(
+        app_name,
+        new_app_flows,
+        flows_from_server,
+        flows_to_delete,
+        flows_to_create,
+        flows_to_modify
+      )
+
+      # Stage 2: Run connectivity check for all the unchanged flows. Check with Chef is this non-deterministic approach
+      # is OK with them for the cookbook.
+      #
+      # Return the current list of created flows if successful
+      get_application_flows(get_app_revision_id_by_name(app_name))
+    end
+
+    # Create all the missing network objects which are simple IPv4 ip or subnet
+    # @param [Array<String>] network_object_names List of the network object names
+    # @raise [RuntimeError] if the request failed
+    # @return Newly created objects
+    def create_missing_network_objects(network_object_names)
+      # TODO: Add unitests that objects are being create only once (if the same object is twice in the incoming list)
+      network_object_names = Set.new(network_object_names)
+      ipv4_or_subnet_objects = network_object_names.map do |object_name|
+        begin
+          IPAddress.parse object_name
+          search_result = search_network_object(object_name, NetworkObjectSearchType::EXACT)
+          # If no object was found in search, we'll count this object for creation
+          search_result.empty? ? object_name : nil
+        rescue ArgumentError
+          # The parsed object name was not IP Address or IP Subnet, ignore it
+          nil
+        end
+      end.compact
+
+      # Create all the objects. If the error from the server tells us that the object already exists, ignore the error
+      ipv4_or_subnet_objects.map do |ipv4_or_subnet|
+        create_network_object(NetworkObjectType::HOST, ipv4_or_subnet, ipv4_or_subnet)
+      end.compact
+    end
+
+    # Create all the missing network services which are of simple protocol/port pattern
+    # @param [Array<String>] service_names List of the network service names
+    # @raise [RuntimeError] if the request failed
+    # @return Newly created objects
+    def create_missing_services(service_names)
+      parsed_services = service_names.map do |service_name|
+        protocol, port = service_name.scan(%r{(TCP|UDP)/(\d+)}i).last
+        [service_name, [protocol, port]] if !protocol.nil? && !port.nil?
+      end.compact
+      # Create all the objects. If the error from the server tells us that the object already exists, ignore the error
+      parsed_services.map do |parsed_service|
+        service_name, service_content = parsed_service
+        begin
+          create_network_service(service_name, [service_content])
+        rescue StandardError => e
+          # If the error is different from "service already exists", the exception will be re-raised
+          raise e if e.to_s.index('Service name already exists').nil?
+        end
+      end.compact
+    end
+  end
+end

data/lib/algosec-sdk/helpers/flow_comparisons.rb

@@ -0,0 +1,48 @@
+require 'set'
+
+module ALGOSEC_SDK
+  ANY_OBJECT = { 'id' => 0, 'name' => 'Any' }.freeze
+  ANY_NETWORK_APPLICATION = { 'revisionID' => 0, 'name' => 'Any' }.freeze
+  # A module to determine if a local flow definition is equal to a flow defined on the server
+  module AreFlowsEqual
+    def self.are_sources_equal_in_flow(source_object_names, server_flow_sources)
+      flow_source_object_names = Set.new(server_flow_sources.map { |source| source['name'] })
+      Set.new(source_object_names) == Set.new(flow_source_object_names)
+    end
+
+    def self.are_dest_equal_in_flow(dest_object_names, server_flow_dests)
+      flow_dest_object_names = Set.new(server_flow_dests.map { |dest| dest['name'] })
+      Set.new(dest_object_names) == Set.new(flow_dest_object_names)
+    end
+
+    def self.are_services_equal_in_flow(service_names, server_flow_services)
+      network_flow_service_names = Set.new(server_flow_services.map { |service| service['name'] })
+      Set.new(service_names) == Set.new(network_flow_service_names)
+    end
+
+    def self.are_apps_equal_in_flow(application_names, server_flow_apps)
+      return application_names == [] if server_flow_apps == [ANY_NETWORK_APPLICATION]
+      flow_application_names = server_flow_apps.map do |network_application|
+        network_application['name']
+      end
+
+      Set.new(application_names) == Set.new(flow_application_names)
+    end
+
+    def self.are_users_equal_in_flow(network_users, server_flow_users)
+      return network_users == [] if server_flow_users == [ANY_OBJECT]
+      flow_users = server_flow_users.map { |user| user['name'] }
+      Set.new(network_users) == Set.new(flow_users)
+    end
+
+    def self.flows_equal?(new_flow, flow_from_server)
+      [
+        are_sources_equal_in_flow(new_flow['sources'], flow_from_server['sources']),
+        are_dest_equal_in_flow(new_flow['destinations'], flow_from_server['destinations']),
+        are_services_equal_in_flow(new_flow['services'], flow_from_server['services']),
+        are_apps_equal_in_flow(new_flow.fetch('applications', []), flow_from_server.fetch('networkApplications', [])),
+        are_users_equal_in_flow(new_flow.fetch('users', []), flow_from_server.fetch('networkUsers', []))
+      ].all?
+    end
+  end
+end

data/lib/algosec-sdk/rest.rb

@@ -0,0 +1,160 @@
+require 'uri'
+require 'net/http'
+require 'openssl'
+require 'json'
+require 'jsonclient'
+
+module ALGOSEC_SDK
+  # Adds the ability for httpclient to set proper content-type for Hash AND Array body
+  class AdvancedJSONClient < JSONClient
+    def argument_to_hash_for_json(args)
+      hash = argument_to_hash(args, :body, :header, :follow_redirect)
+      if hash[:body].is_a?(Hash) || hash[:body].is_a?(Array)
+        hash[:header] = json_header(hash[:header])
+        hash[:body] = JSON.generate(hash[:body])
+      end
+      hash
+    end
+  end
+end
+
+module ALGOSEC_SDK
+  # Contains all the methods for making API REST calls
+  module Rest
+    def init_http_client
+      @http_client = ALGOSEC_SDK::AdvancedJSONClient.new(force_basic_auth: true)
+      @http_client.proxy = nil if @disable_proxy
+      @http_client.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE unless @ssl_enabled
+      @http_client.set_auth(@host, @user, @password)
+    end
+
+    # Make a restful API request to the AlgoSec
+    # @param [Symbol] type the rest method/type Options are :get, :post, :put, :patch, and :delete
+    # @param [String] path the path for the request. Usually starts with "/rest/"
+    # @param [Hash] options the options for the request
+    # @option options [String] :body Hash to be converted into json and set as the request body
+    # @option options [String] :Content-Type ('application/json') Set to nil or :none to have this option removed
+    # @raise [InvalidRequest] if the request is invalid
+    # @raise [SocketError] if a connection could not be made
+    # @raise [OpenSSL::SSL::SSLError] if SSL validation of the AlgoSec's certificate failed
+    # @return [NetHTTPResponse] The response object
+    def rest_api(type, path, options = {})
+      raise InvalidRequest, 'Must specify path' unless path
+      raise InvalidRequest, 'Must specify type' unless type
+      @logger.debug "Making :#{type} rest call to #{@host}#{path}"
+
+      uri = "#{@host}#{path}"
+      response = send_request(type, uri, options)
+      @logger.debug "  Response: Code=#{response.status}. Headers=#{response.headers}\n  Body=#{response.body}"
+      response
+    rescue OpenSSL::SSL::SSLError => e
+      msg = 'SSL verification failed for the request. Please either:'
+      msg += "\n  1. Install the necessary certificate(s) into your cert store"
+      msg += ". Using cert store: #{ENV['SSL_CERT_FILE']}" if ENV['SSL_CERT_FILE']
+      msg += "\n  2. Set the :ssl_enabled option to false for your AlgoSec client (not recommended)"
+      @logger.error msg
+      raise e
+    rescue SocketError => e
+      msg = "Failed to connect to AlgoSec host #{@host}!\n"
+      @logger.error msg
+      e.message.prepend(msg)
+      raise e
+    end
+
+    # Make a restful GET request
+    # Parameters & return value align with those of the {ALGOSEC_SDK::Rest::rest_api} method above
+    def rest_get(path, options = {})
+      rest_api(:get, path, options)
+    end
+
+    # Make a restful POST request
+    # Parameters & return value align with those of the {ALGOSEC_SDK::Rest::rest_api} method above
+    def rest_post(path, options = {})
+      rest_api(:post, path, options)
+    end
+
+    # Make a restful PUT request
+    # Parameters & return value align with those of the {ALGOSEC_SDK::Rest::rest_api} method above
+    def rest_put(path, options = {})
+      rest_api(:put, path, options)
+    end
+
+    # Make a restful PATCH request
+    # Parameters & return value align with those of the {ALGOSEC_SDK::Rest::rest_api} method above
+    def rest_patch(path, options = {})
+      rest_api(:patch, path, options)
+    end
+
+    # Make a restful DELETE request
+    # Parameters & return value align with those of the {ALGOSEC_SDK::Rest::rest_api} method above
+    def rest_delete(path, options = {})
+      rest_api(:delete, path, options)
+    end
+
+    RESPONSE_CODE_OK           = 200
+    RESPONSE_CODE_CREATED      = 201
+    RESPONSE_CODE_ACCEPTED     = 202
+    RESPONSE_CODE_NO_CONTENT   = 204
+    RESPONSE_CODE_BAD_REQUEST  = 400
+    RESPONSE_CODE_UNAUTHORIZED = 401
+    RESPONSE_CODE_NOT_FOUND    = 404
+
+    # Handle the response for rest call.
+    #   If an asynchronous task was started, this waits for it to complete.
+    # @param [HTTPResponse] response
+    # @raise [ALGOSEC_SDK::BadRequest] if the request failed with a 400 status
+    # @raise [ALGOSEC_SDK::Unauthorized] if the request failed with a 401 status
+    # @raise [ALGOSEC_SDK::NotFound] if the request failed with a 404 status
+    # @raise [ALGOSEC_SDK::RequestError] if the request failed with any other status
+    # @return [Hash] The parsed JSON body
+    def response_handler(response)
+      case response.status
+      when RESPONSE_CODE_OK # Synchronous read/query
+        response.body
+      when RESPONSE_CODE_CREATED # Synchronous add
+        response.body
+        # when RESPONSE_CODE_ACCEPTED # Asynchronous add, update or delete
+        # return response.body #
+        # @logger.debug "Waiting for task: #{response.headers['location']}"
+        # task = wait_for(response.headers['location'])
+        # return true unless task['associatedResource'] && task['associatedResource']['resourceUri']
+        # resource_data = rest_get(task['associatedResource']['resourceUri'])
+        # return JSON.parse(resource_data.body)
+      when RESPONSE_CODE_NO_CONTENT # Synchronous delete
+        {}
+      when RESPONSE_CODE_BAD_REQUEST
+        raise BadRequest, "400 BAD REQUEST #{response.body}"
+      when RESPONSE_CODE_UNAUTHORIZED
+        raise Unauthorized, "401 UNAUTHORIZED #{response.body}"
+      when RESPONSE_CODE_NOT_FOUND
+        raise NotFound, "404 NOT FOUND #{response.body}"
+      else
+        raise RequestError, "#{response.status} #{response.body}"
+      end
+    end
+
+    private
+
+    # @param type [Symbol] The type of request object to build (get, post, put, patch, or delete)
+    # @param uri [String] full URI string
+    # @param options [Hash] Options for building the request. All options except "body" are set as headers.
+    # @raise [ALGOSEC_SDK::InvalidRequest] if the request type is not recognized
+    def send_request(type, uri, options)
+      case type.downcase
+      when 'get', :get
+        response = @http_client.get(uri, options)
+      when 'post', :post
+        response = @http_client.post(uri, options)
+      when 'put', :put
+        response = @http_client.put(uri, options)
+      when 'patch', :patch
+        response = @http_client.patch(uri, options)
+      when 'delete', :delete
+        response = @http_client.delete(uri, options)
+      else
+        raise InvalidRequest, "Invalid rest method: #{type}. Valid methods are: get, post, put, patch, delete"
+      end
+      response
+    end
+  end
+end