- Scan their software for potential security issues and violations of organizational policy.
- Prioritize vulnerabilities in the context of their applications.
- Understand the relationships between software components in their applications.
Software prerequisites
Before you begin, verify the following prerequisites:- All applications monitored by Endor Labs must be on Ruby versions 2.6 or higher.
- A Gemfile or a
*.gemspecfile must be present in your Ruby project. - Make sure your repository includes one or more files with
.rbextension.
Prepare Ruby projects
You can prepare your Ruby project before running a scan to lock its dependency versions in aGemfile.lock file.
Ensure your repository has a Gemfile and run the following command to generate the Gemfile.lock file:
Gemfile.lock, endorctl uses it for dependency resolution and does not generate it again.
Configure private RubyGems package repositories
Endor Labs supports fetching and scanning dependencies from private RubyGems package registries. Endor Labs will fetch resources from authenticated endpoints and perform the scan, allowing you to view the resolved dependencies and findings. See RubyGems package manager integrations for more information on configuring private registries.Run a scan
Perform a scan to get visibility into your software composition and resolve dependencies.If you use Endor Labs with an EU tenant, use
https://app.eu.endorlabs.com instead of https://app.endorlabs.com.Understand the scan process
Endor Labs looks forGemfile, *.gemspec, and Gemfile.lock files to find and monitor the dependency activity.
- A Gemfile is a configuration file used in Ruby projects to specify the required RubyGems (libraries or packages) for the project’s dependencies.
- A
*.gemspecfile is a RubyGems specification file used to define the metadata and dependencies for a RubyGem. Endor Labs importsbundlerwhen loading*.gemspecfiles so specifications that referenceBundlerconstants parse. - The
Gemfile.lockfile is automatically generated by Bundler. Refer to Bundler documentation for more information about getting started.
Gemfile.lock is not present in your project, Endor Labs generates this file and stores it in a temp directory. Endor Labs deletes the file after extracting dependency information.
Endor Labs’ dependency resolution mechanism assesses multiple factors, including compatibility, stability, and availability, to determine the most suitable version for usage. Your Ruby project uses the resolved dependency version during build or execution. The dependency graph shows whether a dependency is direct or transitive, whether it is reachable, and whether its source is available. The dependency graph provides a visual representation that allows you to examine the graphical details of these dependencies.
Call graphs
Endor Labs performs reachability analysis and generates call graphs for Ruby projects from the abstract syntax tree. You don’t have to build or install your project for Endor Labs to generate the call graph. Endor Labs also performs an inside-out analysis to determine the reachability of dependencies in your project. When generating Ruby call graphs, Endor Labs fetches private gems from the registry declared inGemfile.lock rather than from rubygems.org. If a private gem registry is configured for token authentication only (token_auth) without basic credentials, Endor Labs skips fetching that gem for call graph generation and logs a warning.
Set the following environment variable before running a scan to enable call graph generation.
Call graph generation is enabled by default for automated scans.
Known limitations
- Ruby call graphs resolve calls where they can statically and do not resolve dynamic method calls, including
method_missing,send,public_send,eval, and other metaprogramming patterns. - If a dependency cannot resolve in the Gemfile, the build for that specific package may not succeed. The package may no longer exist in the Gem package manager. Other packages in the workspace are scanned.
Troubleshoot errors
- Unresolved dependency errors:
The Gemfile is not buildable. Try running
bundler installin the root project to debug this error. - Resolved dependency errors: A dependency version does not exist or cannot be found. The package may no longer exist in the repository.