azure-pipelines-task-lib 5.281.0 → 5.281.2

package/externaloutput.d.ts

@@ -5,23 +5,36 @@ import stream = require('stream');
 import im = require('./internal');
 /** Commands allowed by default once VSO commands are enabled for a path. */
 export declare const defaultAllowedVsoCommands: readonly string[];
+/** Controls whether VSO commands are blocked, reported through telemetry, both, or neither. */
+export type VsoCommandMode = 'disabled' | 'telemetryOnly' | 'blockOnly' | 'blockAndTelemetry';
 /**
  * Where the external output originates. Used for documentation and telemetry only; it does
  * NOT select an automatic allowlist. A task must explicitly enable VSO commands when needed.
  */
 export type ExternalOutputSource = 'remote' | 'childProcess' | 'repository';
+export interface VsoCommandTelemetryEvent {
+    source: ExternalOutputSource;
+    commandName: string;
+    blocked: boolean;
+}
+export type VsoCommandTelemetrySink = (event: VsoCommandTelemetryEvent) => void;
 export interface ExternalOutputOptions {
     /** Origin of the output. Documentation/telemetry only. */
     source: ExternalOutputSource;
     /**
-     * When false or omitted, every "##vso[" marker is blocked. When true, markers whose
-     * command name is in the effective allowlist pass through unchanged.
+        * Controls VSO command blocking and telemetry.
+        * @defaultValue 'blockOnly'
+     */
+    vsoCommandMode?: VsoCommandMode;
+    /**
+        * When blocking is active, false or omitted blocks every "##vso[" marker. When true,
+        * markers whose command name is in the effective allowlist pass through unchanged.
      */
     enableVsoCommands?: boolean;
     /**
      * The allowlist of "area.event" command names to permit when enableVsoCommands is true.
      * Replaces (does not extend) the default list. An explicit empty array allows nothing.
-     * Has no effect when enableVsoCommands is false.
+    * Has no effect when enableVsoCommands is false or blocking is inactive.
      */
     allowedVsoCommands?: readonly string[];
     /** Destination for filtered output. Defaults to process.stdout. */
@@ -35,8 +48,11 @@ export interface ExternalOutputOptions {
 export declare class MarkerFilter {
     private readonly enabled;
     private readonly allowed;
+    private readonly block;
+    private readonly source?;
+    private readonly telemetry?;
     private pending;
-    constructor(enabled: boolean, allowed: Set<string>);
+    constructor(enabled: boolean, allowed: Set<string>, block?: boolean, source?: ExternalOutputSource | undefined, telemetry?: VsoCommandTelemetrySink | undefined);
     push(chunk: Buffer): Buffer;
     flush(): Buffer;
 }

package/externaloutput.js

@@ -63,6 +63,38 @@ var LF = 0x0A;
 var MAX_HEADER = 256;
 /** Commands allowed by default once VSO commands are enabled for a path. */
 exports.defaultAllowedVsoCommands = Object.freeze(['task.debug', 'task.setprogress']);
+function resolveVsoCommandMode(mode) {
+    switch (mode || 'blockOnly') {
+        case 'disabled':
+            return { block: false, telemetry: false };
+        case 'telemetryOnly':
+            return { block: false, telemetry: true };
+        case 'blockAndTelemetry':
+            return { block: true, telemetry: true };
+        case 'blockOnly':
+            return { block: true, telemetry: false };
+        default:
+            // JavaScript callers can bypass the TypeScript union. Preserve the secure default.
+            return { block: true, telemetry: false };
+    }
+}
+function publishVsoCommandTelemetry(event) {
+    try {
+        var telemetryEvent = __assign(__assign({}, event), { SYSTEM_TASKINSTANCEID: im._getVariable('SYSTEM_TASKINSTANCEID') || '', SYSTEM_TASKINSTANCENAME: im._getVariable('SYSTEM_TASKINSTANCENAME') || '', SYSTEM_JOBID: im._getVariable('SYSTEM_JOBID') || '', SYSTEM_PLANID: im._getVariable('SYSTEM_PLANID') || '' });
+        im._command('telemetry.publish', { area: 'TaskLib', feature: 'ExternalOutputVsoCommand' }, JSON.stringify(telemetryEvent));
+    }
+    catch (_err) {
+        console.error(_err);
+        // Telemetry is best effort and must not interrupt external-output handling.
+    }
+}
+function createMarkerFilter(options) {
+    var mode = resolveVsoCommandMode(options.vsoCommandMode);
+    var telemetry = mode.telemetry
+        ? function (event) { return publishVsoCommandTelemetry(event); }
+        : undefined;
+    return new MarkerFilter(!!options.enableVsoCommands, resolveAllowed(options), mode.block, options.source, telemetry);
+}
 function resolveAllowed(options) {
     if (!options.enableVsoCommands) {
         return new Set();
@@ -120,9 +152,13 @@ function scanHeader(buf, start) {
  * boundary, so memory stays bounded regardless of input size.
  */
 var MarkerFilter = /** @class */ (function () {
-    function MarkerFilter(enabled, allowed) {
+    function MarkerFilter(enabled, allowed, block, source, telemetry) {
+        if (block === void 0) { block = true; }
         this.enabled = enabled;
         this.allowed = allowed;
+        this.block = block;
+        this.source = source;
+        this.telemetry = telemetry;
         this.pending = EMPTY;
     }
     MarkerFilter.prototype.push = function (chunk) {
@@ -147,18 +183,23 @@ var MarkerFilter = /** @class */ (function () {
                 out.push(buf.subarray(pos, idx));
             }
             var afterMarker = idx + MARKER.length;
-            if (!this.enabled) {
+            if (this.block && !this.enabled && !this.telemetry) {
                 out.push(NEUTRALIZED);
                 pos = afterMarker;
                 continue;
             }
-            // Enabled: read the command name (up to the first space or ']') and allow the marker
-            // only when that name is allowlisted.
+            if (!this.block && !this.telemetry) {
+                out.push(MARKER);
+                pos = afterMarker;
+                continue;
+            }
+            // Read the command name (up to the first space or ']') for telemetry and, when
+            // blocking, to determine whether the marker is allowlisted.
             var _a = scanHeader(buf, afterMarker), term = _a.term, newline = _a.newline;
             if (term === -1) {
                 if (buf.length - afterMarker >= MAX_HEADER) {
                     // No terminator within the bound: fail closed.
-                    out.push(NEUTRALIZED);
+                    out.push(this.block ? NEUTRALIZED : MARKER);
                     pos = afterMarker;
                     continue;
                 }
@@ -169,14 +210,18 @@ var MarkerFilter = /** @class */ (function () {
             // A CR/LF before the terminator means the agent (which parses per line) would never
             // treat this as a command, so we fail closed and neutralize.
             if (newline) {
-                out.push(NEUTRALIZED);
+                out.push(this.block ? NEUTRALIZED : MARKER);
                 pos = afterMarker;
                 continue;
             }
             var name_1 = canonicalCommandName(buf.toString('utf8', afterMarker, term));
+            var blocked = this.block && !(this.enabled && name_1 && this.allowed.has(name_1));
+            if (this.telemetry && name_1 && this.source) {
+                this.telemetry({ source: this.source, commandName: name_1, blocked: blocked });
+            }
             // Allowlisted markers pass unchanged; the header/data after them flow through as
             // ordinary bytes and any later markers are evaluated independently.
-            out.push(name_1 && this.allowed.has(name_1) ? MARKER : NEUTRALIZED);
+            out.push(blocked ? NEUTRALIZED : MARKER);
             pos = afterMarker;
         }
         if (out.length === 0) {
@@ -196,7 +241,7 @@ var MarkerFilter = /** @class */ (function () {
             return EMPTY;
         }
         // An incomplete command candidate that begins with the full marker is neutralized.
-        if (this.enabled && p.length >= MARKER.length && p.subarray(0, MARKER.length).equals(MARKER)) {
+        if (this.block && p.length >= MARKER.length && p.subarray(0, MARKER.length).equals(MARKER)) {
             return Buffer.concat([NEUTRALIZED, p.subarray(MARKER.length)]);
         }
         // A partial marker (fewer than the full bytes) cannot be executed by the agent, so it
@@ -215,7 +260,7 @@ var ExternalOutputStream = /** @class */ (function (_super) {
     __extends(ExternalOutputStream, _super);
     function ExternalOutputStream(options) {
         var _this = _super.call(this) || this;
-        _this.markerFilter = new MarkerFilter(!!options.enableVsoCommands, resolveAllowed(options));
+        _this.markerFilter = createMarkerFilter(options);
         return _this;
     }
     ExternalOutputStream.prototype._transform = function (chunk, _encoding, callback) {
@@ -262,7 +307,7 @@ function createExternalOutputStream(options) {
 exports.createExternalOutputStream = createExternalOutputStream;
 /** Filters one complete value for internal task-lib consumers. */
 function filterExternalOutput(data, options) {
-    var filter = new MarkerFilter(!!options.enableVsoCommands, resolveAllowed(options));
+    var filter = createMarkerFilter(options);
     var buf = Buffer.isBuffer(data) ? data : Buffer.from(String(data), 'utf8');
     var filtered = filter.push(buf);
     var pending = filter.flush();
@@ -271,7 +316,7 @@ function filterExternalOutput(data, options) {
 exports.filterExternalOutput = filterExternalOutput;
 /** Creates a stateful writer for internal consumers that receive output in chunks. */
 function createFilteredWriter(options, destination) {
-    var filter = new MarkerFilter(!!options.enableVsoCommands, resolveAllowed(options));
+    var filter = createMarkerFilter(options);
     var ended = false;
     return {
         write: function (data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azure-pipelines-task-lib",
-  "version": "5.281.0",
+  "version": "5.281.2",
   "description": "Azure Pipelines Task SDK",
   "main": "./task.js",
   "typings": "./task.d.ts",

package/task.d.ts

@@ -848,7 +848,9 @@ export type ExternalOutputIssueOptions = eom.ExternalOutputIssueOptions;
  *
  * By default every marker is blocked. Set enableVsoCommands to true (optionally with an
  * explicit allowedVsoCommands list) to permit a small set of command names on a
- * compatibility-sensitive path.
+ * compatibility-sensitive path. Set vsoCommandMode to control blocking and Kusto telemetry
+ * independently. Telemetry includes only the output source, canonical command name, and
+ * whether the command was blocked; command properties and data are never included.
  *
  * @param options   External output options. See ExternalOutputOptions.
  * @returns         A writable/readable stream to pipe untrusted output into.

package/task.js

@@ -1533,6 +1533,50 @@ function _legacyFindFiles_getMatchingItems(includePatterns, excludePatterns, inc
     }
     return Object.keys(allFiles).sort();
 }
+function _quoteWindowsCmdPath(value) {
+    // Percent expansion remains active inside quotes, so quote each literal percent separately.
+    return "\"".concat(value.replace(/%/g, '"^%"'), "\"");
+}
+function _publishRmRFSpecialPathTelemetry(inputPath) {
+    try {
+        var hasPercent = inputPath.includes('%');
+        var hasCmdMetachar = /[&|<>^]/.test(inputPath);
+        var hasDelayedExpansion = inputPath.includes('!');
+        var hasParentheses = /[()]/.test(inputPath);
+        if (!hasPercent && !hasCmdMetachar && !hasDelayedExpansion && !hasParentheses) {
+            return;
+        }
+        var message = JSON.stringify({
+            event: 'SpecialPathDetected',
+            hasPercent: hasPercent,
+            hasCmdMetachar: hasCmdMetachar,
+            hasDelayedExpansion: hasDelayedExpansion,
+            hasParentheses: hasParentheses
+        });
+        console.log("##vso[telemetry.publish area=TaskHub;feature=TaskLibRmRF]".concat(message));
+    }
+    catch (err) {
+        (0, exports.debug)("Failed to publish rmRF telemetry: ".concat(err.message));
+    }
+}
+function _rmWindows(targetPath, isDirectory) {
+    var normalizedPath = im._normalizeSeparators(targetPath);
+    if (!getPipelineFeature('EnableRmRFCommandPathQuoting')) {
+        var legacyArgs = isDirectory
+            ? ['/c', 'rd', '/s', '/q', normalizedPath]
+            : ['/c', 'del', '/f', '/a', normalizedPath];
+        childProcess.execFileSync('cmd.exe', legacyArgs);
+        return;
+    }
+    var quotedPath = _quoteWindowsCmdPath(normalizedPath);
+    var args = isDirectory
+        ? ['/d', '/v:off', '/c', 'rd', '/s', '/q', quotedPath]
+        : ['/d', '/v:off', '/c', 'del', '/f', '/a', quotedPath];
+    var options = {
+        windowsVerbatimArguments: true
+    };
+    childProcess.execFileSync('cmd.exe', args, options);
+}
 /**
  * Remove a path recursively with force
  *
@@ -1543,13 +1587,12 @@ function _legacyFindFiles_getMatchingItems(includePatterns, excludePatterns, inc
 function rmRF(inputPath) {
     (0, exports.debug)('rm -rf ' + inputPath);
     if (getPlatform() == Platform.Windows) {
-        // Node doesn't provide a delete operation, only an unlink function. This means that if the file is being used by another
-        // program (e.g. antivirus), it won't be deleted. To address this, we shell out the work to rd/del.
+        _publishRmRFSpecialPathTelemetry(inputPath);
         try {
             var lstats = fs.lstatSync(inputPath);
             if (lstats.isDirectory() && !lstats.isSymbolicLink()) {
                 (0, exports.debug)('removing directory ' + inputPath);
-                childProcess.execFileSync("cmd.exe", ["/c", "rd", "/s", "/q", im._normalizeSeparators(inputPath)]);
+                _rmWindows(inputPath, true);
             }
             else if (lstats.isSymbolicLink()) {
                 (0, exports.debug)('removing symbolic link ' + inputPath);
@@ -1557,7 +1600,7 @@ function rmRF(inputPath) {
                 if (fs.existsSync(realPath)) {
                     var stats_4 = fs.statSync(realPath);
                     if (stats_4.isDirectory()) {
-                        childProcess.execFileSync("cmd.exe", ["/c", "rd", "/s", "/q", im._normalizeSeparators(realPath)]);
+                        _rmWindows(realPath, true);
                         fs.unlinkSync(inputPath);
                     }
                     else {
@@ -1571,7 +1614,7 @@ function rmRF(inputPath) {
             }
             else {
                 (0, exports.debug)('removing file ' + inputPath);
-                childProcess.execFileSync("cmd.exe", ["/c", "del", "/f", "/a", im._normalizeSeparators(inputPath)]);
+                _rmWindows(inputPath, false);
             }
         }
         catch (err) {
@@ -2423,7 +2466,9 @@ exports.ToolRunner = trm.ToolRunner;
  *
  * By default every marker is blocked. Set enableVsoCommands to true (optionally with an
  * explicit allowedVsoCommands list) to permit a small set of command names on a
- * compatibility-sensitive path.
+ * compatibility-sensitive path. Set vsoCommandMode to control blocking and Kusto telemetry
+ * independently. Telemetry includes only the output source, canonical command name, and
+ * whether the command was blocked; command properties and data are never included.
  *
  * @param options   External output options. See ExternalOutputOptions.
  * @returns         A writable/readable stream to pipe untrusted output into.