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'
URL = 
"https://#{HOST}/api/v#{VERSION}"
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:



89
90
91
92
93
94
95
96
97
98
 
# File 'lib/censys/api.rb', line 89

def initialize(id = ENV['CENSYS_ID'], secret = ENV['CENSYS_SECRET'])
  raise(ArgumentError, "'id' argument is required") if id.nil? || id.empty?
  raise(ArgumentError, "'secret' argument is 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.



72
73
74
 
# File 'lib/censys/api.rb', line 72

def certificates
  @certificates
end

#id ⇒ String (readonly)

API UID.



52
53
54
 
# File 'lib/censys/api.rb', line 52

def id
  @id
end

#ipv4 ⇒ Resource (readonly)

IPv4 resource.



62
63
64
 
# File 'lib/censys/api.rb', line 62

def ipv4
  @ipv4
end

#secret ⇒ String (readonly)

API Secret.



57
58
59
 
# File 'lib/censys/api.rb', line 57

def secret
  @secret
end

#websites ⇒ Resource (readonly)

Websites resource.



67
68
69
 
# File 'lib/censys/api.rb', line 67

def websites
  @websites
end

Instance Method Details

#account ⇒ Object 



194
195
196
197
198
 
# File 'lib/censys/api.rb', line 194

def 
  get("/account") do |response|
    .new(response)
  end
end

#data(params = {}) ⇒ Object 



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

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) 


166
167
168
169
170
171
172
173
 
# File 'lib/censys/api.rb', line 166

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.



119
120
121
122
123
 
# File 'lib/censys/api.rb', line 119

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.



140
141
142
143
144
145
146
 
# File 'lib/censys/api.rb', line 140

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

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