NodeSecurity

🔑 The easiest way to control what npm modules can access

NOTE: This package has not gone through any form of security testing! Please do not use it to ensure security at this time. Issues questioning the feasability of our current approach are still outstanding.

• #7

If you're experienced in this area ( I am not ) please contribute!

Overview

This repo / package was inspired a Medium post by David Gilbertson - https://hackernoon.com/npm-package-permissions-an-idea-441a02902d9b

Imagine a package, created and maintained by npm (or someone equally trustworthy and farsighted). Let’s call it @npm/permissions.

You would include this @npm/permissions package as the first import in your app, either in a file, or you run your app like node -r @npm/permissions index.js.

This would override require() to enforce the permissions stated in a package’s package.json permissions property.

With the exception of some small differences, like not using package.json to manage permissions, this package attempts to accomplish this goal.

How it works

NodeSecurity works by overriding the Node.JS require() function, allowing us to enforce access constraints.

Usage

npm install @matthaywardwebdesign/node-security

Firstly include NodeSecurity in your project at the very top of your applications entrypoint (before any other requires) and create a new instance.

  const nodesecurity = require( '@matthaywardwebdesign/node-security' );
  const NodeSecurity = new nodesecurity();

Note: If you're using the ES6 imports you'll need to create a seperate file that is imported at the entrypoint of your application. Without doing this it won't be possible to configure NodeSecurity before any other modules are loaded.

Configure NodeSecurity

NodeSecurity.configure({
  /**
   * The 'core' section controls
   * global access to built in modules. By default
   * all core modules are disabled.
   */
  core: {
    fs: true,
    path: true,
    /* You can disable specific module functions */
    os: {
      arch: false,
      cpus: false,
    }
  },
  /**
   * The 'module' section controls
   * per module access to built in modules. This allows
   * us to disable access globally by allow it on a per
   * module basis.
   */
  module: {
    axios: {
      http: true,
      https: true,
    }
  },
  /**
   * The 'env' section controls what environment
   * variables are accessible via process.env
   */
  env: {
    API_KEY: true,
    API_HOST: true,
  },
  /**
   * The 'sharedObjects' section controls whether
   * or not C++ addons can be loaded. Defaults to
   * false
   */
  sharedObjects: false,
});

🎉 And you're done! 🎉

All required / imported modules from this point onwards will have to be allowed by our configuration.

Example

Here's an example script!

/* Import and create a new instance of NodeSecurity */
const nodesecurity = require( '@matthaywardwebdesign/node-security' );
const NodeSecurity = new nodesecurity();

/* Configure NodeSecurity */
NodeSecurity.configure({
  core: {
    /* Define global fs access */
    fs: false,
    /* Enable other core modules we'll need */
    stream: true,
    util: true,
    path: true,
    os: {
      /* Deny access to OS arch */
      arch: false,
    },
    assert: true,
  },
  module: {
    /* Allow fs-extra to access fs */
    'fs-extra': {
      fs: true,
    }
  }
});

/* This won't throw an error as fs-extra is allowed to access fs */
require( 'fs-extra' );

/* Accessing fs directly will throw an error */
require( 'fs' );

/* Accessing os.arch will throw an error */
const os = require( 'os' );
os.arch();

Plugins

You can extend the functionality of NodeSecurity by creating a plugin. For example you could create a plugin to allow http/s requests to only be made to specific servers.

An example plugin can be found at src/plugins/NodeSecurityPlugin.js

Plugins work by providing a way to override the default functionality of a core module. By default every Node core module (fs, os, etc) has a plugin loaded that allows for module methods to be disabled.

Including your own plugin is as simple as adding a plugins section to your configuration.

plugins: {
  http: MyHTTPPlugin
}

Contributing

Building the package

npm run build

Running the test suite

npm test

Ideas

• Include a set of default plugins that allow for more granular filesystem and network access.

Contributors

Thanks goes to these wonderful people (emoji key):

Matt Hayward 💻 📖	Jake Bolam 🚇	Qix 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!