UV-37 - Document UI flows, roles, and audit logs

docs/security/audit-logs.md

@@ -0,0 +1,182 @@
+---
+id: audit-logs
+title: Audit Logs
+sidebar_position: 2
+---
+
+Audit logs provide visibility into security-relevant and administrative actions
+performed within Cube AI. They help administrators and operators monitor
+activity, investigate issues, and support compliance and accountability
+requirements.
+
+---
+
+## Audit Logs Overview
+
+Audit logs record important events that occur within the Cube AI system,
+particularly those related to:
+
+- User activity
+- Domain-level changes
+- Access control and security-sensitive operations
+
+Audit logging is **domain-scoped**, meaning events are associated with the domain
+in which they occurred.
+
+---
+
+## What Is Recorded
+
+Depending on configuration and permissions, audit logs may include events such as:
+
+- User login and logout activity  
+- Domain creation or deletion  
+- Changes to domain membership  
+- Role assignments or updates  
+- Administrative actions performed through the UI  
+- Security-related configuration changes  
+- Model interactions and inference requests  
+
+Each audit log entry typically captures:
+
+- The type of action performed  
+- The user who performed the action  
+- The affected resource or domain  
+- A timestamp of when the action occurred  
+
+---
+
+## TEE Attestation and Attested mTLS Events
+
+For model workloads running inside a **Trusted Execution Environment (TEE)**,
+Cube AI establishes secure connections using **attested mutual TLS (mTLS)**.
+
+These secure interactions are recorded in audit logs and provide
+cryptographic traceability of confidential model execution.
+
+The following events may be captured:
+
+- Attested mTLS handshake between the Cube AI proxy and the TEE agent  
+- Verification of TEE attestation evidence  
+- Secure session establishment for LLM inference requests
+
+All attested TLS handshakes are recorded as audit events.
+
+These events include metadata about:
+
+- TLS version  
+- Cipher suite  
+- Attestation verification status  
+- Attestation nonce  
+- Secure session metadata  
+
+Audit logs also allow viewing the **attestation report** associated with
+each verified TEE interaction.
+
+These records provide verifiable evidence that model inference was executed
+within a trusted and integrity-verified execution environment.
+
+### Example: Attested LLM Request in Audit Logs
+
+The Audit Logs page displays attestation status for each model interaction.
+
+![Audit logs with attested LLM requests](/img/ui/audit-tee-attestation.png)
+
+Selecting an event opens detailed attestation information, including
+secure handshake metadata and the attestation report.
+
+![Audit log event details with attestation report](/img/ui/audit-tee-attestation-details.png)
+
+---
+
+## Accessing Audit Logs
+
+Audit logs are accessible through the Cube AI UI to users with sufficient
+permissions.
+
+Access to audit logs is restricted to authorized roles to ensure sensitive
+information is not exposed to unauthorized users.
+
+![Audit logs page](/img/ui/audit-logs.png)
+
+---
+
+## Audit Logs in the UI
+
+Audit logs are available from the Cube AI user interface within the context of an
+active domain.
+
+Depending on system activity and configuration, the audit log table may initially
+appear empty until relevant events occur, such as:
+
+- Model interactions (LLM requests)  
+- Role or membership changes  
+- Administrative or security-related actions  
+- TEE attestation and secure handshake events  
+
+This behavior is expected and does not indicate an error.
+
+---
+
+## Using Audit Logs
+
+Audit logs can be used to:
+
+- Review recent administrative activity  
+- Investigate unexpected behavior or configuration changes  
+- Track access-related events  
+- Verify secure model execution within a TEE  
+- Support security reviews and incident analysis  
+
+Audit logs provide an immutable record of events and are intended for
+observability rather than real-time monitoring.
+
+---
+
+## Audit Logs and Roles
+
+Visibility into audit logs depends on the user’s role within a domain.
+
+Typically:
+
+- Administrative roles can view audit logs  
+- Standard users may not have access to audit information  
+
+For more details on role-based permissions, see:  
+👉 **Security & Access → Roles and Access Control**
+
+---
+
+## Audit Logs and Domain Context
+
+All audit log entries are associated with a specific domain.
+
+When switching domains:
+
+- The visible audit logs change accordingly  
+- Only events related to the active domain are shown  
+
+This ensures isolation and clarity when managing multiple domains.
+
+---
+
+## Security and Compliance
+
+Audit logging is a key component of Cube AI’s security posture.
+
+By maintaining a record of critical actions, audit logs help:
+
+- Detect misuse or misconfiguration  
+- Support forensic analysis  
+- Demonstrate accountability and operational transparency  
+- Provide traceability for confidential LLM workloads executed inside a TEE  
+
+---
+
+## Next Steps
+
+To understand how permissions affect access to audit information, review:  
+👉 **Security & Access → Roles and Access Control**
+
+For domain-level workflows, see:  
+👉 **UI → Domains**

