The npm Blog

Today, we’re excited to announce a simple, powerful new way to track changes to the npm registry — and build your own amazing new developer tools: hooks.

What?

Hooks are notifications of npm registry events that you’ve subscribed to. Using hooks, you can build integrations that do something useful (or silly) in response to package changes on the registry.

Each time a package is changed, we’ll send an HTTP POST payload to the URI you’ve configured for your hook. You can add hooks to follow specific packages, to follow all the activity of given npm users, or to follow all the packages in an organization or user scope.

For example, you could watch all packages published in the @npm scope by setting up a hook for @npm. If you wanted to watch just lodash, you could set up a hook for lodash.

When?

If you have a paid individual or organizational npm account, you can start using hooks right now.

Each user may configure a total of 100 hooks, and how you use them is up to you: you can put all 100 on a single package, or scatter them across 100 different packages. If you use a hook to watch a scope, this counts as a single hook, regardless of how many packages are in the scope. You can watch any open source package on the npm registry, and any private package that you control (you’ll only receive hooks for packages you have permission to see).

How?

Create your first hook right now using the wombat cli tool.

First, install wombat the usual way: npm install -g wombat. Then, set up some hooks:

Watch the npm package: wombat hook add npm https://example.com/webhooks shared-secret-text

Watch the @slack organization for updates to their API clients: wombat hook add @slack https://example.com/webhooks but-sadly-not-very-secret

Watch the ever-prolific substack: wombat hook add --type=owner substack https://example.com/webhooks this-secret-is-very-shared

Look at all your hooks and when they were last triggered: wombat hook ls

Protip: Wombat has several other interesting commands. wombat --help will tell you all about them.

We’re also making public an API for working with hooks. Read the docs for details on how you can use the API to manage your hooks without using wombat.

Why?

You can use hooks to trigger integration testing, trigger a deploy, make an announcement in a chat channel, or trigger an update of your own packages.

To get you started, here are some of the things we’ve built while developing hooks for you:

• npm-hook-receiver: an example receiver that creates a restify server to listen for hook HTTP posts. Source code.

• npm-hook-slack: the world’s simplest Slackbot for reporting package events to Slack; built on npm-hook-receiver.

• captain-hook: a much more interesting Slackbot that lets you manage your webhooks as well as receive the posts.

• wombat: a CLI tool for inspecting and editing your hooks. This client exercises the full hooks API. Source code.

• ifttt-hook-translator: Code to receive a webhook and translate it to an IFTTT event, which you can then use to trigger anything else you can do on IFTTT.

• citgm-harness: This is a proof-of-concept of how node.js’s Canary in the Gold Mine suite might use hooks to drive its package tests. Specific package publications trigger continuous integration testing of a different project, which is one way to test that you haven’t broken your downstream dependents.

What do you think?

We’re releasing hooks as a beta, and where we take it from here is up to you. What do you think about it? Are there other events you’d like to watch? Is 100 hooks just right, too many, or not enough?

We’re really (really) (really) interested to see what you come up with. If you build something useful (or silly) using hooks, don’t be shy to drop us a line or poke us on Twitter.

What’s next?

This is the tip of an excitement iceberg — exciteberg, if you will — of cool new ways to use npm. Watch this space!

npm ♥ you!

The 283,000 (!) packages in the npm Registry are only useful if it’s easy for developers to integrate them into their projects and deploy their code, so we’re excited by any chance to streamline your workflow.

If you work with Bitbucket, starting today, it’s easier than ever to install and publish npm private packages — to either your npm account or your self-hosted npm Enterprise installation.

Bitbucket Pipelines is a new continuous integration service built into Bitbucket Cloud for end-to-end visibility, from coding to deployment. We’re excited that they’re launching with npm support.

Why?

• When it’s easier to work with packages, developers do. This integration helps split monolithic projects into multiple npm modules. More, smaller packages means code discovery and re-use, which saves you from reinventing the wheel.
• It’s all in one place. See pipeline information and work with npm right in Bitbucket commits, branches, and PRs, without context switching and waiting for feedback to see if you broke a build.
• You can automate tedious parts of the development workflow. (Did you write a test for that?…)
• It’s easy. To get started, just add a build configuration file into a Bitbucket repo.

