Adding an authority

Authorities have an abbreviation, summary and url and can also be marked as obsolete, as is the case with MIL (milw0rm). The abbreviation will be the string that module authors in metasploit-framework put as the first element in the [<abbreviation>, <designation>] Array<Array(String, String)> for the module 'References'. The summary is an expansion of the abbreviation or acronym. For example, 'CVE' is the abbreviation, but 'Common Vulnerabilities and Exposures' is the summary. It is used for more verbose displays in the UI. Finally, the url is the top-level URL where the database of all references for the authority can be found. Secure, https:// URLs should be used if they are available. In the case of obsolete authorities like milw0rm, the url can be a link to wikipedia or other historical record of the authority.

Seed

The Metasploit::Model::Authority models are seeded. For the purpose of testing the seeds in metasploit-model, the seeds are stored in a constant on Dummy::Authority and speced by Metasploit::Model::Authority shared example, which will also check the seeds for Mdm::Authority in metasploit_data_models.

Code

Open spec/dummy/app/models/dummy/authority.rb and add the seed attributes to the SEED_ATTRIBUTES Array<Hash>. The Hashes should be ordered lexicographically by the :abbreviation value.

SEED_ATTRIBUTES = [
# ...
    {
        abbreviation: '<abbreviation>',
        obsolete: false,
        summary: '<summary>',
        url: '<url>'
    }
# ...
]

Spec

Open the spec/shared/examples/metasploit/model/authority.rb shared example. In the 'seeds' context add an it_should_behave_like 'Metasploit::Model::Authority seed' shared example usage to check that seed is running. The it_should_behave_like 'Metasploit::Model::Authority seed should use the same ordering as the seeds in Dummy::Authority.

Metaspoit::Model::Spec.shared_examples_for 'Authority' do
# ...
  context 'seeds' do
  # ...
     it_should_behave_like 'Metasploit::Model::Authority seed',
                          abbreviation: '<abbreviation>',
                          :extension_name => 'Metasploit::Model::Authority::<titleized abbreviation>',
                          :obsolete => false,
                          :summary => '<summary>',
                          :url => '<url>'
  # ...
  end
# ...
end

designation_url helper

The designation_url helper method transforms an Metasploit::Model::Reference#designation into a Metasploit::Model::Reference#url based on Metasploit::Model::Reference#authority.

Code

Add lib/metasploit/model/authority/<underscored abbreviation>.rb:

# <summary> auhtority-specific code
module Metasploit::Model::Authority::<titleized abbreviation>
  # Returns URL to {Metapsloit::Model::Reference#designation the <abbreviation> ID's} page on <site>.
  #
  # @param designation [String] <format>
  # @return [String] URL
  def self.designation_url(designation)
    <transform designation to URL string>
  end
end

Spec

Sequence

The following specs will make use of an authority-specific sequence for generating Metasploit::Model::Reference#designation of the correct . So, when adding an authority you need to make a new designation sequence in spec/factories/metasploit/model/references.rb.

FactoryGirl.define do
  # ...

  #
  # Metasploit::Model::Authority-specific Metasploit::Model::Reference#designation sequences
  #

  # ...
  
  sequence :metasploit_model_reference_<underscored abbreviation>_designation do |n|
    "<format>" % n
  end  

  # ...
end

Implementation

Add spec/lib/metasploit/mode/authority/<underscored abbreviation>_spec.rb

require 'spec_helper'

describe Metasploit::Model::Authority::<capitalized abbreviation> do
  context 'designation_url' do
    subject(:designation_url) do
      described_class.designation_url(designation)
    end

    let(:designation) do
      FactoryGirl.generate :metasploit_model_reference_<underscored abbreviation>_designation
    end

    <test URL format>
  end
end

Usage by Metasploit::Model::Reference

In spec/shared/examples/metasploit/model/reference.rb in the 'derivation' 'with authority' context, add a context with the . The context should be inserted using the same ordering as the seeds.

Metasploit::Model::Spec.shared_examples_for 'Reference' do
  # ...
  context 'derivation' do
    # ...
    context 'with authority' do
      # ...
      context '<abbreviation>' do
        let(:abbreviation) do
          '<abbreviation>'
        end

        let(:designation) do
          FactoryGirl.generate :metasploit_model_reference_<underscored abbreviation>_designation
        end

        it_should_behave_like 'derives', :url, validates: false
      end
      # ...
    end
    # ...
  end
  # ...
end