azure-rbac-role-matching

name	azure-rbac-role-matching
description	Recommend the least-privilege Azure built-in RBAC roles for one or more requested operations. Use this whenever users ask what role to assign, how to minimize Azure permissions, or which built-in role is the smallest safe match for a service principal, managed identity, app, or operator workflow.
metadata	{"domain":"authorization","confidence":"medium","source":"observed"}

Use When

Use this skill when you need least-privilege built-in Azure RBAC role candidates from a set of requested operations and can work from checked-in snapshot data.

• Find the smallest built-in role that covers one or more exact operations.
• Validate or compare least-privilege role recommendations before assignment.
• Recommend role candidates for service principals, managed identities, automation, or CI/CD jobs.
• Explain why a broad role appears and surface smaller non-privileged alternatives first.

Do Not Use When

• You need custom role JSON generation.
• You need live scope reasoning (resource group vs subscription), PIM, ABAC, or deny assignment analysis.
• You need runtime authorization validation against Azure APIs.

Inputs

• one or more Azure permission strings, such as Microsoft.Support/services/read

Workflow

1. Load references/data/roles-extended.json and references/data/permissions.json.
2. Evaluate each requested permission with wildcard allow/deny logic:
   • actions
   • notActions
   • dataActions
   • notDataActions
3. Use the permission metadata to keep control-plane and data-plane checks separate.
4. Keep only roles that grant every requested permission.
5. Rank matches by matchingPermissionsTotal ascending, while treating 0 as an unknown-coverage edge case and pushing those candidates later.
6. Flag roles as privileged when they also grant Microsoft.Authorization/roleAssignments/write.

The canonical implementation seam is scripts/lib/rbac.js. The sample CLI wrapper is scripts/match-roles.js.

Install and Run

Copilot CLI plugin (primary path)

/plugin install kdcllc/azure-rbac-role-matching-skill

After installation, invoke the skill directly from the Copilot CLI agent. The skill runs entirely offline — no live Azure API calls are made at install time or at match time.

npm (library / CLI path)

Use when integrating the matcher into your own scripts or Node.js tooling:

npm install azure-rbac-role-matching-skill
npx azure-rbac-role-match Microsoft.Support/services/read

For a global install:

npm install -g azure-rbac-role-matching-skill
azure-rbac-role-match Microsoft.Support/services/read

Agent Integration

Use the shared matcher directly when integrating this skill into another agent flow:

const {
   loadExtendedRolesPayload,
   loadPermissionIndex,
   rankRoles,
} = require('azure-rbac-role-matching-skill');

const [payload, permissionIndex] = await Promise.all([
   loadExtendedRolesPayload(),
   loadPermissionIndex(),
]);

const matches = rankRoles(
   ['Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'],
   payload.roles,
   permissionIndex
);

Outputs

• ranked built-in role candidates
• matchingPermissionsTotal for each candidate
• privileged-role flag
• custom-role guidance when no built-in role covers every requested permission

Boundaries

• The corpus is snapshot-based, not live.
• Shipping through a root plugin.json does not change runtime behavior — the matcher always runs offline against checked-in snapshot data.
• This skill covers Azure built-in roles only. Custom role JSON generation is out of scope.
• This repo does not validate scope-specific access behavior.
• This repo does not handle deny assignments, PIM, ABAC, or broader governance logic.
• matchingPermissionsTotal is a size heuristic, not a security score.
• The result list is recommendation guidance, not an enforcement decision.

Validation

npm run validate
npm run match -- Microsoft.Support/services/read
npm pack --dry-run

References

• README.md — package overview
• references/ALGORITHM.md — matcher and ranking details
• references/DATA-REFRESH.md — snapshot refresh process
• references/OPERATOR-GUIDE.md — human workflow and interpretation guidance