@nodesecure/report

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 v24 or higher.

Getting Started

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

``bash
$ git clone https://github.com/NodeSecure/report.git
$ cd report
$ npm i
$ npm run build
$ npm link
`

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

`bash
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.

$3

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.

$3

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

`json
{
"version": "1.0.0",
"i18n": "english",
"strategy": "github-advisory",
"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

$3

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

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

`ts
/**
* 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

`bash
$ 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.

`bash
$ 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