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 versions | Ruby versions |
---|---|
5.x | 2.3–2.7 |
6.0 | 2.5–2.7 |
6.1 | 2.5–3.2 |
7.0 | 2.7–3.2 |
7.1 | 2.7–3.4 |
7.2 | 3.1–3.4 |
8.0 | 3.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, run:
bundle exec veracode prepare
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
To get debugging output, run:
bundle exec veracode prepare -vD | tee veracode-prepare.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-prepare.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.