metasploit-yard 1.0.2-java

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler/gem_tasks'
+require 'cucumber'
+require 'cucumber/rake/task'
+require 'rspec/core/rake_task'
+
+Cucumber::Rake::Task.new(:cucumber) do |t|
+  t.cucumber_opts = "features --format pretty"
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+# Use find_all_by_name instead of find_by_name as find_all_by_name will return pre-release versions
+gem_specification = Gem::Specification.find_all_by_name('metasploit-yard').first
+
+Dir[File.join(gem_specification.gem_dir, 'lib', 'tasks', '**', '*.rake')].each do |rake|
+  load rake
+end
+
+task :default => :spec

data/config/cucumber.yml

@@ -0,0 +1,6 @@
+---
+<% if ENV['TRAVIS'] == 'true' %>
+default: --format pretty --tags ~@travis-ci-wip
+<% else %>
+default: --format pretty
+<% end %>

data/features/rake_task.feature

@@ -0,0 +1,90 @@
+Feature: yard.rake
+
+  In order to generate documentation for metasploit projects, but not end up with multiple actions for the `yard` rake tasks
+  As a developer calling `rake yard`
+  I want `yard.rake` loaded from `metasploit-yard`
+
+  Scenario: Without Rails
+    Given I create a clean gemset "without_rails_use_metasploit_yard"
+    And I use gemset "without_rails_use_metasploit_yard"
+    And I successfully run `bundle gem without_rails_use_metasploit_yard`
+    And I cd to "without_rails_use_metasploit_yard"
+    And I overwrite "without_rails_use_metasploit_yard.gemspec" with:
+      """
+      # coding: utf-8
+      lib = File.expand_path('../lib', __FILE__)
+      $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+      require 'without_rails_use_metasploit_yard/version'
+
+      Gem::Specification.new do |spec|
+        spec.name          = 'without_rails_use_metasploit_yard'
+        spec.version       = WithoutRailsUseMetasploitYard::VERSION
+        spec.authors       = ['Luke Imhoff']
+        spec.email         = ['luke_imhoff@rapid7.com']
+        spec.summary       = 'Uses metasploit-yard without Rails'
+        spec.license       = 'BSD-3-Clause'
+
+        spec.files         = `git ls-files -z`.split("\x0")
+        spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+        spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+        spec.require_paths = ['lib']
+
+        spec.add_development_dependency 'bundler'
+        spec.add_development_dependency 'rake'
+        spec.add_development_dependency 'metasploit-yard'
+      end
+      """
+    And I append to "Rakefile" with:
+      """
+      # Use find_all_by_name instead of find_by_name as find_all_by_name will return pre-release versions
+      gem_specification = Gem::Specification.find_all_by_name('metasploit-yard').first
+
+      Dir[File.join(gem_specification.gem_dir, 'lib', 'tasks', '**', '*.rake')].each do |rake|
+        load rake
+      end
+      """
+    And I install the project gem locally
+    And I successfully run `bundle install`
+    When I run `rake yard`
+    Then the output should contain:
+      """
+      Undocumented Objects:
+      WithoutRailsUseMetasploitYard              (lib/without_rails_use_metasploit_yard.rb:3)
+      WithoutRailsUseMetasploitYard::VERSION     (lib/without_rails_use_metasploit_yard/version.rb:2)
+      """
+    And the stderr from "rake yard" should contain:
+      """
+      Documentation percentage (0.00%) below threshold (100.00%)
+      """
+    # Don't do this in a different scenario because it takes minutes to setup a new gem project
+    Given a file named "config/yard-stats-threshold" with:
+      """
+      0.0
+      """
+    When I successfully run `rake yard`
+    Then the output from "rake yard" should not contain "below threshold"
+
+  @travis-ci-wip
+  Scenario: With a Rails Application
+    Given I create a clean gemset "rails_application_use_metasploit_yard"
+    And I use gemset "rails_application_use_metasploit_yard"
+    And I successfully run `gem install rails`
+    And I successfully run `rails new rails_application_use_metasploit_yard --skip-action-view --skip-active-record --skip-javascript --skip-spring --skip-sprockets --skip-test-unit`
+    And I cd to "rails_application_use_metasploit_yard"
+    And I append to "Gemfile" with:
+      """
+      gem 'metasploit-yard', group: :development
+      """
+    And I install the project gem locally
+    And I successfully run `bundle install`
+    And a file named "config/yard-stats-threshold" with:
+      """
+      0.0
+      """
+    When I successfully run `rake yard`
+    Then the output should contain:
+      """
+      Undocumented Objects:
+      ApplicationController     (app/controllers/application_controller.rb:1)
+      ApplicationHelper         (app/helpers/application_helper.rb:1)
+      """

