Added support for roles and role management.

[pagbabian-splunk]

Related Issue: #1600

Description of changes:

Added support for roles and role management.

Although we have been describing users as users or roles in many contexts, we don't have explicit support for roles (and there was no Role object). This PR adds IAM Role to existing IAM classes, group_management and authorize_session, adds a role_management class and user_management class which combines user_access_management and account_change. The latter two classes are deprecated. Activities are updated in the modified classes to support IAM Roles.

Where there were _result objects they were replaced by updated_ objects, and where Update activities were missing they were added.

IAM classes that had activities against a target, such as user or group such as attaching policies or privileges now consistently use arrays for the attached or assigned objects, so that more than one IAM Role, more than one Policy etc. can be assigned or removed in a single event.

An IAM Role object includes key attributes from the User object but none of the personal information that would not apply to a Role. As an example, a Role object can have a Session for temporary credentials that can expire with the session. A Policy object is available for attaching a policy to a role, as well as privileges as we have with User Management.

Because there are cross-account roles, the IAM Role object can have a different account (via an Account) object than the actor's account (e.g. via the User Management class).

[github-actions]

Schema Description Review

Automated suggestions for improving description clarity for LLM consumption. These are advisory — not required changes.

Based on my comparison with the previous review, here's my updated assessment:

Previous Issues Status

❌ Description issue remains - The uid_alt description in the iam_role object still incorrectly mentions "user identifier" when this attribute is for a role.

✅ CHANGELOG conflicts resolved - The git merge conflicts have been fixed.

Suggestions

1. Object: iam_role
   Attribute: uid_alt
   Issue: Description mentions "user identifier" when this is for a role
   Current: "The alternate user identifier. For example, the Active Directory role GUID or the associated LDAP group DN."
   Suggested: "The alternate role identifier. For example, the Active Directory role GUID or the associated LDAP group DN."

Anti-Pattern Findings

All previously identified anti-patterns persist unchanged:

1. Pattern: Cross-Attribute Inconsistency
   Object/Class: iam_role
   Attribute: name
   Issue: The name attribute uses string_t type in the iam_role object, while the same attribute name uses different types across the schema (file_name_t, process_name_t, username_t). This creates programmatic inconsistency.
   Recommendation: Consider using string_t consistently for role names, or create a distinct attribute name like role_name if the semantic difference warrants a specialized type.

2. Pattern: Cross-Attribute Inconsistency
   Object/Class: iam_role
   Attribute: uid
   Issue: The uid attribute uses string_t type in the iam_role object, while the same attribute name uses resource_uid_t type in other objects. This inconsistency makes the schema harder to consume programmatically.
   Recommendation: Standardize on either string_t or resource_uid_t for all uid attributes, or use distinct attribute names to reflect semantic differences.

3. Pattern: Cross-Attribute Inconsistency
   Object/Class: iam_role
   Attribute: uid_alt
   Issue: The uid_alt attribute uses string_t type in the iam_role object, while the same attribute name uses resource_uid_t type in other objects.
   Recommendation: Align the type choice with the broader schema pattern or use semantically distinct attribute names.

Summary

The PR has resolved the CHANGELOG formatting issues but the main description fix for uid_alt remains unaddressed. All structural anti-patterns identified in the previous review persist, creating ongoing type inconsistencies across the schema.

[floydtree]

Also, do we not want to add this new object to the actor object?

[pagbabian-splunk]

Good comments all - let me take a crack at an update with them included.

[pagbabian-splunk]

Also, do we not want to add this new object to the actor object?

Added iam_role to actor as well.

[github-actions]

Schema Anti-Pattern Check

Automated structural analysis for common schema design anti-patterns. These are advisory — not required changes.

Warnings

1. type-inconsistency — iam_role.name
name has different types across objects: file_name_t (1 object), process_name_t (2 objects), string_t (90 objects), username_t (1 object). Inconsistent types for the same attribute name make the schema harder to consume programmatically.

   Suggestion: Use distinct attribute names for different types, or standardize on a single type across all objects.

2. type-inconsistency — iam_role.uid
uid has different types across objects: resource_uid_t (4 objects), string_t (87 objects). Inconsistent types for the same attribute name make the schema harder to consume programmatically.

   Suggestion: Use distinct attribute names for different types, or standardize on a single type across all objects.

3. type-inconsistency — iam_role.uid_alt
uid_alt has different types across objects: resource_uid_t (4 objects), string_t (11 objects). Inconsistent types for the same attribute name make the schema harder to consume programmatically.

   Suggestion: Use distinct attribute names for different types, or standardize on a single type across all objects.

4. tautological-description — dictionary.updated_role
updated_role description "The updated role. See specific usage." is essentially restating the attribute name. Descriptions should provide meaning beyond what the name already conveys.

   Suggestion: Add context about what this attribute represents, when it applies, or how it should be populated.

5. tautological-description — dictionary.updated_group
updated_group description "The updated group. See specific usage." is essentially restating the attribute name. Descriptions should provide meaning beyond what the name already conveys.

   Suggestion: Add context about what this attribute represents, when it applies, or how it should be populated.

6. tautological-description — dictionary.updated_user
updated_user description "The updated user. See specific usage." is essentially restating the attribute name. Descriptions should provide meaning beyond what the name already conveys.

   Suggestion: Add context about what this attribute represents, when it applies, or how it should be populated.

Summary: 6 warning(s), 0 informational finding(s)

[pagbabian-splunk]

I'm going to experiment with a separate Role Management class rather than adding to the Account Change class. Most of that class has to do with changes to a User although it is also where a User is created.

Since roles are first class citizens of most RBAC based products, the lifecycle of a role, and the changes to a role itself likely belong in a separate class. Assigning roles to users and groups given they already exist can still be done in Group Management and User Access Management.

Entity Management can be reserved for lifecycle and state changes of a Managed Entity (via entity_result) which can be devices, policies, orgs etc. Also user but none of them lists.

[Aniak5]

Great work! This is a huge improvement, and I love the prescriptive descriptions!

I've addressed all the changes requested - I don't know why they haven't resolved.

[dfirence]

This is useful for many products. I want to understand if it will accommodate my use case for enterprise network devices like NXOS where the group management and privileges assigned are classically considered "permissive" - i.e., "permit/deny ..."

This model follows not just a right (read/write), but also follows commands the group can execute -- like sudo command assignments:

[config-role]$ rule 1 permit command {{ command_name_here }}

How would I take my Syslog telemetry and encode these types of group changes given this PR?