ruby-amass 0.1.0

data/lib/amass/hostname.rb

@@ -0,0 +1,73 @@
+require 'amass/address'
+
+module Amass
+  #
+  # A hostname.
+  #
+  # @api public
+  #
+  class Hostname
+
+    # The hostname.
+    #
+    # @return [String]
+    attr_reader :name
+
+    # The domain the hostname belongs to.
+    #
+    # @return [String, nil]
+    attr_reader :domain
+
+    # The addresses associated with the hostname.
+    #
+    # @return [Array<Address>]
+    attr_reader :addresses
+
+    # The tag from `amass`.
+    #
+    # @return [String, nil]
+    attr_reader :tag
+
+    # The source(s) that discovered the hostname.
+    #
+    # @return [Array<String>]
+    attr_reader :sources
+
+    #
+    # Initializes the hostname.
+    #
+    # @param [String] name
+    #   The hostname.
+    #
+    # @param [String, nil] domain
+    #   The domain the hostname belongs to.
+    #
+    # @param [Array<Address>] addresses
+    #   The addresses associated with the hostname.
+    #
+    # @param [String, nil] tag
+    #   The `amass` tag.
+    #
+    # @param [Array<String>] sources
+    #   The source(s) that discovered the hostname.
+    #
+    def initialize(name: , domain: nil, addresses: [], tag: nil, sources: [])
+      @name      = name
+      @domain    = domain
+      @addresses = addresses
+      @tag       = tag
+      @sources   = sources
+    end
+
+    #
+    # Converts the hostname to a String.
+    #
+    # @return [String]
+    #   The hostname.
+    #
+    def to_s
+      @name
+    end
+
+  end
+end

data/lib/amass/output_file.rb

@@ -0,0 +1,124 @@
+require 'amass/parsers/json'
+require 'amass/parsers/txt'
+
+module Amass
+  #
+  # Represents either a `.json` or `.txt` output file.
+  #
+  # ## Example
+  #
+  #     require 'amass/output_file'
+  #     
+  #     output_file = Amass::OutputFile.new('/path/to/amass.json')
+  #     output_file.each do |hostname|
+  #       p hostname
+  #     end
+  #
+  # @api public
+  #
+  class OutputFile
+
+    # Mapping of formats to parsers.
+    #
+    # @api semipublic
+    PARSERS = {
+      :json => Parsers::JSON,
+      :txt  => Parsers::TXT
+    }
+
+    # The path to the output file.
+    #
+    # @return [String]
+    attr_reader :path
+
+    # The format of the output file.
+    #
+    # @return [:json, :txt]
+    attr_reader :format
+
+    # The parser for the output file format.
+    #
+    # @return [Parsers::JSON, Parsers::TXT]
+    #
+    # @api private
+    attr_reader :parser
+
+    #
+    # Initializes the output file.
+    #
+    # @param [String] path
+    #   The path to the output file.
+    #
+    # @param [:json, :txt] format
+    #   The optional format of the output file. If not given, it will be
+    #   inferred by the path's file extension.
+    #
+    def initialize(path, format: self.class.infer_format(path))
+      @path   = File.expand_path(path)
+      @format = format
+
+      @parser = PARSERS.fetch(format) do
+        raise(ArgumentError,"unrecognized file type: #{@path.inspect}")
+      end
+    end
+
+    # Mapping of file extensions to formats
+    #
+    # @api semipublic
+    FILE_FORMATS = {
+      '.json' => :json,
+      '.txt'  => :txt
+    }
+
+    #
+    # Infers the format from the output file's extension name.
+    #
+    # @param [String] path
+    #   The path to the output file.
+    #
+    # @return [:json, :txt]
+    #   The output format inferred from the file's extension name.
+    #
+    # @raise [ArgumentError]
+    #   The output format could not be inferred from the file's name.
+    #
+    # @api semipublic
+    #
+    def self.infer_format(path)
+      FILE_FORMATS.fetch(File.extname(path)) do
+        raise(ArgumentError,"could not infer format of #{path}")
+      end
+    end
+
+    #
+    # Parses the contents of the output file.
+    #
+    # @yield [hostname]
+    #   The given block will be passed each parsed hostname.
+    #
+    # @yieldparam [Hostname] hostname
+    #   A parsed hostname from the output file.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator object will be returned.
+    #
+    def each(&block)
+      return enum_for(__method__) unless block
+
+      File.open(@path) do |file|
+        @parser.parse(file,&block)
+      end
+    end
+
+    #
+    # Converts the output file to a String.
+    #
+    # @return [String]
+    #   The path to the output file.
+    #
+    def to_s
+      @path
+    end
+
+  end
+end

