securitytrails 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a98a7e435666d8e24c6fc43e321f0c830666b5bad72624a889aa9127ed05002
-  data.tar.gz: 208fa1488c86ad91b7a8985c44bb5bf0641c0052612b2e0af112590981025f5b
+  metadata.gz: a7357b61e8302a39f839c4cbc3447cf23569bd60ff26f51171e135fd87519936
+  data.tar.gz: 0ec95a9dce876ad1c16ab72b79e232476ab9510e2b5ec9df8fb6afa5a5aff401
 SHA512:
-  metadata.gz: 5d0716e4993ce48071046aa9fb0758a9e7dde0a5863926f71d39e637ffc960625a099946fcb87f76c8f8d3f3d0b0f1a7d63943ad3a7f94b4ef7be9b9ceb42784
-  data.tar.gz: 6825a21d343225b5d07f88d084de0d62afad3e5d78c2c1d9721406c02723eac9d11a975048125ad9f68ce91ffd7bce11651963d841311e35d5d0b1db31371b7a
+  metadata.gz: 0ac1a84b08a3e2c2a5288295e40f019af446d96306f8b86dc9076381f4c3acdd8d4d7459d46b65df38ce862442d69da1576454b2b6850f11658972dcc9cfce91
+  data.tar.gz: 80dd0c1733bbc6fc7f93b134468a226cecad5ac6d03fbffb090fd9aecc404fdb4b9e11e9131efed7dfef27053ad7a8445cb287bb061aa67fc0bcd2824b79b0e5

data/README.md

@@ -33,6 +33,11 @@ api = SecurityTrails::API.new
 # or you can pass your API key as an argument
 api = SecurityTrails::API.new(YOUR_API_KEY)
 
+# General
+# https://docs.securitytrails.com/reference#general
+api.ping
+api.usage
+
 # Domain details
 # https://docs.securitytrails.com/v1.0/reference#domains
 api.domain.get_by_hostname("github.com")