How?…

Working with private packages in the npm registry

1. Use the bitbucket-pipelines.yml supplied in this repository.
2. Set the NPM_TOKEN environment variable.
   • This token can be found in your local ~/.npmrc, after you log in to the registry.
3. Enable pipelines

Working with private packages in npm Enterprise

1. Use the bitbucket-pipelines.yml supplied in this repository.
2. Set the NPM_TOKEN environment variable:
   • This token can be found in your local ~/.npmrc, after you log in to the registry.
3. Set NPM_REGISTRY_URL to the full URL of your private registry (with scheme).
4. Enable pipelines.

New in the Bitbucket Connect add-on: private packages

Alongside the new pipelines integration, the npm for Bitbucket add-on has been updated to support private modules.

This helps complete an elegant CI/CD workflow:

• Bitbucket Pipelines installs your private and public npm modules, ensuring that your build continues passing;
• npm for Bitbucket Cloud provides constant feedback, ensuring that an up-to-date version of your module has been published.

Get started by installing the add-on now.

Now what?

We have more exciting integrations and improvements in the … pipeline (sorry), but it helps to know what matters to you. Don’t be shy to share feedback in the comments or hit us up on Twitter.

Last month, we released a “one-click” installer for npm Enterprise on AWS. Fresh on its heels, we’re excited to announce support for Google Compute Engine

Getting npm Enterprise up and running on GCE is easy:

Install and configure the Google Cloud SDK

• Download the Google Cloud SDK.
• Authenticate: gcloud auth login.
• Configure your project and default zone:
  • gcloud config set project my-project
  • gcloud config set compute/zone us-east1-d

Run the npm Enterprise deploy template

• Fetch npm’s configuration template:

  curl -XGET https://raw.githubusercontent.com/npm/npme-installer/master/npme-gce.jinja > /tmp/npme-gce.jinja

• Run the npm Enterprise deploy template:

  gcloud deployment-manager deployments create npme-deployment --config /tmp/npme-gce.jinja --properties="zone=us-east1-d"

Note: You can replace us-east1-d with whatever zone you’d like to deploy to.

Go grab a coffee

When you get back, if you visit your cloud console you’ll see a running server called npm-enterprise. That’s all there is to it!

Configure your instance

You can configure your instance by visiting port 8800. Our npm Enterprise will point you in the right direction with information on the various settings that you can configure.

What’s next?

It’s our continued goal to make npm Enterprise painless to run, regardless of your infrastructure. Are we missing a platform that you’d love for us to support? Let us know in the comments.

A story in 6 graphs

How many npm users are there? It’s a surprisingly tricky question.

There are a little over 211,000 registered npm users, of whom about 73,000 have published packages. But far more people than that use npm: most things npm does do not require you to login or register. So how many are there, and what are they up to? Our first and most obvious clue is the number of packages they are downloading:

How many packages are downloaded?

That’s over a billion downloads per week, and that only counts package installs that weren’t already in cache – about 66% of npm package installs don’t require downloading any packages, because they fetch from the cache. Still, the growth is truly, without exaggeration, exponential.

So what’s driving all the downloads? Are the same people building ever-more-complicated applications, downloading more packages to do it? Are the same people running build servers over and over? Or are there actually more people? Our next clue comes from the number of unique IPs hitting the registry:

How many IPs hit the registry?

Here’s a ton of growth again, close to 100% growth year-on-year, but much more linear than the downloads: 3.1 million IPs hit the registry in March. Of course, IP addresses are not people. Some of these IPs are build servers and other robots. Other IP addresses are companies or educational institions that serve thousands or even tens of thousands of people. So while it doesn’t correlate perfectly, generally speaking, more IPs means more people are using npm.

How many times does npm get run?

