Enhancements to Authorization class

[odianosen]

Proposal to update Authorization class with the following changes:

• Add activities for revoking privileges and revoking group.
• Add resource to Authorization class with a constraint that at least one of dst_endpoint or resource is required.

PR #531

[rroupski]

Can you provide examples of logs with resource but no dst_endpoint?

[odianosen]

Most SaaS audit logs provide what resource was changed, but not the destination endpoint for the change. A specific example can be a sample raw log from Asana for authorization:

{
      "gid": "1203872644516546",
      "created_at": "2023-02-01T06:23:39.420Z",
      "event_type": "user_workspace_admin_role_changed",
      "event_category": "roles",
      "actor": {
        "actor_type": "user",
        "gid": "12024...2784",
        "name": "The Real Harry Potter",
        "email": "[email protected]"
      },
      "resource": {
        "resource_type": "user",
        "gid": "12033...2551",
        "name": "",
        "email": "[email protected]"
      },
      "details": {
        "old_value": "member",
        "new_value": "domain_admin",
        "group": {
          "resource_type": "workspace",
          "gid": "12023...6660",
          "name": "9038507.asanatest1"
        }
      },
      "context": {
        "context_type": "web",
        "client_ip_address": "73.169.152.46",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:102.0) Gecko/20100101 Firefox/102.0"
      }
    }

The target resource is provided (workspace), without a dst endpoint.

[rroupski]

This example looks like an entity management event to me. BTW, the resource object does not have an email attribute, or any other resource data attributes.

[odianosen]

This is a raw log, before any OCSF normalization. The resource object here is purely coincidental. This audit log reports an authorization event - a user was granted heightened access (admin role) to a resource by an actor. I don't think its simply entity management.

[rroupski]

BTW, we should split the issue/PR is two separate items:

1. Add activities for revoking privileges and revoking group -- this one is no breaking and it makes sense
2. Add resource to Authorization class with a constraint that at least one of dst_endpoint or resource is required -- this one is a breaking change and IMO it requires more discussions

[odianosen]

Fair enough, but why is no 2 breaking? dst_endpoint is already a required field in Authorization, so existing data already meets this constraint. Help me understand why this constraint is breaking.

[pagbabian-splunk]

Agree on item 1, we need those activities obviously.

However, based on the example, this class, even with item 2 added, would not be able to model the change aspect of the event. In this case above, there is an old role name (member) and a new role name (domain_admin) and we've moved the user from one role to another. There are other systems where a user could have multiple roles. E.g. the user might have a current role PowerUser, and we also assigned the user BackupAdmin. We didn't take away PowerUser.

I'm assuming the user isn't the actor (even though it says actor) as in the example we don't have information about who made the change, just the change of the user's role. And we don't know what the sensitive privileges are, they are assigned to the roles, not to the user. We need to be able to represent that case, assigning privileges to a role, regardless of who is in the role, and we need to generally know who made the change (the actor).

In the proposed class, the Resource is the user so presumably the current role (group) would be part of the User object, but there is no new role/group attribute. If the Resource is the Group, then we don't have the current group, and the User object would have needed to be populated with that information (but it is an array of Groups, unlikely all of the groups would be known, and they may not all be roles).

Also note that a Group object has privileges but a User object does not. The Assign Privileges log event would be unlikely to have all of the Group privileges, but we could add one or more privileges to the group's array from the Authorization class' array of privileges via privileges.

In other words, we need more options in the class:

1. Assign privileges to a User
2. Assign privileges to a Group or Role
3. Revoke privileges of a User
4. Revoke privileges of a Group or Role
5. Add User to a Group or Role (with implied privileges)
6. Remove User from a Group or Role
7. (Maybe Move User from one Group or Role to another - if it is in a single log line like in the example above)

The Resource object has a name for the resource, and a type. With the last update #528 it now has a Group object but no other objects that match with the enum list. Likely should remove it.

5-7 are similar to entity change events, but have authorization implications and so may be better here than in a general Entity Change class.

We might also consider other AuthZ related operations, such as enumerating privileges of a Group/Role or User, enumerating roles of a User.

8. List Privileges of a User or Role
9. List Groups or Roles of a User

So I think there is more to consider.

[odianosen]

I don't disagree with your activities 1-6, but I think that

1. The proposal works well for the example
2. A lot of your points, while valid, can maybe be the focus of a follow up discussion?

This is the general use case for Authorization in this proposal: An actor has assigned/revoked privileges to a user to access a resource/dst_endpoint.

