{"id":18374663,"url":"https://github.com/jupiterone/peril","last_synced_at":"2025-04-14T00:25:17.321Z","repository":{"id":60508996,"uuid":"531602040","full_name":"JupiterOne/peril","owner":"JupiterOne","description":"Project Risk Analysis Tool","archived":false,"fork":false,"pushed_at":"2024-01-02T19:17:15.000Z","size":439,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-27T14:47:10.804Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JupiterOne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-09-01T16:34:31.000Z","updated_at":"2024-06-27T23:08:50.000Z","dependencies_parsed_at":"2023-10-13T14:15:36.603Z","dependency_job_id":"2c98c07b-d0eb-44cf-9ce9-e694c15bb1bc","html_url":"https://github.com/JupiterOne/peril","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fperil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fperil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fperil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fperil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JupiterOne","download_url":"https://codeload.github.com/JupiterOne/peril/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248800104,"owners_count":21163404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T00:15:35.942Z","updated_at":"2025-04-14T00:25:17.286Z","avatar_url":"https://github.com/JupiterOne.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# peril\n\n![GitHub](https://img.shields.io/github/license/jupiterone/peril)\n![GitHub Workflow Status](https://img.shields.io/github/workflow/status/jupiterone/peril/Build)\n![GitHub top language](https://img.shields.io/github/languages/top/jupiterone/peril)\n![npm (scoped)](https://img.shields.io/npm/v/@jupiterone/peril)\n![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/jupiterone/peril)\n![OSS Lifecycle](https://img.shields.io/osslifecycle/jupiterone/peril)\n\nProject Risk Analysis and Reporting Tool\n\nThis is a standalone CLI tool intended to analyze the overall risk profile for\nthe currently-checked-out branch of a code repository. It will draw risk\ninformation from a configurable list of sources, including JupiterOne, before\nrendering an overall risk verdict for the code.\n\nUse-cases include:\n\n- CI/CD gates\n- Local development and remediation\n- Security analysis and code review\n\n## Usage\n\n### Via NPM\n\n```sh-session\n$ npm install -g @jupiterone/peril\n$ peril --help\nJupiterOne Project Risk-Analysis and Reporting Tool\n\nUSAGE\n  $ peril\n\nOPTIONS\n  -V, --version            Show CLI version\n  -c, --config=config      Path to override config file\n  -d, --dir=dir            [default: /Users/erichs/repos/jupiterone/peril] directory path to scan\n  -h, --help               Show CLI help\n  -l, --log=log            Path to output log file\n  -m, --mergeRef=mergeRef  [default: master] Current git ref/tag of default branch (merge target)\n  -p, --pubkeyDir=pubkeyDir  Full path to directory containing trusted public GPG keys\n  -v, --verbose            Enable verbose output\n  --accept                 Accept all risk (do not exit with non-zero status)\n  --debug                  Debug mode, very verbose\n  --noBanner               Do not display splash banner\n  --override               Create a project override object\n```\n\n### Via Docker\n\n```sh-session\ndocker run -v $PWD:/app -e 'J1_API_TOKEN=\u003ctoken\u003e' -e 'J1_ACCOUNT=\u003caccountname\u003e' jupiterone/peril peril --verbose --dir /app\n```\n\n## Assumptions\n\n`peril` assumes that:\n\n- You are using `git`.\n- The present working directory is the top-level of the git project to be\n  analyzed, or the `--dir` flag points to this top-level.\n\n## Risk Scores\n\nThe Risk scores that `peril` produces are arbitrary. A more structured\ncalculation--the\n[DREAD](https://en.wikipedia.org/wiki/DREAD_%28risk_assessment_model%29)\nmodel--was considered but abandoned since that model lacks academic rigor and is\ndifficult to apply in a consistent fashion that produces sensible results.\nInstead, `peril` takes the position that since risk evaluation will always be\nsubjective, the values it uses should be inherently arbitrary and easily\nconfigured for tuning purposes (see below). It is recommended to run `peril`\nwith the `--accept` flag for some time to gather scoring metrics that assist\nwith tuning.\n\nWhile the scores are arbitrary, they are not meaningless: they do correlate\ntightly with the configured checks/practices.\n\n## Configuration\n\n`peril` ships with default risk values out-of-the-box, but these are all\nconfigurable. You may override any of the values or facts found in the\n`./test/fixtures/testConfig.ts` file, in JSON format, and specify a path to your\nlocal config.json override with the `-c` | `--config` flag, e.g.:\n\n```shell\nperil --config ./path/to/my/config.json\n```\n\nNOTE: it is assumed that this override config file is trusted, and the code\n`peril` is analyzing does not have permissions to write or modify this file!\n\nAdditionally, you may provide custom configuration via an executable script or\nprogram that emits JSON on stdout. The path to this executable may also be\nspecified with the `--config` flag. An example script may be found at\n`./test/fixtures/testConfig.sh`. Please ensure that the permissions to this\nscript or program are locked down prior to invoking with `peril --config`!\n\n## Supported Checks\n\n### SCM\n\nChecks related to Git SCM:\n\n| Check            | Config Path                        | Notes                                                               |\n| ---------------- | ---------------------------------- | ------------------------------------------------------------------- |\n| git              | values.checks.scm.git              | I think we can all agree code should be versioned.                  |\n| enforceGpg       | values.checks.scm.enforceGpg       | Encourage code-signing at the repo-level.                           |\n| verifyGpg        | values.checks.scm.verifyGpg        | Ensure recent commits have been signed.                             |\n| gitleaksFindings | values.checks.scm.gitleaksFindings | Committing sensitive data to git is an information disclosure risk. |\n\n### CODE\n\nChecks related to the code being analyzed.\n\n| Check           | Config Path                        | Notes                                                                                                |\n| --------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| linesChanged    | values.checks.code.linesChanged    | Large PRs represent a strain on code reviewers, and increase risk of rubber-stamping.                |\n| filesChanged    | values.checks.code.filesChanged    | Large PRs represent a strain on code reviewers, and increase risk of rubber-stamping.                |\n| depscanFindings | values.checks.code.depscanFindings | 3rd-party dependency vulnerabilities represent a supply-chain risk. `**`                             |\n| bannedLicenses  | values.checks.code.bannedLicenses  | 3rd-party dependencies that have non-compliant or incompatible licenses represent a legal risk. `**` |\n\n### PROJECT\n\nChecks related to the Project (CodeRepo in JupiterOne).\n\n| Check               | Config Path                               | Notes                                                                             |\n| ------------------- | ----------------------------------------- | --------------------------------------------------------------------------------- |\n| snykFindings        | values.checks.project.snykFindings        | 3rd-party dependency vulnerabilities represent a supply-chain risk. `++`          |\n| maintenanceFindings | values.checks.project.maintenanceFindings | Overdue maintenance represents organizational risk. `@@`                          |\n| threatModels        | values.checks.project.threatModels        | Encourage threat modeling activities. Add risk for unmitigated design flaws. `!!` |\n\n#### Legend\n\n| Symbol | Meaning                                                                                                                                                    |\n| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `**`   | Requires local use of [ShiftLeft/sast-scan](https://github.com/ShiftLeftSecurity/sast-scan/) prior to invoking `peril`.                                    |\n| `++`   | Requires the [Snyk integration](https://support.jupiterone.io/hc/en-us/articles/360024788554-Snyk) to be configured for JupiterOne.                        |\n| `@@`   | Will add risk if the CodeRepo entity in JupiterOne relates to overdue [`deferred_maintenance`](https://github.com/JupiterOne/deferred-maintenance/) items. |\n| `!!`   | Works with [OWASP Threat Dragon](http://docs.threatdragon.org/) models.                                                                                    |\n\n## Manual Overrides\n\nFrom time-to-time, it may be necessary or desirable to override the risk\ncalculations `peril` provides. Calling `peril --override` can be used locally to\ncreate an override object that may be committed to the `.peril/` folder of the\ntarget git repository.\n\nTo use this feature, you will need to be a trusted staff member authorized by\nyour business for this purpose. `peril` signs the override files with `gpg`, so\nyour public key will need to be provisioned in advance in CI/CD. See \"Trusting\npubkeys\" below.\n\n### Generating a local override\n\n1. Clone the target repo that is failing in CI/CD\n2. Check out the target branch.\n3. Issue `peril --override`\n4. Answer the interactive prompts.\n5. Commit the resulting file in the `.peril/` folder to git.\n6. Push this change to the remote target branch.\n\n### Trusting pubkeys in CI/CD\n\nProvision your trusted pubkeys in a directory (in binary format, via\n`gpg --export`) reachable by `peril` in CI/CD. This directory, and all pubkey\nfiles within it MUST NOT be world writable. To enable the override feature, you\nmust invoke `peril` with the `--pubkeyDir` flag, and specify a full path to the\ntrusted pubkey directory you've previously provisioned.\n\nFor example, if your pubkeys are available in the `/usr/local/gpgkeys` directory\nof your CI/CD host, you should specify the following parameter:\n\n```sh-session\n--pubkeyDir /usr/local/gpgkeys\n```\n\nIf using `peril` with `docker`, you will likely need to mount this folder into\nthe container with the `-v` flag.\n\ne.g.:\n\n```sh-session\ndocker run -v /usr/local/gpgkeys:/gpgkeys -v $PWD:/app -e 'J1_API_TOKEN=\u003ctoken\u003e' -e 'J1_ACCOUNT=\u003caccountname\u003e' jupiterone/peril peril --verbose --dir /app --pubkeyDir /gpgkeys\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupiterone%2Fperil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjupiterone%2Fperil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupiterone%2Fperil/lists"}