@raishin/vanguard-frontier-agentic 2.2.0 → 2.5.0

package/skills/salesforce/salesforce-soql-explorer-skill/metadata.json

@@ -0,0 +1,35 @@
+{
+  "id": "salesforce-soql-explorer-skill",
+  "name": "Salesforce SOQL Explorer Skill",
+  "type": "skill",
+  "provider": "salesforce",
+  "harnesses": ["claude-code", "codex", "cursor", "gemini", "kiro", "other"],
+  "summary": "Executes read-only SOQL queries against a connected Salesforce org via the sf CLI under T1 least-privilege scope. Returns sanitized JSON output with a structured audit envelope. Live operational counterpart to the static-review skills. No DML. No metadata mutation. Sanitized output only.",
+  "source_type": "original",
+  "category": "operational",
+  "execution_tier": "read-only-runtime",
+  "oauth_scopes": ["api", "refresh_token"],
+  "mcp_servers": [],
+  "run_as_permissions": {
+    "required": ["View Setup and Configuration"],
+    "denied": [
+      "ModifyAllData",
+      "ViewAllData",
+      "ViewEncryptedData",
+      "ModifyMetadata",
+      "AuthorApex",
+      "ManageConnectedApps"
+    ]
+  },
+  "official_docs": [
+    "https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm",
+    "https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm",
+    "https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm",
+    "https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_query.htm"
+  ],
+  "security_notes": "T1 read-only operational scope only. No DML permitted. OAuth scopes restricted to api + refresh_token. Run As service account has no ModifyAllData, ViewAllData, ViewEncryptedData, ModifyMetadata, AuthorApex, or ManageConnectedApps permissions. Org allowlist enforced by Connected App. Every execution emits a structured audit envelope. All Salesforce IDs, user IDs, and PII fields are redacted before output. Refresh token rotation immediately revokes access. Regulated-vertical orgs (Health Cloud, Financial Services Cloud) trigger mandatory compliance escalation.",
+  "last_verified": "2026-05-21",
+  "path": "skills/salesforce/salesforce-soql-explorer-skill",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/salesforce/salesforce-soql-explorer-skill/references/cli-commands.md

@@ -0,0 +1,266 @@
+<!-- Parent: salesforce-soql-explorer-skill/SKILL.md -->
+# Salesforce CLI Commands — SOQL Explorer Reference
+
+
+---
+
+## Org Introspection
+
+### Confirm connectivity and org type
+
+```bash
+sf org display --target-org <alias>
+```
+
+Output includes: username, instance URL, org type (Scratch Org / Sandbox /
+Production), OAuth client ID, access token expiry. Use this to verify
+the org is reachable and that the alias resolves to the expected org type
+before running any query.
+
+**T1 check:** If `orgType` or `isDevHub` indicates production and the
+Connected App allowlist does not explicitly authorize this alias, stop.
+
+### List authorized orgs
+
+```bash
+sf org list --connected
+```
+
+Returns all orgs with active authentication. Use to enumerate valid aliases
+before accepting a user-provided alias. Cross-reference against the
+org allowlist maintained in the Connected App configuration.
+
+```bash
+# JSON output for scripting / allowlist verification
+sf org list --connected --json
+```
+
+---
+
+## Schema Introspection
+
+### Describe an sObject (field list, FLS, encryption flags)
+
+```bash
+sf sobject describe --sobject Account --target-org <alias>
+```
+
+Read the output before building a query:
+- `fields[].name` — API names of available fields
+- `fields[].encrypted` — `true` if Shield PE / PMLE encrypted; **skip these**
+- `fields[].nillable` / `fields[].type` — inform filter design
+- `queryable: true` — confirms the object supports SOQL
+
+```bash
+# JSON output for jq processing
+sf sobject describe --sobject Account --target-org <alias> --json \
+  | jq '[.result.fields[] | {name: .name, type: .type, encrypted: .encrypted}]'
+```
+
+**Encrypted field detection:**
+
+```bash
+sf sobject describe --sobject Contact --target-org <alias> --json \
+  | jq '[.result.fields[] | select(.encrypted == true) | .name]'
+```
+
+Remove any fields returned from this command from your query. Do not
+include them even as placeholders.
+
+---
+
+## Query Execution
+
+### Basic read-only query (JSON output — preferred)
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, Industry FROM Account WHERE CreatedDate = LAST_N_DAYS:30 LIMIT 200" \
+  --target-org <alias> \
+  --result-format json
+```
+
+JSON output is preferred over the default human-readable table because it
+is structured, pipeable to `jq` for redaction, and unambiguous about field
+values.
+
+### Preview with LIMIT 5 before full execution
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM Account LIMIT 5" \
+  --target-org <alias> \
+  --result-format json
+```
+
+Always preview first. Confirm field shape, check for unexpected values,
+verify no encrypted or PII fields slipped through.
+
+### Full execution with appropriate LIMIT
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, StageName, Amount FROM Opportunity WHERE CloseDate >= THIS_QUARTER LIMIT 200" \
+  --target-org <alias> \
+  --result-format json
+```
+
+Maximum interactive LIMIT: 2,000. Do not exceed. For larger volumes,
+route to `salesforce-bulk-data-ops-skill`.
+
+### Count query (no record data returned)
+
+```bash
+sf data query \
+  --query "SELECT COUNT FROM Contact WHERE Email = null" \
+  --target-org <alias> \
+  --result-format json
+```
+
+Use COUNT to answer "how many" questions without returning record values.
+Reduces PII exposure and governor limit consumption.
+
+### Aggregate query
+
+```bash
+sf data query \
+  --query "SELECT StageName, COUNT(Id) cnt, SUM(Amount) total FROM Opportunity GROUP BY StageName" \
+  --target-org <alias> \
+  --result-format json
+```
+
+---
+
+## Tooling API Queries
+
+Use `--use-tooling-api` to query metadata objects (ApexClass, CustomField,
+CustomObject, FlowDefinition, etc.) when schema introspection is needed
+without a metadata retrieve.
+
+```bash
+# Query ApexClass metadata
+sf data query \
+  --query "SELECT Id, Name, Status FROM ApexClass WHERE NamespacePrefix = null LIMIT 50" \
+  --target-org <alias> \
+  --use-tooling-api \
+  --result-format json
+
+# Query CustomField metadata
+sf data query \
+  --query "SELECT Id, DeveloperName, TableEnumOrId, DataType FROM CustomField WHERE TableEnumOrId = 'Account'" \
+  --target-org <alias> \
+  --use-tooling-api \
+  --result-format json
+
+# Query FlowDefinition for automation inventory
+sf data query \
+  --query "SELECT Id, ApiName, ActiveVersionId, ProcessType FROM FlowDefinition LIMIT 100" \
+  --target-org <alias> \
+  --use-tooling-api \
+  --result-format json
+```
+
+> **Note:** Tooling API queries access metadata, not record data. FLS does
+> not apply the same way; however, the Run As account must still have
+> View Setup and Configuration.
+
+---
+
+## Output Sanitization with jq
+
+### Redact Salesforce IDs (replace with placeholder)
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM Account LIMIT 10" \
+  --target-org <alias> \
+  --result-format json \
+  | jq '.result.records[] | {Id: "<record_id_placeholder>", Name: .Name}'
+```
+
+### Redact owner/user ID fields
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, OwnerId FROM Opportunity LIMIT 10" \
+  --target-org <alias> \
+  --result-format json \
+  | jq '.result.records[] | {
+      Id: "<record_id_placeholder>",
+      Name: .Name,
+      OwnerId: "<user_id_placeholder>"
+    }'
+```
+
+### Extract record count only (no record values)
+
+```bash
+sf data query \
+  --query "SELECT COUNT FROM Account" \
+  --target-org <alias> \
+  --result-format json \
+  | jq '.result.totalSize'
+```
+
+### Extract specific fields with multi-field redaction
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, Email, CreatedById FROM Contact LIMIT 5" \
+  --target-org <alias> \
+  --result-format json \
+  | jq '.result.records[] | {
+      Id: "<record_id_placeholder>",
+      Name: .Name,
+      Email: "<redacted_pii>",
+      CreatedById: "<user_id_placeholder>"
+    }'
+```
+
+---
+
+## Bulk Flag Notes
+
+
+### The --all-rows flag
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, IsDeleted FROM Account WHERE IsDeleted = true LIMIT 50" \
+  --target-org <alias> \
+  --all-rows \
+  --result-format json
+```
+
+`--all-rows` includes soft-deleted records (records in the Recycle Bin).
+Use only when explicitly investigating deleted record state. Document the
+intent in the audit envelope `assumptions` field.
+
+---
+
+## Query Plan Analysis
+
+Use `--plan` to inspect the query execution plan before running a query
+against a large object. Requires the Tooling API flag.
+
+```bash
+sf data query \
+  --query "SELECT Id FROM Account WHERE Name = 'Acme'" \
+  --target-org <alias> \
+  --use-tooling-api \
+  --plan
+```
+
+Key fields in plan output:
+- `leadingOperationType: "Index"` — query uses an index (efficient)
+- `leadingOperationType: "TableScan"` — full table scan (warn if object > 10k records)
+- `relativeCost < 1` — efficient
+- `cardinality` — estimated rows returned
+
+If plan shows `TableScan` on a large object, revise the query to add a
+selective indexed filter before executing.
+
+---
+
+## Required CLI Version
+

package/skills/salesforce/salesforce-soql-explorer-skill/references/least-privilege-scope.md

@@ -0,0 +1,224 @@
+<!-- Parent: salesforce-soql-explorer-skill/SKILL.md -->
+# T1 Least-Privilege Scope — SOQL Explorer
+
+.
+
+This document defines the least-privilege boundary for the T1 read-only
+operational tier. Every claim here must be verified against a live Salesforce
+org before production use. Do not assume parity with legacy sfdx behavior.
+
+---
+
+## OAuth Connected App Configuration
+
+The skill authenticates via a Connected App using the OAuth 2.0 JWT Bearer
+or Web Server flow. The Connected App must be configured as follows:
+
+### Permitted OAuth Scopes (check exactly these two)
+
+```
+[x] Access and manage your data (api)
+[x] Perform requests on your behalf at any time (refresh_token, offline_access)
+[ ] Full access (full)                            ← MUST be unchecked
+[ ] Web (web)                                     ← MUST be unchecked
+[ ] Salesforce Platform API features (sfap_api)   ← MUST be unchecked
+[ ] CDP Query API (cdp_query_api)                 ← MUST be unchecked
+[ ] Manage user data via APIs (api) + openid      ← not needed; omit
+```
+
+Any scope beyond `api` and `refresh_token` is prohibited for T1 skills.
+
+### IP Allowlisting
+
+Set **Permitted Users** to "Admin approved users are pre-authorized" and
+configure **IP Relaxation** to "Enforce IP restrictions". Add only the
+IP ranges from which the skill runner (CI system, local developer machine,
+or agent orchestrator) operates.
+
+Do not set IP Relaxation to "Relax IP restrictions".
+
+### Callback URL
+
+Use a non-production callback URL (e.g., `http://localhost:1717/OauthRedirect`
+for JWT flows) or the CI system's callback. Never use a production endpoint
+as the callback for a T1 service account.
+
+### Refresh Token Rotation
+
+Enable **Refresh Token Rotation** in the Connected App OAuth settings.
+This ensures that each token refresh issues a new refresh token and
+invalidates the previous one — a prerequisite for the revocation model
+described below.
+
+---
+
+## Run As Service Account — Profile Design
+
+The "Run As" account is a dedicated Salesforce user (not a named human user)
+whose profile and permission sets define the T1 access boundary.
+
+### System Permissions — REQUIRED
+
+```
+[x] View Setup and Configuration
+    (API: ViewSetup)
+    Required for: sf org display, sobject describe, tooling API queries
+```
+
+No other system permissions are required for T1 SOQL exploration. Do not
+grant any system permission not listed here.
+
+### System Permissions — EXPLICITLY DENIED
+
+These permissions must be absent from the Run As account's profile AND from
+any permission set assigned to the account. Verify via Setup > Users >
+[Run As User] > View Summary.
+
+```
+[ ] Modify All Data        (API: ModifyAllData)
+[ ] View All Data          (API: ViewAllData)          ← system bypass, not record access
+[ ] View Encrypted Data    (API: ViewEncryptedData)
+[ ] Modify Metadata Through Metadata API Functions
+                           (API: ModifyMetadata)
+[ ] Author Apex            (API: AuthorApex)
+[ ] Customize Application  (API: CustomizeApplication)
+[ ] Manage Connected Apps  (API: ManageConnectedApps)
+[ ] API Enabled            ← Wait — this IS required for CLI access. See note below.
+```
+
+> **Note on API Enabled:** The Run As account must have `API Enabled` checked
+> (required for any CLI or API access). All other API-adjacent permissions
+> (ModifyAllData, ViewAllData, etc.) must still be denied. `API Enabled`
+> alone grants only the ability to make authenticated API calls subject
+> to standard sharing and FLS — it does not bypass sharing or FLS.
+
+### Object Permissions — Per-Object Read Only
+
+For each sObject in scope:
+
+```
+[x] Read
+[ ] Create
+[ ] Edit
+[ ] Delete
+[ ] View All    ← MUST be unchecked (bypasses sharing)
+[ ] Modify All  ← MUST be unchecked
+```
+
+Grant Read access only on the specific objects the skill will query. Do not
+grant Read on all objects by default — enumerate the scope explicitly per
+matter or engagement.
+
+### Field-Level Security (FLS)
+
+For each field the skill may query:
+
+```
+[x] Read
+[ ] Edit
+```
+
+FLS must be explicitly configured. The T1 Run As account must not have
+Read access to:
+- Fields marked as encrypted (Shield PE / PMLE)
+- Fields containing PII (email, phone, SSN, health data, financial account
+  numbers) unless the matter explicitly requires it and the field is not
+  encrypted
+- Fields in shadow objects or reporting snapshots unless the matter requires
+
+Use the `sf sobject describe` output (see `cli-commands.md`) to verify
+which fields the Run As account can actually read before constructing queries.
+
+---
+
+## IP Allowlisting at the Connected App Level
+
+Configure the Connected App's IP restrictions to match the expected source
+ranges for the skill runner:
+
+| Environment | Expected Source |
+|---|---|
+| Local developer | Developer machine IP or VPN exit node |
+| CI/CD pipeline | CI runner IP range (static or NAT gateway) |
+| Agent orchestrator | Orchestrator cluster egress IP range |
+
+Review and update IP allowlists quarterly or when infrastructure changes.
+Do not use `0.0.0.0/0`.
+
+---
+
+## Refresh Token Rotation and Revocation
+
+### Rotation cadence
+
+Rotate the Run As account's refresh token:
+- At minimum every 90 days
+- Immediately upon any suspected compromise
+- When the Run As account's org is decommissioned
+
+### Revocation procedure
+
+1. Log in to the Salesforce org as an administrator.
+2. Navigate to Setup > Connected Apps > [App Name] > Manage > OAuth Usage.
+3. Find the Run As account's active token and revoke it.
+4. Alternatively, reset the Run As user's security token via Setup > Users >
+   [Run As User] > Reset Security Token.
+5. Confirm the skill can no longer authenticate by running `sf org display --target-org <alias>`.
+
+Rotating the refresh token immediately invalidates all active sessions for
+the Run As account without affecting any other user or integration.
+
+---
+
+## Audit Trail Enablement
+
+Enable the following in the target Salesforce org to support the T1 audit model:
+
+1. **Setup Audit Trail** — automatically enabled in all orgs. Captures
+   metadata and setup changes. The Run As account's actions appear here.
+2. **Event Monitoring** (add-on, if licensed
+)
+   — captures API query events, login events, and data export events.
+   Strongly recommended for production-adjacent T1 use.
+3. **Platform Event logging** — if the org uses Platform Events, confirm
+   the Run As account cannot publish events (no Create permission on
+   Platform Event objects).
+
+The skill's audit envelope (see `SKILL.md`) is a local record only. The
+org-side audit trail is the authoritative log for compliance purposes.
+
+---
+
+## Org Allowlist Verification
+
+Before executing any query, the skill calls `sf org list --connected --json`
+and verifies that the `--target-org` alias appears in the list. If the alias
+is not in the list:
+
+1. The skill does not attempt to authenticate.
+2. The skill emits a refusal with reason `alias_not_authorized`.
+3. The skill suggests running `sf org login web --alias <alias>` or
+   `sf org login jwt --alias <alias>` as the appropriate remediation.
+
+The Connected App allowlist (Permitted Users + IP restrictions) is the
+enforcement layer. The `sf org list` check is a soft pre-flight that
+reduces unnecessary authentication failures.
+
+---
+
+##Tags in This Document
+
+The following items in this file must be re-verified against the live
+Salesforce documentation before merging to main:
+
+- Permission API names (`ModifyAllData`, `ViewAllData`, `ViewEncryptedData`,
+  `ModifyMetadata`, `AuthorApex`, `CustomizeApplication`, `ManageConnectedApps`,
+  `ViewSetup`) — confirm these match current API names in Spring '26 or later.
+- Connected App OAuth scope labels — Salesforce has renamed scopes in past
+  releases; confirm `api` and `refresh_token` (offline_access) are the
+  correct scope identifiers.
+- Event Monitoring availability and licensing model.
+- `Refresh Token Rotation` Connected App option — confirm it is available
+  in the org edition being targeted.
+- Health Cloud and Financial Services Cloud as regulated-vertical indicators
+  — confirm both are still the primary regulated cloud products.