@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
- Therepo
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) - ThecommitAmount
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
- TheignoreList
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 theignoreList
will not be flagged as recent committers if the gitlog contains these emails. -
maxCommitters
(optional) - ThemaxCommitters
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
- ThereadmeFile
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
- Thefile
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) - Thefile
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
- Thegreeting
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
- Thefile
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
- Thefile
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
- Theworkflows
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
- Thefile
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
- Thefile
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
- Therepo
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) - ThecommitAmount
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
- TheemailDomains
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
- TheignoreList
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 theignoreList
will not be flagged if the gitlog contains these emails. -
maxCommitters
(optional) - ThemaxCommitters
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) - Thefile
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
- ThefilePackageJson
property for package.json file entity. This value should be located in the root directory. -
fileYarnLock
- ThefileYarnLock
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
- Thefile
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}