docs/security/roles-and-access-control.md

@@ -0,0 +1,179 @@
+---
+id: roles-and-access-control
+sidebar_position: 1
+title: Roles and Access Control
+---
+
+Cube AI uses role-based access control (RBAC) to manage what users can
+see and do within a domain. Roles define permissions at the domain level
+and ensure that actions are performed only by authorized users.
+
+## Role-Based Access Control Overview
+
+Access control in Cube AI is **domain-scoped**.
+
+This means that:
+
+- Users can belong to one or more domains
+- A user may have different roles in different domains
+- Permissions apply only within the currently active domain
+
+Roles determine which UI features and actions are available to a user.
+
+## Roles in Cube AI
+
+Each domain includes a default **Admin** role, which has full control
+over domain resources. The domain creator is automatically assigned the
+Admin role.
+
+In addition to the default role, administrators can create custom roles
+with fine-grained permissions.
+
+## Managing Roles
+
+Roles can be created and customized within each domain.
+
+To manage roles:
+
+1. Open a domain.
+2. Navigate to **Roles** in the left-side menu.
+
+![Roles list page](/img/ui/roles.png)
+
+The Roles page displays:
+
+- Role name
+- Created by
+- Created at
+- Updated by
+- Updated at
+
+### Creating a Domain Role
+
+To create a new role:
+
+1. Click **Create**.
+2. Enter a **Role name**.
+3. Select one or more **Actions** (permissions).
+4. Optionally assign existing **Members**.
+5. Click **Create**.
+
+![Create domain role modal](/img/ui/create-role.png)
+
+### Role Permissions (Actions)
+
+Each role is assigned a set of actions (permissions) that define what
+operations users can perform within a domain.
+
+Actions cover domain administration, model usage, audit log access, and other Cube-specific capabilities exposed in the UI.
+
+Available actions are displayed directly in the role creation and editing UI.
+The list of actions is Cube-specific and may evolve between releases.
+
+![Role actions selection](/img/ui/role-actions.png)
+
+Administrators can select one or more actions when creating or editing
+a role. The selected actions determine which UI sections and operations
+are accessible to users assigned to that role.
+
+### Editing a Role
+
+Once created, roles can be modified from their respective role pages.
+
+Users with sufficient permissions can:
+
+- Update the role name
+- Add or remove actions
+- Assign or remove members
+
+Role updates take effect immediately within the domain.
+
+![Domain role details page](/img/ui/role-details.png)
+
+## Inviting Domain Members
+
+Domain administrators can invite users to join a domain.
+
+1. Open a domain.
+2. Navigate to **Invitations**.
+3. Click **Send Invitation**.
+
+![Invitations page](/img/ui/invitations.png)
+
+### Sending an Invitation
+
+1. Select a user.
+2. Select a domain role.
+3. Click **Send**.
+
+![Send invitation modal](/img/ui/invite-member.png)
+
+After sending:
+
+- The invitation appears in the list
+- Its status is set to **Pending**
+- The user must accept the invitation before gaining access
+
+## Accepting an Invitation
+
+An invited user must accept the invitation before becoming a domain
+member.
+
+Acceptance is performed either via an email confirmation link or within
+the UI, depending on deployment configuration.
+
+![Accept invitation screen](/img/ui/accept-invite.png)
+
+Once accepted:
+
+- The user becomes a member of the domain
+- The assigned role is applied immediately
+
+## Assigning Roles to Members
+
+Administrators can assign roles directly from the **Members** section.
+
+1. Navigate to **Members**.
+2. Click **Assign User**.
+3. Select a user and role.
+4. Click **Assign**.
+
+![Members page](/img/ui/members.png)
+
+![Assign user modal](/img/ui/assign-user.png)
+
+## Removing Members
+
+To remove a member from a domain:
+
+1. Navigate to **Members**.
+2. Locate the user.
+3. Use the available actions to remove the member.
+
+Removing a member immediately revokes access to domain resources.
+
+## UI Behavior Based on Roles
+
+The Cube AI UI adapts based on the active user's role.
+
+Depending on permissions:
+
+- Certain navigation items may be hidden
+- Some actions may be disabled or unavailable
+- Administrative sections may only be visible to authorized users
+
+![Domain members and role assignment](/img/ui/domain-members-roles.png)
+
+## Auditing Role-Related Events
+
+Changes to domain membership and roles may be recorded as
+security-relevant events.
+
+For details on how such events are tracked, see: 👉 **Security & Access → Audit Logs**
+
+## Next Steps
+
+To understand how access-related actions are monitored, continue with:
+👉 **Security & Access → Audit Logs**
+
+For domain workflows, see: 👉 **UI → Domains**