backscatterio 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5508c62631c77d734b28d680bbb89c49a56eda99
-  data.tar.gz: ce8ae7f744ba3b595c591a7fc3bc8ebcd283c9f0
+  metadata.gz: fe9d8b796f4fd06e225d8819340b518b86356c39
+  data.tar.gz: 6a463a6f64fc97f3cefea14525da0531f017caf1
 SHA512:
-  metadata.gz: f78082fa1777ec84a86bf497876bc2d79c633682129588ae287bff6c3e1634ffb012bfe0a77e1718d6ae10524954c21c598717f9871f27c104d5f6945f4cca69
-  data.tar.gz: c2f87dc57d467364a7192f6af912da489ab5cc6e63d42f2e01383b8491d050b0d4d3522e15407e8add4db4ec68d831cefa451b42d295e1dbb3bb0d0f88ee3834
+  metadata.gz: e6bb446c2769eff38953008851c26e6adfad0707c54c1cb56718704311861775d973cee02af9d404bf28069b9de459868801ebd7ae7267cda88206afea4342b0
+  data.tar.gz: f633883a98397bc5cf335f8a51d7b0262bdf77a03a833ec88aef27d8ccff1865f3afa0f71e4b1522a1227499be3456a5b7cb5af34a7bbf3434d81cbe71985dba

data/backscatterio.gemspec

@@ -40,6 +40,6 @@ Gem::Specification.new do |s|
 
   s.files         = `find *`.split("\n").uniq.sort.select { |f| !f.empty? }
   s.test_files    = `find spec/*`.split("\n")
-  s.executables   = []
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
   s.require_paths = ["lib"]
 end

data/bin/backscatterio-rb

