sf-permissions

Salesforce Permission Set analysis, visualization, and auditing tool

When to Use This Skill

Use sf-permissions when the user needs to:

• Visualize Permission Set and Permission Set Group hierarchies
• Find out “who has access to X?” (objects, fields, Apex classes, custom permissions)
• Analyze what permissions a specific user has
• Export Permission Set configurations for auditing
• Generate Permission Set XML metadata
• Grant agent access via <agentAccesses> element

Capabilities

Prerequisites

pip install simple-salesforce rich  # Python dependencies
sf --version                         # Must be installed and authenticated
sf org display                       # Check current org

Phase 1: Understanding the Request

Phase 2: Connecting to the Org

sf org list                          # List available orgs
sf org display --target-org <alias>  # Check specific org

# Run from sf-permissions/scripts/
from auth import get_sf_connection
sf = get_sf_connection('myorg')  # or None for default

Phase 3: Executing Queries

3.1 Permission Hierarchy Viewer

cd ~/.claude/plugins/marketplaces/sf-skills/sf-permissions/scripts
python cli.py hierarchy [--target-org ALIAS] [--format ascii|mermaid]

Output Example:

📦 ORG PERMISSION HIERARCHY
════════════════════════════════════════

📁 Permission Set Groups (3)
├── 🔒 Sales_Cloud_User (Active)
│   ├── View_All_Accounts
│   ├── Edit_Opportunities
│   └── Run_Reports
└── 🔒 Service_Cloud_User (Active)
    └── Case_Management

📁 Standalone Permission Sets (12)
├── Admin_Tools
├── API_Access
└── ... (10 more)

3.2 Permission Detector (“Who has access to X?”)

Supported Permission Types: object, field, apex, vf, flow, custom, tab

python cli.py detect object Account --access delete
python cli.py detect field Account.AnnualRevenue --access edit
python cli.py detect apex MyApexClass
python cli.py detect custom Can_Approve_Expenses

3.3 User Permission Analyzer

python cli.py user "john.smith@company.com"
python cli.py user 005xx000001234AAA  # User ID also works

3.4 Permission Set Exporter

python cli.py export Sales_Manager --output /tmp/sales_manager.csv

3.5 Agent Access Permissions

See references/agent-access-guide.md for full <agentAccesses> XML structure, deploy steps, and visibility troubleshooting (missing icon, name mismatch, CopilotSalesforceUser PS).

Employee Agents require <agentAccesses> in a Permission Set — <agentName> must match the agent’s developer_name exactly.

Phase 4: Rendering Output

• ASCII Tree (Terminal): Uses rich library for trees, tables, panels
• Mermaid Diagrams (Docs): python cli.py hierarchy --format mermaid > hierarchy.md

Phase 5: Generating Metadata

python cli.py generate \
    --name "New_Sales_PS" \
    --label "New Sales Permission Set" \
    --objects Account:crud,Opportunity:cru \
    --fields Account.AnnualRevenue:rw \
    --apex MyApexClass,AnotherClass \
    --output /tmp/New_Sales_PS.permissionset-meta.xml

Or delegate to sf-metadata for more complex generation.

SOQL Reference

See references/permission-soql-queries.md for the complete query catalog: Permission Set/Group queries, object permissions, field permissions, setup entity access (Apex, VF, Flows, Custom Permissions).

Quick queries:

-- All Permission Sets (non-profile)
SELECT Id, Name, Label FROM PermissionSet WHERE IsOwnedByProfile = false AND Type != 'Group'

-- User's PS Assignments
SELECT PermissionSetId, PermissionSet.Name FROM PermissionSetAssignment WHERE AssigneeId = '005...'

-- Find PS with delete access to Account
SELECT Parent.Name FROM ObjectPermissions WHERE SobjectType = 'Account' AND PermissionsDelete = true

Troubleshooting

Common Workflows & Examples

See references/workflow-examples.md for detailed step-by-step workflows: audit “Who can delete Accounts?”, troubleshoot user access, document a Permission Set, full org audit, security review, and PS creation examples.

Integration with Other Skills