data/features/step_definitions/project.rb

@@ -0,0 +1,25 @@
+Given(/^I install the project gem locally$/) do
+  process_name = "gem build metasploit-yard.gemspec"
+  root = Pathname.new(__FILE__).parent.parent.parent
+  current_pathname = Pathname.new(current_dir).expand_path
+  root_relative_to_current = root.relative_path_from(current_pathname)
+  current_relative_to_root = current_pathname.relative_path_from(root)
+
+  cd(root_relative_to_current)
+  run_simple(process_name)
+  cd(current_relative_to_root)
+
+  gem_build_output = get_process(process_name).output
+  match = gem_build_output.match(/^  File: (?<gem_file>.*)$/)
+
+  unless match
+    fail "Cannot parse gem build output for built gem name:\n#{gem_build_output}"
+  end
+
+  # need to include root as this is back in tmp/aruba
+  gem_pathname = root.join(match[:gem_file])
+
+  run_simple("gem install #{gem_pathname}")
+
+  gem_pathname.delete
+end

data/features/step_definitions/rvm.rb

@@ -0,0 +1,46 @@
+Before do
+  @gemsets_to_delete = []
+end
+
+Given /^I create a clean gemset "(.*?)"$/ do |gemset|
+  run_simple("rvm gemset create #{gemset}")
+  @gemsets_to_delete << gemset
+end
+
+Given /^I use gemset "(.*?)"$/ do |gemset|
+  current_rvm_env_process_name = 'rvm env'
+  run_simple(current_rvm_env_process_name)
+  current_rvm_env = get_process(current_rvm_env_process_name).stdout
+  current_parsed = Metasploit::Yard::Aruba::RvmEnv.parse(current_rvm_env)
+
+  new_rvm_env_process_name = "rvm @#{gemset} do rvm env"
+  run_simple(new_rvm_env_process_name)
+  new_rvm_env = get_process(new_rvm_env_process_name).stdout
+  new_parsed = Metasploit::Yard::Aruba::RvmEnv.parse(new_rvm_env)
+
+  Metasploit::Yard::Aruba::RvmEnv.change(
+      from: current_parsed,
+      to: new_parsed,
+      world: self
+  )
+
+  #
+  # Remove this gem's bin from path so the gemset is required to declare the gem as a dependency to get access to the
+  # bins
+  #
+
+  directories = ENV['PATH'].split(File::PATH_SEPARATOR)
+  directories.shift
+  path = directories.join(File::PATH_SEPARATOR)
+
+  set_env('PATH', path)
+
+  unset_bundler_env_vars
+end
+
+After('~@no-clobber') do
+  @gemsets_to_delete.each do |gemset|
+    # --force to prevent confirmation prompt
+    run_simple("rvm gemset delete --force #{gemset}")
+  end
+end

data/features/support/env.rb

@@ -0,0 +1,8 @@
+require 'active_support/core_ext/integer/time'
+require 'aruba/cucumber'
+
+require 'metasploit/yard'
+
+Before do
+  @aruba_timeout_seconds = 10.minutes
+end

data/lib/metasploit/yard.rb

@@ -0,0 +1,20 @@
+
+#
+# Project
+#
+
+require 'metasploit/yard/version'
+
+# The namespace shared between all gems related to
+# [Metasploit Framework](https://github.com/rapid7/metasploit-framework) and
+# [Metasploit Commercial Editions](https://metasploit.com)
+module Metasploit
+  # Namespace for this gem.
+  module Yard
+    autoload :Aruba, 'metasploit/yard/aruba'
+
+    if defined?(Rails)
+      require 'metasploit/yard/railtie'
+    end
+  end
+end

data/lib/metasploit/yard/aruba.rb

@@ -0,0 +1,12 @@
+#
+# Gems
+#
+
+require 'active_support/dependencies/autoload'
+
+# Helpers for aruba step definitions for testing `rake yard`
+module Metasploit::Yard::Aruba
+  extend ActiveSupport::Autoload
+
+  autoload :RvmEnv
+end

