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.

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:



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

#certificatesResource (readonly)

Certificates resource.

Returns:



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

def certificates
  @certificates
end

#idString (readonly)

API UID.

Returns:

  • (String)


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

def id
  @id
end

#ipv4Resource (readonly)

IPv4 resource.

Returns:



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

def ipv4
  @ipv4
end

#secretString (readonly)

API Secret.

Returns:

  • (String)


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

def secret
  @secret
end

#websitesResource (readonly)

Websites resource.

Returns:



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

def websites
  @websites
end

Instance Method Details

#accountObject



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

def 
  get("/account") do |response|
    Account.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



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.

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.



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.

Parameters:

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


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