Every time npm runs it generates a unique ID that it sends as a header for every request it makes during that run. This ID is random and not tied to you in any way, and once npm finishes running it is deleted. We use this ID for debugging the registry: it lets us see that these 5, 10 or 50 requests were all part of the same operation, which makes it easier to see what’s going on when somebody has a problem. It also makes it possible to say roughly how many times npm is run – or at least, run in a way that makes a request to the registry. There were 84 million npm sessions in March: this number is growing faster than IPs, but less quickly than downloads.

We can take these last two and combine them:

How many packages per npm run?

This number is interesting because it’s not going anywhere. The ratio of packages downloaded to npm sessions is essentially constant (this is not the same as the number of packages downloaded per install, because many npm sessions don’t result in downloads). But this is a clear signal: the number of packages per install isn’t rising. Applications aren’t getting notably more complicated; people are installing packages more often because they are writing more applications.

Here’s a final clue:

How many packages per IP?

The number of packages downloaded by an IP is also rising linearly. So, not only are more people using npm, but the people who are already using npm are using it more and more frequently. And then of course there’s this number:

Web users

Another way of counting npm users is counting people who visit npm’s website. This also grew enormously; 400% since we started the company. In the last 90 days, npm saw just over 4 million unique users visit our site. Ordinarily, you take web user numbers with a grain of salt – there’s lots of ways they can be wrong. But combined with the IPs, the sessions, and the download numbers, we think that number is probably accurate, maybe even a little conservative.

Invisible users

There are so many sources of error! There are robots who crawl the registry. There are lots of companies who host their own internal registry caches, or run npm Enterprise, and so have their own npm website and registry and never hit ours. There’s the entire nation of China, which finds it difficult to access npm through the great firewall, and is served by our hard-working friends at cnpmjs. There’s errors that inflate our numbers, and errors that deflate them. If you think we’re way off, let us know. But we think we have enough for a good guess.

4 million npm users

We think there are four million npm users, and we think that number is doubling every year. Over at the node.js foundation, they see similar growth numbers. Not only are there more of them, but they’re more engaged than ever before. This is awesome! The 25 very hard working people of npm Inc. thank you for your participation and your contributions to the community, and we hope to see even more of you.

In a previous blog post we showed you how easy it is to run npm Enterprise on Amazon Web Services. Today, we’re happy to announce the public availability of the npm Enterprise Amazon Machine Image (AMI). Now, it’s even easier to run your own private npm registry and website on AWS!

Using our AMI, there is nothing to install. Just launch an instance, configure it using the npm Enterprise admin web UI, and you’re done: it’s a true point-and-click solution for sharing and managing private JavaScript packages within your company.

Let’s take a quick look at the details.

1. Find the AMI in your preferred AWS region

We have AMIs for several AWS regions. When you launch a new instance in the AWS EC2 Console, find the right one by searching for the relevant AMI ID under the Community AMIs tab.

Here’s a list of the AMI IDs by region:

• us-east-1 (N. Virginia): ami-ec52ab81
• us-west-2 (Oregon): ami-a92ad1c9
• eu-central-1 (Frankfurt): ami-d010febf
• ap-southeast-2 (Sydney): ami-e67d5485

Ensure the AMI comes from owner 666882590071.

If you don’t see your preferred region in the list above, contact our support team, and we’ll get one created for you!

2. Launch it

When you launch an instance of the AMI, you’ll need to:

• Choose an instance type: use m3.large or better
• Enter a storage size: must be at least 16 GB; we recommend 50-100 GB for typical installs
• Select or create a security group: open ports 22 (ssh), 8080 (registry), 8081 (website), and 8800 (npm Enterprise admin UI)
• Select or create a .pem key pair: this allows you to ssh into your server instance

It’s not necessary, but if you’d prefer to attach an EBS volume for registry data that is separate from the root volume, you can. However, the root EBS volume cannot be smaller than 16 GB.

For more information (or screenshots) on any of the above, see our docs for Running npm Enterprise in AWS.

3. Configure and start the appliance

You don’t have to, but you can ssh into your EC2 instance to make sure it’s up and running. If you do, you should see a welcome message like the following:

Open your favorite web browser, access your server on port 8800, and follow the prompts to configure and start your appliance.

