Skip to content

architecture.mdx

Latest commit

 

History

History
146 lines (117 loc) · 10.4 KB

architecture.mdx

File metadata and controls

146 lines (117 loc) · 10.4 KB
title Architecture
description System design and module responsibilities for ShipSec Studio

What is ShipSec Studio?

ShipSec Studio is an open-source, no-code security workflow orchestration platform. Build, execute, and monitor security automation workflows through a visual interface — focus on security, not infrastructure.

System Overview

┌────────────────────────────────────────────────────────────────────────┐
│                              FRONTEND                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Visual    │  │  Terminal   │  │  Timeline   │  │   Config    │    │
│  │   Builder   │  │   Viewer    │  │   Replay    │  │    Panel    │    │
│  │ (ReactFlow) │  │  (xterm.js) │  │  (Zustand)  │  │  (Forms)    │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ REST API + Unified SSE
┌───────────────────────────────────▼─────────────────────────────────────┐
│                               BACKEND                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │Workflows │ │ Secrets  │ │ Storage  │ │  Trace   │ │  Auth    │       │
│  │  + DSL   │ │(AES-256) │ │ (MinIO)  │ │ Events   │ │ (Clerk)  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Webhooks │ │Schedules │ │ Agents   │ │Human     │ │Integr-   │       │
│  │          │ │ (CRON)   │ │          │ │Inputs    │ │ations    │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ Temporal Client
┌───────────────────────────────────▼─────────────────────────────────────┐
│                              TEMPORAL                                   │
│            Workflow Orchestration • Retry Logic • Durability            │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ Activity Execution
┌───────────────────────────────────▼─────────────────────────────────────┐
│                               WORKER                                    │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    COMPONENT REGISTRY                           │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐            │    │
│  │  │  Tools   │ │    AI    │ │  Human   │ │   Core   │            │    │
│  │  │(Security)│ │  Agents  │ │ in Loop  │ │  Utils   │            │    │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘            │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                      SERVICE ADAPTERS                           │    │
│  │  Secrets │ Storage │ Artifacts │ Trace │ Terminal │ Logs        │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────────┐
│                           INFRASTRUCTURE                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │PostgreSQL│ │  MinIO   │ │  Redis   │ │Redpanda  │ │   Loki   │       │
│  │  (Data)  │ │ (Files)  │ │(Terminal)│ │ (Kafka)  │ │  (Logs)  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────────────────┘

Technology Stack

Layer Stack
Frontend React 19, TypeScript, Vite, TailwindCSS, Radix UI, ReactFlow, xterm.js, Zustand
Backend NestJS, TypeScript, Bun, Drizzle ORM, Clerk Auth
Worker Node.js, TypeScript, Temporal SDK, Docker
Infrastructure PostgreSQL 16, Temporal, MinIO, Redis, Redpanda (Kafka), Loki

Core Deep-Dives

To keep this guide concise, complicated subsystems are documented in their own dedicated files:

Component Categories

Components are the building blocks of workflows:

Category Description Examples
security Security scanning and enumeration tools Subfinder, DNSX, Nuclei, Naabu, HTTPx, TruffleHog
ai AI/ML and agent components LLM Generate, AI Agent, MCP Providers
core Utility and data processing HTTP Request, File Loader, Logic Script, JSON Transform
notification Alerts and messaging Slack, Email
manual-action Human-in-the-loop Approvals, Forms, Selection
github GitHub integrations Remove Org Membership

Security Architecture

Authentication & Multi-tenancy

  • Clerk Integration — Production-ready authentication for hosted environments.
  • Local Auth — Default for local setup using ADMIN_USERNAME / ADMIN_PASSWORD.
  • Organization Isolation — All data scoped by organization_id.

Secrets Management

  • AES-256-GCM encryption at rest.
  • Versioned secrets with active/inactive tracking.
  • Master key via SECRET_STORE_MASTER_KEY environment variable.

Container Isolation

  • IsolatedContainerVolume — Per-tenant, per-run Docker volumes. See Isolated Volumes.
  • Network isolation — Components run with network: none or bridge.
  • Automatic cleanup — Volumes destroyed after execution.

Development URLs

All application services are accessible through nginx on port 80:

Service URL
Frontend http://localhost/
Backend API http://localhost/api/
Analytics http://localhost/analytics/
Temporal UI http://localhost:8081
MinIO Console http://localhost:9001
Redpanda Console http://localhost:8082
Loki http://localhost:3100
Individual service ports (5173, 3211, 5601) are available for debugging but should not be used in normal development. All traffic flows through nginx on port 80.

Learn More

  • Component Development: /development/component-development
  • Getting Started: /getting-started