@nodesecure/ossf-scorecard-sdk

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.

$ npm i @nodesecure/ossf-scorecard-sdk
# or
$ yarn add @nodesecure/ossf-scorecard-sdk

Usage example

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:

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:

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.

const data = await scorecard.result("NodeSecure/scanner", {
  resolveOnNpmRegistry: false, // default to true
});
console.log(data);

Options are described with the following TypeScript interface:

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

result(repository: string, options?: IResultOptions): Promise< ScorecardResult >

[!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:

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[];
};

badge(repository: string, options?: IBadgeOptions): Promise< BadgeResult >

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

The badge method has an additional style options.

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:

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;
}