{"id":13533155,"url":"https://github.com/purpleteam-labs/purpleteam","last_synced_at":"2025-04-01T21:31:54.796Z","repository":{"id":37018926,"uuid":"146154384","full_name":"purpleteam-labs/purpleteam","owner":"purpleteam-labs","description":"CLI component of OWASP PurpleTeam","archived":false,"fork":false,"pushed_at":"2023-12-13T04:43:28.000Z","size":2361,"stargazers_count":120,"open_issues_count":38,"forks_count":15,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-09-16T02:13:50.615Z","etag":null,"topics":["application-security","build-tool","ci","cli","cloud-security","devsecops","devsecops-pipeline","hacktoberfest","purpleteam","security-regression-testing","security-testing","web-security"],"latest_commit_sha":null,"homepage":"https://owasp.org/www-project-purpleteam","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/purpleteam-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-08-26T05:35:06.000Z","updated_at":"2024-09-13T20:30:09.000Z","dependencies_parsed_at":"2023-12-13T05:28:56.759Z","dependency_job_id":"5160491f-805f-4c0f-a0b8-453691f1cb90","html_url":"https://github.com/purpleteam-labs/purpleteam","commit_stats":{"total_commits":369,"total_committers":3,"mean_commits":123.0,"dds":0.03794037940379402,"last_synced_commit":"d99b899e63b7c2d874ee09f27c83495c9a93494f"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleteam-labs%2Fpurpleteam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleteam-labs%2Fpurpleteam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleteam-labs%2Fpurpleteam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/purpleteam-labs%2Fpurpleteam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/purpleteam-labs","download_url":"https://codeload.github.com/purpleteam-labs/purpleteam/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222774594,"owners_count":17035752,"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":["application-security","build-tool","ci","cli","cloud-security","devsecops","devsecops-pipeline","hacktoberfest","purpleteam","security-regression-testing","security-testing","web-security"],"created_at":"2024-08-01T07:01:17.069Z","updated_at":"2024-11-02T20:31:12.861Z","avatar_url":"https://github.com/purpleteam-labs.png","language":"JavaScript","funding_links":[],"categories":["DAST","Dynamic Application Security Testing"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cbr/\u003e\n  \u003ca href=\"https://purpleteam-labs.com\" title=\"purpleteam\"\u003e\n    \u003cimg width=900px src=\"https://github.com/purpleteam-labs/purpleteam/blob/main/assets/images/purpleteam-banner.png\" alt=\"PurpleTeam logo\"\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n  \u003cbr/\u003e\n  \u003ch2\u003epurpleteam CLI\u003c/h2\u003e\u003cbr/\u003e\n    CLI component of \u003ca href=\"https://purpleteam-labs.com/\" title=\"purpleteam\"\u003e\u003cem\u003ePurpleTeam\u003c/em\u003e\u003c/a\u003e - Currently in alpha\n  \u003cbr/\u003e\u003cbr/\u003e\n\n  \u003ca href=\"https://purpleteam-labs.com/doc/\" title=\"documentation\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/-documentation-blueviolet\" alt=\"documentation\"\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://github.com/purpleteam-labs/purpleteam/commits/main\" title=\"pipeline status\"\u003e\n    \u003cimg src=\"https://github.com/purpleteam-labs/purpleteam/workflows/Node.js%20CI/badge.svg\" alt=\"pipeline status\"\u003e\n  \u003c/a\u003e\n\n  \u003ca href='https://coveralls.io/github/purpleteam-labs/purpleteam?branch=main'\u003e\n    \u003cimg src='https://coveralls.io/repos/github/purpleteam-labs/purpleteam/badge.svg?branch=main' alt='test coverage'\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://github.com/purpleteam-labs/purpleteam/releases\" title=\"latest release\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/purpleteam-labs/purpleteam?color=%23794fb8\u0026include_prereleases\" alt=\"GitHub release (latest SemVer including pre-releases)\"\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003ca href=\"https://youtu.be/ACuaP-ZToKw\" title=\"purpleteam\"\u003e\n    \u003cimg width=900px src=\"https://user-images.githubusercontent.com/2862029/134789647-515d18db-6d5c-4704-864c-2ee5bcc1d015.png\" alt=\"Full System Run\"\u003e\n  \u003c/a\u003e\n\n\u003cbr/\u003e\u003cbr/\u003e\n\u003c/div\u003e\n\nIf you are planning on running the `local` environment, once you have installed, configured and are ready to run the _PurpleTeam_ CLI, head back to the [local setup](https://purpleteam-labs.com/doc/local/set-up/) documentation and make sure all of the other _PurpleTeam_ components are also set-up and ready to run. After that work through the [local workflow](https://purpleteam-labs.com/doc/local/workflow/) documentation.\n\nIf you are planning on targeting the `cloud` environment, the _PurpleTeam_ CLI is all you need to have set-up.\n\nIf you have any issues with the set-up, be sure to check the [trouble shooting](https://purpleteam-labs.com/doc/trouble-shooting/) page.\n\n# Contents\n\n* [Minimum Supported Versions](#minimum-supported-versions)\n* [Install](#install)\n  * [Clone the git repository](#clone-the-git-repository)\n  * [NPM install locally](#npm-install-locally)\n  * [NPM install globally](#npm-install-globally)\n* [Configure](#configure)\n  * [CLI](#cli)\n  * [Job File](#job-file)\n* [Run](#run)\n  * [Clone the git repository option](#clone-the-git-repository-option)\n    * [Run the bin/purpleteam file via npm script](#run-the-binpurpleteam-file-via-npm-script)\n    * [Run the bin/purpleteam file directly](#run-the-binpurpleteam-file-directly)\n  * [NPM install locally option](#npm-install-locally-option)\n    * [Run the _PurpleTeam_ CLI directly](#run-the-purpleteam-cli-directly)\n    * [Run the _PurpleTeam_ CLI directly - with `status` command](#run-the-purpleteam-cli-directly---with-status-command)\n    * [Run the _PurpleTeam_ CLI directly - with `test` command](#run-the-purpleteam-cli-directly---with-test-command)\n    * [Run the _PurpleTeam_ CLI directly - with `test` options](#run-the-purpleteam-cli-directly---with-test-options)\n    * [Run your app (build pipeline)](#run-your-app-build-pipeline)\n    * [Debug your app (build pipeline)](#debug-your-app-build-pipeline)\n    * [Debug your app and _PurpleTeam_ CLI](#debug-your-app-and-purpleteam-cli)\n  * [NPM install globally option](#npm-install-globally-option)\n* [Usage](#usage)\n* [Trouble-Shooting](#trouble-shooting)\n\n\n# Minimum Supported Versions\n\nNodeJS: v14\n\n# Install\n\nThere are several options.\n\n## Clone the git repository\n\nIf you are planning on running/debugging _purpleteam_ stand-alone, cloning is a good option.\n\nFrom a directory that you would like the CLI cloned to run the following command:\n\n```shell\ngit clone https://github.com/purpleteam-labs/purpleteam.git\n```\n\nInstall the dependencies with the following command:\n\n```\nnpm install\n```\n\nAnother option with cloning if you want the CLI (_purpleteam_) to be available as a system wide command is to use the following command from the repositories root directory:\n\n```\nnpm link\n```\n\n## NPM install locally\n\nIf you are planning on running/debugging _purpleteam_ from another NodeJS process, for example a CI/nightly build/build pipeline project of your own, installing via NPM is a good option.\n\nFor the locally installed via NPM option the purpleteam-labs Team uses the [purpleteam-build-test-cli](https://github.com/purpleteam-labs/purpleteam-build-test-cli) project as an example to test that this option works as expected. The following example [package.json](https://github.com/purpleteam-labs/purpleteam-build-test-cli/blob/main/package.json) and [index.js](https://github.com/purpleteam-labs/purpleteam-build-test-cli/blob/main/index.js) files are from the purpleteam-build-test-cli example project. Feel free to clone it, or use your own project to follow along.\n\nThis example exports two environment variables:\n\n* `NODE_ENV=local`: Means that _purpleteam_ will be using the `local` [configuration](#cli). If instead you have signed up for a cloud license, you will want to be targeting the `cloud` environment instead\n* `PURPLETEAM_UI=noUi`: As detailed in the [Configure](#cli) sub-section\n\nUsing the above mentioned example build project files, and for the sake of this example, let's assume your NodeJS build project has the same following files:\n\n\u003cdiv id=\"purpleteam-build-test-cli\"\u003e\u003c/div\u003e\n\n[**package.json**](https://github.com/purpleteam-labs/purpleteam-build-test-cli/blob/main/package.json)\n\n```json\n{\n  \"name\": \"purpleteam-build-test-cli\",\n  \"description\": \"Used to test that the purpleteam CLI runs within a build pipeline successfully\",\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"// Don't forget to export any required env vars before running the purpleteam CLI. For example\": \"NODE_ENV=local and PURPLETEAM_UI=noUi\",\n    \"// Invoke purpleteam binary from NPM script\": \"npm run purpleteam\",\n    \"purpleteam\": \"NODE_ENV=local purpleteam\",\n    \"// Start your node app\": \"npm start\",\n    \"start\": \"NODE_ENV=local PURPLETEAM_UI=noUi node index.js\",\n    \"// Debug your node app\": \"npm run debugApp\",\n    \"debugApp\": \"NODE_ENV=local PURPLETEAM_UI=noUi node --inspect-brk=localhost:9230 index.js\",\n    \"// Debug your node app and the purpleteam CLI\": \"npm run debugAppAndCli\",\n    \"debugAppAndCli\": \"NODE_ENV=local PURPLETEAM_UI=noUi DEBUG_PURPLETEAM=true node --inspect-brk=localhost:9230 index.js\"\n  },\n  \"dependencies\": {\n    \"purpleteam\": \"*\"\n  }\n}\n```\n\n[**index.js**](https://github.com/purpleteam-labs/purpleteam-build-test-cli/blob/main/index.js)\n\n```javascript\nimport { spawn } from 'child_process';\n\n// You will need to define two debuggers in what ever tool you're using.\n// localhost:9230 and localhost:9231\nconst execArgvDebugString = '--inspect-brk=localhost';\nconst childProcessInspectPort = 9231;\n// You can run any of the purpleteam commands [about|status|test|testplan], `test` is just one example.\nconst purpleteamArgs = ['purpleteam', 'test'];\n\nconst startPurpleteam = () =\u003e {\n  const purpleteam = spawn('node', [\n    ...(process.env.DEBUG_PURPLETEAM\n    ? [`${execArgvDebugString}:${childProcessInspectPort}`]\n    : []),\n    ...purpleteamArgs],\n    { cwd: `${process.cwd()}/node_modules/.bin/`, env: process.env, argv0: process.argv[0] }\n  );\n\n  purpleteam.stdout.on('data', (data) =\u003e {\n    process.stdout.write(data);\n  });\n  purpleteam.stderr.on('data', (data) =\u003e {\n    process.stdout.write(data);\n  });\n  purpleteam.on('exit', (code, signal) =\u003e {\n    console.debug(`Child process \"purpleteam\" exited with code: \"${code}\", and signal: \"${signal}\".`);\n  });\n  purpleteam.on('close', (code) =\u003e {\n    console.debug(`\"close\" event was emitted with code: \"${code}\" for \"purpleteam\".`);\n  });\n  purpleteam.on('error', (err) =\u003e {\n    process.stdout.write(`Failed to start \"purpleteam\" sub-process. The error was: ${err}.`);\n  });\n};\n\nstartPurpleteam();\n```\n\nFrom within your NodeJS build project run the following command to install the _PurpleTeam_ CLI locally into your NodeJS project:  \n\n```shell\nnpm install\n```\n\nIf running the _PurpleTeam_ CLI as a sub process or from another nodejs program as we do in the above example:\n\n* It will need to know where it's config.local or config.cloud file is if it's not in the usual location, which is in the config directory relative to the _PurpleTeam_ CLI root directory\n* config.js may also need to have it's `uI.path.cUi` and/or `uI.path.noUi` (depending on which you are using) property values updated due to the fact that the _PurpleTeam_ CLI is now running as a node_module dependency and the paths may not be correct based on where purpleteam is running from\n\n## NPM install globally\n\nFor example, you may have a build project/pipeline that is written in some language besides JavaScript. In this case the most suitable install technique may be to install the _PurpleTeam_ CLI globally.\n\nTo do so, run the following command:  \n\n```shell\nnpm install -g purpleteam\n```\nNow the _PurpleTeam_ CLI is installed and on your path to invoke from anywhere on your system.\n\n```shell\nwhich purpleteam\n# Will print where purpleteam is located.\n# You will need this to configure it if you choose to install globally.\n```\n\nAs mentioned under the [Clone](#clone-the-git-repository) section, another option for a system wide install is to use `npm link`.\n\n# Configure\n\n## CLI\n\nNo matter which install option you decide on the _PurpleTeam_ CLI will require configuration.\n\nIf you are planning on using the `cloud` environment copy the config/config.example.cloud.json to config/config.cloud.json and make the necessary changes.\nIf you are planning on using the `local` environment copy the config/config.example.local.json to config/config.local.json and make the necessary changes.\n\nUse the config/config.js for documentation and further examples.\n\n### `loggers.testerProgress.dirname`\n\nConfigure this property. This is where the CLI logs to. Additional details can be found on the [Log and Outcomes files](https://purpleteam-labs.com/doc/log-and-outcomes-files/#cli-purpleteam-log-files) page.\n\n### `loggers.testPlan.dirname`\n\nConfigure this property. Using the same value as used for `loggers.testerProgress.dirname` is an option. This is where the CLI logs the test plans to when running in `noUi` mode. Additional details can be found on the [Log and Outcomes files](https://purpleteam-labs.com/doc/log-and-outcomes-files/#cli-purpleteam-log-files) page.\n\n### `purpleteamApi`\n\nIf you are planning on using the `local` environment you can stick with the default property values. If you are planning on using the `cloud` environment you will be given this information when you sign-up for a _PurpleTeam_ account.\n\n### `purpleteamAuth`\n\nIf you are planning on using the `local` environment you can stick with the default property values. If you are planning on using the `cloud` environment you will be given this information when you sign-up for a _PurpleTeam_ account.\n\n\u003cdiv id=\"job_fileUri\"\u003e\u003c/div\u003e \u003c!-- Legacy anchor --\u003e\n\n### `job.fileUri`\n\nConfigure this property if you do not want to manually pass it as an argument to the CLI. This is the _Job_ file you have configured to specify your System Under Test (_SUT_) details.\n\nIf you installed the _PurpleTeam_ CLI via `git clone` (You are intending to run _PurpleTeam_ CLI stand-alone), then a relative directory path from the root of the repository (\"./testResources/jobs/your_job_file\") is acceptable.  \nIf you installed the _PurpleTeam_ CLI via `npm install` Then it's more likely that you will need this path to be absolute, as the current directory (./) is more than likely not going to be within the _PurpleTeam_ CLI project itself, but rather wherever the purpleteam binary is itself.\n\nThis value can be [overridden](#run-the-purpleteam-cli-directly---with-test-options) by passing it in as an option to the commands that require it (currently `test` and `testplan`).\n\n### `outcomes.dir`\n\nConfigure this property. This is a directory of your choosing that [_Outcomes_](https://purpleteam-labs.com/doc/definitions/) files from the _PurpleTeam_ API (_orchestrator_ if running in `local` env, AWS API Gateway if running in `cloud` env) will be persisted to. Additional details can be found on the [Log and Outcomes files](https://purpleteam-labs.com//doc/log-and-outcomes-files/#outcomes-files) page.\n\n\u003cdiv id=\"configure-ui\"\u003e\u003c/div\u003e \u003c!-- Legacy anchor --\u003e\n\n### `uI`\n\nThis property is configured by default to use the character user interface (`cUi` value) (your terminal).\nThis value can be changed in one of the following ways:\n\n* Change it directly in config/config.js\n* Add an override to your: config/config.local.json if running in the `local` environment, or config/config.cloud.json if running in the `cloud` environment\n* Exporting the `PURPLETEAM_UI` environment variable (`PURPLETEAM_UI=noUi`) for example\n\n`uI` options:\n\n* `cUi`: Is well suited to running the _PurpleTeam_ CLI directly in your terminal.  \n   With the `uI` configured to use `cUi` the following putpleteam CLI commands have the associated behaviours:  \n    * `about`: Writes to the console using the [purpleteam-logger](https://www.npmjs.com/package/purpleteam-logger) configured with the `SignaleTransport`\n    * `status`: Writes to the console using the purpleteam-logger configured with the `SignaleTransport`, via blessed\n    * `test`: Writes to file using purpleteam-logger configured with the `File` transport, writes to the console using blessed. On a successful test run, an outcomes zip file will be written to the directory specified by `outcomes.dir`\n    * `testplan`: Writes to the console using blessed\n* `noUi`: Is well suited to running the _PurpleTeam_ CLI from another process (your build/CI/CD process for example).\n   With the `uI` configured to use `noUi` the following putpleteam CLI commands have the associated behaviours:\n    * `about`: Writes to the console using the purpleteam-logger configured with the `SignaleTransport`. The about screen is written. Exits with code: \"0\"\n    * `status`: Writes the following messages to the console using the purpleteam-logger configured with the `SignaleTransport`. **These messages and their meanings apply to both `uI` modes**:\n      * `orchestrator is down, or an incorrect URL has been specified in the CLI config` if the _orchestrator_ is unreachable\n      * `orchestrator is ready to take orders.`\n      * `Test Run is in progress.`\n      \n      Exits with code: \"0\"\n    * `test`: Writes to file using purpleteam-logger configured with the `File` transport. **These messages and their meanings apply to both `uI` modes**\n      * If the orchestrator/API is unreachable: `orchestrator is down, or an incorrect URL has been specified in the CLI config` is written using the `SignaleTransport`. Exits with code: \"0\"\n      * If the orchestrator/API is reachable CLI logs will be written to the directory specified by `loggers.testerProgress.dirname` as the Test Run progresses and an outcomes zip file will be written to the directory specified by `outcomes.dir` on Test Run completion. The CLI does not terminate\n      * Retry sequence documented in [this blog post](https://binarymist.io/blog/2021/09/07/purpleteam-tls-tester-implementation/#synchronisation)\n      * If there is a _Tester_ failure `Tester failure:`... will be written using the `SignaleTransport` and to the directory specified by `loggers.testerProgress.dirname` for the specific _Tester_ that issued the `Tester failure:`... message, so you may want to keep watch on the logs for all _Testers_ if you are searching for the `Tester failure:` string. The _orchestrator_ will issue warning messages for the other _Testers_, but they may not contain the text: `Tester failure:`.  \n        This can happen for varius reasons such as:\n        * The number of _Test Sessions_ provided in the _Job_ file falls outside of the valid range:  \n          `Tester failure: The only valid number of tlsScanner resource objects is one. Please modify your Job file.`  \n          `Tester failure: The only valid number of appScanner resource objects is from 1-12 inclusive. Please modify your Job file.`\n        * `Tester failure: S2 app containers were not ready. app Tester(s) failed initialisation. Test Run aborted` - This occurs in the `cloud` environment if ECS doesn't bring the stage two containers up in time. The App Tester gives ECS 2 minutes to bring the stage two containers up, usually they come up from cold start with 40 seconds to spare, if they don't come up in {`s2Containers.serviceDiscoveryServiceInstances.timeoutToBeAvailable` (from the app-scanner config)} milliseconds then the App _Tester_ decides it is unable to start a _Test Run_ due to circumstances outside of it's control (ECS is not going to bring the stage two containers up) and the _orchestrator_ aborts the _Test Run_ with this message. The _orchestrator_ then issues the order to bring all stage two containers down (clean-up).  \n           As the _Build User_ you can rely on the text `Tester failure:` to mean you will need to initiate a retry. You can do this after some time, or continue to issue the CLI `status` command, after approximately {`coolDown.timeout` (from the _orchestrator_ config)} milliseconds the response will change from `Test Run is in progress.` to `orchestrator is ready to take orders.`, at which point you can initiate a retry (run the `test` command again)\n    * `testplan`: Writes to file using purpleteam-logger configured with the `File` transport\n      * If the orchestrator/API is down `orchestrator is down, or an incorrect URL has been specified in the CLI config` is written using the `SignaleTransport`. Exits with code: \"0\"\n      * If the orchestrator/API is up, CLI logs will be written to the directory specified by `loggers.testPlan.dirname` on completion. Exits with code: \"0\"\n\n\u003cbr\u003e\n\nThe _PurpleTeam_ CLI uses the convict package for it's configuration.\n\n### Sensitive Values (`cloud` environment only)\n\nThere are several ways you can handle the sensitive values that need to be read into the _PurpleTeam_ CLI to access your instance of the _PurpleTeam_ `cloud` service:\n\n* Place sensitive values in-line in the `config.cloud.json` file, providing you are confident that you have sufficiently locked down [file, directory permissions](https://f1.holisticinfosecforwebdevelopers.com/chap03.html#vps-identify-risks-unnecessary-and-vulnerable-services-overly-permissive-file-permissions-ownership-and-lack-of-segmentation) and access to the host that will be running the _PurpleTeam_ CLI\n* Place sensitive values in a similarly structured file but in some other directory that the _PurpleTeam_ CLI has access to and is sufficiently locked down as previously mentioned. The path of which said file can be [added to the array](https://github.com/mozilla/node-convict/tree/master/packages/convict#configloadfilefile-or-filearray) as an element that is feed to `config.loadFile` in the main `config.js` file\n* Place sensitive values in environment variables yourself, or pass them as environment variables in the current shell to the _PurpleTeam_ CLI:  \n  ```js\n  PURPLETEAM_APP_CLIENT_ID=\u003capp-client-id\u003e PURPLETEAM_APP_CLIENT_SECRET=\u003capp-client-secret\u003e PURPLETEAM_API_KEY=\u003capi-key\u003e purpleteam test\n  ```\n\nThe precedence order of where values will be read from is defined by [convict](https://github.com/mozilla/node-convict/tree/master/packages/convict#precedence-order).\n\n## Job File\n\nThe [_Job_](https://purpleteam-labs.com/doc/definitions/) file is what purpleteam uses to do the following. Most properties should be self documenting, although the official documentation is [here](https://purpleteam-labs.com/doc/jobfile/). If you are unsure of any of the properties, start a [Github discussion](https://github.com/purpleteam-labs/purpleteam/discussions) or reach out in the [#project-purpleteam channel of OWASP Slack](https://owasp.slack.com/messages/project-purpleteam).\nExamples of _Job_ files that the PurpleTeam-Labs team use can be found [here](https://github.com/purpleteam-labs/purpleteam/tree/main/testResources/jobs). Once you have defined the location of your SUT, you may want to consider defining some of the following:\n\n* Defining your [_Test Session_](https://purpleteam-labs.com/doc/definitions/)(s)\n* Authentication to your [System Under Test (_SUT_)](https://purpleteam-labs.com/doc/definitions/)\n* Which browser you may want to use to test your application in (not applicable to APIs)\n* Defining `alertThreshold`s\n* Defining specific routes to test (for browser based applications), or an API definition\n* Defining fields of each specific route (for browser based applications), other fields \"may\" also be tested\n* Work through the _Job_ file documentation, there are many additional knobs and levers you can apply and tweak\n\nRemember to keep it simple to start with.\n\n# Run\n\nThere are several ways you can run the _PurpleTeam_ CLI. The following options line up with the [Install](#install) options detailed above. Make sure you have [installed](#install) and [configured](#cli) _purpleteam_ correctly before attempting to run:\n\n## Clone the git repository option\n\nFor those that chose to [clone](#clone-the-git-repository) the _purpleteam_:\n\nYou can choose to export the `NODE_ENV` environment variable before running the following commands, or simply do so as part of running the commands. For example: `NODE_ENV=local` or `NODE_ENV=cloud`.\n\n### Run the bin/purpleteam file via npm script\n\n1. From the root directory of the _purpleteam_ repository\n2. Run one of the following commands\n   * To start the CLI:  \n     ```shell\n     npm start\n     # Should print out the PurpleTeam top level help\n     ```\n     \u003cdiv id=\"purpleteam-top-level-help\"\u003e\u003c/div\u003e\n     \u003cimg width=900px src=\"https://user-images.githubusercontent.com/2862029/107207208-e9664680-6a64-11eb-9ea9-48f40e8ef155.png\" alt=\"purpleteam top level help\"\u003e\n   * To start the CLI and pass commands (`status` for example):  \n     ```shell\n     npm start status\n     # Should print the following message if the orchestrator is not running:\n     # ☰  notice     [cUi] orchestrator is down, or an incorrect URL has been specified in the CLI config.\n     ```\n   * To start the CLI and pass commands (`test` for example):  \n     ```shell\n     npm start test\n     # Should print the following message if the orchestrator is not running:\n     # ✖  critical   [apiDecoratingAdapter] orchestrator is down, or an incorrect URL has been specified in the CLI config.\n     ```\n   * To start the CLI and pass commands (`test` for example) with options:  \n     ```shell\n     npm start test -- --help\n     # Should print the available options for the test command:\n     ```\n   * To debug the CLI (passing the `status` command for example):  \n     ```shell\n     npm run debug status\n     # Amongst other messages, you should see the following message:\n     # Debugger listening on ws://localhost:9230/...\n     ```\n     Now open your debugging UI. If you use the chrome developer tools browse to `chrome://inspect` and click the inspect link and you will be dropped into the purpleteam CLI code-base.\n\nFor further details around running and debugging review the [documentation](https://purpleteam-labs.com/doc/local/workflow/).\n\n### Run the bin/purpleteam file directly\n\n1. From the root directory of the _purpleteam_ repository\n2. Run one of the following commands\n   * To start the CLI:  \n     ```shell\n     bin/purpleteam.js\n     # Should print out the PurpleTeam top level help\n     ```\n   * To start the CLI and pass commands (`status` for example):  \n     ```shell\n     bin/purpleteam.js status\n     # Should print the following message if the orchestrator is not running:\n     # ☰  notice     [cUi] orchestrator is down, or an incorrect URL has been specified in the CLI config.\n     ```\n   * To start the CLI and pass commands (`test` for example):  \n     ```shell\n     bin/purpleteam.js test\n     # Should print the following message if the orchestrator is not running:\n     # ✖  critical   [apiDecoratingAdapter] orchestrator is down, or an incorrect URL has been specified in the CLI config.\n     ```\n   * To start the CLI and pass commands (`test` for example) with options:  \n     ```shell\n     bin/purpleteam.js test --help\n     # Should print the available options for the test command:\n     ```\n\nOr if you chose to clone the _PurpleTeam_ CLI (_purpleteam_) repository and `npm link` it, you can run it as a first class citizen:\n\n```\npurpleteam\n```\n\n## NPM install locally option\n\nFor those that chose to [install locally via npm](#npm-install-locally):\n\nThe `NODE_ENV` environment variable needs to be exported so that the _PurpleTeam_ CLI knows whether it's targeting the `cloud` or `local` environment and configuration. In the example build project we have used, `NODE_ENV` is exported as part of the NPM [scripts](https://github.com/purpleteam-labs/purpleteam-build-test-cli/blob/main/package.json#L11), and it is using the `local` environment. Feel free to swap the value to `cloud` if you have signed up for a `cloud` account.\n\nProviding your package.json and the JavaScript file (index.js in the [above example](#purpleteam-build-test-cli)) that is going to run the _PurpleTeam_ CLI is similar to those configured in the above file examples, you should be able to successfully run the following commands from the root directory of your NodeJS CI/nightly build/build pipeline project.\n\n### Run the PurpleTeam CLI directly\n\n```shell\nnpm run purpleteam\n# Should print out the PurpleTeam top level help\n```\n\n### Run the PurpleTeam CLI directly - with `status` command\n\nRun the _PurpleTeam_ CLI directly but pass the `status` command to `purpleteam`:\n\n```shell\nnpm run purpleteam status\n# Should print the following message if the orchestrator is not yet running. Be patient, PurpleTeam CLI retries:\n# ☰  notice     [cUi] orchestrator is down, or an incorrect URL has been specified in the CLI config.\n```\n\n### Run the PurpleTeam CLI directly - with `test` command\n\nRun the _PurpleTeam_ CLI directly but pass the `test` command to `purpleteam`:\n\n```shell\nnpm run purpleteam test\n# Should print the following message if the orchestrator is not yet running:\n# ✖  critical   [apiDecoratingAdapter] orchestrator is down, or an incorrect URL has been specified in the CLI config.\n```\n\n### Run the PurpleTeam CLI directly - with `test` options\n\nRun the _PurpleTeam_ CLI directly but you want to see the help options for the `test` command:\n\n```shell\nnpm run purpleteam test -- --help\n# Should print the available options for the test command:\n```\n\n### Run your app (build pipeline)\n\nRun your NodeJS CI/nightly build/build pipeline project. This will start the NodeJS application we [defined above](#purpleteam-build-test-cli) which will [`spawn`](https://github.com/purpleteam-labs/purpleteam-build-test-cli/blob/189d2f42de46b1484d6195a048505da61cfcd201/index.js#L12-L18) the [`purpleteam test`](https://github.com/purpleteam-labs/purpleteam-build-test-cli/blob/189d2f42de46b1484d6195a048505da61cfcd201/index.js#L8) command.\n\nYou could change the `const purpleteamArgs = ['purpleteam', 'test'];` to use any other _PurpleTeam_ CLI commands, options, or neither.\n\nWhen running the _PurpleTeam_ CLI from another process, you will usually want to export `PURPLETEAM_UI=noUi` as mentioned in the [NPM install locally](#npm-install-locally) sub-section and detailed in the [Configure `uI`](#configure-ui) sub-section.\n\n```shell\nnpm start\n# If the orchestrator is not yet running:\n# Should print the following via the purpleteam.stdout.on('data'... handler\n# ✖  critical   [apiDecoratingAdapter] orchestrator is down, or an incorrect URL has been specified in the CLI config.\n```\n\nIf you get a blank screen or _purpleteam_ help text with an error or warning via a `?⃝  warning` logged to your terminal, please confirm you have [configured](#job_fileUri) _purpleteam_ correctly.\n\nWhen running the _PurpleTeam_ CLI embedded, you should expect the behaviours specified under the [Configure `uI`](#ui) sub-section for the associated _PurpleTeam_ CLI commands.\n\n### Debug your app (build pipeline)\n\nIf you need to debug your NodeJS CI/nightly build/build pipeline project, run the following command:\n\n```shell\nnpm run debugApp\n```\n\nNow open your debugging UI. If you use the chrome developer tools browse to `chrome://inspect` and click the inspect link and you will be dropped into your app (index.js in this case).\n\n### Debug your app and PurpleTeam CLI\n\nIf you need to debug your NodeJS CI/nightly build/build pipeline project as well as the _PurpleTeam_ CLI, do the following:\n\n1. Make sure your debugging UI is configured to listen on the application and CLI debug ports:\n   * `localhost:9230` as defined in the above package.json\n   * `localhost:9231` as defined in the above index.js\n2. run the following command:  \n   ```shell\n   npm run debugAppAndCli\n   ```\n3. Then open your debugging UI. If you use the chrome developer tools browse to `chrome://inspect` and click the \"inspect\" link and you will be dropped into your app (index.js in this case)\n4. Step through the index.js file until the _purpleteam_ process is spawned, at which point you will see the second \"inspect\" link if using the chrome developer tools\n5. Click the second \"inspect\" link and you should be dropped into the _purpleteam_ source code. Now you can step through and inspect both your application code and the _PurpleTeam_ CLI code\n\n\n\n## NPM install globally option\n\nFor those that chose to [install globally via npm](#npm-install-globally):\n\nYou can choose to export the `NODE_ENV` environment variable before running the following commands, or simply do so as part of running the commands.\n\n```shell\nNODE_ENV=local purpleteam\n# Or export NODE_ENV then just run:\npurpleteam\n# Should print out the PurpleTeam top level help\n```\n\nRun any of the [_PurpleTeam_ CLI commands](#purpleteam-top-level-help) as you would with the install of any other system wide binary.\n\nIf you choose to clone the _PurpleTeam_ CLI repository and run `npm link` from it's root directory, the same applies. Plus you get to continue to modify the _PurpleTeam_ CLI config without reinstalling.\n\n# Usage\n\nIf you are running the _PurpleTeam_ CLI in the default [character user interface (`cUi`) mode](#configure-ui) there are some interactions you can perform in the terminal while the CLI is running.\nThe following commands have the associated interactions available:\n\n* `test`: Once testing is under way, you can:\n  * [right-arrow], [left-arrow] through the terminal screens to view the testing progress of each of the [_Testers_](https://purpleteam-labs.com/doc/definitions/) in real-time courtesy of the _PurpleTeam_ API.\n    Another way to follow the log file in real-time for another _Tester_ (TLS for example) is to copy the name of the CLI log file being created and run the following command in another terminal:  \n    `tail tls-NA_[date]T[time].log -f -n +1`\n  * [down-arrow], [up-arrow] to highlight the different Running Statistics of the _Testers_ as they are provided in real-time courtesy of the _PurpleTeam_ API\n* `testplan`: Once the test plans have been retrieved, you can [right-arrow], [left-arrow] through the terminal screens to view the test plans of each specific [_Tester_](https://purpleteam-labs.com/doc/definitions/)\n\n# Trouble-Shooting\n\nIf you encounter any problems with the CLI set-up and you have read and applied the directions, check the [trouble-shooting](https://purpleteam-labs.com/doc/trouble-shooting/) page.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpurpleteam-labs%2Fpurpleteam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpurpleteam-labs%2Fpurpleteam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpurpleteam-labs%2Fpurpleteam/lists"}