Return to Blog

Introducing Patchwork: Dependency Monitoring for Open Source Packages

Like many leading technology companies, Factual’s engineering teams leverage open source code to avoid reinventing the wheel.

As great as these open source packages are, they introduce their own set of challenges:

  • Exposure to vulnerabilities from known security exploits
  • Inclusion of buggy code
  • Technical debt from reliance on unmaintained libraries
  • Increasingly painful maintenance as versions get more outdated

Unfortunately, staying up to date on our dependencies to mitigate these problems can be a huge, time consuming burden. Since there is no singular method to announce new releases or security vulnerabilities, spending five minutes manually searching for every package we use could take 15 or more hours – work that must be replicated in its entirety each and every time we need more information. Clearly, this is an enormous resource burden, especially if we want to regularly check that all of our packages are in working order.

To tackle this issue, Factual recently began a project to research, identify, and implement a more automated approach to maintaining awareness of dependencies and their states.


Earlier this quarter, Factual’s Front team began researching solutions to keep track of packages used across our projects.

We had a few guiding principles:

The solution should be as general and low-effort as possible. Realistically, processes that take lots of developer time to configure or run are used rarely, which would negate the usefulness of the solution in the first place.

We should be able to control access to our code. Allowing outside tools access to Factual’s code repositories can lead to the same security concerns we are trying to prevent. Our final solution should not, for example, require full access to files unrelated to dependency packages.

We should generate as much information as possible from only the package files. In order to triage security concerns as they come in, we need to know more than the simple fact that a security vulnerability exists. With more information, we are less likely to either overlook a serious exploit or spend hours chasing down information on a small bug that does not affect our code at all.

During the initial research phase, we identified VersionEye, a notification service and database that constantly collects information on open source projects, as a great tool to build upon. It’s open source, provides an API as an alternative to requesting code access, and has already done the complex task of aggregating security and versioning information for over 1.5 million packages on many different platforms from all across the web.


Patchwork is a command-line tool built on the VersionEye API that:

  • Searches for dependency files in a given repository
  • Uploads them to VersionEye to check each package against their database of version updates and security vulnerability announcements
  • Posts the aggregated results to Slack
  • Deletes the VersionEye project upon completion so your account isn’t full of uploads from Patchwork

Patchwork wraps the VersionEye API and its informational databases in a simple yet highly configurable interface to make continued monitoring easy and effective. And it was built during Factual’s 6th Annual Hackathon!


Find your dependency files, no matter where they are. Patchwork can search as deeply as you’d like through nested directories with the traversal_depth parameter in the configuration file. If performance is a concern with large repositories, you can also easily exclude certain directories from the search by adding their names to the subdirectory_blacklist in the same file.

Know if your npm packages have outdated or vulnerable dependencies themselves – even if they’re unreported. By default, the node_modules subdirectories are blacklisted so you don’t waste time or resources looking up your dependencies’ dependencies; however, overriding this default will check the package.json of each of these modules in turn and could help you find dependencies that might be affected by an exploit in a common 3rd party package.

Generate clean, actionable notices in Slack. All security notices contain a short description in the title with a link to more information, a longer description that can be expanded, and the exact path to the dependency file(s) containing the vulnerable package. They are also colored based on recency – if a security notice has been reported in the last two weeks, it will be bright red so it is easily distinguishable from old reports that have already been assessed.

Versioning updates are grouped by type (maintenance, minor, major) and also include the path to each mention of a given package in the searched directory, along with the package version included and the highest package version currently available.

Switch technologies without a hitch. Patchwork supports the full range of dependency files parsed by the VersionEye API, and it does not care if a repository contains more than one type of file. For example, developers can run Patchwork on their home directory to quickly find updates and security notices for all projects in one place, regardless of language differences. If a project begins its life in one framework and later moves to another, Patchwork will keep functioning without the need for any additional configuration.


Patchwork is now available publicly at and through the Python package manager as factual-patchwork!

At its simplest, Patchwork requires only three parameters in a configuration file: the API key of the user’s VersionEye account, the organization name of the user’s VersionEye account, and the webhook URL for their Slack integration. These parameters can be specified by running the patchwork-config command, which brings up the following file in your favorite editor:

Full instructions and customization options are available in the README. Once these parameters are saved, just run patchwork from the directory you want to search and see your results in Slack!

Here’s a recap of all the commands needed to run Patchwork:

$  pip3 install factual-patchwork
$  patchwork-config
$  cd /path/to/my/code/repository
$  patchwork

We recommend running Patchwork before every release (or more frequently!) to catch updates and security vulnerabilities before code reaches production.


If you’re using Patchwork, we’d love to hear from you! Bug reports and contributions can be submitted to the GitHub repo. Comments and other feedback can be sent to

Laura Eckman, Front Team Intern, Summer ‘17