first commit
This commit is contained in:
Artem Anufrij
+175
@@ -0,0 +1,175 @@
|
||||
import type {ExecFileOptions, ExecFileSyncOptions} from 'node:child_process';
|
||||
|
||||
export type ExecutePowerShellOptions = Omit<ExecFileOptions, 'shell'> & {
|
||||
/**
|
||||
Path to PowerShell executable.
|
||||
|
||||
@default powerShellPath()
|
||||
*/
|
||||
readonly powerShellPath?: string;
|
||||
|
||||
/**
|
||||
Not supported. PowerShell is always executed directly to prevent shell injection.
|
||||
*/
|
||||
readonly shell?: never;
|
||||
};
|
||||
|
||||
export type ExecutePowerShellSyncOptions = Omit<ExecFileSyncOptions, 'shell'> & {
|
||||
/**
|
||||
Path to PowerShell executable.
|
||||
|
||||
@default powerShellPath()
|
||||
*/
|
||||
readonly powerShellPath?: string;
|
||||
|
||||
/**
|
||||
Not supported. PowerShell is always executed directly to prevent shell injection.
|
||||
*/
|
||||
readonly shell?: never;
|
||||
};
|
||||
|
||||
export type ExecutePowerShellResult = {
|
||||
readonly stdout: string;
|
||||
readonly stderr: string;
|
||||
};
|
||||
|
||||
/**
|
||||
Get the PowerShell executable path on Windows.
|
||||
|
||||
@returns The path to the PowerShell executable.
|
||||
|
||||
@example
|
||||
```
|
||||
import {powerShellPath} from 'powershell-utils';
|
||||
|
||||
const psPath = powerShellPath();
|
||||
//=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
|
||||
```
|
||||
*/
|
||||
export function powerShellPath(): string;
|
||||
|
||||
/**
|
||||
Check if PowerShell is accessible on Windows.
|
||||
|
||||
This checks if the PowerShell executable exists and has execute permissions. Useful for detecting restricted environments where PowerShell may be disabled by administrators.
|
||||
|
||||
@returns A promise that resolves to true if PowerShell is accessible, false otherwise.
|
||||
|
||||
@example
|
||||
```
|
||||
import {canAccessPowerShell} from 'powershell-utils';
|
||||
|
||||
if (await canAccessPowerShell()) {
|
||||
console.log('PowerShell is available');
|
||||
} else {
|
||||
console.log('PowerShell is not accessible');
|
||||
}
|
||||
```
|
||||
*/
|
||||
export function canAccessPowerShell(): Promise<boolean>;
|
||||
|
||||
/**
|
||||
Execute a PowerShell command.
|
||||
|
||||
@param command - The PowerShell command to execute.
|
||||
@returns A promise that resolves to the command output.
|
||||
|
||||
@example
|
||||
```
|
||||
import {executePowerShell} from 'powershell-utils';
|
||||
|
||||
const {stdout} = await executePowerShell('Get-Process');
|
||||
console.log(stdout);
|
||||
```
|
||||
*/
|
||||
export function executePowerShell(
|
||||
command: string,
|
||||
options?: ExecutePowerShellOptions
|
||||
): Promise<ExecutePowerShellResult>;
|
||||
|
||||
export namespace executePowerShell {
|
||||
/**
|
||||
Standard PowerShell arguments that prefix the encoded command: `['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand']`
|
||||
|
||||
Exposed for debugging or for advanced use cases where you need to customize the arguments. For most cases, use `createArguments()` instead.
|
||||
*/
|
||||
export const argumentsPrefix: readonly string[];
|
||||
|
||||
/**
|
||||
Encode a PowerShell command as Base64 UTF-16LE.
|
||||
|
||||
This encoding prevents shell escaping issues and ensures complex commands with special characters are executed reliably.
|
||||
|
||||
@param command - The PowerShell command to encode.
|
||||
@returns Base64-encoded command.
|
||||
|
||||
@example
|
||||
```
|
||||
import {executePowerShell} from 'powershell-utils';
|
||||
|
||||
const encoded = executePowerShell.encodeCommand('Get-Process');
|
||||
```
|
||||
*/
|
||||
export function encodeCommand(command: string): string;
|
||||
|
||||
/**
|
||||
Escape a string argument for use in PowerShell single-quoted strings.
|
||||
|
||||
This makes a value safe as a PowerShell string literal, not as an argument to a native program. PowerShell removes the outer quotes before passing a value onwards, and the receiving process then re-splits it under its own command-line rules, where spaces and double quotes are delimiters. For example, `Start-Process -ArgumentList` receives `'a b'` as two arguments rather than one.
|
||||
|
||||
Escaping also does not make an untrusted value safe to use as the program that `Start-Process` runs. Validate such values against an allowlist.
|
||||
|
||||
@param value - The value to escape.
|
||||
@returns Escaped and quoted string ready for PowerShell.
|
||||
|
||||
@example
|
||||
```
|
||||
import {executePowerShell} from 'powershell-utils';
|
||||
|
||||
const escaped = executePowerShell.escapeArgument("it's a test");
|
||||
//=> "'it''s a test'"
|
||||
|
||||
// Use in command building
|
||||
const command = `Start-Process ${executePowerShell.escapeArgument(appName)}`;
|
||||
```
|
||||
*/
|
||||
export function escapeArgument(value: unknown): string;
|
||||
|
||||
/**
|
||||
Create the full arguments array for PowerShell execution.
|
||||
|
||||
Combines `argumentsPrefix` with the encoded command. Useful when using `spawn()`, `execFile()`, or other process execution methods.
|
||||
|
||||
@param command - The PowerShell command.
|
||||
@returns Array of arguments ready to pass to a process spawner.
|
||||
|
||||
@example
|
||||
```
|
||||
import {spawn} from 'node:child_process';
|
||||
import {powerShellPath, executePowerShell} from 'powershell-utils';
|
||||
|
||||
const args = executePowerShell.createArguments('Get-Process');
|
||||
spawn(powerShellPath(), args);
|
||||
```
|
||||
*/
|
||||
export function createArguments(command: string): string[];
|
||||
}
|
||||
|
||||
/**
|
||||
Execute a PowerShell command synchronously.
|
||||
|
||||
@param command - The PowerShell command to execute.
|
||||
@returns The stdout output as a string.
|
||||
|
||||
@example
|
||||
```
|
||||
import {executePowerShellSync} from 'powershell-utils';
|
||||
|
||||
const stdout = executePowerShellSync('Get-Process');
|
||||
console.log(stdout);
|
||||
```
|
||||
*/
|
||||
export function executePowerShellSync(
|
||||
command: string,
|
||||
options?: ExecutePowerShellSyncOptions
|
||||
): string;
|
||||
+79
@@ -0,0 +1,79 @@
|
||||
import process from 'node:process';
|
||||
import {Buffer} from 'node:buffer';
|
||||
import {promisify} from 'node:util';
|
||||
import childProcess from 'node:child_process';
|
||||
import fs, {constants as fsConstants} from 'node:fs/promises';
|
||||
|
||||
const execFile = promisify(childProcess.execFile);
|
||||
|
||||
export const powerShellPath = () => `${process.env.SYSTEMROOT || process.env.windir || String.raw`C:\Windows`}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
|
||||
|
||||
// Cache for PowerShell accessibility check
|
||||
let canAccessCache;
|
||||
|
||||
export const canAccessPowerShell = async () => {
|
||||
canAccessCache ??= (async () => {
|
||||
try {
|
||||
await fs.access(powerShellPath(), fsConstants.X_OK);
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
})();
|
||||
|
||||
return canAccessCache;
|
||||
};
|
||||
|
||||
const argumentsPrefix = [
|
||||
'-NoProfile',
|
||||
'-NonInteractive',
|
||||
'-ExecutionPolicy',
|
||||
'Bypass',
|
||||
'-EncodedCommand',
|
||||
];
|
||||
|
||||
const encodeCommand = command => Buffer.from(command, 'utf16le').toString('base64');
|
||||
|
||||
/*
|
||||
PowerShell's tokenizer treats the typographic single quotes U+2018, U+2019, U+201A, and U+201B as string delimiters, exactly like the ASCII one, and it does not require the closing quote to match the opening quote. Escaping only the ASCII quote would let any of the others terminate the string and inject a statement. Doubling works for all of them.
|
||||
*/
|
||||
const escapeArgument = value => `'${String(value).replaceAll(/['‘’‚‛]/g, match => match + match)}'`;
|
||||
|
||||
const createArguments = command => [...argumentsPrefix, encodeCommand(command)];
|
||||
|
||||
const createExecFileOptions = options => ({
|
||||
encoding: 'utf8',
|
||||
...options,
|
||||
shell: false,
|
||||
});
|
||||
|
||||
export const executePowerShell = async (command, options = {}) => {
|
||||
const {
|
||||
powerShellPath: psPath,
|
||||
...execFileOptions
|
||||
} = options;
|
||||
|
||||
return execFile(
|
||||
psPath ?? powerShellPath(),
|
||||
createArguments(command),
|
||||
createExecFileOptions(execFileOptions),
|
||||
);
|
||||
};
|
||||
|
||||
executePowerShell.argumentsPrefix = argumentsPrefix;
|
||||
executePowerShell.encodeCommand = encodeCommand;
|
||||
executePowerShell.escapeArgument = escapeArgument;
|
||||
executePowerShell.createArguments = createArguments;
|
||||
|
||||
export const executePowerShellSync = (command, options = {}) => {
|
||||
const {
|
||||
powerShellPath: psPath,
|
||||
...execFileOptions
|
||||
} = options;
|
||||
|
||||
return childProcess.execFileSync(
|
||||
psPath ?? powerShellPath(),
|
||||
createArguments(command),
|
||||
createExecFileOptions(execFileOptions),
|
||||
);
|
||||
};
|
||||
+9
@@ -0,0 +1,9 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
{
|
||||
"name": "powershell-utils",
|
||||
"version": "0.2.1",
|
||||
"description": "Utilities for executing PowerShell commands",
|
||||
"license": "MIT",
|
||||
"repository": "sindresorhus/powershell-utils",
|
||||
"funding": "https://github.com/sponsors/sindresorhus",
|
||||
"author": {
|
||||
"name": "Sindre Sorhus",
|
||||
"email": "sindresorhus@gmail.com",
|
||||
"url": "https://sindresorhus.com"
|
||||
},
|
||||
"type": "module",
|
||||
"exports": {
|
||||
"types": "./index.d.ts",
|
||||
"default": "./index.js"
|
||||
},
|
||||
"sideEffects": false,
|
||||
"engines": {
|
||||
"node": ">=20"
|
||||
},
|
||||
"scripts": {
|
||||
"test": "xo && ava && tsc index.d.ts --skipLibCheck"
|
||||
},
|
||||
"files": [
|
||||
"index.js",
|
||||
"index.d.ts"
|
||||
],
|
||||
"keywords": [
|
||||
"powershell",
|
||||
"windows",
|
||||
"execute",
|
||||
"command",
|
||||
"shell",
|
||||
"console",
|
||||
"terminal",
|
||||
"cli",
|
||||
"spawn",
|
||||
"exec",
|
||||
"utilities"
|
||||
],
|
||||
"devDependencies": {
|
||||
"ava": "^6.4.1",
|
||||
"typescript": "^5.9.3",
|
||||
"xo": "^0.59.0"
|
||||
}
|
||||
}
|
||||
+209
@@ -0,0 +1,209 @@
|
||||
# powershell-utils
|
||||
|
||||
> Utilities for executing PowerShell commands
|
||||
|
||||
## Install
|
||||
|
||||
```sh
|
||||
npm install powershell-utils
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```js
|
||||
import {executePowerShell, powerShellPath} from 'powershell-utils';
|
||||
|
||||
const {stdout} = await executePowerShell('Get-Process');
|
||||
console.log(stdout);
|
||||
|
||||
console.log(powerShellPath());
|
||||
//=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
### powerShellPath()
|
||||
|
||||
Returns: `string`
|
||||
|
||||
Get the PowerShell executable path on Windows.
|
||||
|
||||
```js
|
||||
import {powerShellPath} from 'powershell-utils';
|
||||
|
||||
const psPath = powerShellPath();
|
||||
//=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
|
||||
```
|
||||
|
||||
### canAccessPowerShell()
|
||||
|
||||
Returns: `Promise<boolean>`
|
||||
|
||||
Check if PowerShell is accessible on Windows.
|
||||
|
||||
This checks if the PowerShell executable exists and has execute permissions. Useful for detecting restricted environments where PowerShell may be disabled by administrators.
|
||||
|
||||
```js
|
||||
import {canAccessPowerShell} from 'powershell-utils';
|
||||
|
||||
if (await canAccessPowerShell()) {
|
||||
console.log('PowerShell is available');
|
||||
} else {
|
||||
console.log('PowerShell is not accessible');
|
||||
}
|
||||
```
|
||||
|
||||
### executePowerShell(command, options?)
|
||||
|
||||
Returns: `Promise<{stdout: string, stderr: string}>`
|
||||
|
||||
Execute a PowerShell command.
|
||||
|
||||
```js
|
||||
import {executePowerShell} from 'powershell-utils';
|
||||
|
||||
const {stdout} = await executePowerShell('Get-Process');
|
||||
console.log(stdout);
|
||||
```
|
||||
|
||||
#### command
|
||||
|
||||
Type: `string`
|
||||
|
||||
The PowerShell command to execute.
|
||||
|
||||
#### options
|
||||
|
||||
Type: `object`
|
||||
|
||||
The below option and all options except `shell` in Node.js [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_processexecfilefile-args-options-callback) are supported. PowerShell is always executed directly to prevent shell injection.
|
||||
|
||||
##### powerShellPath
|
||||
|
||||
Type: `string`\
|
||||
Default: `powerShellPath()`
|
||||
|
||||
Path to PowerShell executable. Useful when calling from WSL or when PowerShell is in a non-standard location.
|
||||
|
||||
##### encoding
|
||||
|
||||
Type: `string`\
|
||||
Default: `'utf8'`
|
||||
|
||||
Character encoding for stdout and stderr.
|
||||
|
||||
### executePowerShell.argumentsPrefix
|
||||
|
||||
Type: `string[]`
|
||||
|
||||
Standard PowerShell arguments that prefix the encoded command: `['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand']`
|
||||
|
||||
Exposed for debugging or for advanced use cases where you need to customize the arguments. For most cases, use `createArguments()` instead.
|
||||
|
||||
### executePowerShell.encodeCommand(command)
|
||||
|
||||
Returns: `string`
|
||||
|
||||
Encode a PowerShell command as Base64 UTF-16LE.
|
||||
|
||||
This encoding prevents shell escaping issues and ensures complex commands with special characters are executed reliably.
|
||||
|
||||
#### command
|
||||
|
||||
Type: `string`
|
||||
|
||||
The PowerShell command to encode.
|
||||
|
||||
```js
|
||||
import {executePowerShell} from 'powershell-utils';
|
||||
|
||||
const encoded = executePowerShell.encodeCommand('Get-Process');
|
||||
```
|
||||
|
||||
### executePowerShell.escapeArgument(value)
|
||||
|
||||
Returns: `string`
|
||||
|
||||
Escape a string argument for use in PowerShell single-quoted strings.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> This makes a value safe as a PowerShell string literal, not as an argument to a native program. PowerShell removes the outer quotes before passing a value onwards, and the receiving process then re-splits it under its own command-line rules, where spaces and double quotes are delimiters. For example, `Start-Process -ArgumentList` receives `'a b'` as two arguments rather than one.
|
||||
>
|
||||
> Escaping also does not make an untrusted value safe to use as the program that `Start-Process` runs. Validate such values against an allowlist.
|
||||
|
||||
#### value
|
||||
|
||||
Type: `unknown`
|
||||
|
||||
The value to escape.
|
||||
|
||||
```js
|
||||
import {executePowerShell} from 'powershell-utils';
|
||||
|
||||
const escaped = executePowerShell.escapeArgument("it's a test");
|
||||
//=> "'it''s a test'"
|
||||
|
||||
// Use in command building
|
||||
const command = `Start-Process ${executePowerShell.escapeArgument(appName)}`;
|
||||
```
|
||||
|
||||
### executePowerShell.createArguments(command)
|
||||
|
||||
Returns: `string[]`
|
||||
|
||||
Create the full arguments array for PowerShell execution.
|
||||
|
||||
Combines `argumentsPrefix` with the encoded command. Useful when using `spawn()`, `execFile()`, or other process execution methods.
|
||||
|
||||
#### command
|
||||
|
||||
Type: `string`
|
||||
|
||||
The PowerShell command.
|
||||
|
||||
```js
|
||||
import {spawn} from 'node:child_process';
|
||||
import {powerShellPath, executePowerShell} from 'powershell-utils';
|
||||
|
||||
const args = executePowerShell.createArguments('Get-Process');
|
||||
spawn(powerShellPath(), args);
|
||||
```
|
||||
|
||||
### executePowerShellSync(command, options?)
|
||||
|
||||
Returns: `string`
|
||||
|
||||
Execute a PowerShell command synchronously.
|
||||
|
||||
```js
|
||||
import {executePowerShellSync} from 'powershell-utils';
|
||||
|
||||
const stdout = executePowerShellSync('Get-Process');
|
||||
console.log(stdout);
|
||||
```
|
||||
|
||||
#### command
|
||||
|
||||
Type: `string`
|
||||
|
||||
The PowerShell command to execute.
|
||||
|
||||
#### options
|
||||
|
||||
Type: `object`
|
||||
|
||||
The below option and all options except `shell` in Node.js [`child_process.execFileSync()`](https://nodejs.org/api/child_process.html#child_processexecfilesyncfile-args-options) are supported. PowerShell is always executed directly to prevent shell injection.
|
||||
|
||||
##### powerShellPath
|
||||
|
||||
Type: `string`\
|
||||
Default: `powerShellPath()`
|
||||
|
||||
Path to PowerShell executable.
|
||||
|
||||
##### encoding
|
||||
|
||||
Type: `string`\
|
||||
Default: `'utf8'`
|
||||
|
||||
Character encoding for the output.
|
||||
Reference in New Issue
Block a user