1.5.0 • Published 2 years ago

@jupiterone/transponder-core-plugin v1.5.0

Weekly downloads
-
License
MPL-2.0
Repository
github
Last release
2 years ago

@jupiterone/transponder-core-plugin

This module exports a number of common collectors and publishers that can be imported into your transponder config.

Installation

npm i --dev @jupiterone/transponder-core-plugin

Alternatively if you are using yarn:

yarn add -D @jupiterone/transponder-core-plugin

Usage

Create a transponder configuration file (yml) in your repo

example-repo/example-transponder.yml

Add @jupiterone/transponder-core-plugin to your list of plugins in your transponder configuration file.

Note: "core" is an alias that will reference the "collectors" and "publishers" exposed by @jupiterone/transponder-core-plugin.

Example configuration file:

plugins:
  - core=@jupiterone/transponder-core-plugin

collect:
  codeowners:
    collector: 'core:codeowners'
    params:
      file: <rootDir>/CODEOWNERS_demo
    failOnError: false

publish:
  filesystem:
    publisher: 'core:filesystem'
    params:
      outputDir: '<rootDir>/.j1-transponder'

Collectors

This plugin provides some common collectors that may be useful for your project.

git-contributors - DEPRECATED

This collector is deprecated and will be renamed git-committers.ts.

This collector determines who are making commits to the repo and returns a fragment containing the five most recent of those contributors.

Accepted parameters
  • repo - The repo property contains the repository for the project. This value cannot be changed otherwise the program will not be able to read the gitlog of the project.
  • commitAmount (optional) - The commitAmount property returns the most recent commits in the gitlog with the amount that is returned being customizable. If this value is not given it will be assigned 1000 commits.
  • ignoreList - The ignoreList property contains a list of approved emails. This property should contain the emails that are to be ignored, such as noreply@github.com which is the email that is attached to merges in gitlog. The emails on the ignoreList will not be flagged as recent committers if the gitlog contains these emails.
  • maxCommitters (optional) - The maxCommitters property returns the most recent committers in the gitlog with the amount of the committers being customizable. If this value is not given it will be assigned 5 committers.
Example usage
collect:
  non-employee-git-committers:
    collector: 'core:non-employee-git-committers'
    failOnError: false
    params:
      repo: '.'
      commitAmount: 1000
      ignoreList: ['noreply@github.com']
      maxCommitters: 5

readme - DEPRECATED

This collector is deprecated and will be replaced using the file-exists collector.

This collector determines if the repository contains a README.md file returns a fragment that contains true if so and an error if not.

Accepted parameters
  • readmeFile - The readmeFile property for the README.md entity. This value should be located in the root directory.
Example usage
readme:
  collector: 'core:readme'
  params:
    readmeFile: <rootDir>/README.md

changelog - DEPRECATED

This collector is deprecated and will be replaced using the file-exists collector.

This collector determines if the repository contains a CHANGELOG.md and returns a fragment that contains true if so and false if not.

Accepted parameters
  • file - The file property for the CHANGELOG.md entity. This value should be located in the root directory.
Example usage
changelog:
  collector: 'core:changelog'
  params:
    file: <rootDir>/CHANGELOG.md
  failOnError: false

root

This collector defines _key, _type, and _class of the root entity fragment.

Accepted parameters
  • _key (optional) - The _key property for the root entity. This value should be unique within your configuration.
  • _type (optional) - The _type assigned to the root entity.
  • _class (optional) - The _class assigned to the root entity.
Example usage
publish:
  filesystem:
    publisher: 'core:filesystem'
    params:
      outputDir: '<rootDir>/.j1-transponder'

npmCheck

This collector finds vulnerabilities, such as outdated and broken packages, packages not installed, unused packages, invalid semvers, etc.

Accepted parameters
  • file (optional) - The file propery is not necessary, however, due to the formatting of the project, it is requested.

demo

This collector provides a demo that refereneces the "example" collector and returns a fragment that contains a string.

Accepted parameters
  • greeting - The greeting property is a string that is converted into a fragment.
Example usage
npmCheck:
  collector: 'core:npmCheck'
  params: {}
demo:
  collector: 'core:example'
  params:
    greeting: 'hello'

npm-package-json-dependencies

This collector determines the npmDevDependencies and npmDependencies of package,json and returns a fragment that contains two arrays of the different type of the dependencies.

Accepted parameters
  • file - The file property for the package.json entity. This value should be located in the root directory.
Example usage
npm-package-json-dependencies:
  collector: 'core:npm-package-json-dependencies'
  params:
    file: <rootDir>/package.json
  failOnError: false

codeowners

This collector defines the codeowners of the repository and returns a fragment that contains an array of the codeowners' names.

Accepted parameters
  • file - The file property for the CODEOWNERS entity. This value should be located in the root directory.
Example usage
codeowners:
  collector: 'core:codeowners'
  params:
    file: <rootDir>/CODEOWNERS
  failOnError: false

github-workflows

