Refactor policy configuration (#4026)

Author: michaeljguarino

assets/public/setup-guides/cloud-connections/vsphere.md

@@ -1,18 +1,103 @@
-# vSphere cloud connection
+# Set up the vSphere cloud connection
 
-Create or choose a vCenter user that can read the inventory you want Workbench to query. A read-only role at the vCenter, datacenter, cluster, or folder scope is usually enough for inventory tables.
+Connect Cloud Query to a vCenter inventory. This integration is read-only: it lists VMs, hosts, datastores, and networks. It does not power VMs on or off, change config, or install agents.
 
-Use these values in the connection form:
+The form needs a **vCenter SDK endpoint**, a **vCenter SSO user**, and that user's **password**.
 
-- **vCenter SDK endpoint:** `https://<vcenter-host>/sdk`
-- **User:** a vCenter SSO user such as `administrator@vsphere.local`, or another account with read permissions
-- **Password:** the password for that user
-- **Allow unverified TLS certificates:** enable this only when vCenter uses an internal or self-signed certificate
+## Find the SDK endpoint
+
+The SOAP management API shares the vCenter hostname and HTTPS port with the vSphere Client. The difference is the **path**, not the port.
+
+| What | URL |
+|---|---|
+| vSphere Client (browser UI) | `https://<vcenter-host>/ui` |
+| SOAP SDK (this form) | `https://<vcenter-host>/sdk` |
+| Automation REST API | `https://<vcenter-host>/api` |
+
+1. Log in to the vSphere Client.
+2. Copy the hostname from the browser address bar. Ignore `/ui`, `/vsphere-client`, and any later path.
+3. Enter `https://<vcenter-host>/sdk`.
+
+Example: if the client is `https://vcenter.example.com/ui`, the SDK endpoint is `https://vcenter.example.com/sdk`. Default HTTPS port is **443**. Use `https://<vcenter-host>:<port>/sdk` only when vCenter listens on a non-default port.
 
-You can verify that the SDK endpoint is exposed with:
+Do not use:
+
+- `/ui` or `/vsphere-client` (HTML, not SOAP)
+- `/api` or `/rest` (vSphere Automation REST, not the VIM SDK this connection uses)
+- An ESXi host URL, unless you only have a standalone host. Full inventory (datacenters, clusters, all VMs) requires **vCenter**.
+
+A hostname without a scheme or path (`vcenter.example.com`) also works; the client defaults to `https` and `/sdk`. Prefer the full `https://…/sdk` URL so it is obvious which API you are targeting.
+
+Verify the SDK is reachable:
 
 ```bash
 curl -k https://<vcenter-host>/sdk/vimServiceVersions.xml
 ```
 
-The response should be XML listing the supported `urn:vim25` versions.
+The response should be XML listing `urn:vim25` versions, not an HTML login page.
+
+Enable **Allow unverified TLS certificates** only when vCenter uses an internal or self-signed certificate.
+
+## Create credentials
+
+Create a dedicated vCenter identity. Do not use the ESXi `root` user, and do not paste a vSphere Client session cookie.
+
+### Local SSO user (typical)
+
+1. In the vSphere Client, open **Menu → Administration → Single Sign On → Users and Groups**.
+2. Select the SSO domain (default `vsphere.local`).
+3. **Add User**. Choose a name such as `plural-cloud-query` and set a password.
+
+The form **User** value must include the domain: `plural-cloud-query@vsphere.local`. A bare username without `@vsphere.local` will fail SSO login.
+
+### Active Directory or other identity source
+
+If vCenter is joined to an identity source, create or pick a service account there, then use `user@domain.example` or `DOMAIN\user` as vCenter expects for that source. Still assign vCenter permissions below; directory membership alone does not grant inventory access.
+
+## Grant permissions for the APIs Cloud Query calls
+
+Cloud Query uses the Steampipe vSphere plugin. It authenticates with username/password, then:
+
+1. SOAP `POST https://<vcenter-host>/sdk` (VIM / vim25)
+   - `SessionManager.Login`
+   - `ViewManager.CreateContainerView` on the vCenter root folder
+   - `ContainerView.Retrieve` for `VirtualMachine`, `HostSystem`, `Datastore`, and `Network`
+2. Automation REST (VM tags only, table `vsphere_vm`)
+   - Session login on the vAPI endpoint
+   - `cis/tagging` `GetAttachedTags` and `GetCategory`
+
+It does not call guest operations, power APIs, or write APIs.
+
+### Inventory (required)
+
+Use the built-in **Read-only** role. That role is exactly the system privileges needed to log in and read object properties:
+
+- `System.Anonymous`
+- `System.View`
+- `System.Read`
+
+Assign it so the user can see the objects you want queried:
+
+1. **Menu → Administration → Access Control → Global Permissions → Add**, or right-click the vCenter object (or a datacenter, cluster, or folder) → **Add Permission**.
+2. Select the SSO user.
+3. Role: **Read-only**.
+4. Enable **Propagate to children**.
+
+Without propagate, ContainerView returns nothing below the object you assigned. Scope the permission to a folder or cluster if the connection should not see the whole inventory.
+
+Do not grant Administrator, Virtual machine **Power user**, or other write roles.
+
+### Tags (needed for `vsphere_vm.tags`)
+
+vSphere tags are global objects, not children of a VM. Inventory Read-only on a VM does not include tag reads.
+
+Assign **Read-only** as a **Global Permission** (with propagate) so the user can call tagging REST. If tagging REST fails, VM inventory queries can fail entirely because tag lookup runs as part of listing VMs.
+
+You do not need **vSphere Tagging → Create / Edit / Delete** or **Assign or Unassign vSphere Tag**.
+
+## Complete the configuration
+
+- **vCenter SDK endpoint:** `https://<vcenter-host>/sdk`
+- **User:** SSO principal, for example `plural-cloud-query@vsphere.local`
+- **Password:** that user's password
+- **Allow unverified TLS certificates:** only for internal or self-signed vCenter certs

assets/public/setup-guides/tools/splunk.md

@@ -1,24 +1,94 @@
-# Splunk tool setup
+# Set up the Splunk integration
 
-Use this guide to fill `URL` and either `Bearer token` or `Username` + `Password`.
+Connect a workbench to logs already stored in Splunk Enterprise or Splunk Cloud. This integration is read-only: it streams search results and does not ingest data or install a Splunk forwarder.
 
-## 1) Create read-only access for searches
+The workbench form needs a **management/REST API base URL** and either an **authentication token** or a **username and password**.
 
-Create a dedicated Splunk role/user with read/search capabilities only.
+## Find the API base URL
 
-Common capabilities for API search access:
-- `search`
-- `rest_properties_get`
+The `URL` field is the Splunk **management port** host, not the Splunk Web URL. The integration appends `/services/search/v2/jobs/export` itself, so do not include that path (or any `/en-US/app/...` path).
 
-Also grant access only to the indexes this tool should query.
+Use HTTPS. Default management port is **8089**. Do not use Splunk Web port **8000** or HTTP Event Collector (HEC) port **8088**.
 
-## 2) Choose auth method
+### Splunk Cloud Platform
 
-- Token auth (recommended): create an auth token for the integration user.
-- Basic auth: use dedicated service username/password.
+1. Log in to Splunk Web.
+2. Copy the hostname from the browser address bar (for example `acme.splunkcloud.com`). Ignore everything after the hostname.
+3. Enter `https://<hostname>:8089` in the form.
 
-## 3) Fill the Workbench tool form
+Example: if Splunk Web is `https://acme.splunkcloud.com/en-US/app/search/search`, the API base URL is `https://acme.splunkcloud.com:8089`.
 
-- `URL`: Splunk management/query endpoint base URL
-- Option A: `Bearer token`
-- Option B: `Username` + `Password`
+Port 8089 is often closed until you allowlist the caller:
+
+- Add the workbench egress IPs with the Admin Config Service `search-api` IP allow list, or
+- Open a Splunk support case to enable REST API access on 8089.
+
+Free trial Splunk Cloud stacks cannot use the REST API.
+
+### Splunk Enterprise
+
+1. Identify the search head hostname or IP you use to run searches (not a heavy forwarder).
+2. Confirm the management port: **Settings → Server settings → General settings → Management port** (default `8089`).
+3. Enter `https://<search-head-host>:8089`.
+
+For local or self-signed TLS certificates, append `?insecure_skip_verify=true` to the URL (for example `https://splunk.internal:8089?insecure_skip_verify=true`).
+
+## Create credentials
+
+Create a dedicated integration identity. Do **not** use an HTTP Event Collector (HEC) token from **Settings → Data Inputs → HTTP Event Collector**. HEC tokens ingest events; they cannot call the search REST API.
+
+### Option A: authentication token (recommended)
+
+These are JWT authentication tokens from **Settings → Tokens**, not HEC tokens.
+
+1. Enable token authentication if it is off: **Settings → Tokens → Token Settings → Enable token authentication**. This requires the `edit_tokens_settings` capability (typically `admin` or `sc_admin`).
+2. Create the dedicated user and role described below.
+3. Go to **Settings → Tokens → New Token**.
+4. Set **User** to that dedicated user and **Audience** to a short purpose string such as `plural-workbench`.
+5. Create the token and copy it immediately. Splunk will not show the full value again.
+6. Paste it into **Bearer token**. Leave **Username** and **Password** empty.
+
+### Option B: username and password
+
+1. Create the dedicated user described below and set a password.
+2. Fill **Username** and **Password**. Leave **Bearer token** empty.
+
+## Grant permissions for the search export API
+
+This integration calls only:
+
+`POST {URL}/services/search/v2/jobs/export`
+
+with form fields `search`, `earliest_time`, `latest_time`, and `output_mode=json`. It does not create saved searches, write indexes, or call HEC.
+
+Create a dedicated role: **Settings → Users and authentication → Roles → New Role** (on older Splunk Web: **Settings → Access controls → Roles**).
+
+### Capabilities
+
+Grant only:
+
+- `search` — required to run SPL on `/services/search/v2/jobs/export`
+- `rest_properties_get` — commonly required for REST search clients (covers `/services/properties`; included on Splunk's built-in `user` role)
+
+Do not grant write or admin capabilities such as `indexes_edit`, `admin_all_objects`, `edit_user`, or `edit_roles`.
+
+### Index access (required for data)
+
+Capabilities alone do not return events. On the same role, open **Indexes** and allow only the indexes this tool should query:
+
+- **Indexes** / **Indexes allowed** (`srchIndexesAllowed`) — indexes the user may search
+- **Indexes searched by default** (`srchIndexesDefault`) — optional defaults when a query does not name an index
+
+If these are empty or omit the target index, the export call can succeed with no logs.
+
+### Create the user
+
+**Settings → Users and authentication → Users → New User** (or **Settings → Access controls → Users**). Assign only the role above. Create the authentication token for this user, not for a personal admin account.
+
+## Complete the configuration
+
+- **URL:** management/REST API base URL (`https://<host>:8089`, no search path)
+- **Bearer token:** authentication token from **Settings → Tokens**, or
+- **Username** + **Password:** dedicated service user
+
+After saving, attach the tool to a workbench and run a log query against an index the role can search.

assets/src/components/awaiting-review/AwaitingReviewItem.tsx

@@ -65,16 +65,23 @@ export function AwaitingReviewItem({
         />
       </Flex>
 
-      {configuration?.aiApproval?.enabled && approvalResult?.result && (
+      {approvalResult?.result && (
         <Flex
           direction="column"
           gap="xsmall"
           padding="small"
           css={{
-            backgroundImage: `linear-gradient(${theme.colors['fill-one']}, ${theme.colors['fill-one']}), linear-gradient(316deg, #E3A966 0%, #8961F4 32%, #747AF6 71%, #6D94F9 100%)`,
-            backgroundClip: 'padding-box, border-box',
-            backgroundOrigin: 'border-box',
-            border: '1px solid transparent',
+            ...(configuration?.aiApproval?.enabled
+              ? {
+                  backgroundImage: `linear-gradient(${theme.colors['fill-one']}, ${theme.colors['fill-one']}), linear-gradient(316deg, #E3A966 0%, #8961F4 32%, #747AF6 71%, #6D94F9 100%)`,
+                  backgroundClip: 'padding-box, border-box',
+                  backgroundOrigin: 'border-box',
+                  border: '1px solid transparent',
+                }
+              : {
+                  backgroundColor: theme.colors['fill-one'],
+                  border: theme.borders.default,
+                }),
             borderRadius: theme.borderRadiuses.large,
           }}
         >
@@ -85,10 +92,12 @@ export function AwaitingReviewItem({
             }}
           >
             <CaptionP $color="text-xlight">Approval decision</CaptionP>
-            <AiSparkleFilledIcon
-              color="icon-info"
-              size={13}
-            />
+            {configuration?.aiApproval?.enabled && (
+              <AiSparkleFilledIcon
+                color="icon-info"
+                size={13}
+              />
+            )}
           </StretchedFlex>
           <StackAIApprovalChip
             approvalResult={approvalResult?.result}

assets/src/components/stacks/common/terraformPlan.ts

@@ -0,0 +1,81 @@
+/**
+ * Converts `terraform show -json` output into the reduced plan Spacelift
+ * exposes to plan policies, instead of passing the full Terraform document.
+ *
+ * See: https://docs.spacelift.io/concepts/policy/terraform-plan-policy
+ */
+
+export type TerraformPlanAction =
+  'create' | 'update' | 'delete' | 'no-op' | 'read'
+
+export type PolicyResourceChange = {
+  address?: string
+  type?: string
+  name?: string
+  provider_name?: string | null
+  change: {
+    actions: TerraformPlanAction[]
+    before?: unknown
+    after?: unknown
+  }
+}
+
+export type PolicyPlan = {
+  terraform_version?: string | null
+  resource_changes: PolicyResourceChange[]
+}
+
+type TerraformChange = {
+  actions?: TerraformPlanAction[]
+  before?: unknown
+  after?: unknown
+  after_unknown?: unknown
+  before_sensitive?: unknown
+  after_sensitive?: unknown
+}
+
+type TerraformResourceChange = {
+  address?: string
+  mode?: string
+  type?: string
+  name?: string
+  provider_name?: string
+  change?: TerraformChange
+}
+
+type TerraformPlan = {
+  format_version?: string
+  terraform_version?: string
+  resource_changes?: TerraformResourceChange[]
+}
+
+export function toPolicyPlan(
+  plan: TerraformPlan | null | undefined
+): PolicyPlan {
+  if (!plan) return { terraform_version: null, resource_changes: [] }
+
+  return {
+    terraform_version: plan.terraform_version ?? null,
+    resource_changes: (plan.resource_changes ?? []).map(convertChange),
+  }
+}
+
+function convertChange(change: TerraformResourceChange): PolicyResourceChange {
+  return {
+    address: change.address,
+    type: change.type,
+    name: change.name,
+    provider_name: providerName(change.provider_name),
+    change: {
+      actions: change.change?.actions ?? [],
+      before: change.change?.before,
+      after: change.change?.after,
+    },
+  }
+}
+
+function providerName(name?: string): string | undefined {
+  if (!name) return name
+  const parts = name.split('/')
+  return parts[parts.length - 1]
+}

assets/src/components/stacks/run/Header.tsx

@@ -170,6 +170,7 @@ function StackRunHeaderInfo({ stackRun }): ReactNode {
       >
         <GitCommitIcon />
         {stackRun.git?.ref}
+        {stackRun.committer && <span>{stackRun.committer}</span>}
       </span>
     </div>
   )