Compilation Instructions for Ruby on Rails

Compilation Guide

See the master compilation guidelines for instructions for other platforms.

Required Files

The Veracode Platform requires Ruby on Rails applications to be packaged using a custom Veracode rubygem.

Veracode Packaging Gem

The Veracode Platform requires you to run a special packaging gem prior to uploading your Ruby on Rails code. The gem uses features introduced in Ruby 1.9 to translate your application to an archive format that Veracode can scan. The resulting archive contains the following information:
  • Information about modules and classes, including disassembled instruction sequences for all Ruby methods (disassembly is not available for methods implemented in C).
  • A log of errors generated by the Veracode gem or other code in your application's environment during disassembly
  • Configuration files for Rails, Bundler, or other common gems.
  • Ruby source and template files.
  • A list of files included in the archive.
  • A recursive list of all files in the application directory (including those not contained in the archive).

Supported Ruby on Rails Versions

The Veracode Platform supports Ruby on Rails 3.x-5.x applications. The packaging gem requires the application be compatible with Ruby version 1.9.3, 2.0.x, 2.1.x., or 2.3-2.5. If you use a different version of Ruby in your development environment such as Ruby 1.8.7, or if you use an alternative Ruby interpreter such as JRuby, you need to download and install one of the supported versions of Ruby to package your application for Veracode to scan.

Language Platform Supported Versions Compatibility Support
Ruby Ruby on Rails Ruby 1.9.3, 2.0.x, 2.1.x, 2.3-2.5 / Rails 3.x Rails 4.x, 5.x

Packaging Your Ruby on Rails Application

Veracode recommends installing the gem using Bundler. Because the gem is included in your application's list of dependencies, Veracode recommends making a clean copy of the application source. Veracode also recommends using rvm to set up a clean Ruby environment prior to installing and running the gem. After installing rvm this environment can be created by running the following at the command line:

  1. rvm install <your version>
  2. rvm use <your version>@veracode --create

To install the veracode gem with Bundler, you should add it as a dependency of your application by adding the following lines to the application's Gemfile:

	#Add the following to /your/ruby/on/railsapp/Gemfile
	source 'https://gems.veracode.com'
	gem 'veracode'

Make the following changes and then use Bundler to download and install all of the application's dependencies (including Rails and the veracode gem):

  1. $ cd /your/ruby/on/railsapp
  2. railsapp $ rvm use <your version>@veracode
  3. railsapp $ bundle install --without development test # or other non-production dependency groups

If you have previously installed the veracode gem, you can ensure successful upload and the best scan quality by updating your gem to the latest version by running:


	railsapp $ bundle update veracode

As an alternative to Bundler, you can install the gem manually using the gem install command. Run the following at the command line once you have installed RVM and all other application dependencies are met:

  1. rvm install <your version>
  2. rvm use <your version>@veracode --create
  3. gem sources --add https://gems.veracode.com
  4. gem install veracode --prerelease

JRuby Applications

Veracode can scan many JRuby apps with some minor changes. JRuby-specific gems in the application's Gemfile should be labeled as such using the :platform option:

	source 'http://rubygems.org'

	gem 'rails', '3.1.0'

	gem 'activerecord-jdbcsqlite3-adapter', :platform => :jruby
	gem 'bouncy-castle-java', :platform => :jruby
	gem 'jdbc-sqlite3', :platform => :jruby
	gem 'jruby-openssl', :platform => :jruby
    
	gem 'json'
	gem 'jquery-rails'

When running the prepare command (see the Usage section below), use the --jruby option to enable the JRuby mode.

Packaging Guidance

The packaging gem includes a command line tool called veracode that you should run in your rails application directory with an appropriate subcommand and set of options. If no subcommand is provided, usage information including a list of available subcommands is displayed (equivalent to veracode help).

Note: For the veracode gem to properly analyze and package your application, you must disable the application setting config.cache_classes. You can check that this setting is disabled in the appropriate environment configuration file. For example, if you are using the development environment, RAILS_ENV=development veracode prepare, validate that config/environments/development.rb contains the line config.cache_classes = false.
            /your/ruby/on/railsapp/config/environments/development.rb
            YourApp::Application.configure do
            config.cache_classes = false
            
            # Log error messages when you accidentally call methods on nil.
            config.whiny_nils = true
            ...
         

Usage

	$ cd /my/ruby/on/railsapp
	railsapp $ rvm current      # validate correct ruby and gemset are being used
       railsapp $ veracode prepare

Prepare Command Syntax

	veracode prepare
	veracode prepare [-h|--help]
	veracode prepare [-v|--verbose] [-j|--jruby] [-D|--debug]
	veracode prep
    
	veracode prepare --help
	Usage: veracode prepare [options]
		-v, --verbose                    Run verbosely
		-j, --jruby                      Enable JRuby mode

The prepare subcommand creates the archive that you upload to the Veracode Platform.

The output of the gem is a compressed archive in .zip format that is saved in the tmp folder of the application (for example, /my/ruby/on/railsapp/tmp). The filename is veracode-[application name]-[YYYYmmddHHMMSS timestamp].zip and this is the file you upload to Veracode.

If an error occurs while preparing the application, an error log is available at tmp/veracode-[YYYYmmddHHMMSS timestamp]/error.log. Please include this file with any support requests you make to Veracode.

Supported Template Formats

Veracode supports the following template formats for analyzing Ruby on Rails applications:

  • ERB/Erubis
  • HAML
  • Builder