Okay, so you have heard the news; The NPM supply chain is completely vulnerable to the whims of a few devs and their egos, “Protestware” is all the rage and the whole javascript ecosystem a big stack of cards waiting to come tumbling down at any moment.

Alright now that we’re on the same page let’s take a deep breath, grab a cup of coffee and talk about how we can easily protect ourselves while continuing to do our work and quietly ignore all the world problems surrounding us. (kidding)

Table of Contents

1. Why is this a big deal now?
2. How Supply Chain Attacks Work
3. Best Practices / How to use Docker without knowing Docker (it’s easy now I promise)

Why is this a big deal now?

Honestly, these issues have been on the horizon for years. Developers who subscribe to other languages in other ecosystems will be quick to educate you on how bad javascript is because javascript developers will install just about anything to avoid writing code.

And well, as a javascript dev myself, I don’t think they’re wrong.

Recently and I mean, in the last 3 months we have had 2 high profile package authors publish malicious code to their code base and have potentially effected a large amount of end users.

Marak, the author of Faker.js and Color.js published an update that infinitely pasted algo text in the terminal preventing any dependent application from running. Seemingly to protest his lack of compensation for contributing to larger projects.

Brandon Nozaki (Aka RIAEvangelist), the author of node-ipc, approved a pull request into master that replaces all file contents on the system with a heart emoji. Effectively wiping everything. And while this “protestware” was targeting Russian and Belerusian computers, an american NGO was impacted by this attack.

This is not the first time malicious code has been published to NPM either. However, these have hit mainstream news sources because they are extremely popular and each get tens of millions of downloads every week. So how does this work and how can we protect ourselves?

How Supply Chain Attacks Work (for context)

Before going into the solutions it’s important that everyone reading this understands the problem. If you are already familiar with supply chain attacks I recommend skipping this portion.

And before you google “Supply Chain Software Attack” on google bear in mind that the answers you will likely find there are a little different than what we’re talking about today since most of those examples reference organizations purchasing code from other organizations. Since NPM is open source it’s important to keep in mind that all the players are usually individuals.

I think analogies can be confusing so let’s get straight to the nitty gritty. NPM stands for “Node Package Manager”. It is a command line tool. It is a package registry and it is a company (that was recently purchased by github).

NPM the company provides the NPM command line tool for free and the Node.js community has elected to include it when you install node. Users can submit code (packages) to the NPM registry and users can install packages from the registry by using the CLI tool.

Since you are reading this you are probably doing this all the time already so what’s the problem?

Well I am getting to that. like I said you can skip this part if you want.

Writing code is challenging and/or tedious so it is very common for users to download a package from NPM to save them the hassle of re-writing the code themselves and wasting all that time and energy. As a result the new code now depends on the aforementioned package to function properly. Now if the new code is bundled into a package any code written on top of that will now depend on 2 packages. Here’s a diagram because that sounded confusing even to me.

So what’s the problem? And the answer is the reader’s lack of patience. Stay with me now.

If the user writing myHelloWorldApp.js installs world.js they might not even know they also installed hello.js unless they thoroughly reviewed the world.js github page which is unlikely.

And now if the author of hello.js publishes an “update” to hello.js to NPM. And that “update” over-writes the user’s hard drive with emojis well that would be a supply chain attack. There we made it. Are you happy?

In Summary

A supply chain attack can occur anytime you are downloading or executing third party code on your machine. That’s why your OS is always asking you DO YOU TRUST THIS APPLICATION!?!? or some variation. All Open-Source Package Managers like NPM, PIP, etc are extremely vulnerable to these types attacks because anyone can upload anything to a trusted platform and it is up to the users to defend themselves. Luckily, the community does do a good job of policing itself and issues like these resolve themselves very quickly. Usually.

Best Practices

Okay, so now what?

Fortunately, there are a couple of relatively easy steps we can perform to not get burned like the aforementioned American NGO did when they installed node-ipc. I will list them all here and go into more detail below.

1. trust no one not even your loved ones or the dog.
2. Trace every ip connecting to your computer and destroy the whole thing if you notice an unfamiliar ip address.
3. Take all the cash out of your bank and put it in your mattress
4. Stock up on re-fried beans and hope for the best.

Okay, okay all jokes aside here’s the real list

1. Pin your version numbers in package.json
2. Use a package-lock.json and install with npm ci
3. Use docker or a VM
4. Common sense
5. Use your own package servers
6. Use a vetting service

