investigate 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ac625584a4ae8f946228752e85e8ff967d588d4b
+  data.tar.gz: eb65489710eaefebb6e5253fe582b81fcdf92df9
+SHA512:
+  metadata.gz: b6af4681102260bdf2d264f1cea6bb2d32713e4e5701e384c84b649ec589c352889769cc5d2959fc485f69f36c5f5ab328c0205b1e98473e317b3680e84b61e5
+  data.tar.gz: a6551994bad83549cfbeb092a08dc2e7f79cfef9424a2fa432e8d043063878bbbc670dcfc0df9553c9d621671eb47bfb5e69a3b412c6eebd598f1dd24123dfdb

data/.gitignore

@@ -0,0 +1,3 @@
+*.DS_Store
+*.lock
+*.swp

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--backtrace

data/.ruby-version

@@ -0,0 +1 @@
+2.1.2

data/Gemfile

@@ -0,0 +1,6 @@
+source 'http://rubygems.org'
+
+# gem 'rest-client'
+# gem 'siphash', github: 'emboss/siphash-ruby'
+
+gemspec

data/README.md

@@ -0,0 +1,52 @@
+# Ruby API for the OpenDNS Security Graph
+
+## Usage
+
+In your Ruby script, you can use it like this:
+
+```ruby
+require 'investigate'
+
+inv = Investigate.new('f29be9cc-f833-4a9a-b984-19dc4d5186ac')
+
+# get domain categorization and status
+inv.categorization('amazon.com')
+
+# categorization and status on a list of domains with labels
+domains = ['www.amazon.com', 'www.opendns.com', 'bibikun.ru']
+inv.categorization(domains, true)
+
+# cooccurrences
+inv.cooccurrences('test.com')
+
+# related domains
+inv.related("test.com")
+
+# security features
+inv.security("test.com")
+
+# domain tags
+inv.domain_tags('bibikun.ru')
+
+# domain RR history
+inv.rr_history('bibikun.ru')
+
+# IP RR history
+inv.rr_history('50.23.225.49')
+...
+```
+
+## Installation
+You can do:
+```sh
+gem install investigate
+```
+
+or install manually with:
+```sh
+git clone git@github.com:dead10ck/ruby-investigate.git
+cd ruby-investigate
+bundle install
+gem build investigate.gemspec
+gem install {generated_name}.gem
+```

data/investigate.gemspec

@@ -0,0 +1,22 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'investigate'
+
+Gem::Specification.new do |spec|
+  spec.name          = "investigate"
+  spec.version       = Investigate::VERSION
+  spec.authors       = ["skyler"]
+  spec.email         = ["skyler@opendns.com"]
+  spec.summary       = "Ruby API for the OpenDNS Security Graph"
+  spec.description   = spec.summary
+  spec.homepage      = 'https://github.com/dead10ck/ruby-investigate'
+  spec.license       = "MIT"
+
+  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 "rest-client", "~> 1.7"
+end

data/lib/investigate.rb

@@ -0,0 +1,121 @@
+require 'json'
+require 'rest-client'
+
+# Ruby API for the OpenDNS Security Graph
+class Investigate
+  VERSION = '1.0.0'
+  SGRAPH_URL = 'https://investigate.api.opendns.com'
+  SIPHASH_KEY = 'Umbrella/OpenDNS'
+  SUPPORTED_DNS_TYPES = [
+      "A",
+      "NS",
+      "MX",
+      "TXT",
+      "CNAME"
+  ]
+
+  # Builds a new Investigate object.
+  def initialize(key)
+      @res = RestClient::Resource.new(SGRAPH_URL,
+              :headers => { "Authorization" => "Bearer #{key}" })
+  end
+
+  # Generic GET call to the API with the given URI
+  # Parses the response into a JSON object
+  def get(uri, params={})
+    resp = @res[uri].get(:params => params)
+    JSON.parse(resp)
+  end
+
+  # Generic POST call to the API with the given URI and body
+  # Parses the response into a JSON object
+  def post(uri, body, params)
+    resp = @res[uri].post(body, :params => params)
+    JSON.parse(resp)
+  end
+
+  # Get the domain status and categorization of a domain or list of domains.
+  # 'domains' can be either a single domain, or a list of domains.
+  # Setting 'labels' to True will give back categorizations in human-readable
+  # form.
+  #
+  # For more detail, see https://sgraph.opendns.com/docs/api#categorization
+  def categorization(domains, labels=false)
+    if domains.kind_of?(Array)
+      post_categorization(domains, labels)
+    elsif domains.kind_of?(String)
+      get_categorization(domains, labels)
+    else
+      raise "domains must be a string or a list of strings"
+    end
+  end
+
+  # Get the cooccurrences of the given domain.
+  #
+  # For details, see https://sgraph.opendns.com/docs/api#co-occurrences
+  def cooccurrences(domain)
+    get("/recommendations/name/#{domain}.json")
+  end
+
+  # Get the related domains of the given domain.
+  #
+  # For details, see https://sgraph.opendns.com/docs/api#relatedDomains
+  def related_domains(domain)
+    get("/links/name/#{domain}.json")
+  end
+
+  # Get the Security Information for the given domain.
+  #
+  # For details, see https://sgraph.opendns.com/docs/api#securityInfo
+  def security(domain)
+    get("/security/name/#{domain}.json")
+  end
+
+  # Get the domain tagging dates for the given domain.
+  #
+  # For details, see https://sgraph.opendns.com/docs/api#latest_tags
+  def domain_tags(domain)
+    get("/domains/#{domain}/latest_tags")
+  end
+
+  # Get the RR (Resource Record) History of the given domain or IP.
+  # The default query type is for 'A' records, but the following query types
+  # are supported:
+  #
+  # A, NS, MX, TXT, CNAME
+  #
+  # For details, see https://sgraph.opendns.com/docs/api#dnsrr_domain
+  def rr_history(query, query_type="A")
+    raise "unsupported query type" unless SUPPORTED_DNS_TYPES.include?(query_type)
+    if query =~ /(\d{1,3}\.){3}\d{1,3}/
+      get_ip(query, query_type)
+    else
+      get_domain(query, query_type)
+    end
+  end
+
+  private
+
+  # Make a GET call to '/dnsdb/ip/a/{ip}.json'.
+  # Return the JSON object in the response
+  def get_ip(ip, query_type)
+    get("/dnsdb/ip/#{query_type}/#{ip}.json")
+  end
+
+  # Make a GET call to '/dnsdb/name/a/{domain}.json'.
+  # Return the JSON object in the response
+  def get_domain(domain, query_type)
+    get("/dnsdb/name/#{query_type}/#{domain}.json")
+  end
+
+  def get_categorization(domain, labels)
+    params = labels ? { "showLabels" => true } : {}
+    get("/domains/categorization/#{domain}", params)
+  end
+
+  def post_categorization(domains, labels)
+    params = labels ? { "showLabels" => true } : {}
+    data = JSON.generate(domains)
+    post("/domains/categorization/", data, params)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require_relative '../lib/investigate.rb'

data/spec/tests.rb

@@ -0,0 +1,99 @@
+require 'spec_helper'
+require 'time'
+
+describe "Investigate" do
+  before(:all) do
+    @sg = Investigate.new(ENV['INVESTIGATE_KEY'])
+  end
+
+  def has_keys?(data={}, keys=[])
+    keys.each do |key|
+      expect(data.has_key?(key)).to eq true
+    end
+  end
+
+  it "does categorization() correctly" do
+    # test a single domain
+    cat_keys = ["status", "security_categories", "content_categories"]
+    resp_json = @sg.categorization('www.amazon.com')
+    expect(resp_json.has_key?('www.amazon.com')).to eq true
+    has_keys?(resp_json['www.amazon.com'], cat_keys)
+
+    # test a domain with labels
+    resp_json = @sg.categorization('www.amazon.com', true)
+    expect(resp_json.has_key?('www.amazon.com')).to eq true
+    has_keys?(resp_json['www.amazon.com'], cat_keys)
+
+    # test a list of domains with labels
+    domains = ['www.amazon.com', 'www.opendns.com', 'bibikun.ru']
+    resp_json = @sg.categorization(domains, true)
+    has_keys?(resp_json, domains)
+    domains.each do |d|
+      has_keys?(resp_json[d], cat_keys)
+    end
+
+    # calling with the wrong kind of object should raise an error
+    lambda { @sg.categorization({"blah" => "hello"}) }.should raise_error
+  end
+
+  it "does rr_history() correctly" do
+    # query an IP
+    data = @sg.rr_history('208.64.121.161')
+    has_keys?(data, ['features', 'rrs'])
+
+    # query a domain
+    data = @sg.rr_history('www.test.com')
+    has_keys?(data, ['features', 'rrs_tf'])
+
+    # query a domain with a different query_type
+    data = @sg.rr_history('www.test.com', 'NS')
+    has_keys?(data, ['rrs_tf'])
+
+    # trying an unsupported query type should raise an error
+    lambda { @sg.rr_history('www.test.com', 'AFSDB') }.should raise_error
+  end
+
+  it "does related_domains() correctly" do
+    data = @sg.related_domains('www.test.com')
+    has_keys?(data, ['found', 'tb1'])
+  end
+
+  it "does cooccurrences() correctly" do
+    data = @sg.cooccurrences('www.test.com')
+    has_keys?(data, ['found', 'pfs2'])
+  end
+
+  it "does security() correctly" do
+    data = @sg.security('www.test.com')
+    keys = [
+      "dga_score",
+      "perplexity",
+      "entropy",
+      "securerank2",
+      "pagerank",
+      "asn_score",
+      "prefix_score",
+      "rip_score",
+      "fastflux",
+      "popularity",
+      "geodiversity",
+      "geodiversity_normalized",
+      "tld_geodiversity",
+      "geoscore",
+      "ks_test",
+      "handlings",
+      "attack",
+      "threat_type",
+      "found"
+    ]
+    has_keys?(data, keys)
+  end
+
+  it "does domain_tags() correctly" do
+    resp_json = @sg.domain_tags('bibikun.ru')
+    resp_json.each do |tag_entry|
+      has_keys?(tag_entry, ['category', 'period', 'url'])
+      has_keys?(tag_entry['period'], ['begin', 'end'])
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: investigate
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- skyler
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: Ruby API for the OpenDNS Security Graph
+email:
+- skyler@opendns.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- Gemfile
+- README.md
+- investigate.gemspec
+- lib/investigate.rb
+- spec/spec_helper.rb
+- spec/tests.rb
+homepage: https://github.com/dead10ck/ruby-investigate
+licenses:
+- MIT
+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.2.2
+signing_key: 
+specification_version: 4
+summary: Ruby API for the OpenDNS Security Graph
+test_files:
+- spec/spec_helper.rb
+- spec/tests.rb