This collector checks for workflows in the .github/workflows directory and returns a fragment that contains a list of files.

Accepted parameters
  • workflows - The workflows property for the github-workflows entity. This value should not need to be set, but can be used to point to an alternative workflows directory in the GitHub repo.
Example usage
github-workflows:
  collector: 'core:github-workflows'
  params: {}
  failOnError: false
github-workflows:
  collector: 'core:github-workflows'
  params:
    workflows: <rootDir>/workflowsDirectory/
  failOnError: false

peril

This collector reads the peril.json file and returns the individual security scores contained inside, as well as the package name.

Accepted parameters
  • file - The file property for the peril.json entity. This value should be located in the root directory.
Example usage
peril:
  collector: 'core:peril'
  params:
    file: <rootDir>/packages/transponder-demo/PERIL_demo.json
  failOnError: false

file-exists

This collector reads any file in and returns whether or not the file exists with a transponder fragment name that is customizable. The example being shown below is for the file package.json

Accepted parameters
  • file - The file property for file entity. This value should be located in the root directory.
  • propertyName - The name that will be assigned transponder fragment. This should be unique to the data being determined.
Example usage
file-exists:
  collector: 'core:file-exists'
  params:
    file: <rootDir>/package.json
    propertyName: packageJsonExists
  failOnError: false

non-employee-committers

This collector determines if there is any nonemployees, excluding those who the collector has been told to ignore, making commits to the repo and returns a fragment containing the five most recent of those nonemployees.

Accepted parameters
  • repo - The repo property contains the repository for the project. This value cannot be changed otherwise the program will not be able to read the gitlog of the project.
  • commitAmount (optional) - The commitAmount property returns the most recent commits in the gitlog with the amount that is returned being customizable. If this value is not given it will be assigned 1000 commits.
  • emailDomains - The emailDomains property contains a list of approved email domians. This property should contain the email domian of the company and the emails will not be flagged if the gitlog contains these domains.
  • ignoreList - The ignoreList property contains a list of approved emails. This property should contain the emails that are to be ignored that do not contain domian of the company, such as noreply@github.com which is the email that is attached to merges in gitlog. The emails on the ignoreList will not be flagged if the gitlog contains these emails.
  • maxCommitters (optional) - The maxCommitters property returns the most recent committers in the gitlog with the amount of the committers being customizable. If this value is not given it will be assigned 5 committers.
  collect: non-employee-git-committers:
    collector: "core:non-employee-git-committers"
    failOnError: false
    params:
      repo: '.'
      commitAmount: 1000
      emailDomains: ['jupiterone.com']
      ignoreList: ['noreply@github.com']
      maxCommitters: 5

cycloneDX-SBOM-generation

This collector reads a SBOM file and then returns the dependencies located in it. If the file does not exists a new one will be generated.

Accepted parameters
  • file (optional) - The file property for the SBOM entity. This value should be located in the root directory if currently exists.
  • fileName (optional) - The name that can be assigned to the bom.json file if another name if needed. It is recomended to included newName.json.
Example usage
cycloneDX-SBOM-generation:
  collector: 'core:cycloneDX-SBOM-generation'
  params:
    file:
    fileName:
  failOnError: false

npm-package-required-resolved-version

This collector reads the package.json file and returns the resolved and required versions for a specific tool.

Accepted parameters
  • filePackageJson - The filePackageJson property for package.json file entity. This value should be located in the root directory.
  • fileYarnLock - The fileYarnLock property for yarn.lock file entity. This value should be located in the root directory and where the resolved and required versions are stored.
  • packageName - The name that of what package is being search for after the '@' symbol.
  • propertyName - The name that will be assigned transponder fragment. This should be unique to the data being determined.
npm-package-required-resolved-version:
 collector: "core:npm-package-required-resolved-version"
    params:
      filePackageJson: '<rootDir>/package.json'
      fileYarnLock: '<rootDir>/yarn.lock'
      packageName: '@jupiterone/typescript-tools'
      propertyName: 'typescriptTools'

yarn-lock-versions

This collector reads the yarn.lock file and returns the version of a package being used if it contains it.

Accepted parameters
  • file - The file property for file entity. This value should be located in the root directory.
  • versionName - The name that of what package is being search for after the '@' symbol.
  • propertyName - The name that will be assigned transponder fragment. This should be unique to the data being determined.
Example usage
yarn-lock-version:
 collector: "core:yarn-lock-versions"
    failOnError: false
    params:
      file: <rootDir>/yarn.lock
      versionName: 'j1/name'
      propertyName: 'Version'

Publishers

Below are some publishers included in this plugin that you can forward collected data to.

filesystem

This publisher writes the fragments output by configured collectors to your directory of choice.

Files will be written to disk and can be inspected after transponder runs. This publisher is primarily used to assist with understanding what types of fragments are being produced by configured collectors.

Example output file structure:

<outputDir>/..
  entities
     0-project_metadata.json
  fragments
    entities
      project_metadata
         1-git-contributors.json
         2-readme.json
         3-jupiterone-yaml.json
         4-git-remote-origin.json
         5-npm-package-json-dependencies.json
         6-cycloneDX-SBOM-generation.json
         7-codeowners.json
         8-changelog.json
         9-root.json
         10-demo.json
         11-file-exists.json
         12-non-employee-git-committers.json
         13-docker-file.json
         14-license-file.json
         15-peril.json
         16-typescript-tools-version.json
         17-terraform-modules-version.json
         18-npm-check.json

Example entity stored in <outputDir>/entities/0-project_metadata.json:

{
  "hasReadme": true,
  "readmeFileSize": 7654,
  "_key": "root",
  "_type": "project_metadata",
  "_class": "ProjectMetadata",
  "team": "Core",
  "squad": "Site Reliability",
  "description": "JupiterOne transponder collects data about a project by analyzing\nsource files and build artifacts\n",
  "npmDevDependencies": [
    "@jupiterone/typescript-tools",
    "chalk",
    "lerna",
    "recursive-copy",
    "rimraf",
    "source-map-support"
  ],
  "npmDependencies": [],
  "gitHost": "github.com",
  "gitRepoFullName": "jupiterone/transponder",
  "gitRepoName": "transponder",
  "gitRepoOwner": "jupiterone",
  "gitRemoteOrigin": "git@github.com:JupiterOne/transponder.git",
  "recentGitCommitters": [
    "julia.oghigian@jupiterone.com",
    "ericxiang2000@gmail.com",
    "ian.pena@jupiterone.com",
    "cgriffin@electricgull.com",
    "raf97.to@gmail.com"
  ],
  "bomDependencies": "pkg:npm/%40jupiterone/transponder-monorepo@0.0.0",
  "hasChangelog": false,
  "codeOwners": ["@jupiterone/security", "@jupiterone/transponder"],
  "test": 123,
  "ingestedOn": 1661349466368,
  "message": "hello, world!",
  "hasPackageJson": true,
  "dockerfileFROM": "node:16",
  "dockerfileEXPOSE": [8080, 4343],
  "hasLicenseFile": true,
  "license": "Mozilla Public License Version 2.0",
  "nonEmployeeGitCommitters": [
    "ericxiang2000@gmail.com",
    "cgriffin@electricgull.com",
    "raf97.to@gmail.com"
  ],
  "perilProject": "Test_file_name",
  "perilScmRisk": -0.5,
  "perilCodeRisk": 10,
  "perilProjectRisk": 5,
  "perilManualRiskOverrides": 0,
  "perilTotalRiskScore": 14.5,
  "dockerfileFROM": "node:16",
  "dockerfileEXPOSE": [8080, 4343],
  "devToolsExists": false,
  "devToolsResolvedVersion": "",
  "typescriptToolsExists": true,
  "typescriptToolsRequiredVersion": "^16.0.0",
  "typescriptToolsResolvedVersion": "16.0.0",
  "npmCheckNotInPackageJSON": "@jupiterone/eslint-config@2.0.0",
  "npmCheckPackageUnused": "source-map-support@0.5.21"
}

Example entity fragment stored in <outputDir>/fragments/entities/project_metadata/4-root.json:

{
  "test": 123,
  "dateIngested": "2022-06-29T17:19:22.968Z",
  "_key": "root",
  "_type": "project_metadata",
  "_class": "ProjectMetadata"
}
Accepted parameters
  • outputDir (required) - The directory to store the collected artifacts.
Example usage
publish:
  filesystem:
    publisher: 'core:filesystem'
    params:
      outputDir: '<rootDir>/.j1-transponder'

j1

This publisher uploads your data to JupiterOne via the synchronization API. Entities will show up in your graph shortly after the publishing step completes.

Accepted parameters
  • apiKey (required) - The JupiterOne API Key to authenticate with.
  • apiDomain (required) - The JupiterOne API domain you'd like to target.
  • accountId (required) - The ID of the account you would like to publish the collected entity fragments to.
Example usage
publish:
  j1:
    publisher: 'core:j1'
    params:
      # NOTE:
      # Tokens will be replaced from environment variables with matching name.
      apiKey: ${env.J1_API_KEY}
      apiDomain: ${env.J1_API_DOMAIN}
      accountId: ${env.J1_ACCOUNT_ID}
@cyclonedx/bom@cyclonedx/cyclonedx-library@jupiterone/transponder-sdk@yarnpkg/lockfilecodeowners-utilsdocker-file-parsergit-remote-origin-urlgitloglodashnode-fetchnpm-checkp-queueyaml
@infinitebrahmanuniverse/nolb-_jup@everything-registry/sub-chunk-504@zalastax/nolb-_jup
1.5.0

2 years ago

1.4.0

2 years ago

1.2.0

2 years ago

1.1.0

2 years ago

1.2.2

2 years ago

1.3.0

2 years ago

1.2.1

2 years ago

1.0.8

2 years ago

1.0.7

2 years ago

1.0.6

2 years ago

1.0.4

2 years ago