|Table of Contents|
Mend Supply Chain Defender detects and blocks malicious dependency updates.
Supply Chain Defender acts as a shield between you and the wild world of open-source libraries, allowing you to define policies around the usage of libraries and their versions. Under the hood, Mend runs extensive security checks to find potential vulnerabilities and exploits.
When you run your package manager commands with our plugin, all knowledge, policies and research are combined into one easy-to-understand verdict that you or your security team can use to control and mitigate potential problems before they hit production. The Supply Chain Defender heuristics learn with each package release, and whenever anything is discovered that could pose a threat to your organization, Mend will notify you about it.
Configuring a New Project
Prerequisites: Register the account.
Navigate to your organization’s projects list.
Click the Setup button.
In the setup view, navigate to the By applying changes manually section.
To set up Mend Supply Chain Defender, create a .
diffend.ymlfile in the main directory of the project and copy-paste the configuration settings from the UI.
Follow the remaining instructions specific to the package manager you are using.
Add our bundler
gemright after the source section of your
bundle installand you are ready to go!
Install our Supply Chain Defender package:
npm install -g https://my.diffend.io/releases/npm/stable.tgz
Prefix all calls to npm with diffend:
diffend npm install diffend npm i debug
You can also alias all the npm commands in your shell by putting the presented code in an appropriate file (~/.bash_aliases, ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish):
alias npm='diffend npm'
npm installand that is all.
Yarn 1 setup
Add our Yarn 1 plugin into your project by running the following commands:
Code Block language bash
mkdir -p .yarn/releases wget https://my.diffend.io/releases/yarn/1/stable.js -O .yarn/releases/diffend-stable.js echo 'yarn-path ".yarn/releases/diffend-stable.js"' >> .yarnrc
Run yarn install and you are ready to go
Yarn 2 setup
Add our Yarn 2 plugin into your project by running the following command:
yarn plugin import https://my.diffend.io/releases/yarn/2/stable.js
Run yarn install and you are ready to go!
Running Supply Chain Defender Checks
Mend Supply Chain Defender plugin runs automatically when the following commands are executed:
bundle exec (for environments other than test and development)
bundle secure (introduced by the Ruby plugin)
yarn install (yarn1 and yarn2+)
yarn upgrade (yarn1)
yarn remove (yarn1, yarn2+)
yarn check (yarn1)
yarn add (yarn1, yarn2+)
yarn up (yarn2+)
Whenever you run any of those commands, Mend Supply Chain Defender will make sure that the packages you are trying to download or use are safe and that they meet all the requirements of the organization. This process is fully automatic and you do not have to do anything.
The secure command can be used as a separate step in a CI/CD pipeline to ensure everything is as expected.
In case Mend Supply Chain Defender would stop the bundle process, it will exit with an exit code 1 and will print out the security verdict URL that you can visit for more details.
Mend Supply Chain Defender won't stop the execution of any exec commands. Instead if needed, it will issue a warning verdict on the UI.
Mend Supply Chain Defender works automatically each time you run bundle commands.
Reviewing and Understanding the Security Verdicts
Security verdicts are an essential part of Mend Supply Chain Defender. They ensure that all of your organization requirements in the context of each bundle operation are met. That way we can prevent the usage of packages and their versions that could cause engineering and legal harm.
Each aspect that we check has a dedicated component called guard. Guards can be configured as well as disabled in the Security guards settings section of your organization if they don't meet your requirements.
After running, Supply Chain Defender can give you one of the following verdicts:
allow- everything is good.
warn- something was off but we did not stop the execution.
deny- command execution has been stopped.
All of them correspond with the verdicts you can see on the UI.
Any non-allow verdict means, that something is not meeting with your organization’s security and quality requirements.
When you open the verdict page, you will be presented with all the guards that had doubts in regards to your packages.
You can disable particular guards actions for both packages and their versions in the Gems and versions usage section of your organization settings or by clicking on the gem name or its version on the verdict view directly.
Note: Direct packages and versions usage override on the verdict page do not work for all the guards yet.
Mend Supply Chain Defender is configurable because a single optimal set of settings does not exist. A lot depends on the type of organization you are in, projects you build, and customers you have.
If you have any doubts or need any help figuring out a proper setup for yourself, don't hesitate to contact us.
You should review any non-allow verdicts that we tell you about.
Setting up maximum verdict for particular commands
When using Mend Supply Chain Defender in a legacy system, you may notice, that getting things to a stable and secure state may take a while.
To prevent Mend Supply Chain Defender from blocking all of the commands, you may lower the maximum verdict it reports.
Navigate to the Plugin behaviour settings page of the appropriate technology of your organization.
Select the maximum verdict for a given command.
Press the Save button.
That way you can slowly resolve all of the reported issues one after another, without blocking the development of your project.
You can use our Quality Score to keep track of the improvement of your dependencies setup.
Understanding Quality Score
The Quality Score is a numeric value in between
100 that provides a quick overview of the state of your Gem file. The score is a composite of the sub-scores from each of the Guards and provides a convenient way to monitor trends in so you can take action whenever you see quality degradation.
You can use the Quality Score to keep track of the improvements of your Gem file.
Re-running checks from the UI
When you apply changes to your configuration, you may want to check how it affects the bundling process you were running. You can either run the given command you were interested in again to see a new verdict or you can re-run the checks directly from the UI, by clicking on the Re-run checks button.
The Re-run checks button is available for the security verdicts except those that were finished without any issues. It is available above the successful verdicts on the right side of the UI.
Re-running checks is the easiest way to see how your changes will affect execution of the given command.
Continuous Integration and Delivery environment setup
Mend Supply Chain Defender protects every crucial
bundle command out of the box, but you can still easily set it up as a separate step within your Continuous Integration and Delivery system.
Doing so will allow you to receive notifications based on the CI/CD results via our notifications system.
To set it up, please follow the instructions for the appropriate CI/CD system.
If you are using a different CI system, the setup should be similar. Please contact us if you have examples of other CI systems.
Deployment and production environment setup
Mend Supply Chain Defender requires minimal effort to make it work with the majority of ways you can deploy your applications. If there are no hints below for your way of deployment, it means, that all you need to do is:
DIFFEND_ENVvariable to match your deployment environment.
Make sure, that you have the
.diffend.ymlin your version control system.
You need to remember about setting the
DIFFEND_ENV to match your environment.
Please make sure, to always run
bundle install instead of running
bundle check. To do so, put the following code in your
Make sure, that the
.bundle directory is not amongst the
The changes you need to make, come from limitations of the Bundler plugin system.
Please make sure, that the
.diffend.yml file is included before you run any
bundle commands during the container build process.
To do so, add the
.diffend.yml file into your
Dockerfile, before adding the
When using Heroku, please make sure, that the
.diffend.yml file is included before you run any
bundle commands during the container build process.
If you are using the Heroku Buildpack for Ruby applications you need to set up following environment variables based on the
.diffend.yml file content:
Heroku Buildpack for Ruby requires you to set the three environment variables mentioned above.
monitor gem keeps track of the state of your deployment environments automatically.
Thanks to that, whenever a new threat that could pose a risk to your application is being detected, we can notify you about that using Slack.
In order to receive
Notifications are a great way to make sure, that your team becomes aware of emerging vulnerabilities the moment they are detected.
Connecting Mend Supply Chain Defender to Slack
Navigate to the Notifications settings page of your organization.
herelink visible in the information box. You will be redirected to the Slack platform settings page.
Select a channel where you want Mend Supply Chain Defender to post security notifications and press the Allow button.
You will be redirected back to the Mend Supply Chain Defender notification settings page and a Slack welcome message will be sent to your workspace channel.
Mend Supply Chain Defender sends messages based on events that occur while protecting your applications. Below you can find a list of the events that trigger notifications, together with their short descriptions and other useful details.
New bundle state detected
Mend Supply Chain Defender emits message based on this event whenever you deploy changed to your
Gemfile that affect given environment.
Awareness of newly updated libraries deployed can help you debug when your new code presents unexpected behaviors.
New verdict detected
Mend Supply Chain Defender emits a message based on this event whenever the verdict associated with your deployment has changed.
Bundle secure execution alert
Mend Supply Chain Defender emits a message based on this event whenever there is anything in your
Gemfile that requires attention.
While we are sorry to see you go, we won't make things hard for you. We just kindly ask you to provide us with any feedback you might have on the reasons.
Removing Bundler plugin and gem
Due to some Bundler limitations, you will have to re-bundle your project after removing appropriate files. Just run the code below inside of your project main directory.
Removing Yarn 2 plugin
Due to some Yarn 2 limitations, you will have to re-run the
install command after removing appropriate files. Just run the code below inside of your project main directory.
Questions and answers
Can the .diffend.yml file be committed into our repository version control system?
Yes. This file contains only shareable keys with write-only permissions. The only thing you need to keep in mind in case of open-source projects, is that you will see results of all the security checks of whoever runs your project.
By default, we don't want to stop your running processes or cause any unpredictability in the code execution. Please contact us, if this is a functionality you would want to see.
We are working on a notifications engine that will notify you the moment any threat is detected that could cause risks to your production running processes.
No. All the private repository credentials and other private data is being stripped away before anything is being sent to us.
Just in case, we also have an extra sanitization layer in the API. Even if any private details would be sent, they do not end up being stored or used.
diffend-monitor never executes any code in response to our platform replies. It does not rely on the response content for operations. Its primary purpose is to ping our servers periodically, so we know that the given process is running. We need this information for our real-time monitoring services.
First of all, try to reinstall the plugin by running the following commands in your project root directory:
Both plugin and the monitor operate in the current Bundler execution context.
That means that we won't notify you about issues with gems in your
Gemfile that do not pose any risk as they are not being downloaded or executed.
That is why it is essential to use both the plugin and the monitor to integrate Mend Supply Chain Defender within your CI system.This page is available at Mend’s new Knowledge Hub, here: https://docs.mend.io/bundle/community_tools/page/mend_supply_chain_defender_-_managing_software_supply_chain_risks.html