{"id":19478868,"url":"https://github.com/xan105/node-processmonitor","last_synced_at":"2025-04-25T15:30:59.930Z","repository":{"id":43306072,"uuid":"301710553","full_name":"xan105/node-processMonitor","owner":"xan105","description":"Monitor Windows process creation/deletion events","archived":false,"fork":false,"pushed_at":"2024-10-26T02:09:33.000Z","size":150374,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-09T12:43:57.534Z","etag":null,"topics":["instancecreationevent","instancedeletionevent","instanceoperationevent","monitor","nodejs","process","windows","wmi","wql"],"latest_commit_sha":null,"homepage":"","language":"C++","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/xan105.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"xan105","custom":"https://www.paypal.me/xan105"}},"created_at":"2020-10-06T11:55:20.000Z","updated_at":"2024-10-28T08:13:45.000Z","dependencies_parsed_at":"2024-05-10T16:43:58.778Z","dependency_job_id":"fb4c423a-8cd1-4b0b-aa0b-a35b7ce57e58","html_url":"https://github.com/xan105/node-processMonitor","commit_stats":{"total_commits":78,"total_committers":1,"mean_commits":78.0,"dds":0.0,"last_synced_commit":"1a465297e6647d9ad13d580aa3630e572a45b625"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xan105%2Fnode-processMonitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xan105%2Fnode-processMonitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xan105%2Fnode-processMonitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xan105%2Fnode-processMonitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xan105","download_url":"https://codeload.github.com/xan105/node-processMonitor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224008026,"owners_count":17240290,"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":["instancecreationevent","instancedeletionevent","instanceoperationevent","monitor","nodejs","process","windows","wmi","wql"],"created_at":"2024-11-10T19:51:46.392Z","updated_at":"2024-11-10T19:51:47.655Z","avatar_url":"https://github.com/xan105.png","language":"C++","funding_links":["https://patreon.com/xan105","https://www.paypal.me/xan105"],"categories":[],"sub_categories":[],"readme":"About\n=====\n\nMonitor Windows process creation/deletion events.\n\nExample\n=======\n\n```js\nimport { subscribe } from \"wql-process-monitor\";\n\nconst processMonitor = await subscribe({\n  creation: true,\n  deletion: true\n});\n\nprocessMonitor.on(\"creation\", ([process, pid, filepath, user]) =\u003e {\n  console.log(`creation: ${process}::${pid}(${user}) [\"${filepath}\"]`);\n});\n\nprocessMonitor.on(\"deletion\",([process, pid, filepath]) =\u003e {\n  console.log(`deletion: ${process}::${pid} [\"${filepath}\"]`);\n});\n\n//Keep the event loop running\nsetInterval(()=\u003e{}, 1000 * 60 * 60);\n/*\nYou don't need this if you have something else to keep the event loop running.\nThis is just an example so Node.js doesn't exit directly.\n*/\n```\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/xan105/node-processMonitor/raw/main/screenshot/example.png\"\u003e\n\u003c/p\u003e\n\nDo something when a specific process is started :\n\n```js\nconst processMonitor = await subscribe({\n  creation: true,\n  deletion: false,\n  bin: {\n    filter: [\"firefox.exe\"],\n    whitelist: true\n  }\n});\n\nprocessMonitor.on(\"creation\", ([process, pid, filepath, user]) =\u003e {\n  //Do something only when \"firefox.exe\" is started (creation)\n});\n```\n\nInstallation\n============\n\n```\nnpm install wql-process-monitor\n```\n\nPrerequisite: C/C++ build tools (Visual Studio) and Python 3.x (node-gyp) in order to build [koffi](https://www.npmjs.com/package/koffi).\n\nAPI\n===\n\n⚠️ This module is only available as an ECMAScript module (ESM) starting with version 2.0.0.\u003cbr /\u003e\nPrevious version(s) are CommonJS (CJS) with an ESM wrapper.\n\n## Named export\n\n### `subscribe(option?: object): Promise\u003cAsyncEventEmitter\u003e`\n\nSubscribe to an operation event. You must at least choose one.\n\n**⚙️ Options:**\n\n- creation?: boolean | `true`\n\n  Subscribe to the creation event.\n\n- deletion?: boolean | `true`\n\n\tSubscribe to the deletion event.\n\n- dir?: object\n\n\u003cdetails\u003e\u003csummary\u003eFilter via path:\u003c/summary\u003e\n\n  + filter?: string[] | `[] (none)`\n  \n    Exclude events originating from a list of path(s). This can be a full path or a part of it.\u003cbr/\u003e\n    Path separator can either be `/` (Unix) or `\\\\` (Windows).\n    \n  + whitelist?: boolean | `false`\n\n    Turn the above filter option into a whitelist instead of a blacklist.\u003cbr/\u003e\n    Only the events originating from the list will be allowed.\n    \n    ⚠️ When filtering by executable path you won't be able to catch any elevated process event. Unless you are also elevated. \n    This is a Windows permission issue: \n    \n    WMI `executablePath` requires `SeDebugPrivilege` permission in this case. This token is automatically granted when running with admin privileges. You can set this permission for regular user via group policy but this is considered as a security risk. \n    NB: Please be advised that this library doesn't try to adjust token privilege.\n\n    ⚠️ There is a hard limit to the number of elements you can filter depending on how complex the query is\n    which will cause WMI to return `WBEM_E_QUOTA_VIOLATION`.\n\n    💡 In such cases consider implementing your own filter on top of the event emitter result instead.\n\n\u003c/details\u003e\n  \n- bin?: object\n\n\u003cdetails\u003e\u003csummary\u003eFilter via name:\u003c/summary\u003e\n\n  + filter?: string[] | `[] (none)`\n  \n    List of process to exclude.\u003cbr/\u003e\n    eg: [\"firefox.exe\", \"chrome.exe\", ...]\n    \n  + whitelist?: boolean | `false`\n\n\t  Turn the above filter option into a whitelist instead of a blacklist.\u003cbr/\u003e\n    Only the process from the list will be allowed.\n    \n    ⚠ ️There is a hard limit to the number of elements you can filter depending on how complex the query is which will cause WMI to return `WBEM_E_QUOTA_VIOLATION`.\n\n    💡 In such case consider implementing your own filter on top of the event emitter result instead.\n\n\u003c/details\u003e\n\n**Return**\n\nReturns a non-blocking async event emitter ([emittery](https://github.com/sindresorhus/emittery)):\n\n```ts\n.on(event: \"creation | deletion\", ([\n    process: string, //process name\n    pid: string, //process identifier\n    filepath: string, //file location path\n    user: string //process owner\n]) =\u003e {})\n```\n\n⚠️ `filepath` and/or `user` _might_ be empty if you don't have the permission to access the corresponding process information.\n\n💡 NB: Don't forget to keep the node.js event loop alive.\n\n### `createEventSink(): Promise\u003cvoid\u003e`\n\nInitialize the event sink.\u003cbr/\u003e\nThis is required to do before you can subscribe to any events.\u003cbr/\u003e\nIf the event sink is already initialized then nothing will be done.\n\n💡 Since version \u003e= 2.0.0 this is automatically done for you when you call `subscribe()`.\u003cbr/\u003e\nMethod was merely kept for backward compatibility.\n\n⚠️ If your application (the caller thread) is initializing a COM library you need to set the thread model to [COINIT_MULTITHREADED](https://docs.microsoft.com/en-us/windows/win32/api/combaseapi/nf-combaseapi-coinitializeex)\n\nNB: For this reason using this in Electron's main process isn't viable. Workarounds are in no particular preference order:\n\n- fork a child process via `utilityProcess`\n- fork a regular node child process\n- use web workers\n- use a hidden browser window with node integration and communicate between the main process and background window via IPC.\n\n### `closeEventSink(): Promise\u003cvoid\u003e`\n\n**Properly** close the event sink.\u003cbr/\u003e\nThere is no \"un-subscribe\" thing to do prior to closing the sink. Just close it.\u003cbr/\u003e\nIt is recommended to properly close the event sink when you are done if you intend to re-open it later on.\u003cbr/\u003e\nMost of the time you wouldn't have to bother with this but it's here in case you need it.\n\nNB: This method will also remove every event listener.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxan105%2Fnode-processmonitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxan105%2Fnode-processmonitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxan105%2Fnode-processmonitor/lists"}