Class: Censys::API

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

Overview

Censys Search v2 API wrapper

Constant Summary collapse

VERSION = 
2
HOST = 
"search.censys.io"
URL = 
"https://#{HOST}/api/v#{VERSION}/hosts"

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:



30
31
32
33
34
35
36
 
# File 'lib/censys/api.rb', line 30

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 = id
  @secret = secret
end

Instance Method Details

#aggregate(query, field, num_buckets: nil) ⇒ Hash

Aggregate current index.

Creates a report on the breakdown of the values of a field in a result set. For more details, see our documentation: search.censys.io/api/v2/docs

Parameters:

  • query (String) —

    the query to be executed.

  • field (String) —

    the field you are running a breakdown on.

  • num_buckets (Integer, nil) (defaults to: nil) —

    the maximum number of values. Defaults to 50.

Returns:

  • (Hash) 


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

def aggregate(query, field, num_buckets: nil)
  params = { q: query, field: field, num_buckets: num_buckets }.compact
  get("/aggregate", params) do |json|
    json
  end
end

#search(query, per_page: nil, cursor: nil) ⇒ Hash

Search current index.

Searches the given index for all records that match the given query. For more details, see our documentation: search.censys.io/api/v2/docs

Parameters:

  • query (String) —

    the query to be executed.

Returns:

  • (Hash) 


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

def search(query, per_page: nil, cursor: nil)
  params = { q: query, per_page: per_page, cursor: cursor }.compact
  get("/search", params) do |json|
    json
  end
end

#view(document_id, at_time: nil) ⇒ Hash

View document from current index.

View the current structured data we have on a specific document. For more details, see our documentation: search.censys.io/api/v2/docs

Parameters:

  • document_id (String) —

    the ID of the document you are requesting.

  • at_time (String, Time, nil) (defaults to: nil) —

    Fetches a document at a given point in time.

Returns:

  • (Hash) 


49
50
51
52
53
54
55
56
 
# File 'lib/censys/api.rb', line 49

def view(document_id, at_time: nil)
  at_time = at_time.strftime("%Y-%m-%dT%H:%M:%S.%6NZ") if at_time.is_a?(Time)
  params = { at_time: at_time }.compact

  get("/#{document_id}", params) do |json|
    json
  end
end