data/lib/metasploit/yard/aruba/rvm_env.rb

@@ -0,0 +1,105 @@
+#
+# Gems
+#
+
+require 'active_support/dependencies/autoload'
+require 'active_support/core_ext/hash/keys'
+
+#
+# Project
+#
+
+# Helpers for parsing `rvm env` output
+module Metasploit::Yard::Aruba::RvmEnv
+  extend ActiveSupport::Autoload
+
+  autoload :Export
+  autoload :Prepend
+  autoload :Unset
+  autoload :Variable
+
+  #
+  # CONSTANTS
+  #
+
+  # Class for parsing lines for `rvm env` in order of precedence
+  LINE_PARSER_PRECEDENCE = [
+      # must be before `Metasploit::Yard::Aruba::RvmEnv::Export` because
+      # `Metasploit::Yard::Aruba::RvmEnv::Export::REGEXP` matches a superset of
+      # `Metasploit::Yard::Aruba::RvmEnv::Prepend::REGEXP`
+      Metasploit::Yard::Aruba::RvmEnv::Prepend,
+      Metasploit::Yard::Aruba::RvmEnv::Export,
+      Metasploit::Yard::Aruba::RvmEnv::Unset
+  ]
+
+  # Changes from one `rvm env [@<gemset>]` to another.
+  #
+  # @param options [Hash{Symbol => Array<Metasploit::Yard::Aruba::RvmEnv::Variable>}]
+  # @option options :from [Array<Metasploit::Yard::Aruba::RvmEnv::Variable>] the current rvm env; usually the output of
+  #   parsing `rvm env`.
+  # @option options :to [Array<Metasploit::Yard::Aruba::RvmEnv::Variable>] the new rvm env; usualy the output of parsing
+  #   `rvm env @<gemset>`
+  # @option options [Object] :world the cucumber World instance for the current scenario.
+  def self.change(options={})
+    options.assert_valid_keys(:from, :to, :world)
+
+    from_by_name = parsed_to_hash(options.fetch(:from))
+    to_by_name = parsed_to_hash(options.fetch(:to))
+    world = options.fetch(:world)
+
+    to_by_name.each do |name, to_variable|
+      from_variable = from_by_name[name]
+
+      # ignore variables that didn't change
+      unless to_variable == from_variable
+        to_variable.change(
+            from: from_variable,
+            world: world
+        )
+      end
+    end
+  end
+
+  # Parses the output of `rvm env`.
+  #
+  # @return [Array<Metasploit::Yard::Aruba::RvmEnv::Variable, #apply>]
+  def self.parse(rvm_env)
+    rvm_env.each_line.map { |line|
+      parse_line(line)
+    }
+  end
+
+  # Parses an individual line of `rvm env`
+  #
+  # @return [Metasploit::Yard::Aruba::RvmEnv::Variable, #apply]
+  # @raise [ArgumentError] if no `Class` in {LINE_PARSER_PRECEDENCE} returns a parsed instance.
+  def self.parse_line(line)
+    parsed = nil
+
+    LINE_PARSER_PRECEDENCE.each do |line_parser|
+      parsed = line_parser.parse(line)
+
+      if parsed
+        break
+      end
+    end
+
+    unless parsed
+      raise ArgumentError, "No line parser could parse #{line.inspect}"
+    end
+
+    parsed
+  end
+
+  # Converts output of {parse} into Hash that maps {Metasploit::Yard::Aruba::RvmEnv::Variable#name} to the
+  # {Metasploit::Yard::Aruba::RvmEnv::Variable}.
+  #
+  # @param parsed [Array<Metasploit::Yard::Aruba::RvmEnv::Variable>] output of {parse}.
+  # @return [Hash{String => Metasploit::Yard::Aruba::RvmEnv::Variable}] Map of
+  #   {Metasploit::Yard::Aruba::RvmEnv::Variable#name} to the {Metasploit::Yard::Aruba::RvmEnv::Variable}.
+  def self.parsed_to_hash(parsed)
+    parsed.each_with_object({}) { |variable, variable_by_name|
+      variable_by_name[variable.name] = variable
+    }
+  end
+end

data/lib/metasploit/yard/aruba/rvm_env/export.rb

