Class: Mihari::Clients::Censys

Inherits:
Base
  • Object
show all
Defined in:
lib/mihari/clients/censys.rb

Overview

Censys API client

Instance Attribute Summary

Attributes inherited from Base

#base_url, #headers, #pagination_interval, #timeout

Instance Method Summary collapse

Constructor Details

#initialize(base_url = "https://search.censys.io", id:, secret:, headers: {}, pagination_interval: Mihari.config.pagination_interval, timeout: nil) ⇒ Censys

Returns a new instance of Censys.

Parameters:

  • base_url (String) (defaults to: "https://search.censys.io")
  • id (String, nil)
  • secret (String, nil)
  • headers (Hash) (defaults to: {})
  • pagination_interval (Integer) (defaults to: Mihari.config.pagination_interval)
  • timeout (Integer, nil) (defaults to: nil)

Raises:

  • (ArgumentError) 


19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/mihari/clients/censys.rb', line 19

def initialize(
  base_url = "https://search.censys.io",
  id:,
  secret:,
  headers: {},
  pagination_interval: Mihari.config.pagination_interval,
  timeout: nil
)
  raise(ArgumentError, "id is required") if id.nil?
  raise(ArgumentError, "secret is required") if secret.nil?

  headers["authorization"] = "Basic #{Base64.strict_encode64("#{id}:#{secret}")}"

  super(base_url, headers:, pagination_interval:, timeout:)
end

Instance Method Details

#search(query, per_page: nil, cursor: nil) ⇒ Mihari::Structs::Censys::Response

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.

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

    the number of results to be returned for each page.

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

    the cursor of the desired result set.

Returns:



47
48
49
50
 
# File 'lib/mihari/clients/censys.rb', line 47

def search(query, per_page: nil, cursor: nil)
  params = {q: query, per_page:, cursor:}.compact
  Structs::Censys::Response.from_dynamic! get_json("/api/v2/hosts/search", params:)
end

#search_with_pagination(query, per_page: nil, pagination_limit: Mihari.config.pagination_limit) ⇒ Enumerable<Mihari::Structs::Censys::Response>

Parameters:

  • query (String)
  • per_page (Integer, nil) (defaults to: nil)
  • pagination_limit (Integer) (defaults to: Mihari.config.pagination_limit)

Returns:



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/mihari/clients/censys.rb', line 59

def search_with_pagination(query, per_page: nil, pagination_limit: Mihari.config.pagination_limit)
  cursor = nil

  Enumerator.new do |y|
    pagination_limit.times do
      res = search(query, per_page:, cursor:)

      y.yield res

      cursor = res.result.links.next
      # NOTE: Censys's search API is unstable recently
      # it may returns empty links or empty string cursors
      # - Empty links: "links": {}
      # - Empty cursors: "links": { "next": "", "prev": "" }
      # So it needs to check both cases
      break if cursor.nil? || cursor.empty?

      sleep_pagination_interval
    end
  end
end