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-managed-scanning

Cloud-managed scanning

Cloud-managed scanning turns a signed-in command into a scan that runs in the Strix platform. The command surface selects a workspace, sends an authenticated request, passes the platform billing check, and can track the resulting remote scan until it reaches a final state. It also supports scans that use a reviewed source snapshot from a local directory.

Managed command surface

The strix cloud surface is the terminal entry point for managed platform work. It maps scan, asset, session, workspace, and billing actions to the platform API while keeping output usable for both people and automation. Read the cloud commands and sessions page for the command groups and session controls.

Command routing

The command surface first identifies a command group such as scans, billing, or workspaces. It then turns the selected action into one platform request and returns a process result that describes success, invalid use, authentication needs, or payment needs.

The same surface supports human-facing terminal output and JSON output. A redirected command uses JSON by default so that an agent or script can consume the result without parsing display text.

References: strix/…/__init__.py• L27-45 strix/…/__init__.py• L57-118 strix/…/runner.py• L167-223

Platform request context

Each request uses an API token that comes from the current command, the environment, or the stored sign-in record. The request also carries the selected workspace when the stored sign-in supplies one. This binds the scan and its related data to the account context that the user selected.

The sign-in record is bound to the platform that issued it. The client refuses to send a stored token to a different platform origin. This protects the account context before any scan or billing request leaves the machine.

References: strix/…/http.py• L50-74 strix/…/http.py• L84-120 strix/…/http.py• L148-185

Scan session lifecycle

The scan lifecycle changes a request into a remote operation that can outlive the terminal command. A scan start returns an operation identifier. The user can inspect that operation later or ask the command to poll it until its status is final.

Scan launch

The scans start action accepts the target context and scan instructions. The platform creates the managed scan and runs its agents against the selected assets or source. When the request is an idempotent scan-producing mutation, the client creates or accepts a valid idempotency key and uses it for bounded retries of transport, rate-limit, and retry-safe server responses. An exact retry with the same key does not create a second scan or charge.

The launch result is valid only when it includes an operation identifier. If the request or response fails after the platform may have accepted it, the client reports that the launch outcome is unknown. The safe next step is to inspect the scan list before trying again. The command includes the idempotency key in the recovery result when one is available, so the same request can be retried safely.

References: strix/…/spec.py• L53-86 strix/…/spec.py• L120-154 strix/…/runner.py• L276-330 strix/…/runner.py• L333-403 strix/…/runner.py• L743-753 strix/…/runner.py• L789-849

Scan progress

The scan is an asynchronous remote session. With --wait, the command reads the created operation and checks its status at intervals until it reaches a terminal state such as completed, failed, cancelled, or expired. Without --wait, the operation identifier lets the user return later with a scan read command.

Waiting is bounded by a timeout. An interruption or timeout does not prove that the remote scan stopped. The result tells the user to check the operation before retrying.

References: strix/…/runner.py• L436-460 strix/…/runner.py• L757-786 strix/…/runner.py• L1076-1132

Billing gate

Managed scan work is subject to the workspace credit balance. The platform can reject a scan when the balance or scan credit limit is not sufficient. The cloud surface maps these responses to a payment result instead of treating them as a normal command error.

Users can inspect the workspace balance with strix cloud credits or buy credits with the billing top-up flow. A top-up may require explicit approval and an agent wallet. The client reports payment as confirmed only when it receives a valid billing receipt from the platform.

References: strix/…/__init__.py• L88-92 strix/…/http.py• L324-360 strix/…/billing.py• L98-139 strix/…/billing.py• L207-284

Source-backed scans

A source-backed scan uses a local directory as an explicit input to a managed scan. The command builds a source snapshot, gives the user a chance to review it, uploads the approved archive, and attaches the resulting upload to the scan request. Read the cloud source scans and workspaces page for the source and workspace flows in more detail.

Source snapshot

The source workflow selects files from the requested directory and applies the user's exclusion and inclusion choices. A dry run produces a manifest with the archive digest and selected paths without uploading or starting a scan. Non-interactive use requires either explicit one-shot approval or approval of the digest from a prior dry run.

This approval boundary makes the uploaded source an intentional input. Hidden files, sensitive-looking names, and nested archives are not included unless the user opts in.

References: strix/…/source_scan.py• L40-70 strix/…/source_scan.py• L138-203 strix/…/runner.py• L686-740

Source upload

After approval, the client requests a platform upload, sends the archive to the platform-issued storage location, and marks the upload complete. It then adds the upload identifier to the scan body. The scan type is inferred as a code review when the request uses a local source or other repository input and does not name a type.

The upload remains a separate resource until the scan links it. If the launch outcome is uncertain, the client retains the upload and gives the user its identifier. This permits status checking and deliberate cleanup instead of silently losing the source or creating a duplicate scan.