You’ll need a license key. If you haven’t already purchased one, you can get a free trial key here.

For more information on configuring npm Enterprise, visit our docs.

That’s it! Once you’ve configured and started the appliance, your private npm registry and website are ready for use. See this document for configuring your npm CLI to use your new private registry.

We’re continually striving to provide you the best solutions for distributing, discovering, and reusing your JavaScript code and packages. We hope this AMI makes it just that much easier to leverage the same tools within your organization that work so well in open source communities around the world - a concept we refer to as InnerSource.

As always, if you have questions or feedback, please reach out.

Effective yesterday morning, all requests to the npm registry are made via HTTPS.

What’s different

• npm has accepted HTTPS or HTTP requests for some time. (In fact, only the initial hop from your client to Fastly, our CDN, would use HTTP.) We returned most data to you via HTTPS, but we would serve JSON containing package metadata over HTTP if you requested it via HTTP.
• Starting today, requests you make to the registry over HTTP still work, but we will return all data via HTTPS.
• In a few weeks, Fastly will redirect all HTTP requests to HTTPS. This won’t break your HTTP requests, but they’ll be a bit slower because of the redirect. You will be able to avoid that delay by using HTTPS in your first request.

Practically this means:

• If you request http://registry.npmjs.org/pkgname you get a JSON response
• That JSON used to include http://registry.npmjs.org/pkgname/-/pkgname-1.2.3.tgz
  Now it’s https for the dist.tarball url, https://registry.npmjs.org/pkgname/-/pkgname-1.2.3.tgz.
• Soon, a request to http://registry.npmjs.org/pkgname will 301 (redirect) over to https://registry.npmjs.org/pkgname

Does this mean that package data is/was insecure?

No! The CLI client checks a shashum to verify the package and that check always has been over HTTPS.

How it affects you

• It probably doesn’t. However, a small number of users currently replicate registry data using third-party tools such as Artifactory with configurations to only communicate insecurely.
• This is easily fixed by reconfiguring your tool, or by replicating the npm registry using another method.

How to weather these changes

We’ve developed an ecosystem of tools that you can use to replicate the registry in a way that is resilient to these changes:

1. _changes feed: https://skimdb.npmjs.com/registry/_changes?descending=true&limit=10

   For every change in a package in the registry, the whole package object (with changes) gets emitted as data on the _changes feed of CouchDB.

2. follower: https://github.com/npm/concurrent-couch-follower

   Users wishing to follow the changes feed can use our CouchDB follower wrapper, which will ensure you don’t miss any documents even if you process them asynchronously.

3. normalizer: https://github.com/npm/normalize-registry-metadata

   Finally, we also provide a normalizer, so that you can clean up the data you receive, and implement the changes from the changes feed.

We will never stop making replicating public packages utterly trivial. If anything, we’ll keep making it easier.

We believe these tools should minimize any disruption from our transition to HTTPS — but of course there are edge cases! If you experience difficulty, we want to hear about it and help you out. As always, don’t be shy to reach out: [email protected].

Happy replicating!

Last week, [email protected] (npm LTS) and [email protected] were released to latest. Among other improvements, these fix a vulnerability that could cause the unintentional leakage of bearer tokens.

Here are details on this vulnerability and how it affects you.

How to update npm

An up to date npm is the most secure npm. Update npm to get this patch, as well as other patches:

npm install npm@latest -g

Think you’re at risk? Generate a new bearer token

If you believe that your bearer token may have been leaked, invalidate your current npm bearer tokens and rerun npm login to generate new tokens. Keep in mind that this may cause continuous integration builds in services like Travis to break, in which case you’ll need to update the tokens in your CI server’s configuration.

Details of the vulnerability

Since 2014, npm’s registry has used HTTP bearer tokens to authenticate requests from the npm’s command-line interface. A design flaw meant that the CLI was sending these bearer tokens with every request made by logged-in users, regardless of the destination of their request. (The bearers only should have been included for requests made against a registry or registries used for the current install.)