data/lib/amass/parsers/json.rb

@@ -0,0 +1,80 @@
+require 'amass/hostname'
+require 'amass/address'
+
+require 'json'
+
+module Amass
+  module Parsers
+    #
+    # Parses single-line JSON hashes.
+    #
+    # @api semipublic
+    #
+    module JSON
+      #
+      # Parses a single-line of JSON.
+      #
+      # @param [IO] io
+      #   The IO stream to parse.
+      #
+      # @yield [hostname]
+      #   The given block will be passed each parsed hostname.
+      #
+      # @yieldparam [Hostname] hostname
+      #   The parsed hostname.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator will be returned.
+      #
+      def self.parse(io)
+        return enum_for(__method__,io) unless block_given?
+
+        io.each_line do |line|
+          line.chomp!
+          json = ::JSON.parse(line)
+
+          yield map_hostname(json)
+        end
+      end
+
+      private
+
+      #
+      # Maps a JSON Hash to a {Hostname}.
+      #
+      # @param [Hash{Symbol => Object}] json
+      #   The parsed JSON Hash.
+      #
+      # @return [Hostname]
+      #   The resulting hostname.
+      #
+      def self.map_hostname(json)
+        Hostname.new(
+          name:      json['name'],
+          domain:    json['domain'],
+          addresses: json['addresses'].map(&method(:map_address)),
+          tag:       json['tag'],
+          sources:   json['sources']
+        )
+      end
+
+      #
+      # Maps a JSON Hash to an {Address}.
+      #
+      # @param [Hash{Symbol => Object}] json
+      #   The parsed JSON Hash.
+      #
+      # @return [Address]
+      #   The resulting address.
+      #
+      def self.map_address(json)
+        Address.new(
+          ip:   json['ip'],
+          cidr: json['cidr'],
+          asn:  json['asn'],
+          desc: json['desc']
+        )
+      end
+    end
+  end
+end

data/lib/amass/parsers/txt.rb

@@ -0,0 +1,37 @@
+require 'amass/hostname'
+
+module Amass
+  module Parsers
+    #
+    # Parses single-line hostnames.
+    #
+    # @api semipublic
+    #
+    module TXT
+      #
+      # Parses a single line of plain-text.
+      #
+      # @param [IO] io
+      #   The IO stream to parse.
+      #
+      # @yield [hostname]
+      #   The given block will be passed each parsed hostname.
+      #
+      # @yieldparam [Hostname] hostname
+      #   The parsed hostname.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator will be returned.
+      #
+      def self.parse(io)
+        return enum_for(__method__,io) unless block_given?
+
+        io.each_line do |line|
+          line.chomp!
+
+          yield Hostname.new(name: line)
+        end
+      end
+    end
+  end
+end

data/lib/amass/version.rb

@@ -0,0 +1,4 @@
+module Amass
+  # ruby-amass version
+  VERSION = '0.1.0'
+end

data/lib/amass.rb

@@ -0,0 +1,2 @@
+require 'amass/command'
+require 'amass/version'

data/ruby-amass.gemspec

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'amass/version'
+                  Amass::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = Array(gemspec['requirements'])
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/spec/address_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+require 'amass/address'
+
+describe Amass::Address do
+  let(:ip)   { "93.184.216.34" }
+  let(:cidr) { "93.184.216.0/24" }
+  let(:asn)  { 15133 }
+  let(:desc) { "EDGECAST - MCI Communications Services, Inc. d/b/a Verizon Business" }
+
+  subject { described_class.new(ip: ip, cidr: cidr, asn: asn, desc: desc) }
+
+  describe "#initialize" do
+    it "must set #ip" do
+      expect(subject.ip).to eq(ip)
+    end
+
+    it "must set #cidr" do
+      expect(subject.cidr).to eq(cidr)
+    end
+
+    it "must set #asn" do
+      expect(subject.asn).to eq(asn)
+    end
+
+    it "must set #desc" do
+      expect(subject.desc).to eq(desc)
+    end
+  end
+
+  describe "#to_s" do
+    it "must return the #ip" do
+      expect(subject.to_s).to eq(ip)
+    end
+  end
+end

data/spec/amass_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+require 'amass/version'
+
+describe Amass do
+  it "should have a VERSION constant" do
+    expect(subject.const_get('VERSION')).to_not be_empty
+  end
+end

data/spec/fixtures/enum/amass.json