References: strix/…/source_scan.py• L224-287 strix/…/source_scan.py• L297-374 strix/…/runner.py• L333-403 strix/…/runner.py• L487-497

Workspace execution

A workspace is the account context in which scans, credits, assets, and results are managed. The stored sign-in selects one workspace for normal requests. The user can list workspaces and switch the stored token to another one when the account has access to more than one.

Workspace selection

Login completes the device flow by selecting a workspace and an access scope. The platform returns a token record that includes the workspace identity and granted access. The client stores that record for later cloud commands.

If several workspaces are available, an interactive terminal can select one. A non-interactive command must name the workspace by ID or exact name. This avoids sending a request to an unintended workspace.

References: strix/…/platform_cli.py• L104-188 strix/…/platform_cli.py• L191-296 strix/…/platform_cli.py• L381-426 strix/…/platform_cli.py• L436-475

Workspace switching

The workspaces use action finds a workspace from the account list and asks the platform to rotate the token in place for that workspace. The bearer secret and expiry can stay the same while the workspace metadata and granted scopes change. A normal stored session saves the new context for later requests. An override token changes only the current command context.

The switch is safe to repeat when its result is unclear. The client does not replace the local record until it has a valid platform response. If local storage fails after the platform switch succeeds, the token remains valid and the command reports that the local metadata needs repair.

References: strix/…/workspaces.py• L29-91 strix/…/workspaces.py• L94-200 strix/…/workspaces.py• L203-240

Operational handoffs

Cloud-managed scanning separates work that needs a person from work that an agent can complete. The command can prepare JSON for automation, while browser approval, payment approval, and source approval remain explicit gates when they affect account access or spend.

Human and agent boundaries

Authentication uses a browser device flow. Billing can use a browser or wallet approval. A local source upload needs a reviewed snapshot in non-interactive mode. These boundaries prevent an unattended command from silently granting access, spending credits, or sending an unexpected directory.

The command reports uncertain outcomes with an operation or upload identifier when possible. For idempotent launches, it also reports the key needed for an exact retry. This gives the next command enough state to inspect before it repeats a request.

References: strix/…/platform_cli.py• L241-296 strix/…/billing.py• L121-170 strix/…/source_scan.py• L164-199 strix/…/runner.py• L757-849

Change checklist

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

  • Keep the command routing, command specification, and request error codes aligned. A new scan-producing action must define how the client identifies and waits for its remote operation.
  • Preserve the workspace binding across login, stored-token loading, request headers, and workspace switching. A token and its workspace metadata must not be mixed with another account or platform.
  • Keep source approval, upload attachment, and upload cleanup as one lifecycle. Changes to scan request fields must still preserve the upload identifier and uncertain-outcome recovery.
  • Keep idempotency keys tied to one exact mutation. Retry rules, server retry signals, and recovery output must agree so a retry does not create a duplicate scan or charge.
  • Treat billing responses and top-up receipts as a contract between the platform and the CLI. A payment or credit-limit response must not be reported as a confirmed scan or payment without the required platform result.

Important failure modes

TriggerConsequenceGuard
Stored token belongs to another platform originThe request is refused before the token is sentBind the token to its issuer and require a matching active platform
Scan launch loses its response after the request may have reached the platformA retry could create a duplicate scan or chargeReport an unknown launch outcome; inspect scans; use the same idempotency key only for the same request
A retry reuses an idempotency key for a different requestThe platform can reject the request or associate it with the wrong prior outcomeGenerate or supply a key per exact mutation and never reuse it across changed inputs
Source upload succeeds but scan launch is uncertainThe source object may remain stagedRetain the upload ID and check scans before deleting or retrying
Source options run without --sourceThe command could imply a source upload that does not existReject source-only options unless a directory is supplied
Workspace switch returns an unclear resultLocal context may not match the platform contextKeep the bearer unchanged and safely rerun the same switch or list workspaces
Top-up wallet exits without a trusted receiptCredits may have been charged even though the CLI cannot confirm themCheck the credit balance before retrying payment

Key files

FileWhy to read it
strix/…/__init__.pyShows the strix cloud entry point, command groups, aliases, output modes, and exit-code surface.
strix/…/runner.pyShows how a command becomes an authenticated request, idempotent scan launch, wait, result, or recovery error.
strix/…/spec.pyDefines the high-level cloud actions and identifies which actions create or wait for scan operations.
strix/…/source_scan.pyShows the reviewed local-source, upload, attachment, and cleanup lifecycle.
strix/…/http.pyShows token lookup, platform binding, workspace request context, and cloud error mapping.
strix/…/platform_cli.pyShows browser sign-in, workspace selection, token storage, and session state.
strix/…/workspaces.pyShows how the stored cloud context moves to another workspace.
strix/…/billing.pyShows the credit top-up boundary and the rule for confirming payment.