An attacker could exploit this flaw by setting up an HTTP server that could collect authentication information, then use this authentication information to impersonate the users whose tokens they collected. This impersonation would allow them to do anything the compromised users could do, including publishing new versions of packages.

With the fixes we’ve released, the CLI will only send bearer tokens with requests made against a registry.

Will this break my current setup?

Maybe.

npm’s CLI team believes that the fix won’t break any existing registry setups. Due to the large number of registry software suites out in the wild, though, it’s possible our change will be breaking in some cases.

If so, please file an issue describing the software you’re using and how it broke. Our team will work with you to mitigate the breakage.

Thanks to the community

Thanks to Mitar, Will White & the team at Mapbox, Max Motovilov, and James Taylor for reporting this vulnerability to npm. You can learn more about npm’s security policy on our security page.

-/-

Node.js has also posted about this disclosure. You can read that here.

This week, after we announced changes to our unpublish policy, some community members created a series of packages that depend on every package in the registry. Functionally, these packages exist to ensure that every package has at least one dependent package. A full list of these packages is here.

Other members of the community quickly notified us of these packages. In response, we have contacted the authors of these packages and we are removing all of these packages from the registry, effective 6:00pm PST today (March 30, 2016).

All of the authors we contacted were cooperative and acted in good faith to our requests :) This is not a fight- we’re communicating this situation for the sake of transparency, not drama.

Here’s why we’ve taken this step:

1. These packages violate npm’s Terms of Use. Much like a squatter package, packages like these have no individual functionality beyond depending on other packages.
2. These packages perpetuate a misunderstanding of our updated unpublish policy. Some community members are concerned that packages like these make unpublishing packages completely impossible after the new 24 hour window, but this is not the case. These packages violate npm’s terms of use, so they aren’t valid package dependents. Having them alone wouldn’t make it impossible to unpublish a package — meaning the exercise doesn’t even meet its intended goal.
3. These packages are harmful. If an npm user were to try to install one of them, the installation most likely would fail. Worse, there’s the small chance that installing would succeed … in filling up their hard drive with a lot of junk, and spinning their CPU for a very long time. We can’t guarantee the safety or security of all packages in the registry, but when we learn about packages with harmful effects like these, we have a responsibility to act to protect the community.

We utterly depend on our community — for making the npm registry useful and safe for everyone, and for helping us make policies that balance everyone’s needs and keep everyone safe. We’re grateful to everyone who reached out to alert us to these packages — honestly, thank you! — and we’re also open to continue discussing it with you to understand your concerns. If you have concerns or questions, please contact [email protected].

Here is the email we sent to the authors of these packages.

One of Node.js’ core strengths is the community’s trust in npm’s registry. As it’s grown, the registry has filled with packages that are more and more interconnected.

A byproduct of being so interdependent is that a single actor can wreak significant havoc across the ecosystem. If a publisher unpublishes a package that others depend upon, this breaks every downstream project that depends upon it, possibly thousands of projects.

Last Tuesday’s events revealed that this danger isn’t just hypothetical, and it’s one for which we already should have been prepared. It’s our mission to help the community succeed, and by failing to protect the community, we didn’t uphold that mission.

We’re sorry.

This week, we’ve seen a lot of discussion about why unpublish exists at all. Similar discussions happen within npm, Inc. There are important and legitmate reasons for the feature, so we have no intention of removing it, but now we’re significantly changing how unpublish behaves and the policies that surround it.

These changes, which incorporate helpful feedback from a lot of community members, are intended to ensure that events like Tuesday’s don’t happen again.

Our new policy

Going forward, if you try to unpublish a given package@version:

• If the version is less than 24 hours old, you can unpublish it. The package will be completely removed from the registry. No new packages can be published using the same name and version.

• If the version is older than 24 hours, then the unpublish will fail, with a message to contact [email protected].

• If you contact support, they will check to see if removing that version of your package would break any other installs. If so, we will not remove it. You’ll either have to transfer ownership of the package or reach out to the owners of dependent packages to change their dependency.

• If every version of a package is removed, it will be replaced with a security placeholder package, so that the formerly used name will not be susceptible to malicious squatting.

