Skip to content

NodeSecure/ossf-scorecard-sdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

77 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

@nodesecure/ossf-scorecard-sdk

npm version maintained license ossf scorecard github ci workflow

Requirements

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

Contributors ✨

All Contributors

Thanks goes to these wonderful people (emoji key):

Gentilhomme
Gentilhomme

πŸ’» πŸ‘€ πŸ›‘οΈ
Kouadio Fabrice Nguessan
Kouadio Fabrice Nguessan

πŸ’» πŸ“–
PierreDemailly
PierreDemailly

πŸ’»
yurifa
yurifa

⚠️

License

MIT