azure-pipelines-task-lib 5.281.1 → 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.1",
+  "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

@@ -2466,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.