Class: Investigate

Inherits:
Object
  • Object
show all
Defined in:
lib/investigate.rb

Overview

Ruby API for the OpenDNS Security Graph

Constant Summary collapse

VERSION = 
'1.1.0'
SGRAPH_URL = 
'https://investigate.api.opendns.com'
SIPHASH_KEY = 
'Umbrella/OpenDNS'
SUPPORTED_DNS_TYPES = 
[
    "A",
    "NS",
    "MX",
    "TXT",
    "CNAME"
]

Instance Method Summary collapse

Constructor Details

#initialize(key) ⇒ Investigate

Builds a new Investigate object.



18
19
20
21
 
# File 'lib/investigate.rb', line 18

def initialize(key)
    @res = RestClient::Resource.new(SGRAPH_URL,
            :headers => { "Authorization" => "Bearer #{key}" })
end

Instance Method Details

#categorization(domains, labels = false) ⇒ Object

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 sgraph.opendns.com/docs/api#categorization



43
44
45
46
47
48
49
50
51
 
# File 'lib/investigate.rb', line 43

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

#cooccurrences(domain) ⇒ Object

Get the cooccurrences of the given domain.

For details, see sgraph.opendns.com/docs/api#co-occurrences



56
57
58
 
# File 'lib/investigate.rb', line 56

def cooccurrences(domain)
  get("/recommendations/name/#{domain}.json")
end

#domain_tags(domain) ⇒ Object

Get the domain tagging dates for the given domain.

For details, see sgraph.opendns.com/docs/api#latest_tags



77
78
79
 
# File 'lib/investigate.rb', line 77

def domain_tags(domain)
  get("/domains/#{domain}/latest_tags")
end

#get(uri, params = {}) ⇒ Object

Generic GET call to the API with the given URI Parses the response into a JSON object



25
26
27
28
 
# File 'lib/investigate.rb', line 25

def get(uri, params={})
  resp = @res[uri].get(:params => params)
  JSON.parse(resp)
end

#latest_domains(ip) ⇒ Object

Gets the latest known malicious domains associated with the given IP address, if any. Returns the list of malicious domains.



99
100
101
102
 
# File 'lib/investigate.rb', line 99

def latest_domains(ip)
  resp = get("/ips/#{ip}/latest_domains")
  resp.map { |h| h['name'] }
end

#post(uri, body, params) ⇒ Object

Generic POST call to the API with the given URI and body Parses the response into a JSON object



32
33
34
35
 
# File 'lib/investigate.rb', line 32

def post(uri, body, params)
  resp = @res[uri].post(body, :params => params)
  JSON.parse(resp)
end

#related_domains(domain) ⇒ Object

Get the related domains of the given domain.

For details, see sgraph.opendns.com/docs/api#relatedDomains



63
64
65
 
# File 'lib/investigate.rb', line 63

def related_domains(domain)
  get("/links/name/#{domain}.json")
end

#rr_history(query, query_type = "A") ⇒ Object

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 sgraph.opendns.com/docs/api#dnsrr_domain



88
89
90
91
92
93
94
95
 
# File 'lib/investigate.rb', line 88

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

#security(domain) ⇒ Object

Get the Security Information for the given domain.

For details, see sgraph.opendns.com/docs/api#securityInfo



70
71
72
 
# File 'lib/investigate.rb', line 70

def security(domain)
  get("/security/name/#{domain}.json")
end