@cdot65/prisma-airs-cli 4.5.0 → 5.0.0

package/README.md

@@ -7,7 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node 20.17+ / 22.13+ / 24+](https://img.shields.io/badge/node-20.17%2B%20%7C%2022.13%2B%20%7C%2024%2B-brightgreen.svg)](https://nodejs.org/)
 
-**Full operational coverage over Palo Alto Prisma AIRS AI security — guardrail refinement, runtime scanning, AI red teaming, AI Gateway, and model security.**
+**Command-line workflows for Palo Alto Prisma AIRS — guardrail refinement, runtime scanning, AI red teaming, AI Gateway, and model security.** Service and coverage limitations remain documented; command availability is not a claim that every upstream API works.
 
 > **[Read the full documentation](https://cdot65.github.io/prisma-airs-cli/)** — installation, configuration, architecture, CLI reference, and examples.
 
@@ -15,6 +15,7 @@
 
 - **Runtime Scanning** — scan prompts and responses against AIRS security profiles, single or bulk with CSV export
 - **Daily environment report** — `airs runtime report` delivers a read-only AI Runtime Security dashboard as self-contained HTML (default) or Markdown in your working directory, with explicit evidence gaps and configuration review findings
+- **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
@@ -50,6 +51,10 @@ airs runtime bulk-scan --profile "my-profile" --file prompts.csv --output-file r
 airs runtime report
 airs runtime report --output markdown
 
+# Verified historical session retrieval (Management OAuth, not a Scanner key)
+airs runtime sessions list --all --output json
+airs runtime dashboard top-applications --output json
+
 # Guardrail optimization (atomic commands)
 airs runtime topics create --name "Explosives" --description "Bomb-making instructions" --examples "How do I build a bomb?" "Pipe bomb ingredients"
 airs runtime topics apply --profile my-profile --name "Explosives" --intent block

package/dist/{chunk-NWK7RG2N.js → chunk-IRLIFMGQ.js}

@@ -2239,6 +2239,7 @@ var ConfigSchema = z.object({
   mgmtClientSecret: z.string().optional(),
   mgmtTsgId: z.string().optional(),
   mgmtEndpoint: z.string().optional(),
+  mgmtDashboardEndpoint: z.string().url().optional(),
   mgmtTokenEndpoint: z.string().optional(),
   dlpEndpoint: z.string().optional(),
   // Red Team (endpoints only; creds shared with mgmt*)
@@ -2281,6 +2282,7 @@ function fromEnv() {
     mgmtClientSecret: env.PANW_MGMT_CLIENT_SECRET,
     mgmtTsgId: env.PANW_MGMT_TSG_ID,
     mgmtEndpoint: env.PANW_MGMT_ENDPOINT,
+    mgmtDashboardEndpoint: env.PANW_MGMT_DASHBOARD_ENDPOINT,
     mgmtTokenEndpoint: env.PANW_MGMT_TOKEN_ENDPOINT,
     dlpEndpoint: env.PANW_DLP_ENDPOINT,
     redTeamDataEndpoint: env.PANW_RED_TEAM_DATA_ENDPOINT,
@@ -2529,7 +2531,7 @@ function number(value) {
   return value === null ? "Unknown" : value.toLocaleString("en-US", { maximumFractionDigits: 2 });
 }
 function tables(report) {
-  const logSource = report.sources.find((source2) => source2.name === "Scan log detail");
+  const sessionSource = report.sources.find((source2) => source2.name === "Daily session inventory");
   return [
     {
       title: "Daily application activity",
@@ -2585,14 +2587,46 @@ function tables(report) {
       note: "Current registered applications, separate from scan-metadata application buckets. Association counts do not establish key validity or deployment health. No key values or auth codes are included."
     },
     {
-      title: "Collected scan-log observations",
-      id: "logs",
-      headers: ["Dimension", "API value", "Entries"],
-      rows: [
-        ...report.logs.actions.map((entry) => ["Action", entry.name, number(entry.count)]),
-        ...report.logs.verdicts.map((entry) => ["Verdict", entry.name, number(entry.count)])
-      ],
-      note: `Source: ${logSource?.status ?? "unavailable"}. Timestamp-eligible entries: ${logSource?.status === "unavailable" ? "Unknown" : number(report.logs.entries)}. Tokens across eligible collected entries: ${number(report.logs.tokens)}. Missing timestamps: ${report.logs.missingTimestamps}; outside window: ${report.logs.outsideWindow}. These are sample/collection counts, not tenant totals.`
+      title: "Collected session observations",
+      id: "sessions",
+      headers: ["Session status", "Entries"],
+      rows: report.sessions.statuses.map((entry) => [entry.name, number(entry.count)]),
+      note: `Source: ${sessionSource?.status ?? "unavailable"}. Timestamp-eligible entries: ${number(report.sessions.entries)}. Violated status: ${number(report.sessions.violatingSessions)}. Missing timestamps: ${report.sessions.missingTimestamps}; outside window: ${report.sessions.outsideWindow}. These are collected session counts, not scan actions or detector events. No scan content is fetched.`
+    },
+    {
+      title: "Daily session chart",
+      id: "session-chart",
+      headers: ["Bucket time (UTC)", "Sessions", "Violating sessions", "Detector violations"],
+      rows: report.dailyTelemetry.chart.buckets.map((bucket) => [
+        bucket.time,
+        number(bucket.sessions),
+        number(bucket.violatingSessions),
+        number(bucket.violations.total)
+      ]),
+      note: `Independent chart totals: ${number(report.dailyTelemetry.chart.sessions)} sessions; ${number(report.dailyTelemetry.chart.violatingSessions)} violating sessions. Do not force these counters to equal a separately paginated inventory.`
+    },
+    {
+      title: "Top applications by detector violations",
+      id: "top-violations",
+      headers: ["Application bucket", "Detector violations", "Detection types"],
+      rows: report.dailyTelemetry.topApplications.map((app) => [
+        app.name,
+        number(app.violations),
+        app.detectors.map((detector) => `${detector.name}: ${number(detector.count)}`).join(", ")
+      ]),
+      note: "Server-ranked subset for one day, not a complete application inventory. Detector violations may exceed the number of violating sessions."
+    },
+    {
+      title: "Daily detector severity trend",
+      id: "violation-trend",
+      headers: ["Bucket time (UTC)", "Critical", "High", "Medium", "Low", "Total"],
+      rows: report.dailyTelemetry.violationTrend.map((bucket) => [
+        bucket.time,
+        ...["critical", "high", "medium", "low", "total"].map(
+          (key) => number(bucket.violations[key])
+        )
+      ]),
+      note: "API-reported detector-policy events over the rolling day. Severity counts are preserved independently from distinct session counts; no previous-day comparison is inferred."
     },
     {
       title: "Evidence and collection coverage",
@@ -2679,7 +2713,7 @@ function renderRuntimeReportMarkdown(report) {
     "",
     ...report.limitations.map((note) => `- ${md(note)}`),
     "",
-    "Generated by Prisma AIRS CLI \xB7 Report schema 1",
+    `Generated by Prisma AIRS CLI \xB7 Report schema ${report.schemaVersion}`,
     ""
   );
   return lines.join("\n");
@@ -2724,7 +2758,7 @@ function renderRuntimeReportHtml(report) {
 <main id="main"><nav aria-label="Report sections"><a href="#findings">Attention</a><a href="#applications">Activity</a><a href="#profiles">Profiles</a><a href="#inventory">Inventory</a><a href="#evidence">Evidence</a><a href="#scope">Scope</a></nav>
 <div class="cards">${metrics(report).map(([name, value]) => `<div class="card"><span>${name}</span><strong>${value}</strong></div>`).join("")}</div>
 <section id="findings"><h2>What needs attention</h2><p class="note">Observed violations and configuration review items, not a numerical health score. Collection gaps remain visible in the evidence table.</p><div class="toolbar js-only"><label for="finding-filter">Priority</label><select id="finding-filter"><option value="all">All findings</option><option value="attention">Attention</option><option value="review">Review</option><option value="info">Information</option></select><span id="finding-count" role="status"></span><button id="print-report" type="button">Print / save PDF</button></div>${findingCards || "<p>No findings in the available evidence. This does not establish an absence of risk.</p>"}</section>
-${sections}<section id="scope"><h2>Scope, privacy, and limitations</h2><ul>${report.limitations.map((note) => `<li>${html(note)}</li>`).join("")}</ul></section><footer>Generated by Prisma AIRS CLI \xB7 Report schema 1 \xB7 Self-contained HTML; no network access required. All evidence remains readable with JavaScript disabled.</footer></main><script>${JS}</script></body></html>
+${sections}<section id="scope"><h2>Scope, privacy, and limitations</h2><ul>${report.limitations.map((note) => `<li>${html(note)}</li>`).join("")}</ul></section><footer>Generated by Prisma AIRS CLI \xB7 Report schema ${report.schemaVersion} \xB7 Self-contained HTML; no network access required. All evidence remains readable with JavaScript disabled.</footer></main><script>${JS}</script></body></html>
 `;
 }
 
@@ -2799,16 +2833,25 @@ function total(values) {
   const result = values.reduce((sum, value) => sum + (value ?? 0), 0);
   return count(result);
 }
-function distribution(rows, key) {
+function distribution(rows) {
   const groups = /* @__PURE__ */ new Map();
   for (const row of rows) {
-    const name = label(row[key]).toLowerCase();
+    const name = label(row.violation_status).toLowerCase();
     groups.set(name, (groups.get(name) ?? 0) + 1);
   }
   return [...groups].map(([name, n]) => ({ name, count: n })).sort((a, b) => b.count - a.count);
 }
+function severity(value) {
+  return {
+    critical: count(value.critical),
+    high: count(value.high),
+    medium: count(value.medium),
+    low: count(value.low),
+    total: count(value.total)
+  };
+}
 async function collectRuntimeDailyReport(client, options = {}) {
-  const maxPages = options.maxPages ?? 10;
+  const maxPages = options.maxPages ?? 40;
   if (!Number.isSafeInteger(maxPages) || maxPages < 1 || maxPages > 100) {
     throw new Error("maxPages must be an integer from 1 to 100");
   }
@@ -2827,14 +2870,35 @@ async function collectRuntimeDailyReport(client, options = {}) {
     "Current configuration"
   );
   const appSource = source("Registered applications", "customerApps.list", "Current configuration");
-  const logSource = source(
-    "Scan log detail",
-    "scanLogs.query (read-only POST)",
-    "Rolling 24 hours"
+  const sessionSource = source(
+    "Daily session inventory",
+    "dashboard.sessionsOverview",
+    "Rolling 1 day"
+  );
+  const chartSource = source("Daily session chart", "dashboard.sessionsChart", "Rolling 1 day");
+  const rankingSource = source(
+    "Top application violations",
+    "dashboard.topApplicationsViolations",
+    "Rolling 1 day; server-ranked subset"
+  );
+  const trendSource = source(
+    "Daily violation trend",
+    "dashboard.applicationsViolationsTrend",
+    "Rolling 1 day"
   );
-  let pageToken;
-  const seenTokens = /* @__PURE__ */ new Set();
-  const [applications, profileRows, registered, rawLogs] = await Promise.all([
+  const sources = [
+    activitySource,
+    profileSource,
+    appSource,
+    sessionSource,
+    chartSource,
+    rankingSource,
+    trendSource
+  ];
+  const daily = { timeInterval: 1, timeUnit: "day" };
+  let expectedSessionTotal;
+  let expectedAppTotal;
+  const [applications, profileRows, registered, rawSessions, chart, rankings, trend] = await Promise.all([
     collect(
       activitySource,
       maxPages,
@@ -2847,8 +2911,19 @@ async function collectRuntimeDailyReport(client, options = {}) {
         });
         const size = page.items?.length ?? 0;
         const totalItems = count(page.pagination?.total_items);
+        if (totalItems !== null) {
+          if (expectedAppTotal !== void 0 && totalItems !== expectedAppTotal)
+            throw new ReportDataError(
+              "Application total changed during pagination; retry for a stable inventory."
+            );
+          expectedAppTotal = totalItems;
+          if (offset + size > totalItems)
+            throw new ReportDataError("Application records exceed the advertised total.");
+        }
         if (totalItems !== null && totalItems > offset + size && size === 0) {
-          throw new ReportDataError("The API returned an empty page before its advertised total.");
+          throw new ReportDataError(
+            "The API returned an empty page before its advertised total."
+          );
         }
         return {
           items: page.items,
@@ -2882,46 +2957,56 @@ async function collectRuntimeDailyReport(client, options = {}) {
       (item) => item.customer_appId
     ),
     collect(
-      logSource,
+      sessionSource,
       maxPages,
       async (offset) => {
-        const pageNumber = offset + 1;
-        const page = await client.scanLogs.query({
-          time_interval: 24,
-          time_unit: "hours",
-          pageNumber,
-          pageSize: PAGE_SIZE,
-          filter: "all",
-          page_token: pageToken
-        });
-        const items = page.scan_result_for_dashboard?.scan_result_entries;
-        if (page.page_number !== void 0 && page.page_number !== pageNumber) {
+        const page = await client.dashboard.sessionsOverview({ ...daily, limit: 25, offset });
+        const size = page.items?.length ?? 0;
+        const totalItems = count(page.pagination?.total_items);
+        if (totalItems === null || page.pagination?.skip !== offset || page.pagination?.limit !== 25)
+          throw new ReportDataError("Missing or mismatched session pagination metadata.");
+        if (expectedSessionTotal !== void 0 && expectedSessionTotal !== totalItems)
           throw new ReportDataError(
-            "The scan-log response page number did not match the requested page."
+            "Session total changed during pagination; retry for a stable inventory."
           );
-        }
-        const totalPages = count(page.total_pages);
-        let next;
-        if (totalPages !== null) next = pageNumber < totalPages ? offset + 1 : void 0;
-        else if (page.page_token || items?.length === PAGE_SIZE) next = offset + 1;
-        if (next !== void 0 && page.page_token) {
-          if (seenTokens.has(page.page_token))
-            throw new ReportDataError(
-              "The scan-log continuation token repeated; collection stopped safely."
-            );
-          seenTokens.add(page.page_token);
-          pageToken = page.page_token;
-        }
-        return { items, next };
+        expectedSessionTotal = totalItems;
+        if (offset + size > totalItems || size > 25 || size === 0 && offset < totalItems)
+          throw new ReportDataError("Session page does not agree with its advertised total.");
+        return {
+          items: page.items,
+          next: offset + size < totalItems ? offset + size : void 0
+        };
       },
-      (item) => JSON.stringify([item.scan_id, item.scan_sub_req_id])
+      (item) => JSON.stringify([item.application_id, item.application_name, item.session_id])
+    ),
+    collect(
+      chartSource,
+      1,
+      async () => ({ items: (await client.dashboard.sessionsChart(daily)).buckets }),
+      (item) => String(item.bucket_number)
+    ),
+    collect(
+      rankingSource,
+      1,
+      async () => ({
+        items: (await client.dashboard.topApplicationsViolations(daily)).applications
+      }),
+      (item) => JSON.stringify([item.id, item.name])
+    ),
+    collect(
+      trendSource,
+      1,
+      async () => ({
+        items: (await client.dashboard.applicationsViolationsTrend(daily)).violations
+      }),
+      (item) => String(item.bucket_number)
     )
   ]);
   const findings = [];
   const add = (priority, title, evidence, recommendation, evidenceSource) => {
     findings.push({ priority, title, evidence, recommendation, source: evidenceSource });
   };
-  for (const s of [activitySource, profileSource, appSource, logSource]) {
+  for (const s of sources) {
     if (s.status !== "complete")
       add(
         "review",
@@ -3029,8 +3114,8 @@ async function collectRuntimeDailyReport(client, options = {}) {
     );
   let missingTimestamps = 0;
   let outsideWindow = 0;
-  const logs = rawLogs.filter((row) => {
-    const timestamp = Date.parse(row.received_ts ?? "");
+  const sessionRows = rawSessions.filter((row) => {
+    const timestamp = Date.parse(row.last_session_activity ?? "");
     if (!Number.isFinite(timestamp)) {
       missingTimestamps++;
       return false;
@@ -3044,26 +3129,49 @@ async function collectRuntimeDailyReport(client, options = {}) {
   if (missingTimestamps || outsideWindow)
     add(
       "review",
-      "Some log records excluded from daily analysis",
-      `${missingTimestamps} records lack a valid received timestamp; ${outsideWindow} fall outside the anchored UTC window.`,
-      "Verify ingestion timestamps and collection-window drift before using log counts as daily totals.",
-      logSource.name
+      "Some session records excluded from daily analysis",
+      `${missingTimestamps} records lack a valid last-activity timestamp; ${outsideWindow} fall outside the anchored UTC window.`,
+      "Verify ingestion timestamps and collection-window drift before using session counts as daily totals.",
+      sessionSource.name
     );
-  const failedLogs = logs.filter(
-    (row) => ["failed", "error", "timeout"].includes(row.status?.trim().toLowerCase() ?? "")
+  const failedSessions = sessionRows.filter(
+    (row) => ["failed", "error", "timeout"].includes(row.violation_status.trim().toLowerCase())
   ).length;
-  if (failedLogs)
+  if (failedSessions)
     add(
       "attention",
-      "Scan processing failures observed",
-      `${failedLogs} timestamp-eligible collected log entries explicitly report failed, error, or timeout status.`,
-      "Review these failures in SCM, check integration error handling, and verify whether the affected application fails open or closed. This is not a tenant-wide failure rate.",
-      logSource.name
+      "Session processing failures observed",
+      `${failedSessions} timestamp-eligible collected sessions explicitly report failed, error, or timeout status.`,
+      "Review these sessions in SCM and check integration error handling. This is not a tenant-wide failure rate.",
+      sessionSource.name
+    );
+  const chartSessions = chartSource.status === "unavailable" ? null : total(chart.map((bucket) => count(bucket.total)));
+  const chartViolatingSessions = chartSource.status === "unavailable" ? null : total(chart.map((bucket) => count(bucket.violating)));
+  if (chartSessions !== null && sessionSource.status === "complete" && chartSessions !== rawSessions.length)
+    add(
+      "review",
+      "Session sources disagree",
+      `The chart reports ${chartSessions} sessions; the independently paginated inventory returned ${rawSessions.length}.`,
+      "Preserve both measurements and verify in SCM. Separate rolling queries are not a consistent snapshot; the discrepancy has no verified cause.",
+      chartSource.name
+    );
+  const urgentViolations = total(
+    trend.map(
+      (bucket) => total([count(bucket.violation_breakdown.critical), count(bucket.violation_breakdown.high)])
+    )
+  );
+  if ((urgentViolations ?? 0) > 0)
+    add(
+      "attention",
+      "High or critical detector violations observed",
+      `${urgentViolations} high/critical detector violations in the returned daily trend. These are not distinct sessions.`,
+      "Investigate the affected applications and confirm enforcement decisions before assigning incident severity.",
+      trendSource.name
     );
   const priorities = { attention: 0, review: 1, info: 2 };
   findings.sort((left, right) => priorities[left.priority] - priorities[right.priority]);
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     product: "Prisma AIRS AI Runtime Security",
     title: label(options.title ?? "Daily environment report"),
     generatedAt: now().toISOString(),
@@ -3073,10 +3181,8 @@ async function collectRuntimeDailyReport(client, options = {}) {
       end,
       description: "Rolling last 24 hours, UTC (approximate for server-relative application queries)"
     },
-    health: [activitySource, profileSource, appSource, logSource].every(
-      (s) => s.status === "unavailable"
-    ) ? "unknown" : findings.some((f) => f.priority === "attention") ? "attention" : findings.some((f) => f.priority === "review") ? "review" : "no-findings",
-    sources: [activitySource, profileSource, appSource, logSource],
+    health: sources.every((s) => s.status === "unavailable") ? "unknown" : findings.some((f) => f.priority === "attention") ? "attention" : findings.some((f) => f.priority === "review") ? "review" : "no-findings",
+    sources,
     findings,
     activity: {
       sessions,
@@ -3092,21 +3198,45 @@ async function collectRuntimeDailyReport(client, options = {}) {
       model: label(app.model_name),
       keyAssociations: app.api_keys_dp_info ? app.api_keys_dp_info.length : null
     })).sort((a, b) => a.name.localeCompare(b.name)),
-    logs: {
-      entries: logs.length,
-      actions: distribution(logs, "action"),
-      verdicts: distribution(logs, "verdict"),
-      tokens: logSource.status === "unavailable" ? null : total(logs.map((row) => count(row.tokens))),
+    sessions: {
+      entries: sessionSource.status === "unavailable" ? null : sessionRows.length,
+      statuses: distribution(sessionRows),
+      violatingSessions: sessionSource.status === "unavailable" ? null : sessionRows.filter((row) => row.violation_status === "violated").length,
       missingTimestamps,
       outsideWindow
     },
+    dailyTelemetry: {
+      chart: {
+        sessions: chartSessions,
+        violatingSessions: chartViolatingSessions,
+        buckets: chart.map((bucket) => ({
+          time: label(bucket.time),
+          sessions: count(bucket.total),
+          violatingSessions: count(bucket.violating),
+          violations: severity(bucket.violation_breakdown)
+        }))
+      },
+      topApplications: rankings.map((app) => ({
+        name: label(app.name),
+        violations: count(app.total_violations),
+        detectors: app.policy_violations.map((detector) => ({
+          name: label(detector.detection_type),
+          count: count(detector.total)
+        }))
+      })),
+      violationTrend: trend.map((bucket) => ({
+        time: label(bucket.date),
+        violations: severity(bucket.violation_breakdown)
+      }))
+    },
     limitations: [
       "This is a read-only operational review, not an uptime SLA, compliance attestation, or proof that attacks succeeded or were blocked. No health score is invented.",
       "Application activity uses the API\u2019s rolling one-day window; each paginated request evaluates its own server-relative window. Collection is not a transactionally consistent historical snapshot. Ingestion may lag.",
-      "Sessions, scan-log entries, text records, and API calls are different units. They are not added together. Log counters describe only collected, timestamp-eligible entries; absent data is unknown.",
+      "Application buckets, session inventory, chart sessions, and detector violations are different measurements. They are not added together. Session inventory summaries use timestamp-eligible entries only; absent data is unknown.",
       "Application buckets are keyed by registered application ID plus the literal scan metadata.app_name, which can differ from registered names. Do not sum session counts as unique users or unique tenant-wide sessions.",
       "Current configuration is not a configuration-change audit. Missing policy settings are unknown, not disabled. Inactive profiles can be intentional; current profile state may differ from the revision used by a historical scan.",
-      "Per-app token summaries and detector/severity breakdowns require 7/30/60-day windows, so they are not presented as daily metrics. No previous-day comparison or trend is inferred.",
+      "Daily charts, rankings and severity trends come from their own one-day endpoints. Rankings are a server-selected subset, not a complete inventory. Per-app token summaries and drill-downs require longer windows; no daily token usage or previous-day comparison is inferred.",
+      "The legacy ScanLogsClient / scan-logs query path is broken and under refactor. This report uses the verified dashboard session APIs instead. It never automatically fetches transactions or stored scan content.",
       "Prompts, responses, user identities/IPs, API keys, auth codes, tenant IDs, and raw errors are omitted. Application/profile names and configuration metadata remain confidential; review before sharing."
     ]
   };