Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / cloud-source-scans-and-workspaces

Cloud source scans and workspaces

Cloud source scans turn an approved local source snapshot into input for a managed Strix Cloud scan. The CLI prepares a bounded archive, uploads it, attaches its completed upload reference to a scan specification, and runs that request in the selected cloud workspace. This page is a child of Cloud-managed scanning and relates to Cloud commands and sessions.

Managed source scan model

Scan specification

The scan specification describes what the cloud service must test and how it must run the work. A source-backed request can combine repository or domain assets with uploaded source bundles, engagement guidance, credentials, network settings, notifications, and a scan tier. An upload is an input reference. It does not itself start a scan.

The same scan start operation supports later source updates for full or finding-specific retests. This keeps the scan definition separate from the source object and lets a new upload represent updated code.

References: strix/…/spec.py• L53-86 strix/…/spec.py• L143-150 strix/…/spec.py• L212-227 strix/…/spec.py• L311-317

Source snapshot

The source snapshot is the exact set of local files approved for upload. The CLI accepts a directory, selects files from it, applies built-in safety exclusions and user exclusion patterns, records a manifest, and creates a temporary ZIP archive. By default, it leaves out version-control data, dependency and build trees, hidden paths, likely secret files, and nested archives. The source directory can also provide exclude-only patterns through .strixignore. The caller can explicitly widen the selection for hidden files, sensitive names, or archives.

The snapshot has clear size and count bounds. It also has a SHA-256 digest, which identifies the archive that a person reviewed or approved. The archive is removed after the request lifecycle ends. If a selected file changes while the archive is built, the snapshot is rejected so the approved source cannot differ from the uploaded source.

References: strix/…/source_upload.py• L29-36 strix/…/source_upload.py• L38-127 strix/…/source_upload.py• L130-192 strix/…/source_upload.py• L195-240 strix/…/source_upload.py• L588-647 strix/…/source_upload.py• L662-734

Upload approval

Source data is not sent without an explicit approval step. A person can first use a dry run to inspect the file count, sizes, exclusions, and archive digest. An interactive run asks for approval, while a non-interactive run must use either deliberate one-shot approval or the digest from a reviewed snapshot.

This boundary makes the data transfer visible before the local source leaves the machine. If the source path is absent, source-only options are rejected rather than silently ignored.

References: strix/…/source_scan.py• L40-70 strix/…/source_scan.py• L138-203 strix/…/source_scan.py• L206-217 strix/…/source_upload.py• L154-192

Workspace context

Workspace selection

A workspace is the cloud account context in which scans, uploads, permissions, and related records are managed. The CLI can list workspaces and can switch the stored token to another workspace by number, ID, or exact name. The selected workspace becomes the context for later cloud requests.

Workspace creation makes the caller an administrator. Workspace switching does not create a new bearer secret. It changes the workspace metadata and access granted to the stored credential.

References: strix/…/spec.py• L1084-1092 strix/…/spec.py• L1096-1105 strix/…/workspaces.py• L29-69 strix/…/workspaces.py• L254-291

Credential scope

Workspace access is limited by both the account's authority and the scope choice made at switch time. The caller can preserve the server preference or request a minimal, recommended, full, or custom scope set within the ceiling approved at login. The local record stores the active workspace, granted scopes, requested scopes, and scope ceiling so later commands use the same access context.

An override token is used only for the current command. The CLI does not mix that token with the stored sign-in record or save new workspace state for it. A normal stored login updates local workspace metadata after the platform confirms the switch.

References: strix/…/workspaces.py• L41-67 strix/…/workspaces.py• L94-149 strix/…/workspaces.py• L168-200

Source scan launch lifecycle

Upload association

The upload flow uses a short-lived staging object before scan creation. The CLI requests upload credentials from the platform, sends the ZIP to the supplied upload target, marks the upload complete, and validates the returned upload identity. It then places the completed upload ID in the scan request's upload_ids field.

The scan request can therefore refer to source data without embedding the archive in the scan body. The same upload-ID contract supports updated code for full retests and finding-specific retests. The platform uses the completed upload when it creates the managed scan in the active workspace.

References: strix/…/source_scan.py• L64-70 strix/…/source_scan.py• L224-280 strix/…/spec.py• L71-73 strix/…/spec.py• L1065-1082 strix/…/spec.py• L219-227 strix/…/spec.py• L311-317

Launch sequence

When a source-backed scan is requested, the client follows this sequence:

  1. Build the source manifest and archive.
  2. Show the dry-run result or obtain approval.
  3. Stage and complete the source upload.
  4. Attach the upload ID to the scan specification's upload_ids field.
  5. Start the managed scan and return the scan result with the source summary.
  6. Remove the local temporary archive.

The diagram shows how the local snapshot becomes an input to the cloud scan.

flowchart LR
    A[Local source directory] --> B[Manifest and ZIP snapshot]
    B --> C{Approved?}
    C -- No --> D[Stop without upload]
    C -- Yes --> E[Stage and complete upload]
    E --> F[Attach upload ID]
    F --> G[Start managed scan]
    G --> H[Scan result and source summary]
    B --> I[Remove temporary archive]

References: strix/…/source_scan.py• L49-70 strix/…/source_scan.py• L122-135 strix/…/source_upload.py• L195-240

Failure recovery

The client treats a staged upload differently based on what the platform may have received. A failure before scan launch permits cleanup. A failure after the launch request may have reached the platform retains the upload so the caller can check the scan list before deleting it. This avoids deleting source that an accepted scan still needs.

If cleanup cannot be confirmed, the error reports the upload ID and directs the caller to delete it with the cloud uploads command. If the launch outcome is unknown and an idempotency key exists, an exact retry with the same request body and key is safe; a changed request is not an equivalent retry.

References: strix/…/source_scan.py• L72-120 strix/…/source_scan.py• L283-395

Source and workspace relationships

Source preparation and workspace selection solve different parts of the same managed scan. The source bundle defines which local data is sent. The workspace defines where the upload and scan belong and which account permissions apply. The scan specification joins them by carrying the upload ID through the authenticated workspace request.

This separation also supports operational recovery: a source upload can be inspected or removed as an upload resource, while the resulting scan is checked through the scan resource. For the wider request, payment, rendering, and session behavior, see Cloud commands and sessions.

Lifecycle boundaries

The main boundaries are:

BoundaryResponsibilityResult
Local selectionChoose and review the source snapshotApproved manifest and archive digest
Upload stagingTransfer and confirm the archiveCompleted upload ID
Workspace contextBind requests to an account workspaceActive token and scope context
Scan creationCombine scan settings with upload IDsManaged scan
RecoveryResolve uncertain launch or cleanup stateRetained upload or confirmed deletion

References: strix/…/source_upload.py• L195-240 strix/…/source_scan.py• L40-70 strix/…/source_scan.py• L76-120 strix/…/workspaces.py• L133-180 strix/…/spec.py• L71-73

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the source approval rules aligned with the fields shown in dry-run and final scan responses.
  • Preserve the contract that completed upload IDs are passed through upload_ids for scan starts and retest requests.
  • Keep upload cleanup behavior aligned with the point at which scan launch can become ambiguous.
  • Keep workspace switch response fields aligned with the local credential record and scope display.
  • Keep workspace context consistent for upload, scan creation, scan lookup, and upload deletion requests.

Important failure modes

TriggerConsequenceGuard
Source options are used without a source directoryThe command stops instead of creating an incomplete scan requestRequire --source DIRECTORY for source upload options
The selected source exceeds file, expanded-size, archive, or enumeration boundsArchive creation fails before any source uploadNarrow the source or add exclusions
Non-interactive execution has no explicit source approvalSource transfer does not startReview with dry run and approve the matching archive digest, or use deliberate one-shot approval
A source file changes while the archive is builtThe archive is rejected as a stale snapshotRebuild and approve a fresh snapshot
Scan launch fails after the platform may have accepted the requestAutomatic upload deletion could remove source needed by a scanRetain the upload, check the scan list, then delete only when no scan uses it
Workspace switch response is malformed or its result is uncertainLocal workspace state is not trustedSafely repeat the same switch or list workspaces to verify the active context

Key files

FileWhy to read it
strix/…/source_upload.pyDefines the source snapshot boundary, default exclusions, approval data, archive limits, and temporary bundle lifetime.
strix/…/source_scan.pyConnects source approval and upload staging to scan creation, result wrapping, and ambiguous-outcome recovery.
strix/…/spec.pyDefines the cloud command contract for scan starts, retests, upload staging, upload completion, and workspace operations.
strix/…/workspaces.pyExplains workspace lookup, token switching, scope selection, and local credential-state updates.