{"id":17132187,"url":"https://github.com/bitsofinfo/io-event-reactor-plugin-shell-exec","last_synced_at":"2025-03-24T05:18:43.602Z","repository":{"id":57275603,"uuid":"60539007","full_name":"bitsofinfo/io-event-reactor-plugin-shell-exec","owner":"bitsofinfo","description":"Shell exec filesystem event reactor plugin for: io-event-reactor https://github.com/bitsofinfo/io-event-reactor","archived":false,"fork":false,"pushed_at":"2016-11-10T23:56:23.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-29T08:20:50.562Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitsofinfo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-06T15:28:05.000Z","updated_at":"2016-06-06T17:02:11.000Z","dependencies_parsed_at":"2022-09-15T19:12:49.065Z","dependency_job_id":null,"html_url":"https://github.com/bitsofinfo/io-event-reactor-plugin-shell-exec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fio-event-reactor-plugin-shell-exec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fio-event-reactor-plugin-shell-exec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fio-event-reactor-plugin-shell-exec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fio-event-reactor-plugin-shell-exec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitsofinfo","download_url":"https://codeload.github.com/bitsofinfo/io-event-reactor-plugin-shell-exec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245212311,"owners_count":20578443,"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-10-14T19:26:18.886Z","updated_at":"2025-03-24T05:18:43.571Z","avatar_url":"https://github.com/bitsofinfo.png","language":"JavaScript","readme":"# io-event-reactor-plugin-shell-exec\n\n[![Build Status](https://travis-ci.org/bitsofinfo/io-event-reactor-plugin-shell-exec.svg?branch=master)](https://travis-ci.org/bitsofinfo/io-event-reactor-plugin-shell-exec)\n\nShell exec filesystem event reactor plugin for: [io-event-reactor](https://github.com/bitsofinfo/io-event-reactor) that\nutilizes [stateful-process-command-proxy](https://github.com/bitsofinfo/stateful-process-command-proxy) for executing\nsystem commands in any shell (bash, sh, powershell, ksh, whatever)\n\n[![NPM](https://nodei.co/npm/io-event-reactor-plugin-shell-exec.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/io-event-reactor-plugin-shell-exec/)\n\n## Usage\n\nTo configure this ReactorPlugin in your application that uses [io-event-reactor](https://github.com/bitsofinfo/io-event-reactor) do the following\n\n```\nnpm install io-event-reactor-plugin-shell-exec\n```\n\nThen in your [io-event-reactor](https://github.com/bitsofinfo/io-event-reactor) configuration object that you pass to the `IoReactorService`\nconstructor, you can specify this plugin in the `reactors` block as so:\n\n```\nvar ioReactorServiceConf = {\n\n  ...\n\n  ioReactors: [\n\n          {\n              id: \"reactor1\",\n\n              monitor: {\n                  ...\n              },\n\n              evaluators: [\n                  {\n                      evaluator: myEvaluatorFunction,\n                      reactors: ['shellExec1,...'] // binds shell-exec to this evaluator\n                  }\n              ],\n\n              reactors: [\n\n                  // the \"id\" is what you use to bind this reactor\n                  // to an evaluator above\n                  { id: \"shellExec1\",\n\n                    plugin: \"io-event-reactor-plugin-shell-exec\",\n\n                    config: {\n\n                        // Configuration for stateful-process-command-proxy\n                        // for options see: https://github.com/bitsofinfo/stateful-process-command-proxy\n                        statefulProcessCommandProxy: {\n\n                            // instance: refToExistingInstance\n                            // OR\n                            // pass a new config\n                            \n                            config: {\n                                name: \"whateverYouWant\",\n                                max: 2,\n                                min: 1,\n                                idleTimeoutMS: 120000,\n                                logFunction: yourLoggerFunction,\n                                processCommand: '/bin/bash',\n                                processArgs:  ['-s'],\n                                processRetainMaxCmdHistory : 10,\n                                processCwd : './',\n                                validateFunction: function(processProxy) {\n                                    return processProxy.isValid();\n                                }\n                            }\n                        },\n\n                        /**\n                        * 'commandTemplates' - an array of mustache (https://github.com/janl/mustache.js) command template strings\n                        *                   that will be executed in order using node-mysql when this plugin's react() is invoked.\n                        *\n                        *  Supported mustache template variables that will be made available to you: (a full IoEvent)\n                        *    - see https://github.com/bitsofinfo/io-event-reactor-plugin-support for IoEvent definition\n                        *    - ioEvent.uuid\n                        *    - ioEvent.eventType: one of: 'add', 'addDir', 'unlink', 'unlinkDir', 'change'\n                        *    - ioEvent.fullPath: string full path to file being reacted to (filename/dir inclusive)\n                        *    - ioEvent.parentPath: full path to the directory containing the item manipulated\n                        *    - ioEvent.filename: filename/dirname only (no path information)\n                        *    - ioEvent.optionalFsStats: optional stats object -\u003e https://nodejs.org/docs/latest/api/fs.html#fs_class_fs_stats\n                        *    - ioEvent.optionalExtraInfo: optional object, see the MonitorPlugin you are using to see the spec and when/if its available\n                        */\n                        commandTemplates: [\n                            'cp {{{ioEvent.fullpath}}} /some/other/dir'\n                        ],\n\n                        /**\n                        * 'commandGenerator' - callback function(ioEvent) that must return an array[] of command statements\n                        *                     literals that will be executed in order using\n                        *                     stateful-process-command-proxy when this plugin's react() is invoked.\n                        */\n                        commandGenerator: function(ioEvent) {\n                          return [('cp '+ioEvent.fullpath+' /some/other/dir')];\n                        }\n                     }\n                  },\n\n                  ....\n              ]\n        },\n        ....\n    ]\n\n    ...\n};\n```\n\n### Security\n\nBe aware that this plugin takes raw input from events generated by a monitor plugin\nand allows you to use that data in shell statements that will be executed on your operating system.\nThis potentially could open you up to certain edge cases where command injection could occur.\nIf you are concerned about this you may only want to use the `commandGenerator` option to pre-santize all\narguments before you create shell statements to be executed.\n\n[stateful-process-command-proxy](https://github.com/bitsofinfo/stateful-process-command-proxy) itself has\nsome extensive options built into it that permit you to whitelist and blacklist commands via custom\nregular expressions. This is one potential way you can mitigate such injection issues.\n\n### Unit tests\n\nTo run the unit tests go to the root of the project and run the following.\n\n```\nmocha test/all.js\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fio-event-reactor-plugin-shell-exec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitsofinfo%2Fio-event-reactor-plugin-shell-exec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fio-event-reactor-plugin-shell-exec/lists"}