README.md

This project is designed to generate periodic security reports in both HTML and PDF formats. It leverages the @nodesecure/scanner to retrieve all necessary data.

Screen1	Screen2

Features

• Automatically clones and scans Git repositories using scanner.cwd.
• Provides a visual overview of security threats and quality issues for multiple Git or NPM packages.
• Facilitates visualization of changes over time.
• Generates reports in both HTML and PDF formats.

Requirements

• Node.js v18 or higher.

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ git clone https://github.com/NodeSecure/report.git
$ cd report
$ npm i
$ npm link

After installation, the nreport binary will be available in your terminal.

nreport initialize
nreport execute

Caution

Please read the following sections to understand how to properly set up the configuration. The initialize command generates an incomplete basic template.

Environment Variables

To configure the project you have to register (set) environment variables on your system. These variables can be set in a .env file (that file must be created at the root of the project).

GIT_TOKEN=
NODE_SECURE_TOKEN=

To known how to get a GIT_TOKEN or how to register environment variables follow our Governance Guide.

Note

For NODE_SECURE_TOKEN, please check the NodeSecure CLI documentation.

Configuration Example (.nodesecurerc)

This uses the official NodeSecure runtime configuration (@nodesecure/rc) under the hood.

{
  "version": "1.0.0",
  "i18n": "english",
  "strategy": "npm",
  "report": {
    "title": "NodeSecure Security Report",
    "logoUrl": "https://avatars.githubusercontent.com/u/85318671?s=200&v=4",
    "theme": "light",
    "includeTransitiveInternal": false,
    "reporters": ["html", "pdf"],
    "npm": {
      "organizationPrefix": "@nodesecure",
      "packages": ["@nodesecure/js-x-ray"]
    },
    "git": {
      "organizationUrl": "https://github.com/NodeSecure",
      "repositories": ["vulnera"]
    },
    "charts": [
      {
        "name": "Extensions",
        "display": true,
        "interpolation": "d3.interpolateRainbow",
        "type": "bar"
      },
      {
        "name": "Licenses",
        "display": true,
        "interpolation": "d3.interpolateCool",
        "type": "bar"
      },
      {
        "name": "Warnings",
        "display": true,
        "type": "horizontalBar",
        "interpolation": "d3.interpolateInferno"
      },
      {
        "name": "Flags",
        "display": true,
        "type": "horizontalBar",
        "interpolation": "d3.interpolateSinebow"
      }
    ]
  }
}

The theme can be either dark or light. Themes are editable in public/css/themes (feel free to PR new themes if you want).

Note

All D3 scale-chromatic for charts can be found here.

API

Caution

The API is ESM only

report

function report(
  scannerDependencies: Scanner.Payload["dependencies"],
  reportConfig: ReportConfiguration,
  reportOptions?: ReportOptions
): Promise<Buffer>;

Generates and returns a PDF Buffer based on the provided report options and scanner payload.

/**
 * Configuration dedicated for NodeSecure Report
 * @see https://github.com/NodeSecure/report
 */
export interface ReportConfiguration {
  /**
   * @default `light`
   */
  theme?: "light" | "dark";
  title: string;
  /**
   * URL to a logo to show on the final HTML/PDF Report
   */
  logoUrl?: string;
  /**
   * Show/categorize internal dependencies as transitive
   * @default false
   */
  includeTransitiveInternal?: boolean;
  npm?: {
    /**
     * NPM organization prefix starting with @
     * @example `@nodesecure`
     */
    organizationPrefix: string;
    packages: string[];
  };
  git?: {
    /**
     * GitHub organization URL
     * @example `https://github.com/NodeSecure`
     */
    organizationUrl: string;
    /**
     * List of repositories
     * name are enough, no need to provide .git URL or any equivalent
     */
    repositories: string[];
  };
  /**
   * @default html,pdf
   */
  reporters?: ("html" | "pdf")[];
  charts?: ReportChart[];
}

export interface ReportChart {
  /**
   * List of available charts.
   */
  name: "Extensions" | "Licenses" | "Warnings" | "Flags";
  /**
   * @default true
   */
  display?: boolean;
  /**
   * Chart.js chart type.
   *
   * @see https://www.chartjs.org/docs/latest/charts
   * @default `bar`
   */
  type?: "bar" | "horizontalBar" | "polarArea" | "doughnut";
  /**
   * D3 Interpolation color. Will be picked randomly by default if not provided.
   * @see https://github.com/d3/d3-scale-chromatic/blob/main/README.md
   */
  interpolation?: string;
}

export interface ReportOptions {
  /**
   * Location where the report will be saved.
   * 
   * If not provided, default to cwd if HTML or PDF is saved on disk, or a temp directory else.
   */
  reportOutputLocation?: string | null;
  /**
   * Save the PDF on disk
   * @default false
   */
  savePDFOnDisk?: boolean;
  /**
   * Save the HTML on disk
   * @default false
   */
  saveHTMLOnDisk?: boolean;
}

Scripts

You can generate a preview of a report using the following NPM scripts

$ npm run preview:light
$ npm run preview:dark

Debug mode

You can write in the file "reports/debug-pkg-repo.txt", all data generated from NPM package and GIT repository scanners using the following option. Usefull if you want to get a preview from this data set.

$ nreport exec --debug

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Gentilhomme 💻 📖 👀 🛡️ 🐛	Vincent Dhennin 💻 📖 👀	Nicolas Hallaert 📖	Max 💻	Kouadio Fabrice Nguessan 🚧	halcin 🐛 💻 ️️️️♿️	PierreDemailly 💻
Lilleeleex 💻	Nishi 📖	Erwan Raulo 💻

License

MIT