• The user whose role was updated is represented as resource in the example (probably causing confusion in this discussion). This would be modeled to the user attribute (with User type) in the Authorization class.
• I think the role in this example is a proxy for privileges (which is an open-ended string). domain_admin is the newly assigned privilege. It's not as precise as modeling specific role changes, but it makes sense to me.
• The resource in Authorization will instead be pulled from details in the example - where in this case the resource will be a workspace (not a user) (see "resource_type": "workspace" in the example).
• There is no dst_endpoint, hence the proposal for the constraint.
• The person who effected the change (the actor) is represented by the actor attribute in the example. In Authorization class, a corresponding actor is absent, and I think that's a change that I'll include.

To summarize, after adding an actor attribute, the example above would translate to:
(only relevant attributes included)

{
  "category_name": "Audit Activity",
  "class_name": "Authorization",
  "activity_name": "Assign Privileges",
  "actor": {
    "user": {
      "email_addr": "[email protected]",
      "uid": "12024...2784",
      "name": "The Real Harry Potter"
    }
  },
  "user": {
      "email_addr": "[email protected]",
      "uid": "12033...2551",
      "name": ""
    },
  "privileges": ["domain_admin"],  
  "resource": {
    "type_id": "99",
    "type": "Workspace",
    "uid": "12023...6660",
    "name": "9038507.asanatest1"
  }
}

[odianosen]

If we apply your suggestions 1-6, the output would be:

{
  "category_name": "Audit Activity",
  "class_name": "Authorization",
  "activity_name": "Add User to a Group",
  "actor": {
    "user": {
      "email_addr": "[email protected]",
      "uid": "12024...2784",
      "name": "The Real Harry Potter"
    }
  },
  "user": {
      "email_addr": "[email protected]",
      "uid": "12033...2551",
      "name": ""
    },
  "groups": [{
    name: "domain_admin"
  }],    
  "resource": {
    "type_id": "99",
    "type": "Workspace",
    "uid": "12023...6660",
    "name": "9038507.asanatest1"
  }
}

Where groups attribute would replace privileges.

I think 7 is the same as 6 (with maybe an extra optional field for the previous group: prev_group or something). I can't think of any use cases for 8-9.

[pagbabian-splunk]

This is clearer to me. I think our descriptions need to make clear what the 'roles' (no pun intended) of the various attributes are. Privileges are still important though but I wouldn't want to overload them with roles, so adding the groups is the right way to go. In this example, privileges aren't specifically needed as they are behind the roles as groups.

[JasonKeirstead]

I am voting to "support" that a change be made, because right now we can't even encode an authorization grant for an S3 bucket - the current model is too network-centric. I also agree this is not a breaking change.

I think the things brought up in #533 (comment) are other things to consider but they don't actually have to do with the core issue of the request, which is right now we can not model authorization grants to non-networked (normally, cloud) resources.

[odianosen]

+1

[pagbabian-splunk]

I agree on supporting a change, but disagree though with the current proposal details - there are some structural problems even with solving the basic problem, but Odi has some options to consider that are in the right direction.

[JasonKeirstead]

OK i think I understand now, reading the last conversation.

I was only focusing on "Add resource to Authorization class with a constraint that at least one of dst_endpoint or resource is required."

Most of the conversation has been on "Add activities for revoking privileges and revoking group."

We have somewhat fallen victim again to the proposals having too many things in them.

I think we can all agree (I hope) that the first bit, is obvious and non-breaking. That is the part that I vote should just be done, while we continue discussion on the other part.

[pagbabian-splunk]

Yes, agree. I think the new second part looks pretty good now too.

[odianosen]

Based on the conversation above, thoughts on this structure?

