bugcrowd / vrt-ruby

Ruby library for interacting with Bugcrowd's VRT

VRT Ruby Wrapper

While the Content and Structure is defined in the Vulnerability Rating Taxonomy Repository, this defines methods to allow for easy handling of VRT logic. This gem is used and maintained by Bugcrowd Engineering.

Getting Started

Add this line to your application's Gemfile:

gem 'vrt'

To create the initializer:

rails generate vrt:install

Usage

For convenience in development, we provide a utility for spinning up a playground for playing with the gem. You can invoke it with:

bin/console

When one has a VRT Classification ID, one can check it's validity:

vrt = VRT::Map.new

vrt.valid?('server_side_injection')
=> true

vrt.valid?('test_vrt_classification')
=> false

Get a pretty output for its lineage:

vrt = VRT::Map.new

vrt.get_lineage('server_side_injection.file_inclusion.local')
=> "Server-Side Injection > File Inclusion > Local"

The information within that node:

vrt = VRT::Map.new

vrt.find_node('server_side_injection.file_inclusion.local')

Which returns the corresponding VRT::Node. This node has a variety of methods:

vrt_map = VRT::Map.new

node = vrt_map.find_node('server_side_injection.file_inclusion.local')

node.children # Returns Child Nodes

node.parent # Returns Parent Node

node.priority

node.id

node.name

node.mappings # The node's mappings to other classifications

If you need to deal with translating between versions

VRT module also has a find_node method that is version agnostic. This is used to find the best match for a node under any version and has options to specify a preferred version.

Examples:

# Find a node in a given preferred version that best maps to the given id
VRT.find_node(
  vrt_id: 'social_engineering',
  preferred_version: '1.1'
)
# returns 'other'

# Aggregate vulnerabilities by category
VRT.find_node(
  vrt_id: vrt_id,
  max_depth: 'category'
)

# Query for vulnerabilities by category while maintaining deprecated mappings by adding
# deprecated ids to the search with `all_matching_categories`
categories_to_search_for += VRT.all_matching_categories(categories_to_search_for)

Mappings and external links

Mappings

A mapping is a relationship defined from a node to another classification like cvss or cwe or to more information like remediation advice. The relationships that are defined in mappings are maintained by the Bugcrowd team as well as external contributors to the VRT repo.

Example getting the CWE for a particular VRT ID

VRT.find_node(
  vrt_id: 'server_security_misconfiguration.unsafe_cross_origin_resource_sharing'
).mappings[:cwe]

=> ["CWE-942", "CWE-16"]

Third party links

These are simillar to mappings, but the relationships are maintained by an external party instead of Bugcrowd.

Example getting Secure Code Warrior training link for a particular VRT ID

VRT.find_node(
  vrt_id: 'server_security_misconfiguration.unsafe_cross_origin_resource_sharing'
).third_party_links[:scw]

=> "https://integration-api.securecodewarrior.com/api/v1/trial?id=bugcrowd&mappingList=vrt&mappingKey=server_security_misconfiguration:unsafe_cross_origin_resource_sharing&redirect=true"

vrt-ruby's Issues

Fix undeclared ActiveSupport dependency on `.try`

This uses the .try method that is defined by ActiveSupport, but we do not depend on ActiveSupport
https://github.com/bugcrowd/vrt-ruby/pull/24/files#diff-2c90cdf2771394e4027dd3237e210d0fR30

We do not want to depend on ActiveSupport so let's find a way to remove that.

More importantly that code path is not tested so let's make a spec for it.

Add pull request template

It'd be great to have a pull request template with a note about adding an entry to the changelog, not changing version.rb, etc.

VRT::Map#find_node hits uninformative error when passed bad input

This error is thrown at: https://github.com/bugcrowd/vrt-ruby/blob/master/lib/vrt/map.rb#L21:

def find_node(string, max_depth: 'variant')
  # return nil unless valid_identifier?(string)
  @_found_nodes[string + max_depth] ||= walk_node_tree(string, max_depth: max_depth)
end

when param: string == nil

     NoMethodError:
       undefined method `+' for nil:NilClass
     # ./lib/vrt/map.rb:22:in `find_node'

when param: !string.is_a? String

     TypeError:
       String can't be coerced into Fixnum
     # ./lib/vrt/map.rb:22:in `+'
     # ./lib/vrt/map.rb:22:in `find_node'

Should be fine to just return nil in these cases since that is what we do when no node can be found.

Rename `Vrt::Map`

Now that we have mappings and maps, we need to rename Vrt::Map to be something like Vrt::Hierarchy or something similar. I think that title more accurately describes what it is.