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.

``bash
$ npm i @nodesecure/ossf-scorecard-sdk

or

$ yarn add @nodesecure/ossf-scorecard-sdk
`

Usage example

`ts
import * as scorecard from "@nodesecure/ossf-scorecard-sdk";

const data = await scorecard.result("NodeSecure/scanner");
console.log(data);
`

You can provide either GitHub (github.com), GitHub Enterprise Server (GHES) (github.corp.com) or GitLab (gitlab.com) platform with the options payload:

`ts
const data = await scorecard.result("gitlab-org/gitlab-ui", {
platform: "gitlab.com", // default to github.com
});
console.log(data);
`

You can provide a NPM library:
`ts
const data = await scorecard.result("@nodesecure/scanner");
console.log(data);
`

You can disable resolveOnNpmRegistry option which is true by default.

> [!TIP]
> You can disable version control resolve when you are sure the given repository is well formatted using resolveOnVersionControl: false.
> This can save you from GitHub/GitLab rate limit when working with lots of repositories.

`ts
const data = await scorecard.result("NodeSecure/scanner", {
resolveOnNpmRegistry: false, // default to true
});
console.log(data);
`
Options are described with the following TypeScript interface:

`ts
export interface IResultOptions {
/**
* @description VCS platform. eg. github.com
* @default github.com
*/
platform?: "github.com" | "github.corp.com" | "gitlab.com";
/**
* @description Try to resolve the given repository on the NPM registry if its not found on the given platform.
* @default true
*/
resolveOnNpmRegistry?: boolean;
/**
* @description Try to resolve the given repository on the given platform. This can be useful when the given repository
* is not exactly the same as the one on the given platform (case sensitive).
* @default true
*/
resolveOnVersionControl?: boolean;
/**
* @description The version of the npm package (when resolveOnNpmRegistry only) to retrieve the scorecard for.
* @default "latest"
*/
npmPackageVersion?: string;
}
`

API

$3

> [!TIP]
> You can use GITHUB_TOKEN environment variable to avoid rate-limit when resolveOnVersionControl is true.

Return the OpenSSF ScorecardResult for a given organization and repository.

The response is typed using the following set of types:

`ts
export type ScorecardCheck = {
name: string;
score: number;
reason: string;
details: null | string[];
documentation: {
short: string;
url: string;
};
};

export type ScorecardResult = {
date: string;
metadata: string;
repo: {
name: string;
commit: string;
};
scorecard: {
version: string;
commit: string;
};
score: number;
checks: ScorecardCheck[];
};
`

$3

Return a string URL to the badge image of a given organization and repository.

The badge method has an additional style options.

`ts
export interface IBadgeOptions extends IResultOptions {
/**
* Style to render the badge
*
* @default flat
*/
style?: "plastic" | "flat" | "flat-square" | "for-the-badge" | "social";
}
`

Then the response is described by the BadgeResult interface:

`ts
export interface BadgeResult {
/**
* HTTPS link to shields.io
*
* @example
* https://img.shields.io/ossf-scorecard/github.com/NodeSecure/scanner?label=openssf%20scorecard&style=flat
*/
image: string;
/**
* HTML SVG balise
*/
svg: string;
}
``

Contributors ✨



Thanks goes to these wonderful people (emoji key):

Gentilhomme 💻 👀 🛡️

Kouadio Fabrice Nguessan 💻 📖

PierreDemailly 💻

yurifa ⚠️

License

MIT