Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shipsec.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Temporal Orchestration

ShipSec Studio uses Temporal.io as its core orchestration engine. Temporal ensures that workflows are durable, retriable, and scalable.

​
Workflows vs. Activities

  • Workflows: Contain the orchestration logic. They must be deterministic because Temporal may “replay” them to reconstruct state.
  • Activities: Perform the actual work (e.g., running a Docker container, making an HTTP request). They can be non-deterministic and are automatically retried by Temporal on failure.

​
Worker Architecture

ShipSec uses a specialized worker architecture to handle different types of workloads.

​
Default Worker

  • Task Queue: shipsec-default
  • Responsibilities:
    • Executing workflow logic (orchestration).
    • Running lightweight “inline” activities (logic, simple transforms).

​
Specialized Workers (Scaling)

For high-volume or heavy workloads, we can deploy specialized workers:
Worker TypeTask QueueActivitiesResource Profile
Securitysecurity-toolsNmap, Subfinder, NucleiHigh CPU, High RAM
I/O Boundfile-opsMinIO/S3 uploads, ZIP opsHigh Network/Disk I/O
Long-Runningheavy-scansMassive port scansHigh Timeout, Reserved Capacity

​
Execution Flow

  1. Backend starts a workflow via the Temporal Client.
  2. Temporal Server places a “Workflow Task” on the shipsec-default queue.
  3. Default Worker picks up the task and starts the workflow.
  4. When the workflow reaches a node, it schedules an Activity Task.
  5. The Activity worker (could be the same worker or a specialized one) executes the activity and returns the result.
  6. Temporal persists every step in its Event History, allowing it to recover from worker crashes.

​
Routing Logic

In the workflow code, we route activities to specific queues using proxyActivities: 
// Inside a workflow
const heavyActivities = proxyActivities<SecurityActivities>({
  taskQueue: 'security-tools',  // Routes to specialized security worker
  startToCloseTimeout: '1 hour',
});

const results = await heavyActivities.runScanner({ target: 'example.com' });

​
Scaling

ShipSec workers are horizontally scalable. Multiple workers can poll the same task queue, and Temporal will automatically load-balance tasks between them. Workers can be deployed as separate Docker containers or Kubernetes pods.