ruby-paloalto-client 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bdc9c84ff0f1d1f1e1abde649da826eba4e47288
+  data.tar.gz: ae3c9a3e01f7d336561c33e2754423192b6b159b
+SHA512:
+  metadata.gz: bd186bd765e99f2398e47dded35b8d79d552691d4d002922e95c17722ba7ae6fbb7eb8a76d44b2ff313e31f70616c473cb5cae534d81d7e4e5756e6dd47fc250
+  data.tar.gz: 7274bf968c19fba909e672ffe1ea65a2ca38b474dfe33cfb9cbfb44feff0340d9318714c28e65d139a6af3e33bb55de8fddeeb9694cdb8cb013279b05e62a041

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.swp
+*.swo

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.ruby-gemset

@@ -0,0 +1 @@
+paloalto-client

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ruby-paloalto-client.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Justin Karimi
+
+MIT 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, sublicense, and/or sell copies of the Software, 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
+NONINFRINGEMENT. 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.

data/README.md

@@ -0,0 +1,152 @@
+# Ruby::PaloAlto::Client
+
+Ruby client to interact with the PaloAlto Firewall and Panamera service
+for Version 6.X of the API.
+
+## Background
+
+The following is a notional JSON-based hierarchical representation of the association within the PaloAlto configuration:
+
+```bash
+Device has_many: VirtualSystem
+
+VirtualSystem has_many:
+  - Address
+  - AddressGroup
+  - Ruleset
+
+AddressGroup has_many: Addresses
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby-paloalto-client'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ruby-paloalto-client
+
+## Usage
+
+### Initialization
+
+To interface with a PaloAlto API endpoint, start by requiring the PaloAlto library:
+
+```bash
+require 'palo-alto/client'
+
+=> true
+```
+
+Then, establish a connection to the PaloAlto API with which you wish to interact. For example, this
+PaloAlto device is running version 6 of the API and is located at 'localhost' running on port 443 (secure), and we are connecting with the following:
+
+- Host:        localhost
+- Port:        443
+- Username:    admin
+- Password     adminpass
+- SSL:         true
+- API Version: 6
+
+```bash
+pa_client = PaloAlto::Client.new host:        "localhost",
+                                 port:        "443",
+                                 username:    "admin",
+                                 password:    "adminpass",
+                                 ssl:         true,
+                                 api_version: "6"
+
+=> #<PaloAlto::V6::Api:0x000000026d7340 @host="localhost", @port="443", @ssl=true, @username="admin", @password="adminpass", @auth_key="LUFRPT0va1dzTWZCWjhReWkx354gsUJ0T1VyeFBVRlE9cVpGWUEzNmFmeWtTQU1GcmNHVE0zeHdWRHJKUlhJYXBUMWlXdFBLVnhqND0=">
+```
+
+Once you have your client "pa_client", you can continue to retrieve and manipulate data within the PaloAlto target device.
+Note that queries against the PaloAlto target are performed once for each of the association methods:
+
+- .devices
+- .virtual_systems
+- .address_groups
+- .addresses
+
+### Devices
+
+To obtain a list of all devices, perform the following:
+
+```bash
+# query device directly
+pa_client.devices
+
+=> [#<PaloAlto::Models::Device:0x000000021b1550 @name="localhost.localdomain", @ip="127.0.0.1", @virtual_systems=[#<PaloAlto::Models::VirtualSystem:0x000000021b0b00 @name="vsys1", @addresses=[], @address_groups=[], @rulebases=[]>]>]
+
+# query device once, parse data in-memory
+devices = pa_client.devices
+
+device = devices[0]
+device.virtual_systems
+
+vsys = device.virtual_systems[0]
+vsys.addresses
+vsys.address_groups
+vsys.rulesets
+```
+
+### Virtual Systems
+
+To obtain a list of all virtual systems, perform the following:
+
+```bash
+# query device directly
+pa_client.virtual_systems
+
+=> [#<PaloAlto::Models::VirtualSystem:0x000000027319f8 @name="vsys1", @addresses=[#<PaloAlto::Models::Address:0x0000000272bc60 @name="pool-range", @ip="192.168.80.0/24">, #<PaloAlto::Models::Address:0x0000000272b260 @name="some-ip", @ip="2.2.2.2">], @address_groups=[#<PaloAlto::Models::AddressGroup:0x0000000272a3b0 @name="test", @description="Testing using API", @addresses=[#<PaloAlto::Models::Address:0x00000002729c08 @name="some-ip", @ip="2.2.2.2">]>], @rulebases=[#<PaloAlto::Models::Rulebase:0x00000002729208 @name="DNS">, #<PaloAlto::Models::Rulebase:0x00000002728a88 @name="Allow same network">, #<PaloAlto::Models::Rulebase:0x00000002722138 @name="Deny All">]>]
+
+# query device once, parse data in-memory:
+vsystems = pa_client.virtual_systems
+
+vsys = vsystems[0]
+vsys.addresses
+vsys.address_groups
+
+address_group = vsys.address_groups[0]
+address_group.addresses
+vsys.rulesets
+```
+
+### Addresses
+
+To obtain a list of all addresses, perform the following:
+
+```bash
+# query device directly
+pa_client.addresses
+
+=> [#<PaloAlto::Models::Address:0x0000000268f158 @name="pool-range", @ip="192.168.80.0/24">, #<PaloAlto::Models::Address:0x0000000268e528 @name="some-ip", @ip="2.2.2.2">]
+
+# query device once, parse data in-memory
+addresses = pa_client.addresses
+
+address = addresses[0]
+```
+
+### Address Groups
+
+To obtain a list of all address groups, perform the following:
+
+```bash
+# query device directly
+pa_client.address_groups
+
+=> [#<PaloAlto::Models::AddressGroup:0x00000002661870 @name="test", @description="Testing using API", @addresses=[#<PaloAlto::Models::Address:0x00000002660f88 @name="", @ip="2.2.2.2">]>]
+
+# query device once, parse data in-memory
+address_groups = pa_client.address_groups
+
+address_group = address_groups[0]
+```

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/palo-alto/client/version.rb

@@ -0,0 +1,5 @@
+module PaloAlto
+  module Client
+    VERSION = "0.0.1"
+  end
+end

data/lib/palo-alto/client.rb

@@ -0,0 +1,50 @@
+require "palo-alto/client/version"
+require "palo-alto/common/base-api"
+require "palo-alto/helpers/rest"
+
+module PaloAlto
+  module Client
+    class << self
+      attr_accessor :host, :port, :ssl, :username, :password, :api_version
+
+      # Create and returns a new PaloAlto::VX::Api instance with the given parameters
+      #
+      # == Attributes
+      #
+      # * +host+        - Host where the PaloAlto device is located
+      # * +port+        - Port on which the PaloAlto API service is listening
+      # * +ssl+         - (Boolean) Whether the API interaction is over SSL
+      # * +username+    - Username used to authenticate against the API
+      # * +password+    - Password used to authenticate against the API
+      # * +api_version+ - Major version of the API being interacted with
+      #
+      # == Example
+      #
+      #  PaloAlto::Client.new host:        'localhost.localdomain',
+      #                       port:        '443',
+      #                       ssl:         true,
+      #                       username:    'test_user',
+      #                       password:    'test_pass',
+      #                       api_version: '6'
+      def new(host:, port:, ssl: false, username:, password:, api_version:)
+        api = nil
+
+        # check that the API version is implemented
+        api_version_file = File.join(File.dirname(__FILE__), "v#{api_version}", "api.rb")
+        if File.exist?(api_version_file)
+          require api_version_file.sub('.rb', '')
+
+          api = Object.const_get("PaloAlto::V#{api_version}::Api").new(host: host,
+                                                                       port: port,
+                                                                       ssl:  ssl,
+                                                                       username: username,
+                                                                       password: password)
+        else
+          raise "API version '#{api_version}' is not implemented"
+        end
+
+        api
+      end
+    end
+  end
+end

data/lib/palo-alto/common/base-api.rb

@@ -0,0 +1,84 @@
+require "nokogiri"
+
+module PaloAlto
+  module Common
+    class BaseApi
+      attr_accessor :host, :port, :ssl, :username, :password, :auth_key
+
+      # Create and returns a new PaloAlto::V6::Api instance with the given parameters
+      #
+      # == Attributes
+      #
+      # * +host+        - Host where the PaloAlto device is located
+      # * +port+        - Port on which the PaloAlto API service is listening
+      # * +ssl+         - (Boolean) Whether the API interaction is over SSL
+      # * +username+    - Username used to authenticate against the API
+      # * +password+    - Password used to authenticate against the API
+      #
+      # == Example
+      #
+      #  PaloAlto::V6::Api.new host:        'localhost.localdomain',
+      #                        port:        '443',
+      #                        ssl:         true,
+      #                        username:    'test_user',
+      #                        password:    'test_pass'
+      def initialize(host:, port:, ssl: false, username:, password:)
+        self.host     = host
+        self.port     = port
+        self.ssl      = ssl
+        self.username = username
+        self.password = password
+
+        # attempt to obtain the auth_key
+        raise "Exception attempting to obtain the auth_key" if (self.auth_key = get_auth_key).nil?
+
+        self
+      end
+
+      # Construct and return the API endpoint
+      def endpoint
+        "http#{('s' if self.ssl)}://#{self.host}:#{self.port}/api/"
+      end
+
+      # Get all the Address objects from the device
+      #def addresses
+      #end
+
+      # Get all the AddressGroup objects from the device
+      def address_groups
+      end
+
+      # Get all the Policies from the device
+      def policies
+      end
+
+      private
+
+      # Perform a query to the API endpoint for an auth_key based on the credentials provided
+      def get_auth_key
+        auth_key = nil
+
+        # establish the required options for the key request
+        options            = {}
+        options[:url]      = self.endpoint
+        options[:method]   = :post
+        options[:payload]  = { "type"     => "keygen",
+                               "user"     => self.username,
+                               "password" => self.password }
+
+        # get and parse the response for the key
+        http_response = PaloAlto::Helpers::Rest.make_request(options)
+        unless http_response.nil?
+          xml_data = Nokogiri::XML(http_response)
+          if xml_data.xpath('//response/@status').to_s == "success"
+            return xml_data.xpath('//response/result/key')[0].content
+          else
+            return nil
+          end
+        end
+
+        auth_key
+      end
+    end
+  end
+end

data/lib/palo-alto/helpers/rest.rb

@@ -0,0 +1,46 @@
+require "rest-client"
+
+module PaloAlto
+  module Helpers
+    class Rest
+      # Perform an HTTP request with the respective options
+      #
+      # == Attributes
+      #
+      # * +opts+ - Hash of options to include in the request
+      #
+      # == Input Hash
+      #
+      # The input hash should contain at a minimum, the following:
+      #
+      # * +url+     - The URL to send the request to
+      # * +method+  - The HTTP method to execute (:get, :post, etc)
+      # * +payload+ - Hash of key/value pairs (parameters) to send with the request
+      #
+      # == Returns
+      #
+      # Response of the HTML request
+      def self.make_request(opts)
+        options                           = {}
+        options[:verify_ssl]              = OpenSSL::SSL::VERIFY_NONE
+        options[:headers]                 = {}
+        options[:headers]["User-Agent"]   = "ruby-keystone-client"
+        options[:headers]["Accept"]       = "application/xml"
+        options[:headers]["Content-Type"] = "application/xml"
+
+        # merge in settings from method caller
+        options = options.merge(opts)
+
+        # provide a block to ensure the response is parseable rather than
+        # having RestClient throw an exception
+        RestClient::Request.execute(options) do |response, request, result|
+          if response and response.code == 200
+            return response.body
+          else
+            return nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/palo-alto/models/address-group.rb

@@ -0,0 +1,27 @@
+module PaloAlto
+  module Models
+    class AddressGroup
+      attr_accessor :name, :description, :addresses
+
+      # Create and returns a new PaloAlto::Models::AddressGroup instance with the given parameters
+      #
+      # == Attributes
+      #
+      # * +name+        - Name of the address group
+      # * +description+ - Description for the address group
+      # * +addresses+   - Array containing Model::Address instances
+      #
+      # == Example
+      #
+      #  PaloAlto::Models::AddressGroup.new name:        'address-group-1',
+      #                                     description: 'address-group-1-description'
+      def initialize(name:, description:, addresses: [])
+        self.name        = name
+        self.description = description
+        self.addresses   = addresses
+
+        self
+      end
+    end
+  end
+end

data/lib/palo-alto/models/address.rb

@@ -0,0 +1,25 @@
+module PaloAlto
+  module Models
+    class Address
+      attr_accessor :name, :ip
+
+      # Create and returns a new PaloAlto::Models::Address instance with the given parameters
+      #
+      # == Attributes
+      #
+      # * +name+ - Name of the address
+      # * +ip+   - IP of the address
+      #
+      # == Example
+      #
+      #  PaloAlto::Models::Address.new name: 'address-1',
+      #                                ip:   '2.2.2.2'
+      def initialize(name:, ip:)
+        self.name = name
+        self.ip   = ip
+
+        self
+      end
+    end
+  end
+end

data/lib/palo-alto/models/device.rb

@@ -0,0 +1,27 @@
+module PaloAlto
+  module Models
+    class Device
+      attr_accessor :name, :ip, :virtual_systems
+
+      # Create and returns a new PaloAlto::Models::Device instance with the given parameters
+      #
+      # == Attributes
+      #
+      # * +name+            - Name of the device
+      # * +ip+              - Device IP address
+      # * +virtual_systems+ - Array containing Model::VirtualSystem instances
+      #
+      # == Example
+      #
+      #  PaloAlto::Models::Device.new name: 'device-1',
+      #                               ip:   '1.2.3.4'
+      def initialize(name:, ip:, virtual_systems: [])
+        self.name            = name
+        self.ip              = ip
+        self.virtual_systems = virtual_systems
+
+        self
+      end
+    end
+  end
+end

data/lib/palo-alto/models/rulebase.rb

@@ -0,0 +1,24 @@
+module PaloAlto
+  module Models
+    # Currently, Rulebase is a stand-in for "Security"
+    # TODO: Add different Rulebase types (Security, NAT, etc)
+    class Rulebase
+      attr_accessor :name
+
+      # Create and returns a new PaloAlto::Models::Rulebase instance with the given parameters
+      #
+      # == Attributes
+      #
+      # * +name+ - Name of the rulebase
+      #
+      # == Example
+      #
+      #  PaloAlto::Models::Rulebase.new name: 'rulebase-1'
+      def initialize(name:)
+        self.name = name
+
+        self
+      end
+    end
+  end
+end

data/lib/palo-alto/models/virtual-system.rb

@@ -0,0 +1,28 @@
+module PaloAlto
+  module Models
+    class VirtualSystem
+      attr_accessor :name, :addresses, :address_groups, :rulebases
+
+      # Create and returns a new PaloAlto::Models::VirtualSystem instance with the given parameters
+      #
+      # == Attributes
+      #
+      # * +name+           - Name of the virtual system
+      # * +addresses+      - Array of Model::Address instances
+      # * +address_groups+ - Array of Model::AddressGroup instances
+      # * +rulebases+      - Array of Model::Rulebase instances
+      #
+      # == Example
+      #
+      #  PaloAlto::Models::VirtualSystem.new name: 'vsys-1'
+      def initialize(name:, addresses: [], address_groups: [], rulebases: [])
+        self.name           = name
+        self.addresses      = addresses
+        self.address_groups = address_groups
+        self.rulebases      = rulebases
+
+        self
+      end
+    end
+  end
+end

data/lib/palo-alto/v6/address-api.rb

@@ -0,0 +1,46 @@
+require "palo-alto/models/address"
+
+module PaloAlto
+  module V6
+    module AddressApi
+      # Parse out the addresses from a response to query for addresses
+      #
+      # == Returns
+      #
+      #  * +Array+ - Array of Models::Address instances
+      #
+      # == Raises
+      #
+      #  * +Exception+ - Raises an exception if the request is unsuccessful
+      def addresses
+        address_list = []
+
+        # configure options for the request
+        options = {}
+        options[:url]     = self.endpoint
+        options[:method]  = :post
+        options[:payload] = { type:   "config",
+                              action: "show",
+                              key:    self.auth_key,
+                              xpath:  "/config/devices/entry/vsys/entry" }
+
+        html_result = Helpers::Rest.make_request(options)
+
+        raise "Error obtaining address XML" if html_result.nil?
+
+        # parse the XML data
+        data = Nokogiri::XML(html_result)
+
+        if data.xpath('//response/@status').to_s == "success"
+          data.xpath('//response/result/entry/address/entry').each do |address|
+            address_list << PaloAlto::Models::Address.new(name: address.xpath('@name').to_s, ip: address.xpath('ip-netmask').first.content)
+          end
+        else
+          raise "Error in response XML: #{data.inspect}"
+        end
+
+        address_list
+      end
+    end
+  end
+end

data/lib/palo-alto/v6/address-group-api.rb

@@ -0,0 +1,57 @@
+require "palo-alto/models/address-group"
+require "palo-alto/models/address"
+
+module PaloAlto
+  module V6
+    module AddressGroupApi
+      # Parse out the address groups from a response to query for address groups
+      #
+      # == Returns
+      #
+      #  * +Array+ - Array of Models::AddressGroup instances
+      #
+      # == Raises
+      #
+      #  * +Exception+ - Raises an exception if the request is unsuccessful
+      def address_groups
+        address_group_list = []
+
+        # configure options for the request
+        options = {}
+        options[:url]     = self.endpoint
+        options[:method]  = :post
+        options[:payload] = { type:   "config",
+                              action: "show",
+                              key:    self.auth_key,
+                              xpath:  "/config/devices/entry/vsys/entry" }
+
+        html_result = Helpers::Rest.make_request(options)
+
+        raise "Error obtaining address group XML" if html_result.nil?
+
+        # parse the XML data
+        data = Nokogiri::XML(html_result)
+
+        if data.xpath('//response/@status').to_s == "success"
+          data.xpath('//response/result/entry/address-group/entry').each do |address_group_entry|
+            address_group = PaloAlto::Models::AddressGroup.new(name:        address_group_entry.xpath('@name').to_s,
+                                                               description: address_group_entry.xpath('description').first.content)
+
+            # get all address members for the address group
+            address_group_entry.xpath('*').each do |address_entry|
+              if (specific_address = address_entry.xpath('member')).length > 0
+                address_group.addresses << PaloAlto::Models::Address.new(name: specific_address[0].content, ip: "")
+              end
+            end
+
+            address_group_list << address_group
+          end
+        else
+          raise "Error in response XML: #{data.inspect}"
+        end
+
+        address_group_list
+      end
+    end
+  end
+end

data/lib/palo-alto/v6/api.rb

@@ -0,0 +1,16 @@
+require "palo-alto/v6/device-api"
+require "palo-alto/v6/virtual-system-api"
+require "palo-alto/v6/address-api"
+require "palo-alto/v6/address-group-api"
+
+module PaloAlto
+  module V6
+    class Api < Common::BaseApi
+      # include required APIs for functionality
+      include PaloAlto::V6::DeviceApi
+      include PaloAlto::V6::VirtualSystemApi
+      include PaloAlto::V6::AddressApi
+      include PaloAlto::V6::AddressGroupApi
+    end
+  end
+end