To pin a version number in your package.json you just need to remove the ^ character that is automatically prepended to the version number when you install a package for the first time.

This will prevent NPM from installing the latest valid version and instead only download the version you know you can trust. For more information about the symbols in NPM packages go here: https://docs.npmjs.com/about-semantic-versioning (I also encourage you to check out the version calculator)

But what about my dependency’s dependencies? Well that’s where package-lock.jsoncomes in. This file tracks every single package that is being used for your application and the version being used. If you npm i or npm install your packages and something updates, the package-lock.json file will also be updated to reflect that change.

We don’t want that though. We want package-lock.json to yell at us if we are trying to install a package that does not match the version that is listed.

That’s where npm ci or npm clean-install comes in. It will Error if it tries to install something that conflicts with the package-lock.json file. For those of you who deal with package-lock.json merge conflicts all the time, installing packages with this command will also help mitigate some of that.

And Docker!

I know, I know. For a lot of people docker has been this sort of beast that’s mostly lived in the DevOps world. YAML files are kind of gross and difficult to debug when you have a problem.

But, the Docker team has done an amazing job trying to make utilizing a VM easier and easier every year and now it’s so easy you can setup a persistent development environment in a container (on windows no less!) in less than 5 minutes.

Before, we go through that 10 second tutorial let’s talk about why it’s important.

Pinning your version numbers and reviewing code is fine and all and still important but, part of fun of developing is the ability to explore the internet and try stuff out without fear. Why do we need to tip-toe around because some developers decided they wanted to go on a power trip?

The answer is we don’t. We can set up a safe space to download anything we want while isolating it from the things we actually care about and Docker (and VSCode) make achieving that easy. Here are the steps to add docker to an existing project:

1. Add the Remote Containers VSCode Extension
2. Navigate to your project directory
3. Press Ctrl+Shift+P and type “add development container configuration files”

4. Select Node.js (if it’s a node project of course)

5. Press Ctrl+Shift+P and type “open folder in container”

6. Download and install docker if necessary

7. Done! VSCode should have re-opened itself with a remote connection to your new container with all of your code in it.

Now you can install whatever you want without worrying about bricking your hard drive.

Use your own package servers and vetting service

This was a suggestion provided by a u/Laladelic on Reddit. I am not very familiar with using either of these solutions but, the user did provide links to available solutions:

vetting service: https://snyk.io/

package servers: https://jfrog.com/artifactory/

In Conclusion

None of these solutions are foolproof. Misconfiguration or misunderstanding of the above solutions can defeat their purpose.

It is also up to all of us individually to decided what the right level of security is. How much risk we are willing to take.

There is no such thing as perfect security but, I make these suggestions because I love open source and would hate to see its reputation tarnished because a false sense of trust was attributed to strangers on the internet.

Be safe out there.

P.S. If you want to correct or add anything to what I have written please write a comment and I will do my best to update this post as fast as I can!

[Edit] updated to include package server and vetting service suggestions

How to avoid NPM supply chain attacks. was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

Part 0: Understanding Electron

If you found this guide by wanting to develop cross platform applications then you probably know that Electron.js does just that. You can easily develop and distribute applications for windows/macOS/linux with the same code (bear in mind this does not include android or iOS).

The question becomes, “How does Electron accomplish this?”. In short; Electron launches a headless chromium browser which has access to the Node.js API via Electron’s own API. Which has plenty of use cases but, probably the biggest being is that your app can theoretically work without an internet connection.

If that sounded like a bunch of wumbo that’s okay but, it’s important to understand the Electron combines the browser and Node.js to create this seamless development experience for us.

Part 1: Your first Electron App (AKA Hello World — again)

Inspired by the getting started page https://electronjs.org/docs/tutorial/first-app and assuming you have performed step 0 of my previous guide.

Step 0. Navigate to your project folder (you can just create a new folder wherever on your computer) and run the command npm init and follow the prompt provided

Step 1. NPM Install Electron by running npm install electron --save-dev *NOTE* we use --save-dev instead of --save so you can work on multiple apps with multiple electron version the future.

Step 2. Create two new files called index.js and index.html

Step 3. Inside index.js enter the following code:

const { app, BrowserWindow } = require("electron");

function createWindow() {

    // Create the browser window.

    let win = new BrowserWindow({

        width: 800,

        height: 600,

        webPreferences: {

            nodeIntegration: true

        }

    });

    // and load the index.html of the app.

    win.loadFile("index.html");

}

app.on("ready", createWindow);