• If another member of the community wishes to publish a package with the same name as a security placeholder, they’ll need to contact [email protected].  npm will determine whether to grant this request. (Generally, we will.)

Examples

This can be a bit difficult to understand in the abstract. Let’s walk through some examples.

1. Brenna is a maintainer of a popular package named “supertools”. Supertools has 3 published versions: 0.0.1, 0.3.0, and 0.3.1. Many packages depend on all the versions of supertools, and, across all versions, supertools gets around 2 million downloads a month.

   Brenna does a huge refactor and publishes 1.0.0. An hour later, she realizes that there is a huge vulnerability in the project and needs to unpublish. Version 1.0.0 is less than 24 hours old. Brenna is able to unpublish version 1.0.0.

   Embarrassed, Brenna wants to unpublish the whole package. However, because the other versions of supertools are older than 24 hours Brenna has to contact [email protected] to continue to unpublish. After discussing the matter, Brenna opts instead to transfer ownership of the package to Sarah.

2. Supreet is the maintainer of a package named “fab-framework-plugin”, which has 2 published versions: 0.0.1 and 1.0.0. fab-framework-plugin gets around 5,000 downloads monthly across both versions, but most packages depend on it via ^1.0.0.

   Supreet realizes that there are several serious bugs in 1.0.0 and would like to completely unpublish the version. He attempts to unpublish and is prompted to talk to [email protected] because the 1.0.0 version of his package is older than 24 hours. Instead, Supreet publishes a new version with bug fixes, 1.0.1.

   Because all dependents are satisfied by 1.0.1, support agrees to grant Supreet’s request to delete 1.0.0.

3. Tef works for Super Private Company, which has several private   packages it use to implement static analysis on Node.js packages.

   Working late one night, Tef accidentally publicly publishes a private package called “@super-private-company/secrets”. Immediately noting his mistake, Tef unpublishes secrets. Because secrets was only up for a few minutes — well within the 24 window for unrestricted unpublishes — Tef is able to successfully unpublish.

   Because Tef is a responsible developer aware of security best-practices, Tef realizes that the contents of secrets have been effectively disclosed, and spends the rest of the evening resetting passwords and apologizing to his coworkers.

4. Charlotte is the maintainer of a package called “superfoo”. superfoo is a framework on which no packages depend. However, the consultancy Cool Kids Club has been using it to develop their applications for years. These applications are private, and not published to the registry, so they don’t count as packages that depend on superfoo.

   Charlotte burns out on open source and decides to unpublish all of their packages, including superfoo. Even though there are no published dependents on superfoo, superfoo is older than 24 hours, and therefore Charlotte must contact [email protected] to unpublish it.

   After Charlotte contacts support, insisting on the removal of superfoo, npm deprecates superfoo with a message that it is no longer supported. Whenever it is installed, a notice is displayed to the installer.

   Cool Kids Club sees this notice and republishes superfoo as “coolfoo”. Cool Kids Club software now depends on “coolfoo” and therefore does not break.

Changes to come

This policy is a first step towards balancing the rights of individual publishers with npm’s responsibility to maintain the social cohesion of the open source community.

The policy still relies on human beings making human decisions with their human brains. It’s a fairly clear policy, but there is “meat in the machine”, and that means it will eventually reach scaling problems as our community continues to grow.

In the future, we may extend this policy (including both the human and automated portions) to take into account such metrics as download activity, dependency checking, and other measures of how essential a package is to the community.

Moving forward

In balancing individual and community needs, we’re extremely cognizant that developers feel a sense of ownership over their code. Being able to remove it is a part of that ownership.

However, npm exists to facilitate a productive community. That means we must balance individual ownership with collective benefit.

That tension is at the very core of open source. No package ecosystem can survive without the ability to share and distribute code. That’s why, when you publish a package to the registry, you agree to our Terms of Service. The key lines are:

Your Content belongs to you. You decide whether and how to license it. But at a minimum, you license npm to provide Your Content to users of npm Services when you share Your Content. That special license allows npm to copy, publish, and analyze Your Content, and to share its analyses with others. npm may run computer code in Your Content to analyze it, but npm’s special license alone does not give npm the right to run code for its functionality in npm products or services.

