otx_ruby 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 80186fd6a333eac1ece08c746755f08f06691f2e
+  data.tar.gz: e86becc8bf3d42b0c93bfc851e4bf3b20779e1c5
+SHA512:
+  metadata.gz: 1b951af4d57f56a601617376cae407fdcffbaa0afea9f1169abbd137cd7cd02e119cc4bc9fa96c777eaa01db2a927a2da41c3dd0fa34e76373c833630ad4fe37
+  data.tar.gz: 5deec8205b91c0f72ff275b6c4742ff96ceb55d25e09133a27a80db7efe00752c34b8982296f010ae05738a927c0d6896cdb5be2ee5f8c1fc0a00f868baa891a

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

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

data/README.md

@@ -0,0 +1,61 @@
+# Open Threat Exchange (OTX) Ruby Wrapper
+
+Open Threat Exchange is an open community that allows participants to learn about the latest threats, research indicators of compromise observed in their environments, share threats they have identified, and automatically update their security infrastructure with the latest indicators to defend their environment.
+
+This gem provides a wrapper for Ruby applications to pull pulses from OTX and be consumed by the ruby application.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'otx_ruby'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install otx_ruby
+
+## Usage
+
+```ruby
+  require `otx_ruby`
+
+  api_key = '4xxx........'
+  otx = OTX::Subscribed.new(apikey)
+
+  # Get all subscribed pulses
+  pulses = otx.get_all
+
+  # Read contents of a single pulse
+  pulse_id = '56xxxx..........'
+  pulses = OTX::Pulses.new(apikey)
+
+  pulse = pulses.get_pulse(pulse_id)
+```
+
+## API Key
+
+Library requires your API key this can be found in your settings page https://otx.alienvault.com/settings
+
+## API Timestamp
+
+The API uses ISO Format timestamps, however there is a quirk, the API seems to use Python style timestamps as a result it is important to ensure that the sent time stamp uses the UTC format when sent
+
+```
+"2010-10-25T23:48:46Z"
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mort666/otx_ruby.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "otx_ruby"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/circle.yml

@@ -0,0 +1,9 @@
+machine:
+  ruby:
+    version: 2.1.5
+database:
+  override:
+    - echo 'no database'
+dependencies:
+  pre:
+    - gem install bundler

data/lib/otx_ruby/base.rb

@@ -0,0 +1,75 @@
+module OTX
+  #
+  # Base Class for API access, provides initial wrapper around Faraday performs
+  # base request
+  #
+  class Base
+    #
+    # Initialise object
+    #
+    # @param key [String] API Key for AlienVault OTX API
+    # @param server [String] Base URL for API, defaults to 'https://otx.alienvault.com'
+    #
+    def initialize(key, server="https://otx.alienvault.com")
+      @key = key
+      @server = server
+
+      @conn = Faraday.new(:url => @server) do |faraday|
+        faraday.request  :url_encoded             # form-encode POST params
+        faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
+      end
+    end
+
+    #
+    # Get the provided URL
+    #
+    # @param url [String] URL to make API request to
+    # @param params [Hash] Additional parameters to be added to the requests
+    #
+    def get(url, params={})
+      response = @conn.get do |req|
+        req.url url
+        req.headers['X-OTX-API-KEY'] = @key
+        req.params = params
+      end
+
+      # Parse and return JSON object as hash to caller
+      return Oj.load(response.body)
+    end
+  end
+end
+
+
+module OTX
+  #
+  # Base Data Types for Returned Data from API
+  #
+  # Implements two default handlers for created and modified timestamps as DataTime
+  # objects
+  #
+  module Type
+    #
+    # Base Class for types
+    #
+    # @attr [DateTime] created Date and Time stamp for the creation of the records
+    # @attr [DateTime] modified Date and Time stamp for the last modification of the records
+    #
+    class Base
+      attr_writer :modified, :created
+
+      def created
+        return @created.nil? ? nil : DateTime.parse(@created)
+      end
+
+      def modified
+        return @modified.nil? ? nil : DateTime.parse(@modified)
+      end
+
+      def initialize(attributes={})
+        attributes.each do |key, value|
+          send("#{key}=", value)
+        end
+      end
+    end
+  end
+end

data/lib/otx_ruby/events.rb

@@ -0,0 +1,64 @@
+module OTX
+  #
+  # Besides receiving the pulse information, it is possible to return details of
+  # events that have occured in the OTX system and affect your account. This class
+  # provides a wrapper around this functionality.
+  #
+  class Events < OTX::Base
+    #
+    # Get all events from the API, get all events in chunks defined by limit
+    #
+    # @param limit [Integer] Size of chunk of data to be Returned (default = 20)
+    # @return [Array] Array of OTX::Event records
+    #
+    def get_all(limit=20)
+      uri = '/api/v1/pulses/events'
+      params = {limit: limit}
+      events = []
+      begin
+        json_data = get(uri, params)
+        page = json_data['next']
+
+        params = URI::decode_www_form(URI(page).query).to_h unless page.nil?
+
+        events += json_data['results']
+      end while !page.nil?
+
+      results = []
+      events.each do |event|
+        results << OTX::Event.new(event)
+      end
+
+      return results
+    end
+
+    #
+    # Get all events from the API, get all events in chunks defined by limit and since
+    # timestamp
+    #
+    # @param timestamp [Time] Timestamp of point in time to get records since in ISO Format
+    # @param limit [Integer] Size of chunk of data to be Returned (default = 20)
+    # @return [Array] Array of OTX::Event records
+    #
+    def get_since(timestamp, limit=20)
+      uri = '/api/v1/pulses/events'
+      params = {limit: limit, since: timestamp}
+      events = []
+      begin
+        json_data = get(uri, params)
+        page = json_data['next']
+
+        params = URI::decode_www_form(URI(page).query).to_h unless page.nil?
+
+        events += json_data['results']
+      end while !page.nil?
+
+      results = []
+      events.each do |event|
+        results << OTX::Event.new(event)
+      end
+
+      return results
+    end
+  end
+end

data/lib/otx_ruby/pulses.rb

@@ -0,0 +1,22 @@
+module OTX
+  #
+  # Retrieve and parse into the appropriate object a pulse from the OTX System
+  #
+  class Pulses < OTX::Base
+    #
+    # Download an individually identified pulse and parse the output
+    #
+    # @param id [String] The id value for the pulse to Download
+    # @return [OTX::Pulse] Parsed Pulse
+    #
+    def get_pulse(id)
+        uri = "/api/v1/pulses/#{id}"
+
+        json_data = get(uri)
+
+        pulse = OTX::Pulse.new(json_data)
+
+        return pulse
+    end
+  end
+end

data/lib/otx_ruby/subscribed.rb

@@ -0,0 +1,64 @@
+module OTX
+  #
+  # Within the OTX system you are able to subscribe to pulses from other users,
+  # this class allows the retreival of the currently subscribed pulse feeds and the
+  # associated pulses
+  #
+  class Subscribed < OTX::Base
+    #
+    # Get all subscribed pulses from the API, get all events in chunks defined by limit
+    #
+    # @param limit [Integer] Size of chunk of data to be Returned (default = 20)
+    # @return [Array] Array of OTX::Pulse records
+    #
+    def get_all(limit=20)
+      uri = '/api/v1/pulses/subscribed'
+      params = {limit: limit}
+      pulses = []
+      begin
+        json_data = get(uri, params)
+        page = json_data['next']
+
+        params = URI::decode_www_form(URI(page).query).to_h unless page.nil?
+
+        pulses += json_data['results']
+      end while !page.nil?
+
+      results = []
+      pulses.each do |pulse|
+        results << OTX::Pulse.new(pulse)
+      end
+
+      return results
+    end
+
+    #
+    # Get all subscribed pulses from the API, get all events in chunks defined by limit and since
+    # timestamp
+    #
+    # @param timestamp [Time] Timestamp of point in time to get records since in ISO Format
+    # @param limit [Integer] Size of chunk of data to be Returned (default = 20)
+    # @return [Array] Array of OTX::Pulse records
+    #
+    def get_since(timestamp, limit=20)
+      uri = '/api/v1/pulses/subscribed'
+      params = {limit: limit, modified_since: timestamp}
+      pulses = []
+      begin
+        json_data = get(uri, params)
+        page = json_data['next']
+
+        params = URI::decode_www_form(URI(page).query).to_h unless page.nil?
+
+        pulses += json_data['results']
+      end while !page.nil?
+
+      results = []
+      pulses.each do |pulse|
+        results << OTX::Pulse.new(pulse)
+      end
+
+      return results
+    end
+  end
+end

data/lib/otx_ruby/types/event.rb

@@ -0,0 +1,14 @@
+module OTX
+  #
+  # Account Events Object Type
+  #
+  # @author Stephen Kapp
+  # @attr [String] id ID value for record
+  # @attr [String] action Action peformed, currently supports (subscribe, unsubscribe, delete)
+  # @attr [String] object_type Currently supports events for pulse and user objects
+  # @attr [String] object_id ID value for the object the event is created for
+  #
+  class Event < OTX::Type::Base
+    attr_accessor :id, :action, :object_type, :object_id
+  end
+end

data/lib/otx_ruby/types/indicators.rb

@@ -0,0 +1,31 @@
+module OTX
+  #
+  # Pulse Indicator of Compromise (IoC) records
+  #
+  # @attr [String] _id IoC record ID value
+  # @attr [String] indicator Value of the indicator type
+  # @attr [String] type Type of IoC
+  # @attr [String] description Description associated with the IoC
+  #
+  # Indicator of Compromise types:
+  #   IPv4 - An IPv4 address indicating the online location of a server or other computer.
+  #   IPv6 - An IPv6 address indicating the online location of a server or other computer.
+  #   domain - A domain name for a website or server. Domains encompass a series of hostnames.
+  #   hostname - The hostname for a server located within a domain.
+  #   email - An email associated with suspicious activity.
+  #   URL - Uniform Resource Location (URL) summarizing the online location of a file or resource.
+  #   URI - Uniform Resource Indicator (URI) describing the explicit path to a file hosted online.
+  #   FileHash-MD5 - A MD5-format hash that summarizes the architecture and content of a file.
+  #   FileHash-SHA1 - A SHA-format hash that summarizes the architecture and content of a file.
+  #   FileHash-SHA256 - A SHA-256-format hash that summarizes the architecture and content of a file.
+  #   FileHash-PEHASH - A PEPHASH-format hash that summarizes the architecture and content of a file.
+  #   FileHash-IMPHASH - An IMPHASH-format hash that summarizes the architecture and content of a file.
+  #   CIDR - Classless Inter-Domain Routing (CIDR) address, which describes both a server's IP address and the network architecture (routing path) surrounding that server.
+  #   FilePath - A unique location in a file system.
+  #   Mutex - The name of a mutex resource describing the execution architecture of a file.
+  #   CVE - Common Vulnerability and Exposure (CVE) entry describing a software vulnerability that can be exploited to engage in malicious activity.
+  #
+  class Indicators < OTX::Type::Base
+    attr_accessor :_id, :indicator, :type, :description
+  end
+end

data/lib/otx_ruby/types/pulse.rb

@@ -0,0 +1,32 @@
+module OTX
+  #
+  # AlienVault OTX Pulse Record
+  #
+  # @author Stephen Kapp
+  # @attr [String] id OTX ID value for the pulse Record
+  # @attr [String] name Pulse Name
+  # @attr [String] description Description of the pulse
+  # @attr [String] author_name Name of the pulse author_name
+  # @attr [Array<String>] tags Array of 'tags' to describe the pulse
+  # @attr [Array<String>] referenes Array of references attached to the pulse
+  # @attr [String] revision Revision number of the OTX Pulse Record
+  # @attr [Array<OTX::Indicators>] indicators Array of the IoC attached to the OTX pulse
+  #
+  class Pulse < OTX::Type::Base
+    attr_accessor :id, :name, :description, :author_name,
+      :tags, :references, :revision, :indicators
+
+    def initialize(attributes={})
+      attributes.each do |key, value|
+        if key != 'indicators'
+          send("#{key}=", value)
+        else
+          @indicators = []
+          value.each do |indicator|
+            @indicators << OTX::Indicators.new(indicator)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/otx_ruby/version.rb

@@ -0,0 +1,4 @@
+module OTX
+  # Library Version Number
+  VERSION = "0.5.0"
+end

data/lib/otx_ruby.rb

@@ -0,0 +1,17 @@
+require 'faraday'
+require 'oj'
+
+require "otx_ruby/version"
+require "otx_ruby/base.rb"
+require "otx_ruby/subscribed.rb"
+require "otx_ruby/events.rb"
+require "otx_ruby/pulses.rb"
+require "otx_ruby/types/pulse.rb"
+require "otx_ruby/types/indicators.rb"
+
+#
+# Base AlienVault OTX Module
+#
+module OTX
+
+end

data/otx_ruby.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'otx_ruby/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "otx_ruby"
+  spec.version       = OTX::VERSION
+  spec.authors       = ["Stephen Kapp"]
+  spec.email         = ["mort666@virus.org"]
+  spec.summary       = %q{AlienVault OTX Ruby Gem}
+  spec.description   = %q{AlienVault Open Threat Exchange Threat Intel feed API Wrapper}
+  spec.homepage      = "http://github.com/mort666/otx_ruby"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday"
+  spec.add_dependency "oj"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "vcr"
+  spec.add_development_dependency "webmock"
+end

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: otx_ruby
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Stephen Kapp
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: AlienVault Open Threat Exchange Threat Intel feed API Wrapper
+email:
+- mort666@virus.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- circle.yml
+- lib/otx_ruby.rb
+- lib/otx_ruby/base.rb
+- lib/otx_ruby/events.rb
+- lib/otx_ruby/pulses.rb
+- lib/otx_ruby/subscribed.rb
+- lib/otx_ruby/types/event.rb
+- lib/otx_ruby/types/indicators.rb
+- lib/otx_ruby/types/pulse.rb
+- lib/otx_ruby/version.rb
+- otx_ruby.gemspec
+homepage: http://github.com/mort666/otx_ruby
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: AlienVault OTX Ruby Gem
+test_files: []
+has_rdoc: