Skip to content

PLAT-106: Unified DRF API Surface

Statement

ADR-066 clarification (#2316): programmatic credentials include Knox personal tokens and native service principals. Their scopes/actions are immutable ceilings, not permission grants; live application policy and domain lifecycle also apply. Services must never be resolved as their creator's human user.

All non-public platform HTTP/JSON API endpoints shall be served through Django REST Framework (DRF) and shall enforce the platform's API authentication and scope-based authorization established by PLAT-102: session-cookie authentication with CSRF for browser/SPA clients, and scoped API tokens for programmatic clients. Each endpoint shall declare its required scopes from the central scope registry. Application logic shall remain in the service layer; the DRF layer shall own only HTTP concerns (authentication, scope authorization, serialization/validation, error envelope, pagination). Ad-hoc Django function-view JSON endpoints outside DRF (Mission Control, CTF, CMS) shall be migrated onto this surface. The platform API shall expose an OpenAPI schema.

ADR-066 S4 clarification: principal-aware account administration, membership/ownership facts, scoped profile/lifecycle commands and canonical DRF/browser adapters are prepared without replacing production routes or legacy authority. The coordinated S8 activation in #2321 binds these paths and maps historical facts. Prepared Django-admin writes are disabled in favor of the canonical validated commands.

Rationale

PLAT-102 establishes the token + scope authentication foundation, but the platform currently has two divergent API styles: DRF (risk_register /api/v1) and ad-hoc Django function views (Mission Control, CTF, CMS). A single DRF-based API surface gives one authentication/authorization path, consistent error and pagination contracts, and an OpenAPI schema, the foundation a future SPA frontend and external integrations both consume over the same contract. Consolidating early, before the SPA is built, avoids migrating endpoints out from under a live frontend and removes a class of per-endpoint security retrofits. Business logic already lives in the service layer, so migration re-houses the HTTP layer rather than rewriting behavior.

Traceability

  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/management/api/credential_views.py (Closed credential-management API)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/shared/credentials.py (Provider-neutral credential ceiling and explicit identity)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/shared/api/principals.py (Neutral credential resolution without service-to-human substitution)
  • TESTS → TEST shifter/shifter_platform/tests/management/test_credential_api.py
  • TESTS → TEST shifter/shifter_platform/tests/config/test_service_identity.py

  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/cms/api/artifact_preparation.py (Preparation lifecycle DRF endpoints with service-owned application logic)

  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/cms/api/preparation_adapters.py (Private adapter administration through scoped DRF endpoints)
  • TESTS → TEST shifter/shifter_platform/tests/cms/test_preparation_api.py (Preparation authentication, scopes, CSRF and rejected executable overrides)
  • DOCUMENTS → GITHUB_ISSUE Brad-Edwards/bigrae#1122 (PLAT-106: Migrate CMS (experiments + scenario editor) JSON API to DRF + scoped auth)
  • IMPLEMENTS → GITHUB_ISSUE Brad-Edwards/bigrae#1119 (PLAT-106: Establish platform DRF API conventions and OpenAPI schema)
  • IMPLEMENTS → CONFIG shifter/shifter_platform/config/_drf_settings.py (Platform DRF defaults, schema, pagination, and local docs assets)
  • IMPLEMENTS → CONFIG shifter/shifter_platform/config/api_urls.py (Versioned API route surface and authenticated schema/docs endpoints)
  • IMPLEMENTS → CONFIG shifter/shifter_platform/config/urls.py (Project /api/v1 mount for the platform API)
  • IMPLEMENTS → CONFIG shifter/shifter_platform/config/settings.py (DRF and schema application registration in Django settings)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/shared/api/errors.py (Shared platform API error envelope helpers)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/shared/api/permissions.py (Shared scoped API permission base for DRF endpoints)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/shared/api/schema.py (Shared OpenAPI authentication and error-envelope schema extensions)
  • IMPLEMENTS → DOCUMENTATION docs/technical/dev/api.md (Developer guide for platform DRF API conventions)
  • TESTS → TEST shifter/shifter_platform/tests/config/test_api_urls.py (Tests for authenticated schema/docs and v1 API routing)
  • TESTS → TEST shifter/shifter_platform/tests/config/test_settings.py (Tests for platform DRF settings defaults)
  • TESTS → TEST shifter/shifter_platform/tests/shared/test_api_errors.py (Tests for the shared platform API error envelope)
  • TESTS → TEST shifter/shifter_platform/tests/shared/test_api_permissions.py (Tests for required-scope DRF permission behavior)
  • IMPLEMENTS → GITHUB_ISSUE Brad-Edwards/bigrae#1120 (PLAT-106: Migrate Mission Control JSON API to DRF + scoped auth)
  • IMPLEMENTS → PULL_REQUEST Brad-Edwards/bigrae#1202 (changed: migrate mission control apis to drf)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/shared/api_tokens/scopes.py (Mission Control API-token scope registry entries)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/permissions.py (Mission Control actor and lifecycle DRF permissions)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/serializers.py (Mission Control DRF request serializers and validation contracts)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/urls.py (Canonical Mission Control DRF URL surface)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/_base.py (Shared Mission Control DRF base view and error-envelope handling)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/ranges.py (Mission Control range and catalog DRF endpoints)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/uploads.py (Mission Control upload DRF endpoints with scoped auth)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/guacamole.py (Mission Control Guacamole DRF bootstrap endpoints)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/resources.py (Mission Control NGFW, credential, and script DRF endpoints)
  • TESTS → TEST shifter/shifter_platform/tests/mission_control/test_api_token_access.py (Mission Control scoped API-token access tests)
  • TESTS → TEST shifter/shifter_platform/tests/shared/test_api_tokens_scopes.py (Mission Control API-token scope registry tests)
  • TESTS → TEST shifter/shifter_platform/tests/mission_control/test_range_api.py (Mission Control range DRF compatibility tests)
  • TESTS → TEST shifter/shifter_platform/tests/mission_control/test_views_uploads.py (Mission Control upload DRF compatibility tests)
  • IMPLEMENTS → GITHUB_ISSUE Brad-Edwards/bigrae#1121 (PLAT-106: Migrate CTF JSON API to DRF + scoped auth)
  • IMPLEMENTS → PULL_REQUEST Brad-Edwards/bigrae#1215 (changed: migrate ctf json api to drf boundary)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/ctf/api/_base.py (CTF DRF boundary helpers, actor resolution, scoped auth, and canonical error envelopes)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/ctf/api/urls.py (Canonical CTF DRF API URL surface)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/ctf/api/views.py (Canonical CTF DRF endpoint callables and public scoreboard)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/ctf/views/_parsing.py (Request-body field parsing helpers used by the CTF API views)
  • DOCUMENTS → DOCUMENTATION docs/architecture/ctf-drf-api-preflight-1121.md (CTF DRF API migration preflight and compatibility notes)
  • TESTS → TEST shifter/shifter_platform/tests/ctf/test_drf_api_token_access.py (CTF scoped API-token and canonical API behavior tests)
  • IMPLEMENTS → PULL_REQUEST Brad-Edwards/bigrae#1227 (changed: add CMS DRF API routes)
  • IMPLEMENTS → GITHUB_ISSUE Brad-Edwards/bigrae#1122 (PLAT-106: Migrate CMS (experiments + scenario editor) JSON API to DRF + scoped auth)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/cms/api/permissions.py (CMS DRF actor resolution, authoring permission, and read/write scope composition)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/cms/api/serializers.py (CMS DRF request serializers for YAML and script upload API bodies)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/cms/api/urls.py (Canonical CMS DRF API route surface with experiment feature-flag gating)
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/cms/api/views.py (CMS DRF views delegating scenario-editor and experiment API behavior to CMS services)
  • DOCUMENTS → DOCUMENTATION docs/architecture/cms-drf-api-preflight-1122.md (CMS DRF API migration preflight and binding architecture guidance)
  • DOCUMENTS → DOCUMENTATION docs/technical/dev/api.md (Developer guide for platform and CMS DRF API conventions)
  • IMPLEMENTS → GITHUB_ISSUE Brad-Edwards/bigrae#1124 (PLAT-106: Retire deprecated risk_register APIKey in favor of platform ApiToken)
  • IMPLEMENTS → GITHUB_ISSUE Brad-Edwards/bigrae#1244 (PLAT-106: drop dead risk_register APIKey reference from access.py (follow-up to #1124))
  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/mission_control/api/_vpn.py (Scoped Mission Control OpenVPN profile DRF endpoint)
  • TESTS → TEST shifter/shifter_platform/tests/mission_control/test_vpn_profile_api.py (Mission Control VPN profile API authorization and delivery tests)

  • IMPLEMENTS → CODE_FILE shifter/shifter_platform/config/account_admin_urls.py (S4 prepared administration; activation remains coordinated)

  • TESTS → TEST shifter/shifter_platform/tests/workspaces/test_prepared_admin_routes.py (S4 prepared administration; activation remains coordinated)

  • DOCUMENTS → DOCUMENTATION docs/adr/066-account-principal-resource-scope.md (S8 replaces the retired unscoped scenario-authoring surface with explicit native catalog scope)
  • TESTS → TEST shifter/shifter_platform/tests/cms/test_principal_content_api.py (Native content API proof, credential ceilings, exact placement and opaque denial)