When Your Content is removed from the Website or the Public Registry, whether by you or npm, npm’s special license ends when the last copy disappears from npm’s backups, caches, and other systems. Other licenses, such as open source licenses, may continue after Your Content is removed. Those licenses may give others, or npm itself, the right to share Your Content with npm Services again.

These lines are the result of a clarification that we asked our lawyer to make for the purposes of making this policy as understandable as possible. You can see that in this PR.

We don’t try to hide our policies; in fact, we encourage you to review their full list of changes and updates, linked from every policy page.

We acknowledge that there are cases where you are justified in wanting to remove your code, and also that removing packages can cause harm to other users. That’s exactly why we are working so hard on this issue.

This new policy is just the first of many steps we’ll be taking. We’ll be depending on you to help us consider edge cases, make tough choices, and continue building a robust ecosystem where we can all build amazing things.

You probably have questions about this policy change, and maybe you have a perspective you’d like to share, too.

We appreciate your feedback, even when we can’t respond to all of it. Your participation in this ecosystem is the core of its greatness. Please keep commenting and contributing: you are an important part of this community!

Please post comments and questions here. We’ve moved to a Github issue for improved moderation.

Disclaimer: we had been told this vulnerability would be disclosed on Monday, not Friday, so this post is a little rushed and may be edited later.

As disclosed to us in January and formally discussed in CERT vulnerability note VU#319816, it is possible for a maliciously-written npm package, when installed, to execute a script that includes itself into a new package that it then publishes to the registry, and to other packages owned by that user.

npm cannot guarantee that packages available on the registry are safe. If you see malicious code on the registry, report it to [email protected] and it will be taken down.

How to protect yourself

If you are installing a package that you do not trust, you can avoid this vulnerability by running

npm install --ignore-scripts

If you wish to never run scripts at install time, you can instead run

npm config set ignore-scripts true

Either or both of these steps will prevent you from spreading a worm at install time.

If you install a package that contains malicious code and then execute it (e.g. by require()ing it into your code) it could still perform malicious actions. You should not execute any software downloaded from the Internet if you do not trust it, including software downloaded from npm.

Why does this vulnerability exist?

Installation and other lifecycle scripts are a useful tool that allows package authors to set up configuration, compile binary dependencies, and perform other actions that make using npm packages convenient.

On balance, it’s npm’s belief that the utility of having installation scripts is greater than the risk of worms. This is a tradeoff that we will continue to evaluate.

Is this new?

Package scripts have been a feature of npm since the very beginning. The implications of this feature were clear from the start, but not everyone in the ever-expanding npm community is fully aware of them. Disclosures of this kind are helpful for that reason.

What happens if a worm is published?

You should report malicious packages to [email protected]. Per our terms of service, they will be taken down. Authors publishing malicious code to the registry may be banned from the registry.

npm monitors publish frequency. A spreading worm would set off alarms within npm, and if a spreading worm were identified we could halt all publishing while infected packages were identified and taken down.

Can npm scan packages for worms?

npm is working with security vendors to introduce enhanced security vulnerability scanning and mitigation services. This work is underway but not yet ready.

At root, it is impossible to guarantee that any new piece of software is benign short of manually inspecting it, as mobile app stores do. The work required to do this would be prohibitively expensive. Instead, we rely on users to flag suspicious packages and act quickly to remove them from the registry.

What else can be done?

Other potential steps can be taken to make publishing without an author’s knowledge harder, including implementing 2-factor authentication on publishing. This functionality is already available via integrations in npm On-Site, and npm is working to make various 2-factor solutions available to the public registry. This work is also not yet complete.

What if I…

Ultimately, if a large number of users make a concerted effort to publish malicious packages to npm, malicious packages will be available on npm. npm is largely a community of benevolent, helpful people, and so the overwhelming majority of software in the registry is safe and often useful. We hope the npm community continues to help us to keep things that way, and we will do our best to continuously improve the reliability and security of the registry.