deft/notes/cisco_custom_roles.org

Custom Roles

Current state

Listing Roles (already by org)

GET /iroh/profile/roles

Provide a data structure with describing all roles for an Org:

• 3 roles for XDR (admin, user, sat)
• 2 roles for SX (admin, user)

⚠ Role ≠ Permissions

The role associated to a user do not necessarily matches the user permission.

The role is only one of the component to use to determine a token or even a user permissions. The permissions are represented by scopes which are computed using:

• the user role
• the org properties (activated or not, XDR or not etc…)
• entitlements (not in use but will probably be the case in the future)

⚠ Role ≠ Permissions (Tokens)

• the user scopes
• as well as the client scopes
• as well as the scopes requested during the OAuth2 authorization flow

Current response for an XDR-enabled org

GET /iroh/profile/roles
{:admin {:english {:only-role-name "administrator",
                   :adjective "an",
                   :only-role-name-capitalized "Administrator",
                   :english-role-name "an administrator"},
         :role-name "Administrator",
         :role-id "admin",
         :role-description "An admin of users.",
         :visibility "public"},
 :sat {:english {:only-role-name "security analyst",
                 :adjective "a",
                 :only-role-name-capitalized "Security Analyst",
                 :english-role-name "a security analyst"},
       :role-name "Security Analyst",
       :role-id "sat",
       :role-description
       "No account admin. SXO read only + run existing workflows.",
       :visibility "public"},
 :user {:english {:only-role-name "incident responder",
                  :adjective "an",
                  :only-role-name-capitalized "Incident Responder",
                  :english-role-name "an incident responder"},
        :role-name "Incident Responder",
        :role-id "user",
        :role-description
        "This is the closest to current user role:- no account administration- cannot create/change modules- SXO read only, but can run and edit workflows",
        :visibility "public"}}

Current response for an SX-only org

GET /iroh/profile/roles
{:admin {:english {:only-role-name "admin",
                     :adjective "an",
                     :only-role-name-capitalized "Admin",
                     :english-role-name "an admin"},
           :role-name "Admin",
           :role-id "admin",
           :role-description "An admin of users.",
           :visibility "public"},
   :user {:english {:only-role-name "user",
                    :adjective "a",
                    :only-role-name-capitalized "User",
                    :english-role-name "a user"},
          :role-name "User",
          :role-id "user",
          :role-description "A standard user.",
          :visibility "public"}}

What the API already support

• list all roles for every Org
• change the role of a user
• support roles during invitation and Org access request
• expose a permissions endpoint to check permission access independently of the role
• read/write access restriction
• fine grained resource target in the scopes enrich → enrich/observables/observe:write

What the API does not support

• No support for create+update but not delete.
• No support for multiple roles

• No support for custom role creation (obviously)

  • No scopes API for roles

Expected Changes

New API: (exhaustive scopes list)

Exhaustive list of scopes as a forest structure

[{:scope "global-intel"
  (optional :description) ,,,
  :accessors ["read"]
  :sub-scopes [{:scope "global-intel/incident"
                :accessors ["read"]}
               {:scope "global-intel/sighting"
                :accessors ["read"]}
               ,,,]}
 {:scope "private-intel"
  (optional :description) ,,,
  :accessors ["rw","read","write"]
  :sub-scopes [{,,,}]}]

New API (maybe?)

Expose only a subset of scopes aliases pre-negociated with UX/UI/Doc team:

[{:scope-alias "threat-hunt"
  :scopes ["enrich/observables/observe:read","inspect","investigation"]
  :description ,,,,}
 {:scope-alias "incidents"
  :scopes ["private-intel","global-intel:read"]
  :description ,,,}
 ,,, ]

New API: CRUD+Search

API to manage new custom roles

(s/defschema NewRole
  {:role-name        s/Str
   :role-description s/Str
   :provided-scopes  Scopes})

(s/defschema Role
  (st/merge NewRole
            {:id s/Str
             :created-at Date
             :updated-at Date}))

Existing APIs

The GET /iroh/profile/roles will look like today + added the new custom roles that will look like:

{:admin ...
 :sat ...
 :user ...
 :role-d394db9e-613f-11ee-aff9-325096b39f47
 {:role-name "My Company Custom Role"
  :role-description "This is a role that is read only except for workflows"
  :role-id :role-d394db9e-613f-11ee-aff9-325096b39f47
  :visibility "org"
  :associated-scopes #{"inspect:read" "ao" "insights:read" "profile:read"}}

 :role-8891b9f4-6140-11ee-8e1a-325096b39f47
 {:role-name "Manager"
  :role-description "Only for Sam who manage this team but should not directly act"
  :role-id :role-8891b9f4-6140-11ee-8e1a-325096b39f47
  :visibility "org"
  :associated-scopes #{"inspect:read" "ao:read" "insights:read" "profile:read" "users" "profile"}}}

• visibility; org for custom, public for global.
• associated-scopes; only for role management UI

Introduce sub-accessors (maybe?)

Today: read, write

inspect = inspect:rw
        = inspect:read + inspect:write.

Tomorrow: introduce read:get, read:search, write:create, write:update, write:delete, write:execute.

Equivalence of new accessors

rw = read + write

read  = read:get      # GET by id
      + read:search   # GET/POST search entities
write = write:create  # POST create new entity
      + write:update  # PUT/PATCH
      + write:delete  # DELETE
      + write:execute # POST to trigger action

Most important points

• Dynamic role ids. Must use the API

  • when you call /iroh/profile/whoami
  • when you look into the JWT
  • note: potentially a list of roles!
• associated-scopes field only useful for the Role Management UI.
• Use /iroh/profile/permissions
• can also use scopes claim if present

Multiple Roles

Expect the role to be a sorted comma separated role ids like; admin,role-344,sat,user (which would be equivalent to admin here) in the tokens and not a list to prevent breaking changes. But it will probably be a list in the /whoami response.