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.

Parameters:

  • id (String) (defaults to: ENV['CENSYS_ID']) —

    The API UID used for authentication.

  • secret (String) (defaults to: ENV['CENSYS_SECRET']) —

    The API secret used for authentication.

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.

Returns:



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

def certificates
  @certificates
end

#id ⇒ String (readonly)

API UID.

Returns:

  • (String) 


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

def id
  @id
end

#ipv4 ⇒ Resource (readonly)

IPv4 resource.

Returns:



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

def ipv4
  @ipv4
end

#secret ⇒ String (readonly)

API Secret.

Returns:

  • (String) 


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

def secret
  @secret
end

#websites ⇒ Resource (readonly)

Websites resource.

Returns:



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 



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.

Parameters:

  • resource (:ipv4, :websites, :certificates)
  • params (Hash) (defaults to: {}) —

    Optional search params.

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.

Parameters:

  • resource (:ipv4, :websites, :certificates)
  • id (String) 


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