analyzing-access
Reviewing who holds which ServiceNow roles and explaining access denials. Lists admin and security_admin holders, roles granted directly instead of through groups, roles left on inactive or long-absent users, and diagnoses 401/403 errors, empty results and missing fields. Joins u
Install
npx skills add https://github.com/jschuller/mcp-server-servicenow/tree/main/src/servicenow_mcp/skills/analyzing-access
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install jschuller-mcp-server-servicenow@llmmart
git clone https://github.com/jschuller/mcp-server-servicenow.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole jschuller/mcp-server-servicenow collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Analyzing ServiceNow Access
Two jobs: review role and group hygiene across users, and explain why a call was denied or came back incomplete. Everything here is read-only. See references/access-errors.md for the denial messages and what each one means, and references/acl-evaluation.md for how ServiceNow decides access.
Tables and roles
| Table | What it answers | Readable with |
|---|---|---|
sys_user_has_role |
Which user holds which role, directly or inherited | itil (all users' rows); snc_read_only alone gets 403 |
sys_user_grmember |
Group membership; group names come from sys_user_group through group.name |
itil |
sys_group_has_role |
Which roles a group grants | itil |
sys_user |
active, last_login_time |
snc_read_only |
sys_security_acl |
The ACL rules themselves | admin / security_admin only: 403 for least-privilege identities |
Role names come through dot-walks (role.name). The role table itself (sys_user_role) usually hides some or all of its rows from least-privilege identities, so role.name can come back empty (observed for admin and security_admin) while a filter on role.name=admin still matches. Workflow 5 covers dot-walks and their limits.
When access is denied
- 403 on a table: not assessable with this identity. Say so, name the table, and move on; don't guess.
- 0 rows or fields missing from every row (
list_recordsadds awarning): possibly hidden by an ACL, not proof that nothing exists. - 401 under API-key auth on aggregates or single-record reads: a REST API access policy doesn't cover that API; table reads still work.
Workflows
1. Who holds privileged roles
Progress checklist:
- [ ] List active admin and security_admin grants
- [ ] Flag inactive users and stale logins among them
- [ ] Separate direct grants from group grants
- [ ] Report counts and the accounts to review
- List the grants, with enough user context to judge each one:
Iflist_records(table_name="sys_user_has_role", query="role.nameINadmin,security_admin^state=active", fields="user.user_name,user.active,user.last_login_time,role,role.name,inherited", limit=200)role.namecomes back empty, tell the two roles apart by therolesys_id, or run the query once per role. - A row with
inherited=falseis a direct grant. An inherited row came through a group or through a role that contains this one. To find the group, intersect the user's groups with the groups that grant the role (workflow 2, step 3):list_records(table_name="sys_user_grmember", query="user.user_name=<user>", fields="group.name", limit=100)granted_bystill names the group on some instances, but ServiceNow has deprecated it, so don't rely on it. - Report the holder count per role, then the accounts to review first: inactive users, users with no recent login, and direct grants.
2. Roles granted outside groups
ServiceNow recommends granting roles through groups, so that moving a person between teams moves their access.
- List direct grants on active users:
list_records(table_name="sys_user_has_role", query="inherited=false^state=active^user.active=true", fields="user.user_name,role.name", limit=500) - Group the rows by role and by user. Many direct grants of the same role suggest a missing group.
- Check which groups already grant that role:
list_records(table_name="sys_group_has_role", query="role.name=<role>", fields="group.name,role.name,inherits", limit=50)
3. Roles left on inactive or long-absent users
- Roles on deactivated users:
list_records(table_name="sys_user_has_role", query="user.active=false^state=active", fields="user.user_name,role.name,inherited", limit=500) - Active users who have not logged in for 90 days, and active users who have never logged in:
list_records(table_name="sys_user", query="active=true^last_login_timeRELATIVELT@dayofweek@ago@90", fields="user_name,last_login_time", limit=500) list_records(table_name="sys_user", query="active=true^last_login_timeISEMPTY", fields="user_name", limit=500) - Cross-check the users from step 2 against their roles (workflow 1, filtered by
user.user_name). Integration and service accounts may never log in interactively, so confirm what an account is before calling it stale.
4. Explain a denial or an incomplete answer
Progress checklist:
- [ ] Capture the exact status and message
- [ ] Classify it with references/access-errors.md
- [ ] Check the caller's own roles
- [ ] Say what is and isn't assessable, and the next step
- Take the status code and the message text exactly as returned; the message names the mechanism.
- Classify it with
references/access-errors.md. - Check the caller's roles with
get_current_user(). It lists direct grants; inherited roles come through groups. - For "why can't user X see record Y": read X's roles and groups (workflow 1 filtered to that user), then explain from the role side using
references/acl-evaluation.md. The ACL rules themselves needadmin. Without them, say the rule-level answer is not assessable with this identity, and point an admin to ServiceNow's Access Analyzer, or to the Access Analysis agent where it is licensed.
5. Join through dot-walks
A dot-walk (group.name, user.department.name) reads a field of the referenced record in the same call. Use dot-walks in fields= and query= instead of reading two or three tables and joining them by sys_id yourself.
Progress checklist:
- [ ] Start from the table that holds the link: a membership or a grant
- [ ] Put the dot-walked fields in fields= and the conditions in query=
- [ ] Count people, not rows, when the question is "how many people"
- [ ] Check empty and missing dot-walked values before reporting
- A team roster, in one call. Each row is one membership, with group and person fields read through the references:
Droplist_records(table_name="sys_user_grmember", query="group.name=<group>^user.active=true", fields="group.name,user.user_name,user.name,user.active,user.department.name", limit=200, order_by="user.name")^user.active=trueto see deactivated users who are still members (workflow 3). - Role holders with their groups. First the groups that grant the role, then all their members in one call:
Filter on thelist_records(table_name="sys_group_has_role", query="role.name=<role>^group.active=true", fields="group,group.name,inherits", limit=100) list_records(table_name="sys_user_grmember", query="groupIN<group_sys_id>,<group_sys_id>^user.active=true", fields="group.name,user.user_name,user.active", limit=500, order_by="group.name")groupsys_ids, not on group names: a name can hold a comma, andINsplits on commas. Direct holders are theinherited=falserows of workflow 2. An inherited grant with no matching group came through a role that contains this one. - How many distinct people hold a role:
Each group in the result is one person, so the number of groups is the number of people. A plain count (the same call withoutaggregate_records(table_name="sys_user_has_role", query="role.name=<role>^state=active", group_by="user")group_by) counts grants, not people. One person can hold the same role directly and through several groups, and each grant is its ownsys_user_has_rolerow: on a Brazil instance, one user helditilin two active rows, one direct and one inherited.display_value="all"shows user names next to the sys_ids. Ifaggregate_recordsis refused, list the rows withfields="user"and count the distinct values. Don't count people with an RLQUERY onsys_user: the conditions inside the block were ignored, so it counted every user with any role. - Know the limit: a dot-walk reads only what this identity can read.
- A field that an ACL hides, or a name that doesn't exist, is missing from every row.
list_recordsnames it in itswarning, also when it appears only inquery=. - A referenced record that the identity can't read gives an empty value, or leaves the dot-walked key out of the row. Observed:
role.namecame back empty, or not at all, onadmingrants, whilerole.name=adminstill matched them. When every row leaves it out, thewarningnames the dot-walk and says the condition may still have applied: compare against a value that can't match (role.name=no_such_role) to tell. Report an empty dot-walked value as "not readable or not set", and add the reference itself (role,group,user) tofields=: its sys_id still comes back.
- A field that an ACL hides, or a name that doesn't exist, is missing from every row.
Tips
- A page can hold fewer rows than
limiteven when more readable records exist: the Table API applies the limit before ACLs remove rows. Keep paging withoffsetuntil a page comes back empty. - Role changes take effect at the user's next session, so a fresh grant may not show in that user's current denials.
- Compare counts before trusting a filter. A condition on a field the identity can't read, or an operator ServiceNow doesn't recognise, is ignored rather than rejected, so the "filtered" result equals the unfiltered one.
aggregate_recordscan count rows thatlist_recordswon't return. A count above the rows you can list means row-level ACLs are hiding records.list_recordsandlist_cicheck the fields you filter on inquery=as well as those infields=: if one is hidden or misspelled, the warning names it. A dot-walk inquery=is checked whole only when you passfields=.- Never read ACL
scriptorconditionbodies, or any field that can hold credentials, even with an admin identity. Names and counts answer hygiene questions. - Treat the review as read-only. Recommend role removals; don't make them.
Files (mcp-server-servicenow)
-
references
-
access-errors.md 5.6 KB
Loading… -
acl-evaluation.md 5.2 KB
Loading…
-
-
SKILL.md 10.6 KB
--- name: analyzing-access description: "Reviewing who holds which ServiceNow roles and explaining access denials. Lists admin and security_admin holders, roles granted directly instead of through groups, roles left on inactive or long-absent users, and diagnoses 401/403 errors, empty results and missing fields. Joins users, groups and roles through dot-walks: team rosters, role holders with their groups, how many people hold a role. Use when the user asks who has admin, a role or access review, least privilege, user or group hygiene, who is in a group, why a query returned nothing, why a field is missing, 'why did I get a 403', 'why can't user X see Y', or ACLs." license: MIT metadata: author: jschuller version: "2.1.0" io.github.jschuller/servicenow-roles: "itil snc_read_only" io.github.jschuller/servicenow-tables: "sys_user_has_role sys_user_grmember sys_group_has_role sys_user sys_user_group" --- # Analyzing ServiceNow Access Two jobs: review role and group hygiene across users, and explain why a call was denied or came back incomplete. Everything here is read-only. See `references/access-errors.md` for the denial messages and what each one means, and `references/acl-evaluation.md` for how ServiceNow decides access. ## Tables and roles | Table | What it answers | Readable with | |-------|-----------------|---------------| | `sys_user_has_role` | Which user holds which role, directly or inherited | `itil` (all users' rows); `snc_read_only` alone gets 403 | | `sys_user_grmember` | Group membership; group names come from `sys_user_group` through `group.name` | `itil` | | `sys_group_has_role` | Which roles a group grants | `itil` | | `sys_user` | `active`, `last_login_time` | `snc_read_only` | | `sys_security_acl` | The ACL rules themselves | `admin` / `security_admin` only: 403 for least-privilege identities | Role names come through dot-walks (`role.name`). The role table itself (`sys_user_role`) usually hides some or all of its rows from least-privilege identities, so `role.name` can come back empty (observed for `admin` and `security_admin`) while a filter on `role.name=admin` still matches. Workflow 5 covers dot-walks and their limits. ## When access is denied - **403** on a table: not assessable with this identity. Say so, name the table, and move on; don't guess. - **0 rows** or **fields missing from every row** (`list_records` adds a `warning`): possibly hidden by an ACL, not proof that nothing exists. - **401 under API-key auth** on aggregates or single-record reads: a REST API access policy doesn't cover that API; table reads still work. ## Workflows ### 1. Who holds privileged roles **Progress checklist:** ``` - [ ] List active admin and security_admin grants - [ ] Flag inactive users and stale logins among them - [ ] Separate direct grants from group grants - [ ] Report counts and the accounts to review ``` 1. List the grants, with enough user context to judge each one: ``` list_records(table_name="sys_user_has_role", query="role.nameINadmin,security_admin^state=active", fields="user.user_name,user.active,user.last_login_time,role,role.name,inherited", limit=200) ``` If `role.name` comes back empty, tell the two roles apart by the `role` sys_id, or run the query once per role. 2. A row with `inherited=false` is a direct grant. An inherited row came through a group or through a role that contains this one. To find the group, intersect the user's groups with the groups that grant the role (workflow 2, step 3): ``` list_records(table_name="sys_user_grmember", query="user.user_name=<user>", fields="group.name", limit=100) ``` `granted_by` still names the group on some instances, but ServiceNow has deprecated it, so don't rely on it. 3. Report the holder count per role, then the accounts to review first: inactive users, users with no recent login, and direct grants. ### 2. Roles granted outside groups ServiceNow recommends granting roles through groups, so that moving a person between teams moves their access. 1. List direct grants on active users: ``` list_records(table_name="sys_user_has_role", query="inherited=false^state=active^user.active=true", fields="user.user_name,role.name", limit=500) ``` 2. Group the rows by role and by user. Many direct grants of the same role suggest a missing group. 3. Check which groups already grant that role: ``` list_records(table_name="sys_group_has_role", query="role.name=<role>", fields="group.name,role.name,inherits", limit=50) ``` ### 3. Roles left on inactive or long-absent users 1. Roles on deactivated users: ``` list_records(table_name="sys_user_has_role", query="user.active=false^state=active", fields="user.user_name,role.name,inherited", limit=500) ``` 2. Active users who have not logged in for 90 days, and active users who have never logged in: ``` list_records(table_name="sys_user", query="active=true^last_login_timeRELATIVELT@dayofweek@ago@90", fields="user_name,last_login_time", limit=500) list_records(table_name="sys_user", query="active=true^last_login_timeISEMPTY", fields="user_name", limit=500) ``` 3. Cross-check the users from step 2 against their roles (workflow 1, filtered by `user.user_name`). Integration and service accounts may never log in interactively, so confirm what an account is before calling it stale. ### 4. Explain a denial or an incomplete answer **Progress checklist:** ``` - [ ] Capture the exact status and message - [ ] Classify it with references/access-errors.md - [ ] Check the caller's own roles - [ ] Say what is and isn't assessable, and the next step ``` 1. Take the status code and the message text exactly as returned; the message names the mechanism. 2. Classify it with `references/access-errors.md`. 3. Check the caller's roles with `get_current_user()`. It lists direct grants; inherited roles come through groups. 4. For "why can't user X see record Y": read X's roles and groups (workflow 1 filtered to that user), then explain from the role side using `references/acl-evaluation.md`. The ACL rules themselves need `admin`. Without them, say the rule-level answer is not assessable with this identity, and point an admin to ServiceNow's Access Analyzer, or to the Access Analysis agent where it is licensed. ### 5. Join through dot-walks A dot-walk (`group.name`, `user.department.name`) reads a field of the referenced record in the same call. Use dot-walks in `fields=` and `query=` instead of reading two or three tables and joining them by sys_id yourself. **Progress checklist:** ``` - [ ] Start from the table that holds the link: a membership or a grant - [ ] Put the dot-walked fields in fields= and the conditions in query= - [ ] Count people, not rows, when the question is "how many people" - [ ] Check empty and missing dot-walked values before reporting ``` 1. A team roster, in one call. Each row is one membership, with group and person fields read through the references: ``` list_records(table_name="sys_user_grmember", query="group.name=<group>^user.active=true", fields="group.name,user.user_name,user.name,user.active,user.department.name", limit=200, order_by="user.name") ``` Drop `^user.active=true` to see deactivated users who are still members (workflow 3). 2. Role holders with their groups. First the groups that grant the role, then all their members in one call: ``` list_records(table_name="sys_group_has_role", query="role.name=<role>^group.active=true", fields="group,group.name,inherits", limit=100) list_records(table_name="sys_user_grmember", query="groupIN<group_sys_id>,<group_sys_id>^user.active=true", fields="group.name,user.user_name,user.active", limit=500, order_by="group.name") ``` Filter on the `group` sys_ids, not on group names: a name can hold a comma, and `IN` splits on commas. Direct holders are the `inherited=false` rows of workflow 2. An inherited grant with no matching group came through a role that contains this one. 3. How many distinct people hold a role: ``` aggregate_records(table_name="sys_user_has_role", query="role.name=<role>^state=active", group_by="user") ``` Each group in the result is one person, so the number of groups is the number of people. A plain count (the same call without `group_by`) counts grants, not people. One person can hold the same role directly and through several groups, and each grant is its own `sys_user_has_role` row: on a Brazil instance, one user held `itil` in two active rows, one direct and one inherited. `display_value="all"` shows user names next to the sys_ids. If `aggregate_records` is refused, list the rows with `fields="user"` and count the distinct values. Don't count people with an RLQUERY on `sys_user`: the conditions inside the block were ignored, so it counted every user with any role. 4. Know the limit: a dot-walk reads only what this identity can read. - A field that an ACL hides, or a name that doesn't exist, is missing from every row. `list_records` names it in its `warning`, also when it appears only in `query=`. - A referenced record that the identity can't read gives an empty value, or leaves the dot-walked key out of the row. Observed: `role.name` came back empty, or not at all, on `admin` grants, while `role.name=admin` still matched them. When every row leaves it out, the `warning` names the dot-walk and says the condition may still have applied: compare against a value that can't match (`role.name=no_such_role`) to tell. Report an empty dot-walked value as "not readable or not set", and add the reference itself (`role`, `group`, `user`) to `fields=`: its sys_id still comes back. ## Tips - A page can hold fewer rows than `limit` even when more readable records exist: the Table API applies the limit before ACLs remove rows. Keep paging with `offset` until a page comes back empty. - Role changes take effect at the user's next session, so a fresh grant may not show in that user's current denials. - Compare counts before trusting a filter. A condition on a field the identity can't read, or an operator ServiceNow doesn't recognise, is ignored rather than rejected, so the "filtered" result equals the unfiltered one. - `aggregate_records` can count rows that `list_records` won't return. A count above the rows you can list means row-level ACLs are hiding records. - `list_records` and `list_ci` check the fields you filter on in `query=` as well as those in `fields=`: if one is hidden or misspelled, the warning names it. A dot-walk in `query=` is checked whole only when you pass `fields=`. - Never read ACL `script` or `condition` bodies, or any field that can hold credentials, even with an admin identity. Names and counts answer hygiene questions. - Treat the review as read-only. Recommend role removals; don't make them.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.