Class: Censys::API

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

Defined Under Namespace

Classes: Resource

Constant Summary collapse

VERSION = 
1
HOST = 
'www.censys.io'.freeze
URL = 
"https://#{HOST}/api/v#{VERSION}".freeze
DOCUMENTS = 
{
  ipv4:         IPv4,
  websites:     Website,
  certificates: Certificate
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id = ENV['CENSYS_ID'], secret = ENV['CENSYS_SECRET']) ⇒ API

Initializes the API.

Raises:

  • (ArgumentError) —

    Either id or secret was nil or empty.

See Also:



86
87
88
89
90
91
92
93
94
95
 
# File 'lib/censys/api.rb', line 86

def initialize(id = ENV['CENSYS_ID'], secret = ENV['CENSYS_SECRET'])
  raise(ArgumentError, "'id' argument required") if id.nil? || id.empty?
  raise(ArgumentError, "'secret' argument required") if secret.nil? || secret.empty?

  @id, @secret = id, secret

  @ipv4         = Resource.new(:ipv4, self)
  @websites     = Resource.new(:websites, self)
  @certificates = Resource.new(:certificates, self)
end

Instance Attribute Details

#certificates ⇒ Resource (readonly)

Certificates resource.



69
70
71
 
# File 'lib/censys/api.rb', line 69

def certificates
  @certificates
end

#id ⇒ String (readonly)

API UID.



49
50
51
 
# File 'lib/censys/api.rb', line 49

def id
  @id
end

#ipv4 ⇒ Resource (readonly)

IPv4 resource.



59
60
61
 
# File 'lib/censys/api.rb', line 59

def ipv4
  @ipv4
end

#secret ⇒ String (readonly)

API Secret.



54
55
56
 
# File 'lib/censys/api.rb', line 54

def secret
  @secret
end

#websites ⇒ Resource (readonly)

Websites resource.



64
65
66
 
# File 'lib/censys/api.rb', line 64

def websites
  @websites
end

Instance Method Details

#data(params = {}) ⇒ Object 



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/censys/api.rb', line 172

def data(params = {})
  series = params[:series]
  result = params[:result]
  type, path =
    if series && result.nil? then [:series, "/data/#{series}"]
    elsif series && result then [:result, "/data/#{series}/#{result}"]
    else
      [:series_list, "/data"]
    end
  get(path) do |response|
    case type
    when :series then Data::Series.new(response)
    when :result then Data::Result.new(response)
    else
      Data::SeriesList.new(response)
    end
  end
end

#report(resource, params) ⇒ Object

Builds a report of aggregate data.

Options Hash (params):

  • :query (String) — default: **Required** —

    The query to perform.

  • :field (String) — default: **Required** —

    The field to aggregate.

  • :buckets (Fixnum) —

    Optional maximum number of values to be returned.

  • (Object)

Raises:

  • (ArgumentError) 


163
164
165
166
167
168
169
170
 
# File 'lib/censys/api.rb', line 163

def report(resource, params)
  raise(ArgumentError, "must specify the :query param") unless params[:query]
  raise(ArgumentError, "must specify the :field param") unless params[:field]

  post("/report/#{resource}", params) do |response|
    Report::Response.new(response)
  end
end

#search(resource, params = {}) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Performs a search.

Options Hash (params):

  • :query (String) —

    The query to perform.

  • :page (Fixnum) —

    Optional page number to request.

  • :fields (Array<String>) —

    Optional list of fields to include in the results.



116
117
118
119
120
 
# File 'lib/censys/api.rb', line 116

def search(resource, params = {})
  post("/search/#{resource}", params) do |json|
    Search::Response.new(self, resource, params, json)
  end
end

#view(resource, id) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Requests the document of the given type.



137
138
139
140
141
142
143
 
# File 'lib/censys/api.rb', line 137

def view(resource, id)
  document_class = DOCUMENTS.fetch(resource)

  get("/view/#{resource}/#{id}") do |attributes|
    document_class.new(attributes)
  end
end