@@ -0,0 +1,253 @@
+#!/usr/bin/env ruby
+
+require 'backscatterio'
+require 'getoptlong'
+require 'json'
+require 'ipaddr'
+require 'fileutils'
+
+module BackscatterIO
+  class CLInterface
+    def self.detect_query(query)
+      begin
+        if query.index('/') and IPAddr.new(query[0, query.index('/')])
+          return 'network'
+        elsif IPAddr.new query
+          return 'ip'
+        end
+      rescue
+        if query =~ /^[A-Z]{2}$/i
+          return 'country'
+        elsif query =~ /^AS\d+$/i
+          return 'asn'
+        elsif query =~ /^(TCP|UDP)\d+$/i or [21, 22, 23, 25, 53, 80, 81, 113, 139, 443, 445, 1433, 5222, 5900, 8080].index(query.to_i)
+          return 'port'
+        else
+          return 'asn'
+        end
+      end
+    end
+    
+    def self.parse_command_line(args)
+      origARGV = ARGV.dup
+      ARGV.replace(args)
+      opts = GetoptLong.new(
+        [ '--api-key', '-k', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--query', '-q', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--type', '-t', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--format', '-f', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--scope', '-z', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--count', '-c', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--config', '-a', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--help', '-h', GetoptLong::NO_ARGUMENT ],
+        [ '--verbose', '-v', GetoptLong::NO_ARGUMENT ]
+      )
+
+      options = {
+        :command => 'trends',
+        :api_key => nil,
+        :query => nil,
+        :type => nil,
+        :format => 'json',
+        :scope => '7d',
+        :count => nil,
+        :help => false,
+        :verbose => false,
+        :version => 'v0',
+        :config_file => "#{ENV['HOME']}/.config/backscatter/config.json"
+      }
+
+      opts.each do |opt, arg|
+        case opt
+        when '--api-key'
+          options[:api_key] = arg
+        when '--query'
+          options[:query] = arg
+        when '--type'
+          options[:type] = arg
+        when '--format'
+          options[:format] = arg
+        when '--scope'
+          options[:scope] = arg
+        when '--count'
+          options[:count] = arg
+        when '--config'
+          options[:config_file] = arg
+        when '--help'
+          options[:help] = true
+        when '--verbose'
+          options[:verbose] = true
+        else
+          raise "Unknown option #{opt}"
+        end
+      end
+      
+      if options[:config_file]
+        if File.exist?(options[:config_file])
+          data = JSON.parse(open(options[:config_file]).read)
+          options[:api_key] = data["api_key"]
+          options[:version] = data["version"]
+        end
+      end
+
+      [options, args]
+    end
+    
+    def self.error(message)
+      puts message
+      exit
+    end
+    
+    
+    def self.run(args)
+      options, items = parse_command_line(args)
+      if items[0]
+        options[:command] = items[0]
+      end
+      
+      if not options[:api_key]
+        error("An API key is required to use the Backscatter.io service.  Please specify one via -k or in a configuration file #{ENV['HOME']}/.config/backscatter/config.json")
+      end
+      
+      if options[:help]
+        usage
+        exit
+      end
+            
+      BackscatterIO.configure do |config|
+        # Configure API key authorization: ApiKeyAuth
+        config.api_key['X-API-KEY'] = options[:api_key]
+      end
+
+      client = BackscatterIO::Api.new
+      
+      case options[:command]
+      when 'observations'
+        if not options[:query]
+          error("-q <query_item> is a required parameter to the observations command")
+        end
+        options[:type] ||= detect_query(options[:query])
+        if not options[:type]
+          error "Could not determine the format of the query, please use the -t flag to specify the type"
+        end
+        results = client.observations(options[:type], options[:query], { "scope" => options[:scope] })
+      when 'trends'
+        options[:type] ||= 'ip'
+        results = client.trends(options[:type], { "scope" => options[:scope], "count" => options[:count] })
+      when 'enrich'
+        if not options[:query]
+          error "-q <query_item> is a required parameter to the enrich command"
+        end
+        options[:type] ||= detect_query(options[:query])
+        if not options[:type]
+          error "Could not determine the format of the query, please use the -t flag to specify the type"
+        end
+        case options[:type]
+        when 'ip'
+          results = client.enrich_ip(options[:query])
+        when 'network'
+          results = client.enrich_network(options[:query])
+        when 'asn'
+          results = client.enrich_asn(options[:query])
+        else
+          error "Enrichment is not available for #{options[:type]}"
+        end
+      when 'setup'
+        dirname = File.dirname(options[:config_file])
+        if not File.exist?(dirname)
+          FileUtils.mkdir_p(dirname)
+        end
+        fh = open(options[:config_file], 'w')
+        fh.write(JSON.pretty_generate({"version" => options[:version], "api_key" => options[:api_key]}))
+        fh.close
+        results = { "message" => "Configuration saved" }
+      else
+        error "Unknown command #{options[:command]}"
+      end
+      
+      if options[:format] == 'json'
+        return results.to_hash.to_json
+      else
+        return tabulate(results)
+      end
+    end
+    
+    def self.tabulate(results)
+      if not results.success
+        return "Unsuccessful"
+      end
+      
+      table = ""
+      
+      if results.query == nil or results.query.type == "top_x_query"
+        maxlen = 0
+        results.results.each do |k,v|
+          if k.length > maxlen
+            maxlen = k.length
+          end
+        end
+        maxlen += 1
+        results.results.keys.sort {|a,b| results.results[b] <=> results.results[a]}.each do |k|
+          table += "#{k.to_s.ljust(maxlen)}: #{results.results[k]}\n"
+        end
+      else
+        headers = {}
+        headers = {'observed' => 9, 'src_ip' => 7, 'protocol' => 9, 
+          'fragment_flags' => 15, 'id' => 3, 'dst_port' => 9, 'length' => 7, 'ttl' => 4, 'tos' => 4, 
+          'precedence' => 11, 'window' => 7}
+        results.results.observations.each do |item|
+          headers.each_key do |h|
+            vl = item.__send__(h).length + 1
+            if vl > headers[h]
+              headers[h] = vl
+            end
+          end
+        end
+        headers.each_key do |h|
+          table += "#{h.ljust(headers[h])}"
+        end
+        table += "\n"
+        results.results.observations.each do |item|
+          headers.each_key do |h|
+            table += "#{item.__send__(h).ljust(headers[h])}"
+          end
+          table += "\n"
+        end
+      end
+      table
+    end
+    
+    def self.usage
+      usage = <<EOD
+Usage: #{ARGV[0]} [setup|observations|trends|enrich] [options]
+  setup: Configure this client with your API key in order to run commands without issue. Find your API key at https://backscatter.io/account.
+-k  Specify an API key to save to your configuration file [required]
+
+  observations: queries observations matching your query. https://backscatter.io/developers#observations
+-k  Specify an API key to use for the API [required if not specified in the configuration]
+-q  Specify an IP, netblock, ASN, country, or port [required]
+-t  The type of the query you wish to make: ip, netblock, ASN, country, or port [autodetects]
+-f  Output format of the results. table or json, defaults to json
+--scope  Days to search back through (integer)
+
+  trends: queries trends (top N) of items of a given type seen withing the scope
+-k  Specify an API key to use for the API [required if not specified in the configuration]
+-t  Trend type: ip, network, asn, port, or country, defaults to ip
+-f  Output format of the results. table or json, defaults to json
+--scope  Days to search back through (integer)
+
+  enrich: adds enriching information to the queried item
+-k  Specify an API key to use for the API [required if not specified in the configuration]
+-q  Specify an IP, netblock, ASN, country, or port [required]
+-t  The type of the query you wish to make: ip, netblock, ASN, country, or port [autodetects]
+-f  Output format of the results. table or json, defaults to json
+EOD
+      puts usage
+    end
+  end
+  # Alias for the CLInterface class
+  CLI = BackscatterIO::CLInterface
+end
+
+results = BackscatterIO::CLI.run(ARGV)
+puts results

data/lib/backscatterio/version.rb

@@ -11,5 +11,5 @@ Swagger Codegen version: 2.4.0
 =end
 
 module BackscatterIO
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

data/swagger.yaml

@@ -0,0 +1,387 @@
+---
+swagger: "2.0"
+info:
+  description: |
+    [This is the Backscatter.io API.](https://backscatter.io/developers)
+  version: 1.0.0
+  title: Backscatter.io
+  termsOfService: https://backscatter.io/tos
+  contact:
+    email: info@backscatter.io
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+host: api.backscatter.io
+basePath: /v0
+schemes:
+- https
+security:
+- ApiKeyAuth: []
+paths:
+  /hello:
+    get:
+      summary: authenticate to the service
+      operationId: hello
+      consumes:
+      - application/json
+      produces:
+      - application/json
+      parameters: []
+      responses:
+        200:
+          description: authenticated
+          schema:
+            $ref: '#/definitions/Hello'
+        405:
+          description: Invalid input
+  /observations/{queryType}:
+    get:
+      summary: fetches observations for a given querytype
+      operationId: observations
+      consumes:
+      - application/json
+      produces:
+      - application/json
+      parameters:
+      - name: queryType
+        in: path
+        description: query type ip, network, asn, port, country
+        required: true
+        type: string
+      - name: query
+        in: query
+        description: ip address, cidr block, asn, port, or country
+        required: true
+        type: string
+      - name: scope
+        in: query
+        description: timeframe to search over, e.g., 1d, 7d
+        required: false
+        type: string
+      responses:
+        200:
+          description: observations
+          schema:
+            $ref: '#/definitions/Observations'
+        405:
+          description: Invalid input
+  /trends/popular/{trendType}:
+    get:
+      summary: Top N items
+      description: A listing of the top N items observered over the query scope
+      operationId: trends
+      produces:
+      - application/json
+      parameters:
+      - name: trendType
+        in: path
+        description: which item type you want to perform a trend over
+        required: true
+        type: string
+        enum:
+        - ip
+        - network
+        - asn
+        - port
+        - country
+      - name: scope
+        in: query
+        description: timeframe to search over, e.g., 1d, 7d
+        required: false
+        type: string
+      responses:
+        200:
+          description: observations
+          schema:
+            $ref: '#/definitions/Trends'
+        405:
+          description: Invalid input
+  /enrichment/ip:
+    get:
+      summary: enriches ip
+      description: returns enrichment data for an ip
+      operationId: enrich_ip
+      produces:
+      - application/json
+      parameters:
+      - name: query
+        in: query
+        required: true
+        type: string
+      responses:
+        200:
+          description: ip_enrichment
+          schema:
+            $ref: '#/definitions/IPEnrichment'
+        405:
+          description: Invalid input
+  /enrichment/network:
+    get:
+      summary: enriches network
+      description: returns enrichment data for a network
+      operationId: enrich_network
+      produces:
+      - application/json
+      parameters:
+      - name: query
+        in: query
+        required: true
+        type: string
+      responses:
+        200:
+          description: network_enrichment
+          schema:
+            $ref: '#/definitions/NetworkEnrichment'
+        405:
+          description: Invalid input
+  /enrichment/asn:
+    get:
+      summary: enriches asn
+      description: returns enrichment data for an ASN
+      operationId: enrich_asn
+      produces:
+      - application/json
+      parameters:
+      - name: query
+        in: query
+        required: true
+        type: string
+      responses:
+        200:
+          description: asn_enrichment
+          schema:
+            $ref: '#/definitions/ASNEnrichment'
+        405:
+          description: Invalid input
+securityDefinitions:
+  ApiKeyAuth:
+    type: apiKey
+    name: X-API-KEY
+    in: header
+definitions:
+  Hello:
+    type: object
+    properties:
+      message:
+        type: string
+      success:
+        type: boolean
+  Observations:
+    type: object
+    properties:
+      query:
+        $ref: '#/definitions/Query'
+      results:
+        $ref: '#/definitions/Results'
+      success:
+        type: boolean
+  Query:
+    type: object
+    properties:
+      after_time:
+        type: string
+      focus:
+        type: string
+      scope:
+        type: string
+      type:
+        type: string
+        enum:
+        - ip_query
+        - network_query
+        - asn_query
+        - port_query
+        - country_query
+        - top_x_query
+  Results:
+    type: object
+    properties:
+      observations:
+        type: array
+        items:
+          $ref: '#/definitions/Observation'
+      summary:
+        $ref: '#/definitions/Summary'
+      unique:
+        $ref: '#/definitions/Unique'
+  Observation:
+    type: object
+    properties:
+      dst_port:
+        type: string
+      fragment_flags:
+        type: string
+      id:
+        type: string
+      length:
+        type: string
+      observed:
+        type: string
+      precedence:
+        type: string
+      protocol:
+        type: string
+      res:
+        type: string
+      src_ip:
+        type: string
+      src_port:
+        type: string
+      tcp_flags:
+        type: string
+      tos:
+        type: string
+      ttl:
+        type: string
+      window:
+        type: string
+  Summary:
+    type: object
+    properties:
+      autonomous_system_count:
+        type: integer
+        format: int32
+      has_observations:
+        type: boolean
+      ip_address_count:
+        type: array
+        items:
+          type: string
+      network_count:
+        type: integer
+        format: int32
+      observations:
+        type: boolean
+      observations_count:
+        type: integer
+        format: int32
+      port_count:
+        type: integer
+        format: int32
+      protocol_count:
+        type: integer
+        format: int32
+  Unique:
+    type: object
+    properties:
+      autonomous_systems:
+        type: array
+        items:
+          type: string
+      countries:
+        type: array
+        items:
+          type: string
+      ip_addresses:
+        type: array
+        items:
+          type: string
+      networks:
+        type: array
+        items:
+          type: string
+      ports:
+        type: array
+        items:
+          type: string
+      protocols:
+        type: array
+        items:
+          type: string
+  Trends:
+    type: object
+    properties:
+      query:
+        $ref: '#/definitions/Query'
+      results:
+        type: object
+        properties: {}
+      success:
+        type: boolean
+  IPEnrichment:
+    type: object
+    properties:
+      results:
+        $ref: '#/definitions/IPEnrichment_results'
+      success:
+        type: boolean
+  NetworkEnrichment:
+    type: object
+    properties:
+      results:
+        $ref: '#/definitions/NetworkEnrichment_results'
+      success:
+        type: boolean
+  ASNEnrichment:
+    type: object
+    properties:
+      results:
+        $ref: '#/definitions/ASNEnrichment_results'
+      success:
+        type: boolean
+  IPEnrichment_results:
+    properties:
+      as_name:
+        type: string
+      as_num:
+        type: integer
+        format: int32
+      city:
+        type: string
+      country_iso:
+        type: string
+      country_name:
+        type: string
+      ip:
+        type: string
+      ip_hex:
+        type: string
+      ip_version:
+        type: integer
+        format: int8
+      latitude:
+        type: number
+      longitude:
+        type: number
+      network:
+        type: string
+      network_broadcast:
+        type: string
+      network_hostmask:
+        type: string
+      network_netmask:
+        type: string
+      network_size:
+        type: integer
+        format: int32
+      postal_code:
+        type: string
+      region_iso:
+        type: string
+      region_name:
+        type: string
+  NetworkEnrichment_results:
+    properties:
+      cidr:
+        type: string
+      network_addresses:
+        type: array
+        items:
+          type: string
+      network_size:
+        type: integer
+        format: int32
+  ASNEnrichment_results:
+    properties:
+      as_num:
+        type: integer
+        format: int32
+      as_name:
+        type: string
+      prefix_count:
+        type: integer
+        format: int32
+      prefixes:
+        type: array
+        items:
+          type: string

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backscatterio
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - rubygems@chrislee.dhs.org
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-31 00:00:00.000000000 Z
+date: 2019-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus
@@ -193,7 +193,8 @@ dependencies:
 description: "[This is the Backscatter.io API.](https://backscatter.io/developers) "
 email:
 - rubygems@chrislee.dhs.org
-executables: []
+executables:
+- backscatterio-rb
 extensions: []
 extra_rdoc_files: []
 files:
@@ -201,7 +202,9 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- backscatterio-1.0.0.gem
 - backscatterio.gemspec
+- bin/backscatterio-rb
 - docs/ASNEnrichment.md
 - docs/ASNEnrichmentResults.md
 - docs/Api.md
@@ -256,6 +259,7 @@ files:
 - spec/models/trends_spec.rb
 - spec/models/unique_spec.rb
 - spec/spec_helper.rb
+- swagger.yaml
 homepage: https://github.com/backscatterio/ruby
 licenses:
 - Unlicense