censu 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dc032c148fcfd0d25166894346ef57abb771edba
+  data.tar.gz: 7bc3d93c58883260e0eb274f9104b505ea99156a
+SHA512:
+  metadata.gz: a7283ce3bb2407fd4e85874432139a2742d4d052b2d2db8674cbd23ad208cd43f67ff883d3c4339caccba23787aa721c59e2cb007622707db568916fc84879f7
+  data.tar.gz: 5c8011da8618be9bd7cc7e5f7ababd13f811c00fe896de01b2ba34924431ea42e07a3f80c4827e3e8becb0a930b35a853ce931ac7f164f66b7250eab4b66f3f4

data/.codeclimate.yml

@@ -0,0 +1,13 @@
+version: "2"
+prepare:
+  fetch:
+    - url: "https://raw.githubusercontent.com/janlelis/relaxed.ruby.style/master/.rubocop.yml"
+      path: "alternate-rubocop-path.yml"
+plugins:
+  rubocop:
+    enabled: true
+    config:
+      file: "alternate-rubocop-path.yml"
+exclude_patterns:
+  - "spec/"
+  - "!spec/support/helpers"

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.md
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle
+/.env
+/.yardoc/
+/Gemfile.lock
+/doc/
+/pkg/
+/vendor/cache/*.gem
+/vendor/bundle

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.rubocop.yml

@@ -0,0 +1,166 @@
+# Relaxed.Ruby.Style
+## Version 2.1
+
+Style/Alias:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylealias
+
+Style/AsciiComments:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styleasciicomments
+
+Style/BeginBlock:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylebeginblock
+
+Style/BlockDelimiters:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styleblockdelimiters
+
+Style/CommentAnnotation:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylecommentannotation
+
+Style/Documentation:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styledocumentation
+
+Layout/DotPosition:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#layoutdotposition
+
+Style/DoubleNegation:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styledoublenegation
+
+Style/EndBlock:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styleendblock
+
+Style/FormatString:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styleformatstring
+
+Style/IfUnlessModifier:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styleifunlessmodifier
+
+Style/Lambda:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylelambda
+
+Style/ModuleFunction:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylemodulefunction
+
+Style/MultilineBlockChain:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylemultilineblockchain
+
+Style/NegatedIf:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylenegatedif
+
+Style/NegatedWhile:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylenegatedwhile
+
+Style/ParallelAssignment:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styleparallelassignment
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylepercentliteraldelimiters
+
+Style/PerlBackrefs:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styleperlbackrefs
+
+Style/Semicolon:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesemicolon
+
+Style/SignalException:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesignalexception
+
+Style/SingleLineBlockParams:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesinglelineblockparams
+
+Style/SingleLineMethods:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesinglelinemethods
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#layoutspacebeforeblockbraces
+
+Layout/SpaceInsideParens:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#layoutspaceinsideparens
+
+Style/SpecialGlobalVars:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylespecialglobalvars
+
+Style/StringLiterals:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylestringliterals
+
+Style/TrailingCommaInArguments:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styletrailingcommainarguments
+
+Style/TrailingCommaInLiteral:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#styletrailingcommainliteral
+
+Style/WhileUntilModifier:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylewhileuntilmodifier
+
+Style/WordArray:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylewordarray
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#lintambiguousregexpliteral
+
+Lint/AssignmentInCondition:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#lintassignmentincondition
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+
+cache:
+  bundler: true
+
+rvm:
+  - 2.4
+
+script: bundle exec rake test
+
+gemfile:
+- Gemfile

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "CenSys Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,4 @@
+### 0.1.0 / 2016-02-18
+
+* Initial release:
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2017 ninoseki(Manabu Niseki)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# Censu
+
+[![Build Status](https://travis-ci.org/ninoseki/censu.svg?branch=master)](https://travis-ci.org/ninoseki/censu)
+[![Maintainability](https://api.codeclimate.com/v1/badges/39e77d63ce6a7d89b4dc/maintainability)](https://codeclimate.com/github/ninoseki/censu/maintainability)
+
+* [Homepage](https://github.com/ninoseki/censu)
+* [Issues](https://github.com/ninoseki/censu/issues)
+
+## Description
+
+Ruby API client to the [Censys] internet search engine.
+
+## Features
+
+## Examples
+
+Initialize the API:
+
+    require 'censys'
+    api = Censys::API.new(uid,secret)
+
+Initialize the API using `$CENSYS_ID` and `$CENSYS_SECRET` environment
+variables:
+
+    api = Censys::API.new
+
+Search for IPv4 addresses:
+
+    response = api.ipv4.search(query: 'dropbox.com')
+
+Search for Websites:
+
+    response = api.websites.search(query: 'dropbox.com')
+
+Search for Certificates:
+
+    response = api.certificates.search(query: 'dropbox.com')
+
+Enumerate through search results:
+
+    response.each_page do |page|
+      puts ">>> Page ##{page.metadata.page} / #{page.metadata.pages} ..."
+
+      page.each do |result|
+        puts result
+      end
+    end
+
+Generate aggregate reports:
+
+    response = api.websites.report(
+      query: '80.http.get.headers.server: Apache',
+      field: 'location.country_code',
+      buckets: 100
+    )
+
+    response.each do |country,count|
+      puts "#{country}: #{count}"
+    end
+
+## Requirements
+
+* [ruby] >= 2.0
+
+## Install
+
+    $ gem install censu
+
+## License
+
+See {file:LICENSE.txt} for details.
+
+Note:: This gem is forked from [trailofbits/censys-ruby](https://github.com/trailofbits/censys-ruby).
+
+[ruby]: http://www.ruby-lang.org/
+[Cens:qys]: https://censys.io/

data/Rakefile

@@ -0,0 +1,21 @@
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+rescue LoadError => e
+  abort e.message
+end
+
+require 'rake'
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task test: :spec
+task default: :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+task doc: :yard

data/censys.gemspec

@@ -0,0 +1,28 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'censys/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "censu"
+  gem.version       = Censys::VERSION
+  gem.summary       = "API client for censys.io"
+  gem.description   = "Ruby API client for the Censys Internet search engine."
+  gem.license       = "MIT"
+  gem.authors       = ["Manabu Niseki"]
+  gem.email         = "manabu.niseki@gmail.com"
+  gem.homepage      = "https://github.com/ninoseki/censu"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_development_dependency 'bundler', '~> 1.16'
+  gem.add_development_dependency 'dotenv', '~> 2.2'
+  gem.add_development_dependency 'rake', '~> 12.3'
+  gem.add_development_dependency 'rspec', '~> 3.7'
+  gem.add_development_dependency 'rubygems-tasks', '~> 0.2'
+  gem.add_development_dependency 'vcr', '~> 4.0'
+  gem.add_development_dependency 'webmock', '~> 3.1'
+  gem.add_development_dependency 'yard', '~> 0.9'
+end

data/lib/censys.rb

@@ -0,0 +1,2 @@
+require 'censys/api'
+require 'censys/version'

data/lib/censys/api.rb

@@ -0,0 +1,254 @@
+require 'censys/exceptions'
+require 'censys/search'
+require 'censys/report'
+require 'censys/ipv4'
+require 'censys/website'
+require 'censys/certificate'
+
+require 'net/https'
+require 'json'
+
+module Censys
+  class API
+    VERSION = 1
+    HOST = 'www.censys.io'.freeze
+    URL = "https://#{HOST}/api/v#{VERSION}".freeze
+
+    class Resource
+      def initialize(type, api)
+        @type = type
+        @api  = api
+      end
+
+      #
+      # @see API#search
+      #
+      def search(params = {})
+        @api.search(@type, params)
+      end
+
+      #
+      # @see API#view
+      #
+      def [](id)
+        @api.view(@type, id)
+      end
+
+      #
+      # @see API#report
+      #
+      def report(params)
+        @api.report(@type, params)
+      end
+    end
+
+    # API UID.
+    #
+    # @return [String]
+    attr_reader :id
+
+    # API Secret.
+    #
+    # @return [String]
+    attr_reader :secret
+
+    # IPv4 resource.
+    #
+    # @return [Resource]
+    attr_reader :ipv4
+
+    # Websites resource.
+    #
+    # @return [Resource]
+    attr_reader :websites
+
+    # Certificates resource.
+    #
+    # @return [Resource]
+    attr_reader :certificates
+
+    #
+    # 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 https://censys.io/account
+    #   Censys - My Account
+    #
+    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
+
+    #
+    # Performs a search.
+    #
+    # @param [:ipv4, :websites, :certificates] resource
+    #
+    # @param [Hash] params
+    #   Optional search params.
+    #
+    # @option params [String] :query
+    #   The query to perform.
+    #
+    # @option params [Fixnum] :page
+    #   Optional page number to request.
+    #
+    # @option params [Array<String>] :fields
+    #   Optional list of fields to include in the results.
+    #
+    # @api private
+    #
+    def search(resource, params = {})
+      post("/search/#{resource}", params) do |json|
+        Search::Response.new(self, resource, params, json)
+      end
+    end
+
+    DOCUMENTS = {
+      ipv4:         IPv4,
+      websites:     Website,
+      certificates: Certificate
+    }.freeze
+
+    #
+    # Requests the document of the given type.
+    #
+    # @param [:ipv4, :websites, :certificates] resource
+    #
+    # @param [String] id
+    #
+    # @api private
+    #
+    def view(resource, id)
+      document_class = DOCUMENTS.fetch(resource)
+
+      get("/view/#{resource}/#{id}") do |attributes|
+        document_class.new(attributes)
+      end
+    end
+
+    #
+    # 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
+    #
+    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
+
+    private
+
+    #
+    # Returns a URL for the API sub-path.
+    #
+    # @param [String] path
+    #   Path relative to `/api/v1`.
+    #
+    # @return [URI::HTTPS]
+    #   Fully qualified URI.
+    #
+    def url_for(path)
+      URI(URL + path)
+    end
+
+    #
+    # 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.
+    #
+    def request(req)
+      Net::HTTP.start(HOST, 443, use_ssl: true) 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
+
+    #
+    # Creates a new HTTP GET request.
+    #
+    # @param [String] path
+    #
+    # @see #request
+    #
+    def get(path, &block)
+      get = Net::HTTP::Get.new(url_for(path))
+      get.basic_auth @id, @secret
+
+      request(get, &block)
+    end
+
+    #
+    # Creates a new HTTP POST request.
+    #
+    # @param [String] path
+    #
+    # @param [#to_json] json
+    #
+    # @see #request
+    #
+    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
+
+    def validate_index!(index)
+      raise(ArgumentError, "unsupported index type: #{index}") unless INDEXES.include?(index)
+    end
+  end
+end