@@ -55,8 +60,8 @@ api.domains.stats(
 
 # History
 # https://docs.securitytrails.com/v1.0/reference#history
-api.history.get_dns_history("github.com", "a")
-api.history.get_all_dns_history("github.com", "a")
+api.history.get_dns_history("github.com", type: "a")
+api.history.get_all_dns_history("github.com", type: "a")
 api.history.get_whois_history("github.com")
 
 # IPs
@@ -67,18 +72,8 @@ api.ips.stats("ptr_part = 'amazon.com'")
 
 # Feeds
 # https://docs.securitytrails.com/v1.0/reference#feeds
-api.feeds.domain("new")
-api.feeds.domain("new", tld: "jp")
-```
-
-All the API response (JSON / Hash) is wrapped by [OpenStruct](https://github.com/ruby/ostruct).
-
-It means you can access to a response through a property-like syntax.
-
-```ruby
-res = api.domain.get_by_hostname("github.com")
-puts res.hostname # => "github.com"
-puts res.current_dns.a.first_seen # => "2018-09-12"
+api.feeds.domains("new")
+api.feeds.domains("new", tld: "jp")
 ```
 
 ## Contributing

data/lib/securitytrails.rb

@@ -5,9 +5,10 @@ require "securitytrails/version"
 require "securitytrails/utility"
 
 require "securitytrails/api"
-require "securitytrails/response"
 require "securitytrails/client"
 
+require "securitytrails/clients/general"
+
 require "securitytrails/clients/domain"
 require "securitytrails/clients/domains"
 require "securitytrails/clients/feeds"

data/lib/securitytrails/api.rb

@@ -1,21 +1,75 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module SecurityTrails
   class API
-    attr_reader :domain
-    attr_reader :domains
-    attr_reader :history
-    attr_reader :ips
-    attr_reader :feeds
+    extend Forwardable
+
+    attr_reader :api_key
 
     def initialize(api_key = ENV["SECURITYTRAILS_API_KEY"])
-      raise(ArgumentError, "'api_key' argument is required") unless api_key
+      @api_key = api_key
+      raise ArgumentError, "'api_key' argument is required" unless api_key
+    end
+
+    #
+    # General API client
+    #
+    # @return [SecurityTrails::Clients::General]
+    #
+    def general
+      @general ||= Clients::General.new(api_key)
+    end
+
+    %w(ping usage scroll).each do |delegate_method|
+      sym = delegate_method.to_sym
+      def_delegator :general, sym, sym
+    end
+
+    #
+    # Domain API client
+    #
+    # @return [SecurityTrails::Clients::Domain]
+    #
+    def domain
+      @domain ||= Clients::Domain.new(api_key)
+    end
+
+    #
+    # Domains API client
+    #
+    # @return [SecurityTrails::Clients::Domains]
+    #
+    def domains
+      @domains ||= Clients::Domains.new(api_key)
+    end
+
+    #
+    # History API client
+    #
+    # @return [SecurityTrails::Clients::History]
+    #
+    def history
+      @history ||= Clients::History.new(api_key)
+    end
+
+    #
+    # IPs API client
+    #
+    # @return [SecurityTrails::Clients::IPs]
+    #
+    def ips
+      @ips ||= Clients::IPs.new(api_key)
+    end
 
-      @domain   = Clients::Domain.new(api_key)
-      @domains  = Clients::Domains.new(api_key)
-      @history  = Clients::History.new(api_key)
-      @ips      = Clients::IPs.new(api_key)
-      @feeds    = Clients::Feeds.new(api_key)
+    #
+    # Feed API client
+    #
+    # @return [SecurityTrails::Clients::Feeds]
+    #
+    def feeds
+      @feeds ||= Clients::Feeds.new(api_key)
     end
   end
 end

data/lib/securitytrails/client.rb

@@ -42,7 +42,7 @@ module SecurityTrails
         raise(Error, "unsupported response code returned: #{response.code}") unless response.code == "200"
 
         if response["Content-Type"].to_s.include? "application/json"
-          yield JSON.parse(response.body, object_class: Response)
+          yield JSON.parse(response.body)
         else
           yield response.body
         end

data/lib/securitytrails/clients/domain.rb

@@ -3,22 +3,67 @@
 module SecurityTrails
   module Clients
     class Domain < Client
+      #
+      # Returns the current data about the given domain. In addition to the current data, you also get the current statistics associated with a particular record. For example, for a records you'll get how many other domains have the same IP.
+      #
+      # @see https://docs.securitytrails.com/reference#get-domain
+      #
+      # @param [String] hostname
+      #
+      # @return [Hash]
+      #
       def get_by_hostname(hostname)
         get("/domain/#{hostname}") { |json| json }
       end
 
+      #
+      # Returns subdomains for a given hostname
+      #
+      # @see https://docs.securitytrails.com/reference#list-subdomains
+      #
+      # @param [String] hostname
+      #
+      # @return [Hash]
+      #
       def get_subdomains(hostname)
         get("/domain/#{hostname}/subdomains") { |json| json }
       end
 
+      #
+      # Returns tags for a given hostname
+      #
+      # @see https://docs.securitytrails.com/reference#list-tags
+      #
+      # @param [String] hostname
+      #
+      # @return [Hash]
+      #
       def get_tags(hostname)
         get("/domain/#{hostname}/tags") { |json| json }
       end
 
+      #
+      # Find all domains that are related to a domain you input
+      #
+      # @see https://docs.securitytrails.com/reference#find-associated-domains
+      #
+      # @param [String] hostname
+      #
+      # @return [Hash]
+      #
       def get_associated_domains(hostname)
         get("/domain/#{hostname}/associated") { |json| json }
       end
 
+      #
+      # Returns the current WHOIS data about a given domain with the stats merged together
+      #
+      # @see https://docs.securitytrails.com/reference#get-whois
+      #
+      # @param [String] hostname
+      #
+      # @return [Hash]
+      #
       def get_whois(hostname)
         get("/domain/#{hostname}/whois") { |json| json }
       end

data/lib/securitytrails/clients/domains.rb

@@ -3,11 +3,29 @@
 module SecurityTrails
   module Clients
     class Domains < Client
-      def search(params)
+      #
+      # Filter and search specific records using this endpoint.
+      #
+      # @see https://docs.securitytrails.com/reference#domain-search
+      #
+      # @param [Hash] **params
+      #
+      # @return [Hash]
+      #
+      def search(**params)
         post("/domains/list", params) { |json| json }
       end
 
-      def stats(params)
+      #
+      # Search statistics
+      #
+      # @see https://docs.securitytrails.com/reference#search-count
+      #
+      # @param [Hash] **params
+      #
+      # @return [Hash]
+      #
+      def stats(**params)
         post("/domains/stats", params) { |json| json }
       end
     end

data/lib/securitytrails/clients/feeds.rb

@@ -3,6 +3,19 @@
 module SecurityTrails
   module Clients
     class Feeds < Client
+      #
+      # Fetch zone files including authoritative nameservers with ease
+      #
+      # @see https://docs.securitytrails.com/reference#domains-1
+      #
+      # @param [String] type valid values are "all", "dropped", "new" or "registered"
+      # @param [String, nil] filter valid values are "cctld" and "gtld"
+      # @param [String, nil] tld Can be used to only return domains of a specific tld, such as "com"
+      # @param [Boolean, nil] ns show nameservers in the list
+      # @param [String, nil] date Date to fetch data for, format YYYY-MM-DD,
+      #
+      # @return [<Type>] <description>
+      #
       def domains(type, filter: nil, tld: nil, ns: nil, date: nil)
         params = { filter: filter, tld: tld, ns: ns, date: date }.compact
 

data/lib/securitytrails/clients/general.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SecurityTrails
+  module Clients
+    class General < Client
+      #
+      # You can use this simple endpoint to test your authentication and access to the SecurityTrails API.
+      #
+      # @see https://docs.securitytrails.com/reference#ping
+      #
+      # @return [Hash]
+      #
+      def ping
+        get("/ping") { |json| json }
+      end
+
+      #
+      # Usage
+      #
+      # @see https://docs.securitytrails.com/reference#usage
+      #
+      # @return [Hash]
+      #
+      def usage
+        get("/account/usage") { |json| json }
+      end
+
+      #
+      # A fast and easy way to fetch many results. Currently only available for the DSL API endpoints.
+      #
+      # @see https://docs.securitytrails.com/reference#scroll
+      #
+      # @param [String] The scroll_id returned in the scroll request.
+      #
+      # @return [Hash]
+      #
+      def scroll(scroll_id)
+        get("/scroll/#{scroll_id}") { |json| json }
+      end
+    end
+  end
+end

data/lib/securitytrails/clients/history.rb

@@ -3,21 +3,42 @@
 module SecurityTrails
   module Clients
     class History < Client
-      def get_dns_history(hostname, type, page = 1)
+      #
+      # Lists out specific historical information about the given hostname parameter
+      #
+      # @see https://docs.securitytrails.com/reference#dns-history-by-record-type
+      #
+      # @param [String] hostname
+      # @param [String] type allowed values: a, aaaa, mx, ns, soa or txt
+      # @param [Integer] page The page of the returned results
+      #
+      # @return [Hash]
+      #
+      def get_dns_history(hostname, type:, page: 1)
         raise ArgumentError, "The API currently supports a, aaaa, mx, ns, soa and txt records." unless valid_type?(type)
 
         get("/history/#{hostname}/dns/#{type.downcase}", page: page) { |json| json }
       end
 
-      def get_all_dns_history(hostname, type)
-        first_page = get_dns_history(hostname, type, 1)
+      #
+      # Lists out specific historical information about the given hostname parameter with auto paging
+      #
+      # @see https://docs.securitytrails.com/reference#dns-history-by-record-type
+      #
+      # @param [String] hostname
+      # @param [String] type allowed values: a, aaaa, mx, ns, soa or txt
+      #
+      # @return [Hash]
+      #
+      def get_all_dns_history(hostname, type:)
+        first_page = get_dns_history(hostname, type: type, page: 1)
         pages = first_page["pages"].to_i
 
         records = []
         records << first_page["records"]
 
         (2..pages).each do |page_idx|
-          next_page = get_dns_history(hostname, type, page_idx)
+          next_page = get_dns_history(hostname, type: type, page: page_idx)
           records << next_page["records"]
         end
 
@@ -25,6 +46,15 @@ module SecurityTrails
         first_page
       end
 
+      #
+      # Returns historical WHOIS information about the given domain
+      #
+      # @see https://docs.securitytrails.com/reference#whois-history-by-domain
+      #
+      # @param [String] hostname
+      #
+      # @return [Hash]
+      #
       def get_whois_history(hostname)
         get("/history/#{hostname}/whois/") { |json| json }
       end

data/lib/securitytrails/clients/ips.rb

@@ -3,14 +3,41 @@
 module SecurityTrails
   module Clients
     class IPs < Client
+      #
+      # Returns the neighbors in any given IP level range and essentially allows you to explore closeby IP addresses.
+      #
+      # @see https://docs.securitytrails.com/reference#explore-ips
+      #
+      # @param [String] ipaddress Starting IP address (optionally with CIDR subnet mask)
+      #
+      # @return [Hash]
+      #
       def explore(ipaddress)
         get("/ips/nearby/#{ipaddress}") { |json| json }
       end
 
+      #
+      # Search IPs (DSL)
+      #
+      # @see https://docs.securitytrails.com/reference#search-ips-dsl
+      #
+      # @param [String] query The DSL query you want to run against the IPs database.
+      #
+      # @return [Hash]
+      #
       def search(query)
         post("/ips/list", query: query) { |json| json }
       end
 
+      #
+      # IP Search statistics
+      #
+      # @see https://docs.securitytrails.com/reference#ip-search-statistics
+      #
+      # @param [String] query
+      #
+      # @return [Hash]
+      #
       def stats(query)
         post("/ips/stats", query: query) { |json| json }
       end

data/lib/securitytrails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SecurityTrails
-  VERSION = "0.2.0"
+  VERSION = "1.0.0"
 end

data/securitytrails.gemspec

@@ -26,9 +26,8 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "coveralls", "~> 0.8"
-  spec.add_development_dependency "dotenv", "~> 2.7"
-  spec.add_development_dependency "rake", "~> 12.3"
-  spec.add_development_dependency "rspec", "~> 3.8"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.9"
   spec.add_development_dependency "vcr", "~> 5.0"
-  spec.add_development_dependency "webmock", "~> 3.6"
+  spec.add_development_dependency "webmock", "~> 3.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: securitytrails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Manabu Niseki
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-06-21 00:00:00.000000000 Z
+date: 2019-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,48 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
-- !ruby/object:Gem::Dependency
-  name: dotenv
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '3.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '3.7'
 description: SecurityTrails API wrapper for Ruby
 email:
 - manabu.niseki@gmail.com
@@ -119,7 +105,6 @@ files:
 - ".rspec"
 - ".travis.yml"
 - Gemfile
-- LICENSE
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -131,9 +116,9 @@ files:
 - lib/securitytrails/clients/domain.rb
 - lib/securitytrails/clients/domains.rb
 - lib/securitytrails/clients/feeds.rb
+- lib/securitytrails/clients/general.rb
 - lib/securitytrails/clients/history.rb
 - lib/securitytrails/clients/ips.rb
-- lib/securitytrails/response.rb
 - lib/securitytrails/utility.rb
 - lib/securitytrails/version.rb
 - securitytrails.gemspec
@@ -156,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: SecurityTrails API wrapper for Ruby

data/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2018 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/lib/securitytrails/response.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-require "ostruct"
-
-module SecurityTrails
-  class Response < OpenStruct
-    def openstruct_to_hash(object, hash = {})
-      return object unless object.respond_to?(:each_pair)
-
-      object.each_pair do |key, value|
-        hash[key] = case value
-                    when OpenStruct then openstruct_to_hash(value)
-                    when Array then value.map { |v| openstruct_to_hash(v) }
-                    else value
-                    end
-      end
-      hash
-    end
-
-    def to_h
-      openstruct_to_hash(self)
-    end
-  end
-end