https://github.com/NodeSecure/report
NodeSecure HTML & PDF report generator for any public and/or private git repositories.
https://github.com/NodeSecure/report
hacktoberfest nodejs report security security-tool
Last synced: 6 months ago
JSON representation
NodeSecure HTML & PDF report generator for any public and/or private git repositories.
- Host: GitHub
- URL: https://github.com/NodeSecure/report
- Owner: NodeSecure
- License: mit
- Created: 2019-09-20T21:59:40.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-10-07T23:07:09.000Z (over 1 year ago)
- Last Synced: 2024-10-11T00:08:35.402Z (over 1 year ago)
- Topics: hacktoberfest, nodejs, report, security, security-tool
- Language: JavaScript
- Homepage:
- Size: 1.42 MB
- Stars: 14
- Watchers: 3
- Forks: 13
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://api.securityscorecards.dev/projects/github.com/NodeSecure/report)
This project is designed to generate periodic security reports in both HTML and PDF formats. It leverages the [@nodesecure/scanner](https://github.com/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](https://nodejs.org/en/) v20 or higher.
## Getting Started
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```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.
### 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](https://github.com/SlimIO/Governance/blob/master/docs/tooling.md#environment-variables).
> [!NOTE]
> For NODE_SECURE_TOKEN, please check the [NodeSecure CLI documentation](https://github.com/NodeSecure/cli?tab=readme-ov-file#private-registry--verdaccio).
### Configuration Example (.nodesecurerc)
This uses the official NodeSecure [runtime configuration](https://github.com/NodeSecure/rc) (`@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](https://github.com/d3/d3-scale-chromatic/blob/master/README.md).
## API
> [!CAUTION]
> The API is ESM only
### report
```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 ✨
[](#contributors-)
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Gentilhomme
💻 📖 👀 🛡️ 🐛
Vincent Dhennin
💻 📖 👀
Nicolas Hallaert
📖
Max
💻
Kouadio Fabrice Nguessan
🚧
halcin
🐛 💻 ️️️️♿️
PierreDemailly
💻
Lilleeleex
💻
Nishi
📖
Erwan Raulo
💻
## License
MIT