In this file we are importing the app and BrowserWindow modules from the Electron package we installed earlier. When the Electron app is ready we create a new BrowserWindow with the provided properties and load in our index.html file.

Step 4. Put some content into your index.html file.
It can be whatever you want but, I like to use <h1>Hello World</h1> for old time’s sake.

Step 5. Running your application
There are a couple of gotchya’s to running an electron application. The first of which is that you might expect to run your app via node index.js just as you would with any node application.

Unfortunately, that won’t work. You need to run your javascript via Electron’s binary which is conveniently included in your Node_Modules folder. If you have looked at Electron’s documentation you might think you can run your app via electron . . Which is close but, won’t work unless you do some additional setup configuring your environment variables and having a global Electron installation. Which is beyond the scope of this guide.

Instead we will make an npm script by opening the package.json file (which was created when we executed npm init earlier) and adding a new start script with the property electron . . Your package.json should look something like the one below:

{

    "name": "electron-part1",

    "version": "1.0.0",

    "description": "An electron tutorial",

    "main": "index.js",

    "scripts": {

        "start": "electron .",

        "test": "echo \"Error: no test specified\" && exit 1" 

    },

    "author": "",

    "license": "ISC",

    "devDependencies": {

        "electron": "^5.0.3"

    }

}

Finally, you can run your application by entering npm start in the terminal. And you should see a window that looks like this if you’re on a mac:

Part 2: Your actual first Electron app.

Okay hello world is great and all but, let’s try and practice with some of the actual functionality Electron provides. Don’t throw away the Hello World app because we will just be building on it.

Step 0. Add some styling
One of Electron’s biggest draws is that you can create an amazing custom GUI as easily as you can write html/css which is a hell of a lot easier than Qt and other native apps.

Create a css file called styles.css and include it in the root of your project and add the proper reference in your index.html file:

<link rel="stylesheet" type="text/css" href="./styles.css" />

Any changes you make to your styles will show up when you re-run your electron project npm start .

I personally like to use skeleton.css for these demos because it’s lightweight and we won’t be needing much (and I’m too lazy to write css sometimes). It is important to remember that if you want your app to look the same offline you can’t include the cdn script in your html. You need to download the css file and reference it locally.

This guide assumes you know how to write html and css so I won’t go over that and you can just steal it from the github that I have linked at the bottom. In any case my electron app now looks like this:

Step 1. Add some functionality

Before you add the jQuery to your html file (which you totally can) let’s focus on adding functionality that does not occur in your normal browser. Our goal here is to be creating a text file and saving it to our computer.

*Note* You may have downloaded files to your computer before but, those are likely from server requests. Javascript running in the browser does not have write or read permissions to your file system.

1.1 Create a new file called app.js with the following code. This our javascript file that will only be running on the browser to capture user input.

// note that the fs package does not exist on a normal browser

const fs = require("fs");

//a dialog box module from electron

const { dialog } = require("electron").remote;

// Also note that document does not exist in a normal node environment

// button click event

document.getElementById("mybutton").addEventListener("click", () => {

    const data = "Successfully wrote to the desktop"; // the data we want to save to the desktop

    //launch save dialog window

    dialog.showSaveDialog(filename => {

        //save file at the destination indicated by filename

        fs.writeFileSync(filename + ".txt", data, "utf-8", () => {

            console.log("attempted to write to the desktop");

        });

    });

});

1.2 If you have added a button with the id “mybutton” then the next time you run your node application and click that button, you should see a success.txt automatically be generated where you decided to save it.

Not too bad right? More functionality will come the more you learn about Node and Javascript in general. But, hopefully now you have a solid fundamental understanding of how Electron works.

Step 2. Packaging your app

You probably know by now you can’t just hand your potential users the project files and hope they figure out how to run everything on their own. They likely don’t have node installed and why should they?

What we need to do is compile our application into a binary that our end users can simply double click and execute. To do that, install the electron packager by typing the following in your terminal:

npm install electron-packager --save-dev

Then add the following line to your package.json scripts

"package": "electron-packager .",

Finally execute the packager by typing the following in your terminal:

npm run package

You should see a new folder in your project directory that matches your current system. Included in that folder is an application (or .exe if you are using windows).

In Conclusion: This guide should have given you a fundamental understanding of how Electron works. If you had trouble following this guide I suggest spending more time learning Node.js before jumping into Electron. If this guide was too simple, I highly suggest checking out the following resources:

• Electron Documentation: https://electronjs.org/docs
• Electron Packager Documentation: https://github.com/electron-userland/electron-packager

GITHUB: https://github.com/Mikkal24/tutorials/tree/master/electron-part1

Objective: This guide will teach you how to write a program that accepts command line arguments using Node.js.
Audience: People who have never written a single Node.js program but, are somewhat familiar with the terminal and have some basic programming knowledge.

Step 0: Setup
Most guides like these already have environment setup instructions so I won’t dive too deep here but, for the uninitiated here is a summary of the steps you should take and a few relevant links:
1. Install node.js

2. Ready a terminal (powershell, gitbash, mac terminal, etc)

3. Verify that node.js is installed by opening a terminal and typing node -v in the terminal(this guide was written using v10.13.0)

4. Ready a favorite text editor (I prefer Visual Studio Code)

Step 1: Console Logging and Hello World
Yep, it’s another hello world application. You already know what to expect so let’s get right into it.

1. Create a new file named hello-world.js (for those terminal enthusiasts just type touch hello-world.js)
2. Open that file with your favorite text editor and type console.log("hello world!"); on the first line. To those new to javascript, console.log prints whatever string you pass as an argument similar to python’s print function. Go ahead and save that file.
3. Open or go back to your terminal and change your directory (cd) to where you saved that javascript file we just created. Inside the terminal type node hello-world (note that the .js file ending is not strictly necessary). You should see the output hello world! in your terminal. Congratulations you just created and executed your first Node.js program.

Step 2: Process.argv and accepting user input
Alright so we know how to run a node.js program but logging to the console is not terribly useful. We do know that most command line tools accept some form of input (ex. cd <some location>). How do we do that in Node.js?

Node.js exposes a global variable called Process that we can use to grab information from the user. Now let’s see exactly how we can do that.

1. Create a new file called hello.js
2. Open that file and insert the following snippet and save the file.

const name = process.argv[2];

console.log("hello " + name);

In short, we are storing a user submitted value into a constant variable we call name then we are logging it into the console. There are a couple things which I encourage you to go mull over like the const keyword and string concatenation but, those are beyond the scope of this guide.

3. Run the program by typing node hello samantha wherever you saved the file. You should find that the program responds with hello samantha . You should then repeat this using a different name to confirm that it is capturing user input. Neat!

Step 3. Process.argv continued…
Okay there’s a lot to unpack with process.argv but, in an attempt to sum it up it is an array of values corresponding to the values entered in the command.

For example; the last program we ran was node hello samantha if you console.log(process.argv) you should see values like this:

[ '/your/nodejs/installation/path', '/the/path/to/your/hello.js', 'samantha']

You can include virtually as many command line arguments as you need thanks to this feature.

Step 4. adding functionality
To finish off this guide I want to leave you with the ability to read more in-depth node.js guides from any time period. With that let’s write a program that manipulates some of the values the user provides.

1. Create a new file called add.js
2. Open that file in your text editor and add code that accepts 2 values and stores those values into variables.

const num1 = process.argv[2];

const num2 = process.argv[3];

3. Include a function that adds those values together

function add(param_num1, param_num2) {

    return param_num1 + param_num2;

}

4. Call that function and store the result in a variable called sum

const sum = add(num1, num2);

5. Log sum to the console

console.log(`sum: ${sum}`);

Now if you run the program by typing the following into your terminal: node add 2 2 you might be surprised to see the number 22 appear on your screen. That is because Node.js can only interpret user input as a string data type. Data types in javascript can be a little tricky if coming from a more strictly typed language so I highly suggest reviewing W3Schools article on the subject.

To resolve this issue we can change parse the values to be numbers like

const num1 = parseInt(process.argv[2]);

const num2 = parseInt(process.argv[3]);

So if we run the program we should see the expected output of 4 .

**A note on functions**
Functions can take many different shapes in javascript and there are many ways to declare them. For experienced developers the differences are important but, for beginners the end result is mostly the same.

• function(){ //some logic } is an anonymous function
• function myFunction(){ //some logic } is a named function
• const myFunction = function(){ // some logic } is also a named function
• const myArrowFunction = () => { // some logic } is a named arrow function

You may see functions appear in different forms on your journey to learn Node.js and javascript. Javascript has been changing since its inception and will likely continue to while old guides will still be out there on the internet. Hopefully this information will shed some additional insight into what otherwise might be a confusing read.

Github Repository: https://github.com/Mikkal24/tutorials/tree/master/cli-part1