https://github.com/matthaywardwebdesign/node-security
:key: The easiest way to control what npm modules can access
https://github.com/matthaywardwebdesign/node-security
Last synced: about 1 month ago
JSON representation
:key: The easiest way to control what npm modules can access
- Host: GitHub
- URL: https://github.com/matthaywardwebdesign/node-security
- Owner: matthaywardwebdesign
- License: mit
- Created: 2018-12-29T10:46:42.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2019-01-02T09:33:45.000Z (over 6 years ago)
- Last Synced: 2024-08-02T06:24:34.416Z (9 months ago)
- Language: JavaScript
- Size: 43.9 KB
- Stars: 483
- Watchers: 23
- Forks: 14
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# NodeSecurity
:key: The easiest way to control what npm modules can access
[](#contributors)
**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.
- [https://github.com/matthaywardwebdesign/node-security/issues/7](https://github.com/matthaywardwebdesign/node-security/issues/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](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
```bash
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.
```javascript
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**
```javascript
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,
});
```
:tada: **And you're done!** :tada:
All required / imported modules from this point onwards will have to be allowed by our configuration.
## Example
Here's an example script!
```javascript
/* 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.
```javascript
plugins: {
http: MyHTTPPlugin
}
```
## Contributing
Building the package
```
npm run build
```
Running the test suite
```bash
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](https://github.com/kentcdodds/all-contributors#emoji-key)):
| [
Matt Hayward](http://www.matthayward.com.au)
[💻](https://github.com/matthaywardwebdesign/node-security/commits?author=matthaywardwebdesign "Code") [📖](https://github.com/matthaywardwebdesign/node-security/commits?author=matthaywardwebdesign "Documentation") | [
Jake Bolam](https://jakebolam.com)
[🚇](#infra-jakebolam "Infrastructure (Hosting, Build-Tools, etc)") | [
Qix](https://github.com/Qix-)
[🤔](#ideas-Qix- "Ideas, Planning, & Feedback") |
| :---: | :---: | :---: |
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!