@@ -0,0 +1,14 @@
+{"name":"www.example.com","domain":"example.com","addresses":[{"ip":"93.184.216.34","cidr":"93.184.216.0/24","asn":15133,"desc":"EDGECAST - MCI Communications Services, Inc. d/b/a Verizon Business"},{"ip":"2606:2800:220:1:248:1893:25c8:1946","cidr":"2606:2800:220::/48","asn":15133,"desc":"EDGECAST - MCI Communications Services, Inc. d/b/a Verizon Business"}],"tag":"cert","sources":["CertSpotter"]}
+{"name":"example.com","domain":"example.com","addresses":[{"ip":"2606:2800:220:1:248:1893:25c8:1946","cidr":"2606:2800:220::/48","asn":15133,"desc":"EDGECAST - MCI Communications Services, Inc. d/b/a Verizon Business"},{"ip":"93.184.216.34","cidr":"93.184.216.0/24","asn":15133,"desc":"EDGECAST - MCI Communications Services, Inc. d/b/a Verizon Business"}],"tag":"cert","sources":["CertSpotter"]}
+{"name":"waterregion643.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"api","sources":["Sublist3rAPI"]}
+{"name":"ringneo5.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"api","sources":["Sublist3rAPI"]}
+{"name":"ratara72.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"api","sources":["Sublist3rAPI"]}
+{"name":"serafim.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"api","sources":["Sublist3rAPI"]}
+{"name":"a8boyyy.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"api","sources":["Sublist3rAPI"]}
+{"name":"bikamzhaz.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"api","sources":["Sublist3rAPI"]}
+{"name":"wwwakamai.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"alt","sources":["Alterations"]}
+{"name":"wwwakamaiint.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"alt","sources":["Alterations"]}
+{"name":"billing-serafim.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"alt","sources":["Alterations"]}
+{"name":"bikamzhazstaff.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"alt","sources":["Alterations"]}
+{"name":"bikamzhaz-6.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"alt","sources":["Alterations"]}
+{"name":"wwwakamaiintorigin.example.com","domain":"example.com","addresses":[{"ip":"54.144.128.85","cidr":"54.144.0.0/14","asn":14618,"desc":"AMAZON-AES - Amazon.com, Inc."}],"tag":"alt","sources":["Alterations"]}

data/spec/fixtures/enum/amass.txt

@@ -0,0 +1,24 @@
+example.com
+wbldr2.example.com
+qwewowgo40.example.com
+intermarksavills.example.com
+www.example.com
+wild1990.example.com
+artsupergol1.example.com
+wild1990server.example.com
+gaev.ilya.s.example.com
+wbldr22.example.com
+www-las.example.com
+work1.rabot.example.com
+wild1990serverphp.example.com
+69.48.131.151.static.example.com
+email-wbldr22.example.com
+wbldr22ops.example.com
+wbldr22ids.example.com
+wbldr22opsbrasil.example.com
+email-wbldr22stage.example.com
+email-wbldr22stageaws.example.com
+wbldr22opsredirector.example.com
+machinework1.rabot.example.com
+wild1990serverphp-testing.example.com
+169.48.131.151.static.example.com

data/spec/hostname_spec.rb

@@ -0,0 +1,93 @@
+require 'spec_helper'
+require 'amass/hostname'
+
+describe Amass::Hostname do
+  let(:name) { "www.example.com" }
+  let(:domain) { "example.com" }
+
+  let(:ip1) { "93.184.216.34" }
+  let(:cidr1) { "93.184.216.0/24" }
+  let(:asn1) { 15133 }
+  let(:desc1) { "EDGECAST - MCI Communications Services, Inc. d/b/a Verizon Business" }
+
+  let(:ip2)   { "2606:2800:220:1:248:1893:25c8:1946" }
+  let(:cidr2) { "2606:2800:220::/48" }
+  let(:asn2)  { 15133 }
+  let(:desc2) { "EDGECAST - MCI Communications Services, Inc. d/b/a Verizon Business" }
+
+  let(:tag) { "cert" }
+  let(:source1) { "CertSpotter" }
+
+  let(:addresses) do
+    [
+      Amass::Address.new(ip: ip1, cidr: cidr1, asn: asn1, desc: desc1),
+      Amass::Address.new(ip: ip2, cidr: cidr2, asn: asn2, desc: desc2)
+    ]
+  end
+
+  let(:sources) { [source1] }
+
+  subject do
+    described_class.new(
+      name:      name,
+      domain:    domain,
+      addresses: addresses,
+      tag:       tag,
+      sources:   sources
+    )
+  end
+
+  describe "#intialize" do
+    context "when only the name: keyword is given" do
+      subject { described_class.new(name: name) }
+
+      it "must set #name" do
+        expect(subject.name).to eq(name)
+      end
+
+      it "must initialize the Hostname's #domain to nil" do
+        expect(subject.domain).to be(nil)
+      end
+
+      it "must initialize the Hostname's #addresses to []" do
+        expect(subject.addresses).to eq([])
+      end
+
+      it "must initialize the Hostname's #tag to nil" do
+        expect(subject.tag).to be(nil)
+      end
+
+      it "must initialize the Hostname's #sources to []" do
+        expect(subject.sources).to eq([])
+      end
+    end
+
+    context "when all keyword arguments are given" do
+      it "must set #name" do
+        expect(subject.name).to eq(name)
+      end
+
+      it "must set #domain" do
+        expect(subject.domain).to be(domain)
+      end
+
+      it "must set #addresses" do
+        expect(subject.addresses).to eq(addresses)
+      end
+
+      it "must set #tag" do
+        expect(subject.tag).to eq(tag)
+      end
+
+      it "must set #sources" do
+        expect(subject.sources).to eq(sources)
+      end
+    end
+  end
+
+  describe "#to_s" do
+    it "must return #name" do
+      expect(subject.to_s).to eq(name)
+    end
+  end
+end

data/spec/output_file_spec.rb

@@ -0,0 +1,111 @@
+require 'spec_helper'
+require 'amass/output_file'
+
+describe Amass::OutputFile do
+  let(:fixtures_dir) { File.expand_path(File.join(__dir__,'fixtures')) }
+  describe ".infer_format" do
+    subject { described_class.infer_format(path) }
+
+    context "when the path ends in .json" do
+      let(:path) { '/path/to/file.json' }
+
+      it { expect(subject).to eq(:json) }
+    end
+
+    context "when the path ends in .txt" do
+      let(:path) { '/path/to/file.txt' }
+
+      it { expect(subject).to eq(:txt) }
+    end
+  end
+
+  describe "PARSERS" do
+    subject { described_class::PARSERS }
+
+    describe ":txt" do
+      it { expect(subject[:txt]).to eq(Amass::Parsers::TXT) }
+    end
+
+    describe ":json" do
+      it { expect(subject[:json]).to eq(Amass::Parsers::JSON) }
+    end
+  end
+
+  describe "FILE_FORMATS" do
+    subject { described_class::FILE_FORMATS }
+
+    describe ".txt" do
+      it { expect(subject['.txt']).to be(:txt) }
+    end
+
+    describe ".json" do
+      it { expect(subject['.json']).to be(:json) }
+    end
+  end
+
+  describe "#initialize" do
+    let(:path) { "/path/to/file.json" }
+
+    subject { described_class.new(path) }
+
+    it "must set #path" do
+      expect(subject.path).to eq(path)
+    end
+
+    it "must infer the format from the file's extname" do
+      expect(subject.format).to eq(:json)
+    end
+
+    it "must set #parser based on #format" do
+      expect(subject.parser).to eq(described_class::PARSERS[subject.format])
+    end
+
+    context "when given an format: keyword" do
+      let(:format) { :txt }
+
+      subject { described_class.new(path, format: format) }
+
+      it "must set #format" do
+        expect(subject.format).to be(format)
+      end
+
+      it "must set #parser based on the given format:" do
+        expect(subject.parser).to eq(described_class::PARSERS[format])
+      end
+    end
+  end
+
+  let(:path) { File.join(fixtures_dir,'enum','amass.json') }
+
+  subject { described_class.new(path) }
+
+  describe "#each" do
+    context "when a block is given" do
+      it "must yield each parsed Hostname object" do
+        yielded_hostnames = []
+
+        subject.each do |hostname|
+          yielded_hostnames << hostname
+        end
+
+        expect(yielded_hostnames).to_not be_empty
+        expect(yielded_hostnames).to all(be_kind_of(Amass::Hostname))
+      end
+    end
+
+    context "when no block is given" do
+      it "must return an Enumerator of the parsed Hostname objects" do
+        hostnames = subject.each.to_a
+
+        expect(hostnames).to_not be_empty
+        expect(hostnames).to all(be_kind_of(Amass::Hostname))
+      end
+    end
+  end
+
+  describe "#to_s" do
+    it "must return #path" do
+      expect(subject.to_s).to eq(path)
+    end
+  end
+end