class Censys::API

Constants

DOCUMENTS
HOST
URL
VERSION

Attributes

certificates[R]

Certificates resource.

@return [Resource]

id[R]

API UID.

@return [String]

ipv4[R]

IPv4 resource.

@return [Resource]

secret[R]

API Secret.

@return [String]

websites[R]

Websites resource.

@return [Resource]

Public Class Methods

new(id = ENV['CENSYS_ID'], secret = ENV['CENSYS_SECRET']) click to toggle source

Initializes the API.

@param [String] id

The API UID used for authentication.

@param [String] secret

The API secret used for authentication.

@raise [ArgumentError]

Either `id` or `secret` was `nil` or empty.

@see censys.io/account

Censys - My Account
# 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

Public Instance Methods

account() click to toggle source
# File lib/censys/api.rb, line 194
def account
  get("/account") do |response|
    Account.new(response)
  end
end
data(params = {}) click to toggle source
# 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) click to toggle source

Builds a report of aggregate data.

@param [:ipv4, :websites, :certificates] resource

@param [Hash] params

@option params [String] :query

(**Required**) The query to perform.

@option params [String] :field

(**Required**) The field to aggregate.

@option params [Fixnum] :buckets

Optional maximum number of values to be returned.

@option params

# 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
view(resource, id) click to toggle source

Requests the document of the given type.

@param [:ipv4, :websites, :certificates] resource

@param [String] id

@api private

# 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

Private Instance Methods

get(path, &block) click to toggle source

Creates a new HTTP GET request.

@param [String] path

@see request

# File lib/censys/api.rb, line 273
def get(path, &block)
  get = Net::HTTP::Get.new(url_for(path))
  get.basic_auth @id, @secret

  request(get, &block)
end
https_options() click to toggle source

Return HTTPS options

@return [Hash]

# File lib/censys/api.rb, line 220
def https_options
  if proxy = ENV["HTTPS_PROXY"]
    uri = URI(proxy)
    {
      proxy_address:  uri.hostname,
      proxy_port:     uri.port,
      proxy_from_env: false,
      use_ssl: true
    }
  else
    { use_ssl: true }
  end
end
post(path, json, &block) click to toggle source

Creates a new HTTP POST request.

@param [String] path

@param [#to_json] json

@see request

# File lib/censys/api.rb, line 289
def post(path, json, &block)
  post = Net::HTTP::Post.new(url_for(path))
  post.basic_auth @id, @secret
  post.content_type = 'application/json'
  post.body = json.to_json

  request(post, &block)
end
request(req) { |parse| ... } click to toggle source

Sends the HTTP request and handles the response.

@param [Net::HTTP::Get, Net::HTTP::Post] req

The prepared request to send.

@yield [json]

The given block will be passed the parsed JSON.

@yieldparam [Hash{String => Object}] json

The parsed JSON.

@raise [NotFound, RateLimited, InternalServerError, ResponseError]

If an error response is returned, the appropriate exception will be
raised.
# File lib/censys/api.rb, line 250
def request(req)
  Net::HTTP.start(HOST, 443, https_options) do |http|
    response = http.request(req)

    case response.code
    when '200' then yield JSON.parse(response.body)
    when '302' then raise(AuthenticationError, response.body)
    when '404' then raise(NotFound, "#{req.uri} not found")
    when '429' then raise(RateLimited, "rate limit exceeded")
    when '500' then raise(InternalServerError, response.body)
    else
      raise(ResponseError, "unsupported response code returned: #{response.code}")
    end
  end
end
url_for(path) click to toggle source

Returns a URL for the API sub-path.

@param [String] path

Path relative to `/api/v1`.

@return [URI::HTTPS]

Fully qualified URI.
# File lib/censys/api.rb, line 211
def url_for(path)
  URI(URL + path)
end
validate_index!(index) click to toggle source
# File lib/censys/api.rb, line 298
def validate_index!(index)
  raise(ArgumentError, "unsupported index type: #{index}") unless INDEXES.include?(index)
end