@cdot65/prisma-airs-cli 5.10.0 → 5.11.0

package/README.md

@@ -20,7 +20,7 @@
 - **SCM dashboard and sessions** — `runtime dashboard` and `runtime sessions` expose application activity, daily trends, checked pagination and explicit session-to-content drill-down. Legacy `scan-logs query` is **broken/under refactor** and exits with migration guidance; see the [session reference](https://cdot65.github.io/prisma-airs-cli/cli/runtime/sessions/)
 - **Guardrail Optimization** — atomic CLI commands (`create`, `apply`, `eval`, `revert`) for custom topic guardrails, designed for autonomous agent loops (see [`AGENTS.md`](AGENTS.md))
 - **AI Red Teaming** — adversarial scanning with static, dynamic, and custom prompt set attack modes
-- **[AI Gateway](https://cdot65.github.io/prisma-airs-cli/cli/aigateway/resources/)** — workspaces, configs, guardrails, providers, API keys, integrations, MCP, deployments, plugins, audit logs, and telemetry
+- **[AI Gateway](https://cdot65.github.io/prisma-airs-cli/cli/aigateway/resources/)** — workspaces (scope-first provisioning), IAM scopes, configs, guardrails, providers, API keys, integrations, MCP, deployments, plugins, audit logs, and telemetry
 - **Model Security** — ML model supply chain scanning with security groups, rules, and violation tracking
 - **Unified automation output** — resource reads support `pretty`, `table`, `markdown`, `csv`, `json`, and `yaml`, with pipe-safe stdout; environment deliverables use HTML or Markdown
 - **Complete pagination** — consistent `--limit`, `--offset`, and `--all` traversal with a configurable safety cap

package/dist/{chunk-XQOICLSH.js → chunk-37SN57XQ.js}

@@ -2268,6 +2268,8 @@ var ConfigSchema = z.object({
   aiGwDataEndpoint: z.string().optional(),
   aiGwAdminEndpoint: z.string().optional(),
   aiGwTokenEndpoint: z.string().optional(),
+  // SCM IAM (workspace scopes); creds shared with mgmt*
+  iamEndpoint: z.string().optional(),
   // Runtime inference has separate key authentication, never management OAuth.
   aiGwInferenceEndpoint: z.string().optional(),
   aiGwInferenceApiKey: z.string().optional(),
@@ -2488,6 +2490,7 @@ function fromEnv() {
     aiGwDataEndpoint: env.PANW_AI_GW_DATA_ENDPOINT,
     aiGwAdminEndpoint: env.PANW_AI_GW_ADMIN_ENDPOINT,
     aiGwTokenEndpoint: env.PANW_AI_GW_TOKEN_ENDPOINT,
+    iamEndpoint: env.PANW_IAM_ENDPOINT,
     aiGwInferenceEndpoint: env.PANW_AI_GW_INFERENCE_ENDPOINT,
     aiGwInferenceApiKey: env.PANW_AI_GW_INFERENCE_API_KEY,
     aiGwInferenceModel: env.PANW_AI_GW_INFERENCE_MODEL,

package/dist/cli/index.js

@@ -40,7 +40,7 @@ import {
   validateTopic,
   writeBackupFile,
   writeReportFile
-} from "../chunk-XQOICLSH.js";
+} from "../chunk-37SN57XQ.js";
 
 // src/cli/index.ts
 import "dotenv/config";
@@ -126,6 +126,7 @@ function aiGatewayClientOptions(config) {
     tsgId: config.mgmtTsgId,
     dataEndpoint: config.aiGwDataEndpoint,
     adminEndpoint: config.aiGwAdminEndpoint,
+    iamEndpoint: config.iamEndpoint,
     tokenEndpoint: config.aiGwTokenEndpoint ?? config.mgmtTokenEndpoint
   };
 }
@@ -707,6 +708,62 @@ function renderWorkspaceDetail(workspace, format = "pretty") {
   }
   console.log();
 }
+function scopeBindings(scope) {
+  return scope.resources.map((r) => `${r.resourceType}:${r.resourceId}`).join(", ");
+}
+function renderScopeList(scopes, format = "pretty") {
+  if (scopes.length === 0 && (format === "json" || format === "yaml")) {
+    console.log(format === "json" ? "[]" : yamlDump([]).trimEnd());
+    return;
+  }
+  if (scopes.length === 0) {
+    ui.emptyList("IAM scopes");
+    return;
+  }
+  if (format !== "pretty") {
+    const rows = scopes.map((s) => ({
+      name: s.name,
+      description: s.description,
+      resources: scopeBindings(s),
+      tsgId: s.tsgId
+    }));
+    console.log(
+      formatOutput(
+        rows,
+        [
+          { key: "name", label: "Name" },
+          { key: "description", label: "Description" },
+          { key: "resources", label: "Bound resources" },
+          { key: "tsgId", label: "TSG" }
+        ],
+        format
+      )
+    );
+    return;
+  }
+  ui.section("IAM Scopes:");
+  for (const s of scopes) {
+    const bindings = scopeBindings(s);
+    console.log(`    ${s.name}  ${bindings ? chalk4.dim(bindings) : chalk4.yellow("unbound")}`);
+    if (s.description) console.log(`    ${chalk4.dim(s.description)}`);
+    console.log();
+  }
+}
+function renderScopeDetail(scope, format = "pretty") {
+  if (format !== "pretty") {
+    console.log(format === "json" ? JSON.stringify(scope, null, 2) : yamlDump(scope));
+    return;
+  }
+  ui.section("IAM Scope:");
+  ui.keyValue([
+    ["Name", scope.name],
+    ["Description", scope.description || chalk4.dim("(none)")],
+    ["TSG", scope.tsgId],
+    ["ID", scope.id],
+    ["Bound resources", scopeBindings(scope) || chalk4.yellow("none \u2014 unbound")]
+  ]);
+  console.log();
+}
 function renderCostReport(report, format = "pretty") {
   if (format !== "pretty") {
     emitDetail(
@@ -3251,6 +3308,18 @@ function normalizeWorkspaceDetail(raw) {
     settings: raw.settings
   };
 }
+function normalizeScope(raw) {
+  return {
+    name: raw.name,
+    description: raw.description,
+    resources: raw.resources.map((r) => ({
+      resourceType: r.resource_type,
+      resourceId: r.resource_id
+    })),
+    tsgId: raw.tsg_id,
+    id: raw.id
+  };
+}
 function aiGatewayGrantHint(err) {
   const status = err?.status ?? err?.statusCode;
   if (status !== 403) return void 0;
@@ -3294,18 +3363,38 @@ var SdkAiGatewayService = class {
     }
   }
   async createWorkspace(request) {
-    const body = {
-      name: request.name,
-      scope_name: request.scopeName
-    };
+    const body = { name: request.name };
+    if (request.scopeName !== void 0) body.scope_name = request.scopeName;
     if (request.description !== void 0) body.description = request.description;
     if (request.icon !== void 0) body.icon = request.icon;
     if (request.defaults !== void 0) body.defaults = request.defaults;
     if (request.users !== void 0) body.users = request.users;
     if (request.usageLimits !== void 0) body.usage_limits = request.usageLimits;
     if (request.rateLimits !== void 0) body.rate_limits = request.rateLimits;
-    const created = await this.client.workspaces.create(body);
-    return this.refetchAfterWrite(created.id, created);
+    const result = await this.client.workspaces.provision(
+      body,
+      request.existingScope ? { existingScope: true } : {}
+    );
+    const created = result.workspace;
+    const workspace = await this.refetchAfterWrite(created.id, created);
+    return { workspace, scope: normalizeScope(result.scope), scopeCreated: result.scopeCreated };
+  }
+  async listScopes() {
+    const response = await this.client.iamScopes.list();
+    return response.items.map(normalizeScope);
+  }
+  async getScope(name) {
+    return normalizeScope(await this.client.iamScopes.get(name));
+  }
+  async createScope(request) {
+    return normalizeScope(await this.client.iamScopes.create(request));
+  }
+  async bindScope(name, workspaceRef) {
+    const slug = await this.resolveWorkspaceRef(workspaceRef, ["admin"], true);
+    return normalizeScope(await this.client.iamScopes.bindWorkspace(name, slug));
+  }
+  async deleteScope(name) {
+    await this.client.iamScopes.delete(name);
   }
   async updateWorkspace(workspaceRef, request) {
     const ref = await this.resolveWorkspaceRef(workspaceRef, ["admin"]);
@@ -5414,44 +5503,60 @@ function registerAiGatewayCommand(program) {
       failWithGrantHint(err);
     }
   });
-  workspace.command("create").description("Create a workspace (admin plane)").requiredOption("--name <name>", "Display name").requiredOption(
+  const workspaceCreate = workspace.command("create").description("Create a workspace: IAM scope \u2192 workspace \u2192 bind scope (admin plane)").requiredOption("--name <name>", "Display name").option(
     "--scope-name <scope>",
-    "SCM role scope granting data-plane access (e.g. ws_production_bx7qw0) \u2014 not derived from --name"
+    "IAM scope to create and bind (e.g. ws_production_bx7qw0). Default: ws_<name>_<suffix>"
+  ).option(
+    "--existing-scope",
+    "Bind an IAM scope that already exists instead of creating one (requires --scope-name)"
   ).option("--description <text>", "Workspace description").option("--icon <icon>", "Workspace icon").option("--metadata <json>", "Sugar for defaults.metadata (flat string map)").option("--defaults <json>", "Workspace defaults object").option("--users <ids>", "Comma-separated user ids to seed the workspace with").option("--usage-limits <json>", "Usage-limit policies \u2014 a JSON ARRAY of policy objects").option("--rate-limits <json>", "Rate-limit policies \u2014 a JSON ARRAY of policy objects").option("--output <format>", "Output format: pretty, json, yaml", "pretty").addHelpText(
     "after",
     examples(
+      'airs aigateway workspaces create --name truffles --description "Online recipe generation application"',
       "airs aigateway workspaces create --name Production --scope-name ws_production_bx7qw0",
-      `airs aigateway workspaces create --name Production --scope-name ws_production_bx7qw0 --metadata '{"env":"production"}' --rate-limits '[{"type":"requests","unit":"rpm","value":100}]'`
+      "airs aigateway workspaces create --name Staging --scope-name ws_staging_q1x8mz --existing-scope",
+      `airs aigateway workspaces create --name Production --metadata '{"env":"production"}' --rate-limits '[{"type":"requests","unit":"rpm","value":100}]'`
     )
   ).action(async (opts) => {
     try {
-      const fmt = opts.output;
+      const fmt = await resolveOutput(workspaceCreate, opts, {
+        allowed: ["pretty", "json", "yaml"]
+      });
       if (fmt === "pretty") renderAiGatewayHeader();
-      if (scopeNameLooksUnrelated(opts.name, opts.scopeName)) {
+      if (opts.existingScope && !opts.scopeName) {
+        throw new CliUsageError("--existing-scope requires --scope-name");
+      }
+      if (opts.scopeName && scopeNameLooksUnrelated(opts.name, opts.scopeName)) {
         ui.warn(
-          `--scope-name '${opts.scopeName}' shares no token with --name '${opts.name}'. A workspace created with a scope nobody holds will not appear in data-plane lists.`
+          `--scope-name '${opts.scopeName}' shares no token with --name '${opts.name}'. Operators find workspaces by scope in SCM Access Management; an unrelated name is easy to lose.`
         );
       }
       const service = await createService();
-      const workspace2 = await service.createWorkspace({
+      const { workspace: workspace2, scope, scopeCreated } = await service.createWorkspace({
         ...buildWorkspaceWriteRequest(opts),
         name: opts.name,
-        scopeName: opts.scopeName
+        ...opts.scopeName !== void 0 ? { scopeName: opts.scopeName } : {},
+        ...opts.existingScope ? { existingScope: true } : {}
       });
       ui.success(`Workspace created: ${workspace2.id}`);
+      ui.status(
+        `IAM scope ${scope.name} ${scopeCreated ? "created and " : ""}bound to workspace ${workspace2.slug}. Grant that scope to the service accounts that should reach the workspace on the data plane.`
+      );
       renderWorkspaceDetail(workspace2, fmt);
     } catch (err) {
       failWithGrantHint(err);
     }
   });
-  workspace.command("update <ref>").description("Update a workspace (admin plane, partial patch)").option("--name <name>", "New display name").option("--description <text>", "New description").option("--icon <icon>", "New icon").option("--metadata <json>", "Sugar for defaults.metadata (flat string map)").option("--defaults <json>", "Workspace defaults object").option("--usage-limits <json>", "Usage-limit policies \u2014 a JSON ARRAY of policy objects").option("--rate-limits <json>", "Rate-limit policies \u2014 a JSON ARRAY of policy objects").option("--output <format>", "Output format: pretty, json, yaml", "pretty").addHelpText(
+  const workspaceUpdate = workspace.command("update <ref>").description("Update a workspace (admin plane, partial patch)").option("--name <name>", "New display name").option("--description <text>", "New description").option("--icon <icon>", "New icon").option("--metadata <json>", "Sugar for defaults.metadata (flat string map)").option("--defaults <json>", "Workspace defaults object").option("--usage-limits <json>", "Usage-limit policies \u2014 a JSON ARRAY of policy objects").option("--rate-limits <json>", "Rate-limit policies \u2014 a JSON ARRAY of policy objects").option("--output <format>", "Output format: pretty, json, yaml", "pretty").addHelpText(
     "after",
     examples(
       `airs aigateway workspaces update ws-produc-985697 --description 'Production workloads, us-east'`
     )
   ).action(async (ref, opts) => {
     try {
-      const fmt = opts.output;
+      const fmt = await resolveOutput(workspaceUpdate, opts, {
+        allowed: ["pretty", "json", "yaml"]
+      });
       if (fmt === "pretty") renderAiGatewayHeader();
       const request = buildWorkspaceWriteRequest(opts);
       if (Object.keys(request).length === 0) {
@@ -5492,6 +5597,83 @@ function registerAiGatewayCommand(program) {
   };
   workspace.command("archive <ref>").description("Archive a workspace (soft delete \u2014 there is no hard delete)").option("--force", "Skip confirmation prompt").addHelpText("after", examples("airs aigateway workspaces archive ws-produc-985697 --force")).action((ref, opts) => archiveWorkspace(ref, opts, false));
   workspace.command("delete <ref>", { hidden: true }).description("Deprecated compatibility command for archive").option("--force", "Skip confirmation prompt").action((ref, opts) => archiveWorkspace(ref, opts, true));
+  const scopes = aigateway.command("scopes").description("Manage SCM IAM scopes \u2014 the objects a workspace scope_name points at (/iam/v1)").action(() => scopes.outputHelp());
+  const scopeList = scopes.command("list").description("List every IAM scope in the tenant (unbound scopes have no resources)").option("--output <format>", "Output format: pretty, table, markdown, csv, json, yaml").addHelpText(
+    "after",
+    examples("airs aigateway scopes list", "airs aigateway scopes list --output json")
+  ).action(async (opts) => {
+    try {
+      const fmt = await resolveOutput(scopeList, opts);
+      if (fmt === "pretty") renderAiGatewayHeader();
+      const service = await createService();
+      renderScopeList(await service.listScopes(), fmt);
+    } catch (err) {
+      failWithGrantHint(err);
+    }
+  });
+  const scopeGet = scopes.command("get <name>").description("Get one IAM scope by name").option("--output <format>", "Output format: pretty, table, markdown, csv, json, yaml").addHelpText("after", examples("airs aigateway scopes get ws_production_bx7qw0")).action(async (name, opts) => {
+    try {
+      const fmt = await resolveOutput(scopeGet, opts);
+      if (fmt === "pretty") renderAiGatewayHeader();
+      const service = await createService();
+      renderScopeDetail(await service.getScope(name), fmt);
+    } catch (err) {
+      failWithGrantHint(err);
+    }
+  });
+  const scopeCreate = scopes.command("create").description("Create an unbound IAM scope (step 1 of provisioning, on its own)").requiredOption("--name <name>", "Scope name, e.g. ws_production_bx7qw0").option("--description <text>", "Scope description").option("--output <format>", "Output format: pretty, json, yaml", "pretty").addHelpText(
+    "after",
+    examples(
+      `airs aigateway scopes create --name ws_production_bx7qw0 --description 'All production applications'`
+    )
+  ).action(async (opts) => {
+    try {
+      const fmt = await resolveOutput(scopeCreate, opts, { allowed: ["pretty", "json", "yaml"] });
+      if (fmt === "pretty") renderAiGatewayHeader();
+      const service = await createService();
+      const scope = await service.createScope({
+        name: opts.name,
+        ...opts.description !== void 0 ? { description: opts.description } : {}
+      });
+      ui.success(`IAM scope created: ${scope.name}`);
+      ui.status(
+        "The scope is not bound to anything yet \u2014 `workspaces create --existing-scope` or `scopes bind` finishes the job."
+      );
+      renderScopeDetail(scope, fmt);
+    } catch (err) {
+      failWithGrantHint(err);
+    }
+  });
+  const scopeBind = scopes.command("bind <name>").description("Bind a workspace to an existing IAM scope (step 3 of provisioning, on its own)").requiredOption("--workspace <ref>", "Workspace slug, UUID, or unique display name").option("--output <format>", "Output format: pretty, json, yaml", "pretty").addHelpText(
+    "after",
+    examples("airs aigateway scopes bind ws_production_bx7qw0 --workspace ws-produc-985697")
+  ).action(async (name, opts) => {
+    try {
+      const fmt = await resolveOutput(scopeBind, opts, { allowed: ["pretty", "json", "yaml"] });
+      if (fmt === "pretty") renderAiGatewayHeader();
+      const service = await createService();
+      const scope = await service.bindScope(name, opts.workspace);
+      ui.success(`IAM scope ${scope.name} now binds ${scope.resources.length} resource(s)`);
+      renderScopeDetail(scope, fmt);
+    } catch (err) {
+      failWithGrantHint(err);
+    }
+  });
+  scopes.command("delete <name>").alias("rm").description("Delete an IAM scope by name (not live-verified upstream; the API may decline)").option("--force", "Skip confirmation prompt").addHelpText("after", examples("airs aigateway scopes delete ws_truffles_ggolfu --force")).action(async (name, opts) => {
+    try {
+      renderAiGatewayHeader();
+      await confirmOrAbort(
+        `Delete IAM scope ${name}? Workspaces bound to it lose their data-plane grant.`,
+        Boolean(opts.force),
+        { action: `delete IAM scope ${name}` }
+      );
+      const service = await createService();
+      await service.deleteScope(name);
+      ui.success(`IAM scope deleted: ${name}`);
+    } catch (err) {
+      failWithGrantHint(err);
+    }
+  });
   const telemetry = aigateway.command("telemetry").description("AI Gateway runtime telemetry (data plane)").action(() => telemetry.outputHelp());
   registerAiGatewayTelemetryReads(telemetry);
   const cost = addChartFilterOptions(

package/dist/index.d.ts

@@ -1666,6 +1666,7 @@ declare const ConfigSchema: z.ZodObject<{
     aiGwDataEndpoint: z.ZodOptional<z.ZodString>;
     aiGwAdminEndpoint: z.ZodOptional<z.ZodString>;
     aiGwTokenEndpoint: z.ZodOptional<z.ZodString>;
+    iamEndpoint: z.ZodOptional<z.ZodString>;
     aiGwInferenceEndpoint: z.ZodOptional<z.ZodString>;
     aiGwInferenceApiKey: z.ZodOptional<z.ZodString>;
     aiGwInferenceModel: z.ZodOptional<z.ZodString>;
@@ -1700,6 +1701,7 @@ declare const ConfigSchema: z.ZodObject<{
     aiGwDataEndpoint?: string | undefined;
     aiGwAdminEndpoint?: string | undefined;
     aiGwTokenEndpoint?: string | undefined;
+    iamEndpoint?: string | undefined;
     aiGwInferenceEndpoint?: string | undefined;
     aiGwInferenceApiKey?: string | undefined;
     aiGwInferenceModel?: string | undefined;
@@ -1730,6 +1732,7 @@ declare const ConfigSchema: z.ZodObject<{
     aiGwDataEndpoint?: string | undefined;
     aiGwAdminEndpoint?: string | undefined;
     aiGwTokenEndpoint?: string | undefined;
+    iamEndpoint?: string | undefined;
     aiGwInferenceEndpoint?: string | undefined;
     aiGwInferenceApiKey?: string | undefined;
     aiGwInferenceModel?: string | undefined;

package/dist/index.js

@@ -28,7 +28,7 @@ import {
   validateTopic,
   writeBackupFile,
   writeReportFile
-} from "./chunk-XQOICLSH.js";
+} from "./chunk-37SN57XQ.js";
 export {
   AirsScanService,
   SDK_ASYNC_BATCH_SIZE,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cdot65/prisma-airs-cli",
   "packageManager": "pnpm@10.6.5",
-  "version": "5.10.0",
+  "version": "5.11.0",
   "description": "CLI and library for Palo Alto Prisma AIRS — guardrail refinement, AI red teaming, model security scanning, profile audits",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@cdot65/prisma-airs-sdk": "0.30.1",
+    "@cdot65/prisma-airs-sdk": "0.31.0",
     "@inquirer/prompts": "^8.3.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",