feat: SDK updates to support platform RBAC (#213)

* feat(models): Add Workspace and Organization models

Introduce new data models for Workspace and Organization in dreadnode/api/models.py. Also updates the Project model to include a 'workspace_id'.

* feat(api): Add methods for Organization and Workspace management

Introduce four new client methods: list_organizations, get_organization, list_workspaces, and get_workspace. These methods handle CRUD-like operations for the newly introduced RBAC-related models.

* feat(sdk): Integrate Organization and Workspace into Dreadnode client

Adds support for specifying default Organization and Workspace via environment variables (DREADNODE_ORGANIZATION, DREADNODE_WORKSPACE) or initialization parameters. The client now includes logic to automatically select an organization and workspace if only one exists, and raises errors for ambiguity or non-existence, enforcing the new RBAC structure.

* feat(api): Implement organization, workspace, and project resolution logic

This commit refactors the initialization logic in `Dreadnode` to automatically resolve or create the current organization, workspace, and project based on configuration or defaults.

The changes include:
* **API Client Enhancements**: Added methods for `create_workspace`, `create_project`, and updated existing `list_projects`, `get_project`, `list_workspaces`, `get_organization`, and `get_workspace` to support filters, pagination (for workspaces), and UUID identifiers.
* **RBAC Resolution**: New private methods (`_resolve_organization`, `_resolve_workspace`, `_resolve_project`, `_resolve_rbac`) handle the full resolution workflow, including default creation for workspaces and projects if they don't exist.
* **Model Updates**: Introduced `WorkspaceFilter`, and `PaginatedWorkspaces` Pydantic models.
* **RunSpan Update**: Renamed `project` attribute to `project_id` in `RunSpan` for clarity, reflecting the use of the ID in traces/spans.
* **Constants**: Added `DEFAULT_WORKSPACE_NAME` and `DEFAULT_PROJECT_NAME`.

This enables a much smoother initialization experience for users, automatically provisioning necessary resources.

* chore: updates to fix typing

* refactor(config): Improve organization, workspace, and project resolution

Introduce robust logic for resolving organization, workspace, and project from configuration, environment variables, or path strings (e.g., 'org/ws/project').

Updates include:

* Add organization/workspace to `DreadnodeConfig`.

* `ApiClient.get_workspace` now optionally accepts `org_id`.

* Project creation now uses 'org_id' in API payload.

* Add `_extract_project_components` to parse project path format.

* Centralize configuration logging with `_log_configuration`.

* Renamed `Workspace.owner_id` to `Workspace.created_by` in models.

* fix: updated regex to handle spaces

* feat(otel): Include SDK version in OTLP User-Agent

* refactor(workspace): remove automatic default workspace creation

* fix(exporter): decode User-Agent bytes and add type hints

Author: briangreunke

dreadnode/api/client.py

@@ -6,6 +6,7 @@
 from datetime import datetime, timezone
 from pathlib import Path
 from urllib.parse import urlparse
+from uuid import UUID
 
 import httpx
 from loguru import logger
@@ -19,6 +20,8 @@
     ExportFormat,
     GithubTokenResponse,
     MetricAggregationType,
+    Organization,
+    PaginatedWorkspaces,
     Project,
     RawRun,
     RawTask,
@@ -34,6 +37,8 @@
     TraceTree,
     UserDataCredentials,
     UserResponse,
+    Workspace,
+    WorkspaceFilter,
 )
 from dreadnode.api.util import (
     convert_flat_tasks_to_tree,
@@ -276,16 +281,47 @@ def list_projects(self) -> list[Project]:
         response = self.request("GET", "/strikes/projects")
         return [Project(**project) for project in response.json()]
 
-    def get_project(self, project: str) -> Project:
+    def get_project(self, project_identifier: str | UUID, workspace_id: UUID) -> Project:
         """Retrieves details of a specific project.
 
         Args:
-            project (str): The project identifier.
+            project (str | UUID): The project identifier. ID, name, or slug.
 
         Returns:
             Project: The Project object.
         """
-        response = self.request("GET", f"/strikes/projects/{project!s}")
+        response = self.request(
+            "GET",
+            f"/strikes/projects/{project_identifier!s}",
+            params={"workspace_id": workspace_id},
+        )
+        return Project(**response.json())
+
+    def create_project(
+        self,
+        name: str | UUID | None = None,
+        workspace_id: UUID | None = None,
+        organization_id: UUID | None = None,
+    ) -> Project:
+        """Creates a new project.
+
+        Args:
+            name (str | UUID | None): The name of the project. If None, a default name will be used.
+            workspace (str | UUID | None): The workspace ID to create the project in. If None, the default workspace will be used.
+            organization (str | UUID | None): The organization ID to create the project in. If None, the default organization will be used.
+
+        Returns:
+            Project: The created Project object.
+        """
+        payload: dict[str, t.Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if workspace_id is not None:
+            payload["workspace_id"] = str(workspace_id)
+        if organization_id is not None:
+            payload["org_id"] = str(organization_id)
+
+        response = self.request("POST", "/strikes/projects", json_data=payload)
         return Project(**response.json())
 
     def list_runs(self, project: str) -> list[RunSummary]:
@@ -757,3 +793,97 @@ def get_platform_templates(self, tag: str) -> bytes:
         response = self.request("GET", "/platform/templates/all", params=params)
         zip_content: bytes = response.content
         return zip_content
+
+    # RBAC
+    def list_organizations(self) -> list[Organization]:
+        """
+        Retrieves a list of organizations the user belongs to.
+
+        Returns:
+            A list of organization names.
+        """
+        response = self.request("GET", "/organizations")
+        return [Organization(**org) for org in response.json()]
+
+    def get_organization(self, organization_id: str | UUID) -> Organization:
+        """
+        Retrieves details of a specific organization.
+
+        Args:
+            organization_id (str): The organization identifier.
+
+        Returns:
+            Organization: The Organization object.
+        """
+        response = self.request("GET", f"/organizations/{organization_id!s}")
+        return Organization(**response.json())
+
+    def list_workspaces(self, filters: WorkspaceFilter | None = None) -> list[Workspace]:
+        """
+        Retrieves a list of workspaces the user has access to.
+
+        Returns:
+            A list of workspace names.
+        """
+        response = self.request(
+            "GET", "/workspaces", params=filters.model_dump() if filters else None
+        )
+        paginated_workspaces = PaginatedWorkspaces(**response.json())
+        # handle the pagination
+        all_workspaces: list[Workspace] = paginated_workspaces.workspaces.copy()
+        while paginated_workspaces.has_next:
+            response = self.request(
+                "GET",
+                "/workspaces",
+                params={
+                    "page": paginated_workspaces.page + 1,
+                    "limit": paginated_workspaces.limit,
+                    **(filters.model_dump() if filters else {}),
+                },
+            )
+            next_page = PaginatedWorkspaces(**response.json())
+            all_workspaces.extend(next_page.workspaces)
+            paginated_workspaces.page = next_page.page
+            paginated_workspaces.has_next = next_page.has_next
+
+        return all_workspaces
+
+    def get_workspace(self, workspace_id: str | UUID, org_id: UUID | None = None) -> Workspace:
+        """
+        Retrieves details of a specific workspace.
+
+        Args:
+            workspace_id (str): The workspace identifier.
+
+        Returns:
+            Workspace: The Workspace object.
+        """
+        params: dict[str, str] = {}
+        if org_id:
+            params = {"org_id": str(org_id)}
+        response = self.request("GET", f"/workspaces/{workspace_id!s}", params=params)
+        return Workspace(**response.json())
+
+    def create_workspace(
+        self,
+        name: str,
+        organization_id: UUID,
+    ) -> Workspace:
+        """
+        Creates a new workspace.
+
+        Args:
+            name (str): The name of the workspace.
+            organization_id (str | UUID): The organization ID to create the workspace in.
+
+        Returns:
+            Workspace: The created Workspace object.
+        """
+
+        payload = {
+            "name": name,
+            "org_id": str(organization_id),
+        }
+
+        response = self.request("POST", "/workspaces", json_data=payload)
+        return Workspace(**response.json())

dreadnode/api/models.py

@@ -431,6 +431,8 @@ class Project(BaseModel):
     """Name of the project."""
     description: str | None = Field(repr=False)
     """Description of the project."""
+    workspace_id: UUID | None
+    """Unique identifier for the workspace the project belongs to."""
     created_at: datetime
     """Timestamp when the project was created."""
     updated_at: datetime
@@ -441,6 +443,77 @@ class Project(BaseModel):
     """Last run associated with the project, if any."""
 
 
+class Workspace(BaseModel):
+    id: UUID
+    """Unique identifier for the workspace."""
+    name: str
+    """Name of the workspace."""
+    slug: str
+    """URL-friendly slug for the workspace."""
+    description: str | None
+    """Description of the workspace."""
+    created_by: UUID
+    """Unique identifier for the user who created the workspace."""
+    org_id: UUID
+    """Unique identifier for the organization the workspace belongs to."""
+    org_name: str | None
+    """Name of the organization the workspace belongs to."""
+    is_active: bool
+    """Is the workspace active?"""
+    is_default: bool
+    """Is the workspace the default one?"""
+    project_count: int | None
+    """Number of projects in the workspace."""
+    created_at: datetime
+    """Creation timestamp."""
+    updated_at: datetime
+    """Last update timestamp."""
+
+
+class WorkspaceFilter(BaseModel):
+    """Filter parameters for workspace listing"""
+
+    org_id: UUID | None = Field(None, description="Filter by organization ID")
+
+
+class PaginatedWorkspaces(BaseModel):
+    workspaces: list[Workspace]
+    """List of workspaces in the current page."""
+    total: int
+    """Total number of workspaces available."""
+    page: int
+    """Current page number."""
+    limit: int
+    """Number of workspaces per page."""
+    total_pages: int
+    """Total number of pages available."""
+    has_next: bool
+    """Is there a next page available?"""
+    has_previous: bool
+    """Is there a previous page available?"""
+
+
+class Organization(BaseModel):
+    id: UUID
+    """Unique identifier for the organization."""
+    name: str
+    """Name of the organization."""
+    slug: str
+    """URL-friendly slug for the organization."""
+    description: str | None
+    """Description of the organization."""
+    is_active: bool
+    """Is the organization active?"""
+    allow_external_invites: bool
+    """Allow external invites to the organization?"""
+    max_members: int
+    """Maximum number of members allowed in the organization."""
+    created_at: datetime
+    """Creation timestamp."""
+    updated_at: datetime
+    """Last update timestamp."""
+
+
 # Derived types
 
 

dreadnode/cli/shared.py

@@ -14,6 +14,10 @@ class DreadnodeConfig:
     """Server URL"""
     token: str | None = None
     """API token"""
+    organization: str | None = None
+    """Organization name"""
+    workspace: str | None = None
+    """Workspace name"""
     project: str | None = None
     """Project name"""
     profile: str | None = None
@@ -35,6 +39,8 @@ def apply(self) -> None:
             server=self.server,
             token=self.token,
             profile=self.profile,
+            organization=self.organization,
+            workspace=self.workspace,
             project=self.project,
             console=self.console,
         )

dreadnode/constants.py

@@ -1,6 +1,8 @@
 import os
 import pathlib
 
+from dreadnode.version import VERSION
+
 #
 # Defaults
 #
@@ -29,6 +31,10 @@
 DEFAULT_DOCKER_REGISTRY_LOCAL_PORT = 5005
 # default docker registry image tag
 DEFAULT_DOCKER_REGISTRY_IMAGE_TAG = "registry"
+# default workspace name
+DEFAULT_WORKSPACE_NAME = "Personal Workspace"
+# default project name
+DEFAULT_PROJECT_NAME = "Default"
 
 #
 # Environment Variable Names
@@ -39,6 +45,8 @@
 ENV_API_TOKEN = "DREADNODE_API_TOKEN"  # noqa: S105 # nosec
 ENV_API_KEY = "DREADNODE_API_KEY"  # pragma: allowlist secret (alternative to API_TOKEN)
 ENV_LOCAL_DIR = "DREADNODE_LOCAL_DIR"
+ENV_ORGANIZATION = "DREADNODE_ORGANIZATION"
+ENV_WORKSPACE = "DREADNODE_WORKSPACE"
 ENV_PROJECT = "DREADNODE_PROJECT"
 ENV_PROFILE = "DREADNODE_PROFILE"
 ENV_CONSOLE = "DREADNODE_CONSOLE"
@@ -61,3 +69,6 @@
 
 # Default values for the file system credential management
 FS_CREDENTIAL_REFRESH_BUFFER = 900  # 15 minutes in seconds
+
+# Default User-Agent
+DEFAULT_USER_AGENT = f"dreadnode/{VERSION}"

dreadnode/exporter.py

@@ -0,0 +1,25 @@
+import typing as t
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+from dreadnode.constants import DEFAULT_USER_AGENT
+
+
+class CustomOTLPSpanExporter(OTLPSpanExporter):
+    """A custom OTLP exporter that injects our SDK version into the User-Agent."""
+
+    def __init__(self, **kwargs: t.Any) -> None:
+        super().__init__(**kwargs)
+
+        # 2. Get the current User-Agent set by OTel (e.g., OTel-OTLP-Exporter-Python/<version>)
+        otlp_user_agent = self._session.headers.get("User-Agent")
+        if isinstance(otlp_user_agent, bytes):
+            otlp_user_agent = otlp_user_agent.decode("utf-8")
+
+        # 3. Combine the User-Agent strings.
+        if otlp_user_agent:
+            combined_user_agent = f"{DEFAULT_USER_AGENT} {otlp_user_agent}"
+            self._session.headers["User-Agent"] = combined_user_agent
+        else:
+            # Fallback if somehow OTel didn't set a User-Agent
+            self._session.headers["User-Agent"] = DEFAULT_USER_AGENT