Plugins

Adviser is modular and allows creating plugins, in this wiki page you will find everything you know about implementing a plugin.

Naming convention

Your plugin name must be named as adviser-plugin-[name], examples:

• adviser-plugin-audit-npm
• adviser-plugin-suspicious-packages

Structure

Plugin structure

Adviser is expecting an object with all the defined rules, like:

{
  "rules": {
    "min-vulnerabilities-allowed": Rule,
    "skip-vulnerabilities": Rule,
  }
}

Rule structure

To define a rule, you should create a class the inherit from Adviser.Rule; once you have the class you can use the rule lifecycle method to implement your rule.

Rule lifecycle

1. Constructor - Called when the rule is parsed by the engine
2. run - Action rule method called when the engine runs the rule
3. ruleExecutionFailed - Called when the rule execution failed
4. ruleExecutionEnded - Called when the rule execution ended

Example

class MinVulnerabilityAllowed extends Adviser.Rule {
  constructor(context) {
    console.log(context);
  }

  run(sandbox) {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        sandbox.report({ message: 'lalalalalalal' });
        resolve();
      }, 3000);
    });
  }

  ruleExecutionFailed(feedback, error) {
    console.log(feedback);
  }

  ruleExecutionEnded(feedback) {
    console.log(feedback);
  }
}

MinVulnerabilityAllowed.meta = {
  category: 'Vulnerabilities',
  description: 'To be fill',
  recommended: true,
  docsUrl: 'https://github..com/jam3/',
  schema: {
    enum: ['low', 'moderate', 'high', 'critical']
  }
};

Testing

Besides the unit tests for your Rule logic, if you would like to run your new rule with Adviser, follow the below steps:

1. Run $ npm link where your plugin's package.json is
2. Create a new folder
3. Create an empty package.json and install adviser ($ npm install adviser)
4. Run $ npm link <your plugin name> in your new folder
5. Create a config file .adviserrc (Read below for an example)
6. Run Adviser

Configuration file example

{
  "plugins": ["audit-npm"],
  "rules": {
    "audit-npm/min-vulnerabilities-allow": ["error", { "level": "high" }]
  }
}