@@ -0,0 +1,75 @@
+# Recognizes `export`s of a variable
+class Metasploit::Yard::Aruba::RvmEnv::Export < Metasploit::Yard::Aruba::RvmEnv::Variable
+  #
+  # CONSTANTS
+  #
+
+  # Matches line with format `export <name>=<quote><value><quote>`
+  REGEXP = /\Aexport (?<name>\S+?)(\s+;\s+\k<name>)?=(?<quote>"|')(?<value>.*?)\k<quote>\Z/
+
+  #
+  # Attributes
+  #
+
+  # @!attribute value
+  #   The value to which {Metasploit::Yard::Aruba::RvmEnv::Variable#name} should be set
+  #
+  #   @return [String]
+  attr_accessor :value
+
+  #
+  # Class Methods
+  #
+
+  # Parses line of `rvm env` output into an {Export} if it matches {REGEXP}.
+  #
+  # @param line [String] a line of `rvm env` output
+  # @return [Export] if line contains `export`.
+  # @return [nil] otherwise
+  def self.parse(line)
+    # use self:: so subclasses can override
+    match = self::REGEXP.match(line)
+
+    if match
+      new(
+          name: match[:name],
+          value: match[:value]
+      )
+    end
+  end
+
+  #
+  # Instance Methods
+  #
+
+  # @param attributes [Hash{Symbol=>String}]
+  # @option attributes [String] :name (see Metasploit::Yard::Aruba::RvmEnv::Variable#name})
+  # @option attributes [String] :value (see #value)
+  def initialize(attributes={})
+    attributes.assert_valid_keys(:name, :value)
+
+    super(name: attributes[:name])
+    @value = attributes[:value]
+  end
+
+  # Whether this export is the same class and has the same {#value} as `other`.
+  #
+  # @return [true] if `other.class` is `Metasploit::Yard::Aruba::RvmEnv::Export` and `other.value` is {#value}.
+  # @return [false] otherwise
+  def ==(other)
+    super(other) && other.value == self.value
+  end
+
+  # Set {Metasploit::Yard::Aruba::RvmEnv::Variable#name} to {#value}.
+  #
+  # @param options [Hash{Symbol => Object}]
+  # @option options [Metasploit::Yard::Aruba::RvmEnv::Unset] :from the old state of this variable
+  # @option options [Object] :world the cucumber world instance for the current scenario
+  def change(options={})
+    options.assert_valid_keys(:from, :world)
+
+    world = options.fetch(:world)
+
+    world.set_env(name, value)
+  end
+end

data/lib/metasploit/yard/aruba/rvm_env/prepend.rb

@@ -0,0 +1,35 @@
+# Recognizes `export`s that are actually prepending values to the pre-existing value as is the case with `PATH`.
+class Metasploit::Yard::Aruba::RvmEnv::Prepend < Metasploit::Yard::Aruba::RvmEnv::Export
+  #
+  # CONSTANTS
+  #
+
+  # Matches line with format `export <name>=<quote><value>$<name><quote>`.  `<value>` will contain trailing
+  # `File::PATH_SEPARATOR`, so it can be directly prepended to the current value of `<name>` to get the value to set
+  # the environment variable.
+  REGEXP = /\Aexport (?<name>\S+?)(\s+;\s+\k<name>)?=(?<quote>"|')(?<value>.*?#{File::PATH_SEPARATOR})\$\k<name>\k<quote>\Z/
+
+  # Replaces {Metasploit::Yard::Aruba::RvmEnv::Export#value `:from` value} with
+  # {Metasploit::Yard::Aruba::RvmEnv::Export#value this variable's value}.
+  #
+  # @param options [Hash{Symbol => Object}]
+  # @option options [Metasploit::Yard::Aruba::RvmEnv::Unset] :from the old state of this variable.
+  # @option options [Object] :world the cucumber world instance for the current scenario
+  def change(options={})
+    options.assert_valid_keys(:from, :world)
+
+    from = options.fetch(:from)
+    world = options.fetch(:world)
+
+    from_directories = from.value.split(File::PATH_SEPARATOR)
+    to_directories = value.split(File::PATH_SEPARATOR)
+
+    path = ENV[name]
+
+    to_directories.zip(from_directories) do |to_directory, from_directory|
+      path = path.gsub(from_directory, to_directory)
+    end
+
+    world.set_env(name, path)
+  end
+end