{
  "caption": "Authorization",
  "description": "Authorization events report special privileges or groups assigned to a user or user session.",
  "extends": "access_control",
  "name": "authorization",
  "uid": 3,
  "attributes": {
    "activity_id": {
        "1": {
        "description": "Assign privileges to a user or session.",
        "caption": "Assign Privileges to User"
      },
      "2": {
        "description": "Assign groups to a user or session.",
        "caption": "Add User to Groups"
      },
      "3": {
        "description": "Assign privileges to a group or role.",
        "caption": "Assign Privileges to Group"
      },
      "4": {
        "description": "Remove privileges from a user or session.",
        "caption": "Revoke User Privileges"
      },
      "5": {
        "description": "Remove a user or session from groups or roles.",
        "caption": "Remove User from Groups"
      },
      "6": {
        "description": "Remove privileges from a group or role.",
        "caption": "Revoke Group Privileges"
      }
    },
    "actor": {
      "description": "The actor that performed the authorization grant or revocation.",
      "group": "context",
      "requirement": "optional"
    },
    "dst_endpoint": {
      "description": "The Endpoint for which the authorization was targeted.",
      "group": "primary",
      "requirement": "recommended"
    },
    "groups": {
      "description": "The groups or roles that were assigned to the user.",
      "requirement": "recommended"
    },
    "privileges": {
      "description": "The list of privileges assigned to the user, user session, or group.",
      "group": "primary",
      "requirement": "recommended"
    },
    "resource": {
      "description": "The resource that was the target of the authorization change.",
      "group": "primary",
      "requirement": "recommended"
    },
    "session": {
      "description": "The modified user session.",
      "requirement": "optional"
    },
    "user": {
      "description": "The user to which new privileges were assigned.",
      "group": "primary",
      "requirement": "required"
    }
  },
  "constraints": {
    "at_least_one": [
      "dst_endpoint",
      "resource"
    ]
  }
}

[pagbabian-splunk]

Much better. I think this one covers the basics. Do we need to say 'special' privileges or just privileges? Also, for the description of groups I think we need to also include "or the groups to which new privileges were assigned or removed."

[odianosen]

Thanks. PR #531 updated.

Also, for the description of groups I think we need to also include "or the groups to which new privileges were assigned or removed

For completeness, I created another attribute assigned_group as the group to which new privileges are assigned or removed. I think its better not to overload the meaning of groups and to cover the use case of assigning groups to a groups.

Btw, I think an improvement to this class would be the creation of a new object called Principal. This would encapsulate the object to which privileges, groups or roles are assigned. Within Principal would be attributes for user,group and session, and it can be extended in the future with other attributes to which privileges can be assigned (like service for AWS IAM auth grant?). The authorization activities would be simplified to assign/revoke privileges/groups to/from Principal, and won't change as we add new attributes to Principal. But that's for a different proposal, so as not to over-bloat this one.

[odianosen]

After some discussion with @jp-harvey, here's what we arrived at:

{
  "caption": "Authorization",
  "description": "Authorization events report privileges or groups assigned to a user, user session or group.",
  "extends": "access_control",
  "name": "authorization",
  "uid": 3,
  "attributes": {
    "activity_id": {
      "1": {
        "description": "Grant permissions or privileges to a principal.",
        "caption": "Assign Grants"
      },
      "2": {
        "description": "Revoke permissions or privileges from a principal.",
        "caption": "Revoke Grants"
      }
    },
    "actor": {
      "description": "The actor that performed the authorization grant or revocation.",
      "group": "context",
      "requirement": "optional"
    },
    "principal": {
      "description": "The entity to which permissions were granted.",
      "group": "primary",
      "requirement": "required"
    },
    "grants": {
      "description": "The permissions or privileges that were assigned to or revoked from a principal.",
      "group": "primary",
      "requirement": "required"
    },
    "dst_endpoint": {
      "description": "The Endpoint for which the authorization was targeted.",
      "group": "primary",
      "requirement": "recommended"
    },
    "resource": {
      "description": "The resource that was the target of the authorization change.",
      "group": "primary",
      "requirement": "recommended"
    }
  },
  "constraints": {
    "at_least_one": [
      "dst_endpoint",
      "resource"
    ]
  }
}

Proposing 2 new objects:
Principal:

{
  "caption": "Principal",
  "description": "An entity to which permissions were assigned or revoked, such as a user, user session or group.",
  "name": "principal",
  "attributes": {
    "group": {
      "description": "A group to which new privileges, groups or roles were assigned or removed.",
      "requirement": "recommended"
    },
    "session": {
      "description": "A session to which new privileges, groups or roles were assigned or removed.",
      "requirement": "recommended"
    },
    "user": {
      "description": "A user to which new privileges, groups or roles were assigned or removed.",
      "requirement": "recommended"
    }
  },
  "constraints": {
    "at_least_one": [
      "group",
      "user",
      "session"
    ]
  }
}

and Grants :

{
  "caption": "Grants",
  "description": "Permissions or privileges that are granted to or revoked from a principal.",
  "name": "grants",
  "attributes": {
    "assigned_groups": {
      "description": "The list of groups or roles that are granted or revoked.",
      "group": "primary",
      "requirement": "recommended"
    },
    "privileges": {
      "description": "The list of privileges that are granted or revoked.",
      "group": "primary",
      "requirement": "recommended"
    }
  },
  "constraints": {
    "at_least_one": [
      "assigned_groups",
      "privileges"
    ]
  }
}