permset-audit

You are building a permission audit matrix for the target org. The matrix is rows=objects/fields, columns=profile-or-permset, cells=R/CRUD/-. Use it to spot orphan permsets, fields that no one can see, and divergence between similarly named profiles and permsets.

Security: data-with-consent

This skill queries PermissionSetAssignment, which links permission sets to specific user records. That's customer data per the plugin's security model — the metadata-only allowlist blocks it by default, so the skill prompts the user for per-call consent before running.

The other queries used by this skill (Profile, PermissionSet, ObjectPermissions, FieldPermissions) ARE on the metadata allowlist and do not require consent.

When the assistant sees exit code 77 from sf_cli_query with reason: SOQL_DATA_OBJECT and target: PermissionSetAssignment:

[argo/security] CONSENT REQUIRED

Skill:    /permset-audit
Org:      <alias>
Action:   SOQL query against PermissionSetAssignment
Records:  ~N (one per active permset assignment in the org)
What enters your conversation context with Claude:
  • User Ids (AssigneeId)
  • Permission Set Ids (PermissionSetId)
  • No field values, no email/name fields are projected

Choose:
  [a] Allow once    — runs this query (audit log: "permset-audit / soql / PermissionSetAssignment / allow-once")
  [d] Deny this part — skip the assignments query; the audit will report orphan permsets without per-user assignments
  [c] Cancel        — abort the skill

On [a] re-invoke the same sf_cli_query after export ARGO_CONSENT_GRANTED=once. Per the plugin contract this is a single-use override; a follow-up call inside the same skill run requires another consent.

Read Project Config First

source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/config.sh"
source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/sf-cli.sh"
sf_cli_check || exit 2
ORG="$(sf_config_get '.platform.defaultTargetOrg' "$ENV")"
SKILL_NAME="permset-audit"; export SKILL_NAME

Input

$ARGUMENTS:

• (empty) — full audit of all custom objects + selected standard objects (Account, Contact, Case, Opportunity, Lead, User)
• <object> — limit to a single sObject API name
• <object>.<field> — limit to a single field
• --include-managed — include objects from managed packages (default: skip)
• --target-org <alias> / --env <name> — standard overrides
• --ci / --format json|sarif / --out <path>

Steps

1. Pull profiles, permsets, and assignments

sf_cli_query "
  SELECT Id, Name, UserType, IsCustom FROM Profile
" "$ORG" > /tmp/permset-audit-profiles.json

sf_cli_query "
  SELECT Id, Name, Label, License.Name, Type, IsCustom
  FROM PermissionSet
  WHERE IsOwnedByProfile = false
" "$ORG" > /tmp/permset-audit-permsets.json

# PermissionSetAssignment links permsets to specific users (customer data) —
# routing through sf_cli_query fires the metadata-allowlist consent prompt here.
sf_cli_query "
  SELECT AssigneeId, PermissionSetId
  FROM PermissionSetAssignment
  WHERE PermissionSet.IsOwnedByProfile = false
" "$ORG" > /tmp/permset-audit-assignments.json

2. Pull object permissions

For the in-scope objects:

sf_cli_query "
  SELECT ParentId, Parent.Name, Parent.Type, Parent.Profile.Name,
         SObjectType, PermissionsRead, PermissionsCreate, PermissionsEdit,
         PermissionsDelete, PermissionsViewAllRecords, PermissionsModifyAllRecords
  FROM ObjectPermissions
  WHERE SObjectType IN ('Account','Contact', ...)
" "$ORG"

3. Pull field permissions (per object — paginate)

sf_cli_query "
  SELECT ParentId, Parent.Name, Parent.Type, Parent.Profile.Name,
         SObjectType, Field, PermissionsRead, PermissionsEdit
  FROM FieldPermissions
  WHERE SObjectType = 'Account'
" "$ORG"

FieldPermissions queries are large; loop per object instead of one giant IN clause.

4. Build the matrix in memory

Pseudocode:

matrix = {}  # (sobject, field) -> { permsetId -> "R" / "CRUD" / "-" }
for fp in field_permissions:
    key = (fp.sobject, fp.field)
    matrix.setdefault(key, {})
    cell = matrix[key]
    perms = []
    if fp.PermissionsEdit: perms.append("U")
    if fp.PermissionsRead: perms.append("R")
    cell[fp.parent_id] = "".join(perms) or "-"

Repeat for object-level perms.

5. Findings

• PERM-ORPHAN-PERMSET (warning) — permset not assigned to any user, never granted access to any object/field used by any LWC/Apex in source
• PERM-FIELD-NO-READ (error) — custom field with no profile or permset granting read; nobody can see it
• PERM-DIVERGENCE (warning) — profile and similarly-named permset both grant access to the same object but with different CRUD masks (likely accidental)
• PERM-MASTER-DETAIL-NO-CRU (warning) — master object grants edit but child master-detail object doesn't (or vice versa) — likely a misconfigured share path

6. Output

Default Markdown:

# Permission Audit: <ORG>

Run at: ...
Scope: 27 custom objects + 6 standard

## Findings

### Critical (must fix)
- `Account.Risk_Score__c` — no profile or permset grants Read access (PERM-FIELD-NO-READ)
- ...

### High
- Permset `Sales_Old` is unassigned and grants no source-referenced access (PERM-ORPHAN-PERMSET)
- ...

## Coverage matrix excerpt: Account

| Field | Sales User | Sales Manager | Acme_Sales_PS | Acme_Manager_PS |
|-------|------------|----------------|----------------|-------------------|
| Name  | R          | RU             | RU             | RU                |
| Risk_Score__c | -  | -              | RU             | RU                |
| ...

(Full matrix in CI JSON output.)

CI JSON shape:

{
  "org": "...", "ranAt": "...",
  "findings": [{ "ruleId": "PERM-FIELD-NO-READ", "severity": "error", "message": "...", "file": "(metadata)", "line": 1 }],
  "matrix": {
    "Account": {
      "Name": { "Sales User": "R", "Acme_Sales_PS": "RU" },
      "Risk_Score__c": { "Acme_Sales_PS": "RU" }
    }
  }
}

SARIF: each finding emitted via ${CLAUDE_PLUGIN_ROOT}/hooks/lib/sarif.sh. The matrix is omitted from SARIF (SARIF is for findings, not data) — emit JSON sidecar at <out>.matrix.json.

7. Exit codes

• 0 — no error-level findings
• 1 — any error-level finding
• 2 — query/setup error

Rules

• No write operations. This is read-only; never deploy or modify perms
• Page large queries. FieldPermissions on a heavy org can return tens of thousands of rows — paginate per sObject
• Excluded by default: managed-package objects (namespacePrefix set), the User object's standard fields, and audit fields (CreatedDate, etc.)
• Skip system permsets. IsOwnedByProfile = true permsets are profile-derived; we only audit user-managed permsets