Skip to main content

Ruby on Rails packaging

Your Ruby on Rails applications must meet specific packaging requirements before you can submit them for scanning.

See Supported languages and platforms for instructions for other platforms.

You can analyze applications using Veracode Static Analysis or Veracode Software Composition Analysis (SCA) upload and scan, if licensed. For SCA agent-based scan requirements, see Using Veracode SCA with Programming Languages.

Automated packaging​

Auto-packaging simplifies the packaging process for Ruby on Rails projects.

Required files​

The Veracode RubyGem generates a ZIP file containing all necessary files for analysis, ensuring compatibility with Veracode Static Analysis.

Supported Ruby on Rails versions​

Rails versionsRuby versions
5.x2.3–2.7
6.02.5–2.7
6.12.5–3.2
7.02.7–3.2
7.12.7–3.4
7.23.1–3.4
8.03.2–3.4

Veracode Static Analysis does not support non-Rails applications.

Use of the Veracode RubyGem on a non-Rails Ruby application will not result in a scannable artifact.

Supported template formats​

Veracode supports these template formats for analyzing Ruby on Rails applications:

  • Builder
  • ERB/Erubis
  • HAML

Packaging guidance​

Prerequisite - Ensure you have the right environment​

Veracode Static Analysis does not analyze Ruby source code directly. Instead, it uses the Veracode RubyGem to compile your Ruby code into YARV (Yet Another Ruby VM) instructions, which are the only supported input for analysis of Ruby applications.

To achieve this, the Veracode RubyGem runs your application server, loading all Ruby files and compiling them using RubyVM::InstructionSequence. The resulting instructions are stored in a text file within a ZIP archive, which can then be used for analysis.

This means that when you run veracode prepare, the machine you use to package your application must be setup for your application server to run. For example, if your application server does not run without an environment variable called API_KEY and this is not available when running veracode prepare, then veracode prepare will not be able to run.

We typically recommend you use a container image used by the development team.

Prerequisite - Opening a terminal and navigating to your Ruby application​

In a terminal window change directories to your Ruby application, for example:

cd /your/ruby/on/railsapp

Prerequisite - Ruby​

To ensure Ruby is installed with the correct version, run the following command:

ruby --version

Check the output against our Supported Ruby on Rails versions.

Prerequisite - Selecting a Rails environment​

The Veracode RubyGem uses RAILS_ENV which is set to development by default. You may wish to select the production environment as this may produce improved results, namely no results from development functionality. However, depending on your application's configuration, it may not significantly impact results and may make packaging significantly harder. Veracode recommends starting with the default development environment and evaluating the results. If these results contain many non-production relevant flaws and you want to switch to the production environment you can do so with:

# OPTIONAL - Using a production environment may simplify results but can complicate packaging due to configuration differences. Proceed with caution.
export RAILS_ENV=production

Important:

For the veracode gem to properly analyze and package your application, you must disable the application setting config.cache_classes.

You can verify that this setting is disabled in the appropriate environment configuration file. For example, if you are using the development environment, 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

Prerequisite - Ruby Gems​

Veracode Static Analysis and Veracode Software Composition Analysis require use of Bundler. Run the following command to ensure you have bundler installed and working:

# OPTIONAL - If you are using the "production" RAILS_ENV you should consider adding "--without development test".
bundle install

Veracode Static Analysis requires use of Ruby on Rails. Run the following command to ensure you have Rails installed:

bundle info rails

Check the output against our Supported Ruby on Rails versions.

Prerequisite - Veracode RubyGem​

Veracode Static Analysis requires that you install the latest version. Check if you already have the veracode gem installed with:

bundle info veracode

If you have the gem installed, update it with:

bundle update veracode

If you do not, install the gem with:

bundle add veracode --source "https://rubygems.org"

For Ruby versions earlier than 2.4:

Add the following lines to your Gemfile to specify a compatible version of rubyzip:

bundle add rubyzip --version "~> 1.0" --source "https://rubygems.org"

Prerequisite - Test your application runs​

To test your application runs in the environment, before packaging you should run:

bundle exec rails server

If the application server fails to start, review the error messages and ensure all dependencies are correctly installed and configured.

You can also consider targeting a different Rails environment. For more information see Before you get started - Selecting a Rails environment.

Packaging the application​

To package the application, you should run the following command:

bundle exec veracode package

In the tmp folder of the application, find the new file named veracode-[application name]-[YYYYmmddHHMMSS timestamp].zip. Upload this ZIP archive to Veracode.

Troubleshooting​

For additional debugging output, you can run:

bundle exec veracode package -vD | tee veracode-package.log

If an error occurs while preparing the application, you can view the error log at tmp/veracode-[YYYYmmddHHMMSS timestamp]/error.log. Include this file and the above veracode-package.log with any support requests you make to Veracode.

If this does not resolve your issue please consider scheduling a consultation call to review your packaging.

Contents of the packaged zip file​

The resulting archive contains this information:

  • 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 environment during disassembly.
  • Configuration files for Rails, Bundler, or other common gems.
  • Ruby source and template files.
  • A list of included files.
  • A recursive list of all files in the application directory, including those not contained in the archive.
Last updated on