ruby-paloalto-client 0.0.1

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

@@ -0,0 +1,55 @@
+require "palo-alto/models/device"
+require "palo-alto/models/virtual-system"
+
+module PaloAlto
+  module V6
+    module DeviceApi
+      # Parse out the devices from a response to query for devices
+      #
+      # == Returns
+      #
+      #  * +Array+ - Array of Models::Device instances
+      #
+      # == Raises
+      #
+      #  * +Exception+ - Raises an exception if the request is unsuccessful
+      def devices
+        devices_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" }
+
+        html_result = Helpers::Rest.make_request(options)
+
+        raise "Error obtaining device 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/devices/entry').each do |device_entry|
+            device = PaloAlto::Models::Device.new(name: device_entry.xpath('@name').to_s,
+                                                  ip:   device_entry.xpath('deviceconfig/system/ip-address').first.content)
+
+            # get all virtual_system members for the device
+            device_entry.xpath('vsys/entry').each do |vsys_entry|
+              device.virtual_systems << PaloAlto::Models::VirtualSystem.new(name: vsys_entry.xpath('@name').to_s)
+            end
+
+            devices_list << device
+          end
+        else
+          raise "Error in response XML: #{data.inspect}"
+        end
+
+        devices_list
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+require "palo-alto/models/virtual-system"
+require "palo-alto/models/address"
+require "palo-alto/models/address-group"
+require "palo-alto/models/rulebase"
+
+module PaloAlto
+  module V6
+    module VirtualSystemApi
+      # Parse out the virtual systems from a response to query for virtual systems
+      #
+      # == Returns
+      #
+      #  * +Array+ - Array of Models::VirtualSystem instances
+      #
+      # == Raises
+      #
+      #  * +Exception+ - Raises an exception if the request is unsuccessful
+      def virtual_systems
+        virtual_systems_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" }
+
+        html_result = Helpers::Rest.make_request(options)
+
+        raise "Error obtaining virtual system 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/vsys/entry').each do |vsys_entry|
+            vsys = PaloAlto::Models::VirtualSystem.new(name: vsys_entry.xpath('@name').to_s)
+
+            # get all address members for the virtual system
+            vsys_entry.xpath('address/entry').each do |address_entry|
+              vsys.addresses << PaloAlto::Models::Address.new(name: address_entry.xpath('@name').to_s,
+                                                              ip:   address_entry.xpath('ip-netmask').first.content)
+            end
+
+            # get all address group members for the virtual system
+            vsys_entry.xpath('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)
+
+              # associate addresses with the address group
+              address_group_entry.xpath('*/member').each do |address_entry|
+                address_group.addresses << PaloAlto::Models::Address.new(name: address_entry.content, ip: "")
+              end
+
+              vsys.address_groups << address_group
+            end
+
+            # get all rulebase members for the virtual system
+            # TODO: Expand beyond just the security rulebase
+            vsys_entry.xpath('rulebase/security/rules/entry').each do |rulebase_entry|
+              vsys.rulebases << PaloAlto::Models::Rulebase.new(name: rulebase_entry.xpath('@name').to_s)
+            end
+
+            virtual_systems_list << vsys
+          end
+        else
+          raise "Error in response XML: #{data.inspect}"
+        end
+
+        virtual_systems_list
+      end
+    end
+  end
+end

data/ruby-paloalto-client.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'palo-alto/client/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ruby-paloalto-client"
+  spec.version       = PaloAlto::Client::VERSION
+  spec.authors       = ["Justin Karimi"]
+  spec.email         = ["jekhokie@gmail.com"]
+  spec.summary       = %q{Ruby PaloAlto Client (API V6.X)}
+  spec.description   = %q{A Ruby-based client library to interact with the PaloAlto APIs.}
+  spec.homepage      = ""
+  spec.license       = "Apache 2.0"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "nokogiri"
+  spec.add_runtime_dependency "rest-client"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "fakeweb"
+end

data/spec/fixtures/address_groups.xml

@@ -0,0 +1,14 @@
+<response status="success" code="19">
+  <result total-count="1" count="1">
+    <entry name="test" src="tpl" admin="admin" time="2015/02/02 13:45:00">
+      <address-group admin="someone" time="2015/03/04 13:45:08">
+        <entry name="test" admin="someone" time="2015/03/04 13:45:08">
+          <static admin="someone" time="2015/03/04 13:45:08">
+            <member admin="someone" time="2015/03/04 13:45:08">10.10.111.225-1</member>
+          </static>
+          <description>Testing using API</description>
+        </entry>
+      </address-group>
+    </entry>
+  </result>
+</response>

data/spec/fixtures/addresses.xml

@@ -0,0 +1,14 @@
+<response status="success">
+  <result>
+    <entry name="test" src="tpl" admin="admin" time="2015/02/02 13:45:00">
+      <address>
+        <entry name="test-1">
+          <ip-netmask>192.168.80.0/24</ip-netmask>
+        </entry>
+        <entry name="test-2">
+          <ip-netmask>10.10.111.225</ip-netmask>
+        </entry>
+      </address>
+    </entry>
+  </result>
+</response>

data/spec/fixtures/blank_address_groups.xml

@@ -0,0 +1,6 @@
+<response status="success" code="19">
+  <result total-count="1" count="1">
+    <entry name="test" src="tpl" admin="admin" time="2015/02/02 13:45:00">
+    </entry>
+  </result>
+</response>

data/spec/fixtures/blank_addresses.xml

@@ -0,0 +1,5 @@
+<response status="success">
+  <result>
+    <entry name="test" src="tpl" admin="admin" time="2015/02/02 13:45:00">
+  </result>
+</response>

data/spec/fixtures/blank_devices.xml

@@ -0,0 +1,4 @@
+<response status="success">
+  <result total-count="0" count="0">
+  </result>
+</response>

data/spec/fixtures/blank_virtual_systems.xml

@@ -0,0 +1,4 @@
+<response status="success" code="19">
+  <result total-count="0" count="0">
+  </result>
+</response>

data/spec/fixtures/devices.xml

@@ -0,0 +1,17 @@
+<response status="success">
+  <result total-count="1" count="1">
+    <devices src="tpl" admin="admin" time="2015/03/05 10:22:56">
+      <entry name="localhost.localdomain" src="tpl" admin="admin" time="2015/03/05 10:22:56">
+        <vsys src="tpl" admin="jkarimi" time="2015/03/05 10:22:56">
+          <entry name="vsys1" src="tpl" admin="jkarimi" time="2015/03/05 10:22:56">
+          </entry>
+        </vsys>
+        <deviceconfig>
+          <system>
+            <ip-address>2.2.2.2</ip-address>
+          </system>
+        </deviceconfig>
+      </entry>
+    </devices>
+  </result>
+</response>

data/spec/fixtures/failure.xml

@@ -0,0 +1,2 @@
+<response status="fail">
+</response>

data/spec/fixtures/no_address_group_virtual_systems.xml

@@ -0,0 +1,24 @@
+<response status="success" code="19">
+  <result total-count="1" count="1">
+    <vsys src="tpl" admin="admin" time="2015/03/05 10:22:56">
+      <entry name="vsys1" src="tpl" admin="admin" time="2015/03/05 10:22:56">
+        <rulebase admin="admin" time="2015/03/04 13:46:08">
+          <security admin="admin" time="2015/03/04 13:46:08">
+            <rules admin="admin" time="2015/03/04 13:46:08">
+              <entry name="DNS" admin="admin" time="2015/03/04 13:46:07">
+              </entry>
+            </rules>
+          </security>
+        </rulebase>
+        <address admin="admin" time="2015/03/05 10:22:56">
+          <entry name="address-1" admin="admin" time="2015/03/04 13:39:03">
+            <ip-netmask admin="admin" time="2015/03/04 13:39:02">1.1.1.1</ip-netmask>
+          </entry>
+          <entry name="address-2" admin="admin" time="2015/03/05 10:22:56">
+            <ip-netmask admin="admin" time="2015/03/05 10:22:56">2.2.2.2</ip-netmask>
+          </entry>
+        </address>
+      </entry>
+    </vsys>
+  </result>
+</response>

data/spec/fixtures/no_address_virtual_systems.xml

@@ -0,0 +1,24 @@
+<response status="success" code="19">
+  <result total-count="1" count="1">
+    <vsys src="tpl" admin="admin" time="2015/03/05 10:22:56">
+      <entry name="vsys1" src="tpl" admin="admin" time="2015/03/05 10:22:56">
+        <rulebase admin="admin" time="2015/03/04 13:46:08">
+          <security admin="admin" time="2015/03/04 13:46:08">
+            <rules admin="admin" time="2015/03/04 13:46:08">
+              <entry name="DNS" admin="admin" time="2015/03/04 13:46:07">
+              </entry>
+            </rules>
+          </security>
+        </rulebase>
+        <address-group admin="admin" time="2015/03/04 13:45:08">
+          <entry name="test" admin="admin" time="2015/03/04 13:45:08">
+            <static admin="admin" time="2015/03/04 13:45:08">
+              <member admin="admin" time="2015/03/04 13:45:08">address-group-1</member>
+            </static>
+            <description>Testing using API</description>
+          </entry>
+        </address-group>
+      </entry>
+    </vsys>
+  </result>
+</response>

data/spec/fixtures/no_members_address_groups.xml

@@ -0,0 +1,11 @@
+<response status="success" code="19">
+  <result total-count="1" count="1">
+    <entry name="test" src="tpl" admin="admin" time="2015/02/02 13:45:00">
+      <address-group admin="someone" time="2015/03/04 13:45:08">
+        <entry name="test" admin="someone" time="2015/03/04 13:45:08">
+          <description>Testing using API</description>
+        </entry>
+      </address-group>
+    </entry>
+  </result>
+</response>

data/spec/fixtures/no_rulebase_virtual_systems.xml

@@ -0,0 +1,24 @@
+<response status="success" code="19">
+  <result total-count="1" count="1">
+    <vsys src="tpl" admin="admin" time="2015/03/05 10:22:56">
+      <entry name="vsys1" src="tpl" admin="admin" time="2015/03/05 10:22:56">
+        <address admin="admin" time="2015/03/05 10:22:56">
+          <entry name="address-1" admin="admin" time="2015/03/04 13:39:03">
+            <ip-netmask admin="admin" time="2015/03/04 13:39:02">1.1.1.1</ip-netmask>
+          </entry>
+          <entry name="address-2" admin="admin" time="2015/03/05 10:22:56">
+            <ip-netmask admin="admin" time="2015/03/05 10:22:56">2.2.2.2</ip-netmask>
+          </entry>
+        </address>
+        <address-group admin="admin" time="2015/03/04 13:45:08">
+          <entry name="test" admin="admin" time="2015/03/04 13:45:08">
+            <static admin="admin" time="2015/03/04 13:45:08">
+              <member admin="admin" time="2015/03/04 13:45:08">address-group-1</member>
+            </static>
+            <description>Testing using API</description>
+          </entry>
+        </address-group>
+      </entry>
+    </vsys>
+  </result>
+</response>

data/spec/fixtures/no_vsys_devices.xml

@@ -0,0 +1,13 @@
+<response status="success">
+  <result total-count="1" count="1">
+    <devices src="tpl" admin="admin" time="2015/03/05 10:22:56">
+      <entry name="localhost.localdomain" src="tpl" admin="admin" time="2015/03/05 10:22:56">
+        <deviceconfig>
+          <system>
+            <ip-address>2.2.2.2</ip-address>
+          </system>
+        </deviceconfig>
+      </entry>
+    </devices>
+  </result>
+</response>

data/spec/fixtures/virtual_systems.xml

@@ -0,0 +1,32 @@
+<response status="success" code="19">
+  <result total-count="1" count="1">
+    <vsys src="tpl" admin="admin" time="2015/03/05 10:22:56">
+      <entry name="vsys1" src="tpl" admin="admin" time="2015/03/05 10:22:56">
+        <rulebase admin="admin" time="2015/03/04 13:46:08">
+          <security admin="admin" time="2015/03/04 13:46:08">
+            <rules admin="admin" time="2015/03/04 13:46:08">
+              <entry name="DNS" admin="admin" time="2015/03/04 13:46:07">
+              </entry>
+            </rules>
+          </security>
+        </rulebase>
+        <address admin="admin" time="2015/03/05 10:22:56">
+          <entry name="address-1" admin="admin" time="2015/03/04 13:39:03">
+            <ip-netmask admin="admin" time="2015/03/04 13:39:02">1.1.1.1</ip-netmask>
+          </entry>
+          <entry name="address-2" admin="admin" time="2015/03/05 10:22:56">
+            <ip-netmask admin="admin" time="2015/03/05 10:22:56">2.2.2.2</ip-netmask>
+          </entry>
+        </address>
+        <address-group admin="admin" time="2015/03/04 13:45:08">
+          <entry name="test" admin="admin" time="2015/03/04 13:45:08">
+            <static admin="admin" time="2015/03/04 13:45:08">
+              <member admin="admin" time="2015/03/04 13:45:08">address-group-1</member>
+            </static>
+            <description>Testing using API</description>
+          </entry>
+        </address-group>
+      </entry>
+    </vsys>
+  </result>
+</response>

data/spec/lib/palo-alto/client_spec.rb

@@ -0,0 +1,36 @@
+require "palo-alto/client"
+
+describe "PaloAlto::Client" do
+  let(:host)        { "some.host" }
+  let(:port)        { "443" }
+  let(:ssl)         { true }
+  let(:username)    { "admin" }
+  let(:password)    { "admin" }
+  let(:api_version) { "6" }
+
+  describe ".new" do
+    let(:fake_api) { Class.new }
+
+    it "attempts to create a new Api instance" do
+      expect(Object).to receive(:const_get).and_return(fake_api)
+      expect(fake_api).to receive(:new)
+
+      PaloAlto::Client.new(host:        host,
+                           port:        port,
+                           ssl:         ssl,
+                           username:    username,
+                           password:    password,
+                           api_version: api_version)
+    end
+
+    it "raises an exception for an un-implemented API version" do
+      expect(File).to receive("exist?").and_return(false)
+      expect{ PaloAlto::Client.new(host:        host,
+                                   port:        port,
+                                   ssl:         ssl,
+                                   username:    username,
+                                   password:    password,
+                                   api_version: "BOGUS") }.to raise_exception
+    end
+  end
+end

data/spec/lib/palo-alto/common/base_api_spec.rb

@@ -0,0 +1,121 @@
+require "palo-alto/common/base-api"
+require "palo-alto/helpers/rest"
+
+describe "PaloAlto::Common::BaseApi" do
+  let(:host)          { "some.host" }
+  let(:port)          { "443" }
+  let(:ssl)           { false }
+  let(:username)      { "admin" }
+  let(:password)      { "admin" }
+  let(:api_version)   { "6" }
+  let(:url)           { "http://#{host}:#{port}/api/" }
+  let(:auth_key)      { "039th90hg092h" }
+  let(:auth_response) { "<response status=\"success\">
+                           <result>
+                             <key>#{auth_key}</key>
+                           </result>
+                         </response>" }
+
+  before do
+    FakeWeb.clean_registry
+    FakeWeb.register_uri(:post, url, :status => [ 200 ], :body => auth_response)
+
+    @api = PaloAlto::Common::BaseApi.new(host:     host,
+                                         port:     port,
+                                         ssl:      ssl,
+                                         username: username,
+                                         password: password)
+  end
+
+  it "has a host attribute" do
+    expect(@api).to respond_to(:host)
+  end
+
+  it "has a port attribute" do
+    expect(@api).to respond_to(:port)
+  end
+
+  it "has a ssl attribute" do
+    expect(@api).to respond_to(:ssl)
+  end
+
+  it "has a username attribute" do
+    expect(@api).to respond_to(:username)
+  end
+
+  it "has a password attribute" do
+    expect(@api).to respond_to(:password)
+  end
+
+  it "has an auth_key attribute" do
+    expect(@api).to respond_to(:auth_key)
+  end
+
+  describe ".initialize" do
+    it "returns a PaloAlto::V6::Api instance" do
+      expect(@api).to be_instance_of(PaloAlto::Common::BaseApi)
+    end
+
+    it "assigns host" do
+      expect(@api.host).to eq(host)
+    end
+
+    it "assigns port" do
+      expect(@api.port).to eq(port)
+    end
+
+    it "assigns ssl" do
+      expect(@api.ssl).to eq(ssl)
+    end
+
+    it "assigns username" do
+      expect(@api.username).to eq(username)
+    end
+
+    it "assigns password" do
+      expect(@api.password).to eq(password)
+    end
+
+    it "obtains and assigns the auth_key" do
+      expect(@api.auth_key).to eq(auth_key)
+    end
+
+    describe "when an auth_key cannot be obtained" do
+      before do
+        FakeWeb.clean_registry
+        FakeWeb.register_uri(:post, url, :status => [ 401 ], :body => File.open(fixture_file("failure.xml")).read)
+      end
+
+      it "throws and exception" do
+        expect{ PaloAlto::Common::BaseApi.new(host:     host,
+                                              port:     port,
+                                              ssl:      ssl,
+                                              username: username,
+                                              password: password) }.to raise_exception
+      end
+    end
+  end
+
+  describe ".endpoint" do
+    it "returns the endpoint with secure protocol" do
+      url = "http://#{host}:#{port}/api/"
+      expect(@api.endpoint).to eq(url)
+    end
+  end
+
+  describe "private method" do
+    describe ".get_auth_key" do
+      it "returns the resulting auth_key from a request" do
+        expect(PaloAlto::Helpers::Rest).to receive(:make_request).and_return(auth_response)
+
+        expect(@api.send(:get_auth_key)).to eq(auth_key)
+      end
+
+      it "returns nil when a HTTP request attempt is unsuccessful" do
+        expect(PaloAlto::Helpers::Rest).to receive(:make_request).and_return(File.open(fixture_file("failure.xml")).read)
+
+        expect(@api.send(:get_auth_key)).to be_nil
+      end
+    end
+  end
+end

data/spec/lib/palo-alto/helpers/rest_spec.rb

@@ -0,0 +1,32 @@
+require "palo-alto/helpers/rest"
+require "rest-client"
+
+describe "PaloAlto::Helpers::Rest" do
+  let(:url)            { "http://localhost.localdomain:443/api/" }
+  let(:specified_opts) { { url:    url,
+                           method: :post,
+                           payload: {
+                             type:   "config",
+                             action: "set"
+                           }
+                         }
+                       }
+  let(:final_opts)     { { verify_ssl: OpenSSL::SSL::VERIFY_NONE,
+                           headers: {
+                             "User-Agent"   => "ruby-keystone-client",
+                             "Accept"       => "application/xml",
+                             "Content-Type" => "application/xml"
+                           }
+                         }.merge(specified_opts)
+                       }
+
+  describe "#make_request" do
+    before do
+      expect(RestClient::Request).to receive(:execute).with(final_opts).and_return(true)
+    end
+
+    it "makes the specified request" do
+      expect(PaloAlto::Helpers::Rest.make_request(specified_opts)).to be_truthy
+    end
+  end
+end

data/spec/lib/palo-alto/models/address_group_spec.rb

@@ -0,0 +1,43 @@
+require "palo-alto/models/address-group"
+
+describe "PaloAlto::Models::AddressGroup" do
+  let(:name)        { "test-address-group" }
+  let(:description) { "test-address-group-description" }
+  let(:addresses)   { [ "a", "b" ] }
+
+  before do
+    @address_group = PaloAlto::Models::AddressGroup.new(name:        name,
+                                                        description: description,
+                                                        addresses:   addresses)
+  end
+
+  it "has a name attribute" do
+    expect(@address_group).to respond_to(:name)
+  end
+
+  it "has a description attribute" do
+    expect(@address_group).to respond_to(:description)
+  end
+
+  it "has an addresses attribute" do
+    expect(@address_group).to respond_to(:addresses)
+  end
+
+  describe ".initialize" do
+    it "returns a PaloAlto::Models::AddressGroup instance" do
+      expect(@address_group).to be_instance_of(PaloAlto::Models::AddressGroup)
+    end
+
+    it "assigns name" do
+      expect(@address_group.name).to eq(name)
+    end
+
+    it "assigns description" do
+      expect(@address_group.description).to eq(description)
+    end
+
+    it "assigns addresses" do
+      expect(@address_group.addresses).to eq(addresses)
+    end
+  end
+end

data/spec/lib/palo-alto/models/address_spec.rb

@@ -0,0 +1,32 @@
+require "palo-alto/models/address"
+
+describe "PaloAlto::Models::Address" do
+  let(:name) { "test-address" }
+  let(:ip)   { "2.2.2.2" }
+
+  before do
+    @address = PaloAlto::Models::Address.new(name: name, ip: ip)
+  end
+
+  it "has a name attribute" do
+    expect(@address).to respond_to(:name)
+  end
+
+  it "has an ip attribute" do
+    expect(@address).to respond_to(:ip)
+  end
+
+  describe ".initialize" do
+    it "returns a PaloAlto::Models::Address instance" do
+      expect(@address).to be_instance_of(PaloAlto::Models::Address)
+    end
+
+    it "assigns name" do
+      expect(@address.name).to eq(name)
+    end
+
+    it "assigns ip" do
+      expect(@address.ip).to eq(ip)
+    end
+  end
+end