Security

← Back to Documentation

This document provides a security overview of Shaper, an open-source, SQL-first data analytics, reporting, and embedded dashboard platform developed by Taleshape.

---

1. Executive Summary & Security Posture

Shaper is built with a privacy-first, local-execution design philosophy:

• Self-Contained Single Binary: Shaper embeds all required operational components—including the analytical SQL engine (DuckDB), system metadata database (SQLite), and cluster event broker (NATS JetStream)—into a single process.
• Zero External Data Egress: Shaper does not transmit telemetry, analytics pings, diagnostic data, or query contents to external servers. It operates completely disconnected from external networks if required.
• Deterministic Isolation: Queries are validated against an AST/prefix parser to enforce read-only data access for dashboards. The DuckDB query engine configuration is locked against runtime mutation.
• Zero Trust Supply Chain: All releases, binaries, and container images are cryptographically signed with Sigstore Cosign and accompanied by cryptographically verifiable SLSA build provenance attestations.

---

2. Architecture & Data Flow

Software Architecture & Component Isolation

Shaper operates as a unified service without requiring external database servers, caching fleets, or message queues:

graph TD
    subgraph Clients["Client Boundaries"]
        Browser["User Browser (Web UI)"]
        HostApp["Host Application (React / JS SDK / IFrame)"]
        CLI["Shaper CLI Developer Tools"]
    end

    subgraph SecurityPerimeter["Shaper Security Perimeter (Local Process / Container)"]
        Echo["Web Layer (Echo v4)<br/>• TLS / HSTS / BodyLimit(2MB)<br/>• Security Headers / CORS<br/>• Recover Middleware"]
        AuthLayer["Authentication & Authorization Engine<br/>• bcrypt (Password hashing)<br/>• Salted HMAC-SHA256 (Sessions & API Keys)<br/>• HS256 JWT Verification (Embedding & RLS)"]
        MetricsEndpoint["Protected /metrics<br/>(API Key + PermissionReadMetrics required)"]

        subgraph Engine["Execution Engine"]
            Validator["SQL AST & Prefix Validator<br/>(Read-Only Enforcer)"]
            DuckDB["Embedded DuckDB Engine<br/>• SET lock_configuration = true<br/>• SET allow_persistent_secrets = false<br/>• Extension Allowlist Enforcement"]
        end

        subgraph StateStore["State & Metadata Store"]
            SQLite["Embedded SQLite<br/>(Users, Sessions, API Keys, Permissions)"]
            NATS["Embedded NATS JetStream<br/>(Distributed Event Stream & State Replication)"]
        end
    end

    subgraph DataSources["Customer Infrastructure"]
        DataWarehouse["Customer Databases / Parquet / S3 / Iceberg / Postgres"]
    end

    Browser -->|"Bearer JWT (Exchanged from Session)"| Echo
    HostApp -->|Scoped JWT with RLS Claims| Echo
    CLI -->|Hashed API Key / Token| Echo
    Echo --> AuthLayer
    AuthLayer --> SQLite
    Echo --> MetricsEndpoint
    Echo --> Validator
    Validator --> DuckDB
    DuckDB <--> NATS
    DuckDB -->|"SQL Queries (Local/Customer VPC)"| DataWarehouse

Core Components

1. Web Layer (Echo v4): Handles HTTP/WebSocket endpoints, applies security middlewares (BodyLimit, Secure, Recover, CORS), terminates TLS, and enforces authentication.
2. Embedded DuckDB Engine: Serves as the high-performance analytical engine executing dashboard SQL queries, transforming datasets, and caching intermediate tables.
3. Embedded SQLite: Houses system state, users, session tokens, API keys, dashboard layout metadata, and permission structures.
4. Embedded NATS JetStream: Provides distributed state distribution, scheduled task orchestration, and background job queuing across multiple Shaper nodes without external messaging brokers.

---

Zero External Egress & Air-Gapped Operation

• No Phone-Home or Telemetry: Shaper contains no telemetry SDKs, analytics tracking beacons, licensing servers, or automated remote reporting.
• Air-Gapped Readiness: Shaper can run in secure enclaves, isolated VPCs, on-premise bare-metal servers, and completely offline air-gapped data centers.
• Local Asset Delivery: All frontend scripts, styles, web fonts (DM Sans, Source Sans Pro), Monaco editor bundles, and icons are bundled and served directly from the embedded Go binary filesystem (//go:embed dist). No external CDNs or external font services are accessed at runtime.

---

Dashboard Data Flow Lifecycle

When a dashboard is requested or rendered, data travels through the following sequence:

sequenceDiagram
    autonumber
    actor Client as User Browser / Host Application
    participant Web as Echo Web Layer
    participant Auth as Auth & Context Engine
    participant Val as SQL Validator
    participant DDB as Embedded DuckDB
    participant Source as Analytical Data Source

    Client->>Web: GET /api/dashboards/:id or /api/sql
    Note over Client,Web: Includes Bearer JWT (exchanged from session), Scoped JWT, or API Key
    Web->>Auth: Validate Credentials & Context
    Auth-->>Web: Verified Actor (User / API Key / Embed) & Variables

    Web->>Val: Check SQL Content for Dashboard
    Note over Val: Validates query against read-only statement whitelist.<br/>Rejects DROP, DELETE, UPDATE, INSERT, ATTACH, PRAGMA.
    Val-->>Web: Query Permitted

    Web->>DDB: Acquire Database Connection
    Note over DDB: Injects validated JWT variables using SET VARIABLE.<br/>Sets lock_configuration = true.
    DDB->>Source: Execute SQL Query (Local memory or customer DB)
    Source-->>DDB: Return Raw Result Set
    Note over DDB: Cleans up session variables with RESET VARIABLE.

    DDB-->>Web: Stream Structured Result Set (Max rows capped)
    Web-->>Client: HTTP JSON / CSV / Parquet Stream Response

1. Ingress & Authentication: The request arrives with a signed JWT Bearer token (obtained by exchanging a user session token or issued for embedding) or an API key (shaperkey.*). User session tokens are not sent with regular requests.
2. Context Establishment: Shaper constructs an Actor context (ActorUser, ActorAPIKey, or ActorPublic) and extracts any signed embed variables.
3. Variable Sanitization: Variables passed via JWT claims or URL parameters are validated against strict alphanumeric identifier rules (util.IsValidVariableName), escaped (util.EscapeSQLIdentifier, util.EscapeSQLString), and injected into the DuckDB session using SET VARIABLE.
4. AST Statement Verification: Every query is evaluated using IsAllowedStatement(). Destructive statements, administrative operations, or arbitrary attachment commands are blocked.
5. Execution & Cleanup: The query executes against attached DuckDB datasets or external sources. Upon completion, session variables are reset using RESET VARIABLE.
6. Streaming Egress: Query results are serialized directly to the client as JSON or streamed as CSV/Excel without staging on external third-party storage.

---

3. Authentication & Access Control (IAM)

Web UI Authentication & Session Management

• Initial Setup Guard: When Shaper initializes without an existing user, the /api/auth/setup endpoint allows creating the initial administrator. Once established, subsequent setup requests are blocked (ErrUserSetupCompleted returns HTTP 409 Conflict).
• Password Hashing: Passwords are cryptographically hashed using bcrypt with standard salt generation before storage in SQLite (users.password_hash). Raw passwords are never logged or stored.
• Cryptographic Session Tokens:
  • Tokens use the format shapersession.<cuid2>.<random32>, generating 256 bits of entropy.
  • Stored sessions are protected using keyed HMAC-SHA256 with an independent per-session salt stored in the SQLite database.
  • Verification uses constant-time comparison (crypto/subtle.ConstantTimeCompare) to mitigate side-channel timing attacks.
• Session Token & JWT Exchange:
  • No Session Tokens on Routine Requests: User session tokens are not sent with every request.
  • Exchange for Short-Lived JWT: When a user logs in (via /api/login), the session token is issued and immediately exchanged for a short-lived signed JSON Web Token (JWT) via /api/auth/token.
  • Stateless Authorization: All subsequent requests to protected API endpoints use the short-lived JWT as a Bearer token in the Authorization header (Authorization: Bearer <jwt>). This eliminates database session lookups on every API request and keeps long-lived session credentials out of regular network traffic.
  • Automatic Refresh: When the short-lived JWT expires (SHAPER_JWTEXP, default: 15 minutes), the client exchanges the session token for a fresh JWT as long as the underlying session remains valid (SHAPER_SESSIONEXP, default: 30 days).
• Session Lifecycle & Pruning:
  • Session lifetime is governed by SHAPER_SESSIONEXP (or --sessionexp, default: 30 days).
  • Expired sessions are automatically pruned from the database on subsequent user authentications.
  • Explicit logout (/api/logout) deletes the session record immediately.
• Invitation System: New users are provisioned via cryptographically generated invite links with configurable expiry (SHAPER_INVITEEXP / --inviteexp, default: 7 days).

---

Embedded Analytics & Row-Level Security (RLS)

Shaper provides secure analytics embedding for SaaS platforms, portals, and customer-facing applications without requiring insecure <iframe> configurations or sharing master database credentials.

graph LR
    subgraph HostBackend["Customer Host Application (Backend)"]
        Signer["Signs JWT with Shared Secret<br/>(HS256)"]
        Claims["Claims Payload:<br/>• dashboardId: 'dash_123'<br/>• exp: 15 minutes<br/>• variables: { org_id: 'org_abc' }"]
    end

    subgraph Client["End-User Browser"]
        SDK["Shaper React / JS SDK"]
    end

    subgraph ShaperInstance["Shaper Core"]
        Verify["Verify HS256 Signature<br/>with jwt-secret"]
        ScopeCheck["Enforce dashboardId Scope"]
        Inject["SET VARIABLE org_id = 'org_abc'"]
        Query["Run Query:<br/>WHERE organization_id = getvariable('org_id')"]
    end

    Claims --> Signer
    Signer -->|Signed JWT| SDK
    SDK -->|Authorization: Bearer JWT| Verify
    Verify --> ScopeCheck
    ScopeCheck --> Inject
    Inject --> Query

1. Cryptographic Signature Verification:
   • Embedding relies on HMAC-SHA256 (HS256) signed JWTs.
   • The signing secret is configured statically via SHAPER_JWT_SECRET (or --jwt-secret, recommended for production) or automatically generated and stored in NATS KV.
2. Dashboard Scope Enforcement:
   • Tokens can restrict the caller to a single dashboard (dashboardId claim). Requests attempting to access unauthorized dashboards are rejected with HTTP 401 Unauthorized.
3. Row-Level Security (RLS) via Session Variables:
   • The host application’s backend signs tenant attributes into the JWT variables object (e.g. {"organization_id": "org_12345", "user_tier": "enterprise"}).
   • Shaper extracts these verified variables and binds them to the query session.
   • SQL queries reference these values via DuckDB’s getvariable('organization_id').
   • Tamper Resistance: Because the JWT is signed by the host application’s backend, end users cannot alter or tamper with variable values to view other tenants’ data.
4. Public & Password-Protected Sharing:
   • Dashboards can be individually configured as private, public, or password-protected.
   • Password protection hashes the dashboard passphrase. Correct validation issues a temporary, scoped JWT.
   • Both sharing modes can be disabled globally across the instance using SHAPER_NO_PUBLIC_SHARING=true and SHAPER_NO_PASSWORD_PROTECTED_SHARING=true (or CLI flags --no-public-sharing and --no-password-protected-sharing).

---

CLI & API Key Authentication

• API Key Format & Storage:
  • API keys follow the format shaperkey.<cuid2>.<random32>.
  • Stored in SQLite as HMAC-SHA256 hashes with per-key salt. Verification is performed using subtle.ConstantTimeCompare.
• Role-Based Access Control (RBAC):
  • API keys can be restricted to specific permissions:
    • metrics: Access to the /metrics endpoint.
    • deploy: Ability to deploy dashboards and tasks.
    • ingest: Permission to ingest streaming data events (/api/data/:table_name).
    • query: Permission to execute direct SQL queries (/api/sql).
    • schema: Permission to inspect database schemas (/api/schema).
    • read_dashboard: Read-only access to dashboard data.
    • jwt: Permission to request or issue embedded JWTs.
• CLI Authentication Loopback Protocol:
  • Running shaper login starts an ephemeral loopback HTTP server on 127.0.0.1:<ephemeral-port>.
  • The browser opens the Shaper authentication interface.
  • The CLI server validates that the HTTP Origin header strictly matches the target Shaper base URL, preventing cross-site scripting attacks or malicious local websites from injecting tokens.
  • Tokens are saved in the .shaper-auth file next to the shaper.json configuration file with strict POSIX permissions (0600—readable and writable solely by the file owner). This file location can be changed by setting the --auth-file flag.

---

Single Sign-On (SSO) Integration

Shaper provides built-in Single Sign-On (SSO) capabilities allowing organizations to centralize identity management and integrate with their existing authentication infrastructure.

Base JWT-Based SSO

The open-source version of Shaper implements a lightweight, redirect-and-callback JWT SSO mechanism configured via SHAPER_SSO_LOGIN_URL (or --sso-login-url) and SHAPER_JWT_SECRET (or --jwt-secret):

1. Authentication Delegation: When SHAPER_SSO_LOGIN_URL is configured, unauthenticated users attempting to access the Shaper dashboard/UI are redirected to your custom SSO login endpoint. Shaper appends a redirect query parameter containing the target URL the user originally requested.
2. User Authentication & Token Generation: Your SSO endpoint authenticates the user (via your internal application session or an upstream auth system) and generates a JSON Web Token (JWT) signed with HMAC-SHA256 (HS256) using the shared SHAPER_JWT_SECRET. The payload includes:
   • userId (required): Unique identifier for the user.
   • userEmail (optional): Email address for auditing and user identification.
   • userName (optional): Display name for the user in Shaper.
3. Redirect Handshake: The SSO endpoint appends the signed JWT to the original target URL as a token query parameter (<redirect_url>?token=<jwt>) and redirects the user back to Shaper. Shaper verifies the token signature against the shared secret and establishes an authenticated session.
4. Administrative Isolation: When SSO is enabled, local username/password login and user invitation interfaces are automatically disabled in the UI, ensuring all identity lifecycle management (onboarding, offboarding, credential rotation) is governed centrally.

For a complete walkthrough and code examples, see the Single Sign-On Documentation.

If you are interested in native OpenID Connect (OIDC) or Proxy Header Authentication for your deployment, please reach out to our team.

---

4. Database & Execution Sandboxing

SQL AST & Query Statement Validation

Shaper intercepts and parses SQL statements before execution to guarantee safety across user-authored dashboards:

Statement Category	Allowed Statements	Blocked / Disallowed Statements
Data Retrieval (Dashboards)	SELECT, WITH, VALUES, SUMMARIZE, DESCRIBE, DESC, SHOW TABLES, SHOW ALL TABLES, PIVOT, UNPIVOT, EXPLAIN, EXPLAIN ANALYZE	INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, MERGE
Session Side Effects (Dashboards)	SET VARIABLE, RESET VARIABLE, CREATE TEMPORARY TABLE/VIEW/MACRO/FUNCTION, BEGIN, COMMIT, ROLLBACK	PRAGMA, persistent CREATE TABLE, persistent CREATE VIEW, ATTACH (in persistent mode)
Background Tasks	Analytical pipeline commands, ATTACH/DETACH, CREATE SECRET	PRAGMA, arbitrary system SET/RESET configuration commands, unapproved extensions

• Query Whitelisting: Dashboard queries are restricted to non-destructive statements. Any statement not matching the strict read-only grammar is rejected before reaching the query planner.
• Variable Validation: Variable names must adhere to strict alphanumeric patterns (^[a-zA-Z0-9_]+$). Values are escaped prior to DuckDB variable assignment.

Disabling Tasks: If your deployment does not require scheduled background jobs or data pipelines, you can disable the background task execution engine and task scheduler API entirely by setting the environment variable SHAPER_NO_TASKS=true or passing the --no-tasks CLI flag. Existing tasks will be disabled rather than deleted, so removing the flag or variable restores them. For more details, see Tasks & Scheduling and Configuration Options.

---

DuckDB Engine Hardening

When initializing or providing DuckDB database handles, Shaper enforces critical engine-level locks:

• Configuration Lockdown: Executes SET lock_configuration = true. This prevents analytical queries from modifying DuckDB internal settings, security boundaries, or memory ceilings at runtime.
• Persistent Secret Isolation: In in-memory mode, Shaper executes SET allow_persistent_secrets = false. This guarantees transient dashboard sessions cannot access or write credentials to the host machine’s persistent secret storage directory.
• Community Extension Lockdown: By setting SHAPER_NO_DUCKDB_COMMUNITY_EXTENSIONS=true (or --no-duckdb-community-extensions), Shaper executes SET allow_community_extensions = false, blocking the installation of unverified community extensions.
• Extension Whitelisting: By setting SHAPER_ALLOWED_DUCKDB_EXTENSIONS (or --allowed-duckdb-extensions), Shaper disables DuckDB’s automatic extension installer (SET autoinstall_known_extensions = false) and permits only explicitly approved extensions.

---

Environment Variable Access Scoping

To prevent analytical queries from reading server environment variables (such as database passwords, API tokens, or host keys):

• DuckDB’s getenv scalar user-defined function (UDF) is strictly scoped.
• The UDF is dynamically registered and enabled only during startup when processing SHAPER_INIT_SQL / SHAPER_INIT_SQL_FILE (or --init-sql / --init-sql-file).
• It is immediately unregistered and disabled (defer getenv.Disable()) before any user-facing requests or dashboard queries can be executed.

---

5. Infrastructure & Network Hardening

HTTP Security Headers & Request Safeguards

The HTTP service is protected by standard defense-in-depth middlewares:

• Request Body Limiting: middleware.BodyLimit("2M") enforces a strict 2-megabyte payload limit on all incoming HTTP requests, preventing memory exhaustion and denial-of-service (DoS) attacks.
• Content Type Sniffing Prevention: X-Content-Type-Options: nosniff is enforced on all HTTP responses.
• Clickjacking Protection: X-Frame-Options: SAMEORIGIN prevents unauthorized framing of the application interface.
• Strict Transport Security (HSTS): HSTSMaxAge: 2592000 (30 days) is enabled to mandate encrypted connections.
• Cross-Origin Resource Sharing (CORS): Configurable via SHAPER_CORS_DOMAINS (or --cors-domains) to restrict Access-Control-Allow-Origin to trusted application domains and origins (defaults to * when unconfigured).
• Panic Recovery: middleware.Recover() intercepts unhandled panics, logs the failure, and returns a sanitized HTTP 500 without crashing the server process.

---

Automated TLS / ACME Support

Shaper contains native support for automated TLS certificate issuance and renewal via Let’s Encrypt (ACME):

• Configuring SHAPER_TLS_DOMAIN=<domain> (or --tls-domain <domain>) automatically provisions certificates, activates TLS termination on port 443, and enforces HTTP-to-HTTPS redirection on port 80.
• Certificate caches are stored locally (SHAPER_TLS_CACHE / --tls-cache) with restricted file permissions.
• Alternatively, Shaper can run behind enterprise ingress controllers, reverse proxies (NGINX, Envoy, Traefik), or cloud load balancers.

---

Prometheus Monitoring Security & Metrics Inventory

Shaper exposes a Prometheus metrics endpoint at /metrics:

• Access Control: The /metrics endpoint is protected by API key authentication. An incoming request must present an API key with the metrics (PermissionReadMetrics) permission. Unauthenticated or unauthorized requests receive HTTP 401 or HTTP 403.
• Metrics Inventory:
  • HTTP Metrics: Request counts, error rates (4xx/5xx), request duration histograms, and payload byte counters broken down by route, method, and status code.
  • Host System Metrics (server/metrics/metrics.go):
    • system_disk_space_bytes: Available and total disk space on the underlying root filesystem (labels: path, type="total"|"used").
    • system_memory_bytes: Physical host memory utilization (labels: type="total"|"available"|"used").
    • system_cpu_usage_percent: Current CPU utilization percentage.
  • Runtime Metrics: Go runtime telemetry including active goroutines, heap allocations, and garbage collection pauses.

---

Container Security & Non-Root Execution

The official Shaper Docker image (taleshape/shaper) incorporates container security best practices:

• Immutable Base Images: The Dockerfile pins the Debian slim base and headless browser dependencies to immutable cryptographic SHA256 digests:
  • Base: debian:13.6-slim@sha256:3a39a0592364683e6bab97937b72cad5a8fa6dcbbee90edb3bb48c7f8e94f258
  • Browser: chromedp/headless-shell:151.0.7922.109@sha256:2d349b544a1ea6b5b5fd7c0fe99215ff662339c57407ee2e8c0a11af93516b04
• Non-Root Execution:
  • The container provisions a dedicated system group and user: shaper:shaper.
  • The docker-entrypoint.sh script verifies permissions on /data and /var/lib/shaper and immediately steps down from root privileges using gosu shaper before executing the Shaper binary.
• Attack Surface Reduction: Package manager caches, build dependencies, and temporary files are purged during container compilation (rm -rf /var/lib/apt/lists/*).
• Integrated Healthcheck: The container defines a non-verbose health check querying the local /health endpoint every 5 seconds.

---

6. Hardening Guide: Running Shaper Securely in Docker

To achieve a production-hardened deployment compliant with enterprise InfoSec benchmarks (e.g., CIS Benchmarks, SOC 2, ISO 27001), deploy the official Shaper container image (taleshape/shaper) using environment variables for configuration.

Container Deployment

Run the container with a dedicated persistent data volume and supply configuration via an environment file protected by strict permissions (chmod 0600):

docker run -d \
  --name shaper \
  --restart unless-stopped \
  -p 5454:5454 \
  -v /var/lib/shaper/data:/data \
  --env-file /etc/shaper/shaper.env \
  taleshape/shaper:latest

Production Environment File (/etc/shaper/shaper.env)

# /etc/shaper/shaper.env (chmod 0600)
SHAPER_ADDR="0.0.0.0:5454"
SHAPER_CORS_DOMAINS="example.com,https://app.example.com"
SHAPER_JWT_SECRET="<random-64-character-secret>"
SHAPER_NATS_JS_KEY="<high-entropy-encryption-key>"
SHAPER_ALLOWED_DUCKDB_EXTENSIONS="httpfs,parquet,json,postgres_scanner"
SHAPER_NO_DUCKDB_COMMUNITY_EXTENSIONS="true"
SHAPER_NO_PUBLIC_SHARING="true"
SHAPER_NO_PASSWORD_PROTECTED_SHARING="true"
SHAPER_NO_TASKS="true"
SHAPER_NO_EDIT="true"
SHAPER_SESSIONEXP="168h"
SHAPER_JWTEXP="15m"

Security Configuration Reference

Environment Variable	Recommended Setting	Rationale
SHAPER_CORS_DOMAINS	Explicit list (e.g. example.com,https://app.example.com)	Restricts CORS Access-Control-Allow-Origin to trusted application domains.
SHAPER_ALLOWED_DUCKDB_EXTENSIONS	Explicit list (e.g. parquet,httpfs)	Disables automatic extension installation and prevents downloading arbitrary binary extensions.
SHAPER_NO_DUCKDB_COMMUNITY_EXTENSIONS	true	Restricts extensions strictly to official DuckDB binaries, disallowing unverified community repositories.
SHAPER_NO_PUBLIC_SHARING	true	Prevents users from publishing dashboards to an unauthenticated public state.
SHAPER_NO_PASSWORD_PROTECTED_SHARING	true	Enforces identity-based access (SSO/JWT) by disabling standalone passphrase-protected public links.
SHAPER_NO_TASKS	true (if background jobs unused)	Disables the background task execution engine and task scheduler API entirely.
SHAPER_NO_EDIT	true (for GitOps environments)	Disables in-app dashboard authoring and editing in the UI. Enforces that all changes occur via Git and CI/CD pipelines.
SHAPER_JWT_SECRET	64+ char random string	Replaces the ephemeral auto-generated secret with a managed secret provisioned from an enterprise KMS/vault.
SHAPER_NATS_JS_KEY	High-entropy key	Encrypts NATS JetStream event storage and state replication at rest.
SHAPER_JWTEXP	15m	Enforces short lifespans for embedded tokens to minimize token replay windows.
SHAPER_SESSIONEXP	8h to 24h	Limits idle session duration for administrative web users.

---

Secrets & Storage Management

• Never Hardcode Secrets: Deliver sensitive credentials (such as SHAPER_JWT_SECRET and SHAPER_NATS_JS_KEY) through --env-file, Docker secrets, or Kubernetes Secrets—never commit them into version control or bake them into container images.
• Volume Permissions: Ensure the host directory mounted to /data has proper file ownership for the container’s unprivileged user (shaper:shaper, UID 1000).
• Startup SQL Files: When using SHAPER_INIT_SQL_FILE to mount data warehouse attachments, mount the file read-only (-v /etc/shaper/init.sql:/init.sql:ro) with host permissions 0400 or 0600, and leverage environment variable interpolation ($DB_PASSWORD) rather than hardcoding plaintext credentials.

---

Database Connection Isolation

• Least Privilege Credentials: When connecting Shaper to upstream databases (PostgreSQL, MySQL, Snowflake, BigQuery, ClickHouse), configure database credentials with strictly read-only privileges on specific analytical schemas.
• Container Network Isolation: Run the Shaper container on an isolated Docker bridge network or private VPC subnet with egress limited strictly to the required analytical database ports.

---

Network Boundaries & Ingress

• Enforce TLS 1.3 / HTTPS: Terminate TLS at an ingress reverse proxy (such as NGINX, Traefik, Caddy, or a cloud load balancer) or use Shaper’s built-in ACME engine (SHAPER_TLS_DOMAIN). Never expose unencrypted HTTP (port 5454) to public networks.
• CORS Restrictions: If embedding dashboards across distinct web properties, configure SHAPER_CORS_DOMAINS to restrict Access-Control-Allow-Origin to trusted application domains.
• Protect /metrics: Restrict network routing to the container’s /metrics endpoint so that only designated Prometheus scrapers can access the port, in addition to the mandatory API key verification.

---

7. Development & Software Supply Chain Security

Multi-Ecosystem Dependency Management & Pinning

Shaper adheres to strict supply chain security principles across all supported runtime languages and package ecosystems:

graph TD
    subgraph Ecosystems["Multi-Language Ecosystem"]
        direction TB
        Go["Go Engine<br/>(go.mod & go.sum)"]
        Node["Frontend UI<br/>(package.json & package-lock.json)"]
        Docker["Container Base<br/>(Debian & Chrome Headless)"]
        GHA["GitHub Actions<br/>(.github/workflows/*.yml)"]
        Python["Python Package<br/>(pip-package/pyproject.toml)"]
    end

    subgraph Defense["Supply Chain Controls"]
        direction TB
        Pin["Cryptographic SHA / Checksum Pinning"]
        Immutable["Immutable Release Tags<br/>(npm, Docker, PyPI)"]
        Cooldown["Dependabot 7-Day Cooldown Period"]
        NoScripts["npm ci --ignore-scripts (Neutralize Lifecycle Hooks)"]
    end

    subgraph Releases["Attestation & Provenance"]
        direction TB
        Cosign["Sigstore Cosign Keyless Signatures"]
        Provenance["SLSA Mode:MAX Build Provenance"]
        TrustedPub["OIDC Trusted Publishing (npm & PyPI)"]
    end

    Ecosystems --> Defense
    Defense --> Releases

1. Cryptographic Checksum Pinning:
   • Go: Dependencies are locked in go.mod with cryptographic hashes stored in go.sum.
   • Node.js: Versions and dependency trees are locked in package-lock.json. Frontend builds in CI run with npm ci --ignore-scripts to neutralize malicious pre/post-install lifecycle scripts.
   • Docker: Base images are pinned by exact cryptographic SHA256 digest (debian:13.6-slim@sha256:...).
   • GitHub Actions: Third-party actions in CI/CD workflows are pinned to full 40-character commit SHAs rather than mutable git tags (e.g., actions/checkout@3d3c42e5... # v7.0.1).
   • Python: Dependencies are strictly pinned in pyproject.toml.
2. Dependabot with 7-Day Cooldown Period:
   • Dependabot continuously monitors all 5 ecosystems (gomod, npm, docker, github-actions, pip).
   • A mandatory 7-day cooldown period (default-days: 7) is enforced across all ecosystems. Updates are withheld until a version has existed publicly for at least 7 days, significantly mitigating zero-day supply chain attacks and compromised package releases.
3. Registry Release Tag Immutability:
   • Release tags published to npm, Docker Hub, and PyPI are strictly immutable. Package versions and container image tags cannot be overwritten, modified, or retroactively replaced once published, protecting downstream systems from tag-sliding and dependency substitution attacks.

---

Complete Dependency Inventory

Core Go Runtime Dependencies (go.mod)

Module / Package	Version	Purpose
github.com/duckdb/duckdb-go/v2	v2.10505.0	In-process analytical SQL engine bindings
modernc.org/sqlite	v1.56.0	Pure-Go embedded SQLite engine (no CGO required)
github.com/nats-io/nats.go	v1.52.0	JetStream client for state replication and distributed messaging
github.com/nats-io/nats-server/v2	v2.14.4	Embedded NATS JetStream server engine
github.com/labstack/echo/v4	v4.15.4	Core HTTP/REST web framework and middleware engine
github.com/labstack/echo-jwt/v4	v4.4.0	JWT middleware for token parsing and authentication
github.com/golang-jwt/jwt/v5	v5.3.1	JSON Web Token issuance, signing, and verification
golang.org/x/crypto	v0.54.0	Cryptographic primitives (bcrypt, ACME/autocert)
github.com/prometheus/client_golang	v1.23.2	Prometheus telemetry client and metric registries
github.com/shirou/gopsutil/v4	v4.26.6	Host system performance metrics (CPU, disk, memory)
github.com/chromedp/chromedp	v0.15.1	Headless Chrome instrumentation for PDF/PNG generation
github.com/xuri/excelize/v2	v2.11.0	Automated report generation in Excel (XLSX) format
github.com/jmoiron/sqlx	v1.4.0	General database abstraction library
github.com/nrednav/cuid2	v1.1.0	Cryptographically secure collision-resistant unique IDs
github.com/samber/slog-echo	v1.23.0	Structured JSON logging integration for Echo

Key Frontend Dependencies (package.json)

Package	Version	Purpose
react / react-dom	^18.3.1	Core UI rendering framework
@tanstack/react-router	^1.170.15	Client-side routing with type-safe search parameters
echarts	^6.1.0	High-performance interactive charting engine
monaco-editor	^0.55.1	In-browser SQL code editor with syntax highlighting
@radix-ui/react-*	Various	Accessible, unstyled UI primitives (dialogs, menus, tabs)
tailwindcss	^3.4.19	Utility-first CSS styling framework
clsx / tailwind-merge	Various	Class name composition and deduplication utilities

Container Base Images (Dockerfile)

Base Image	Digest	Purpose
debian:13.6-slim	sha256:3a39a0592364683e6bab97937b72cad5a8fa6dcbbee90edb3bb48c7f8e94f258	Minimal, hardened runtime container OS
chromedp/headless-shell:151.0.7922.109	sha256:2d349b544a1ea6b5b5fd7c0fe99215ff662339c57407ee2e8c0a11af93516b04	Isolated headless browser binary for PDF rendering

---

Cryptographic Code Signing & SLSA Build Provenance

All release artifacts undergo cryptographic verification and signing during automated CI runs:

graph LR
    Build["GitHub Actions Runner (OIDC Token)"]
    Cosign["Sigstore Cosign"]
    Attest["GitHub Artifact Attestations"]

    Artifacts["Binaries & Checksums<br/>(SHA256SUMS)"]
    DockerImg["Docker Images<br/>(taleshape/shaper)"]
    Registries["npm & PyPI Packages"]

    Build -->|Keyless Signing| Cosign
    Build -->|SLSA Provenance Mode:MAX| Attest

    Cosign -->|Detached Signature Bundle| Artifacts
    Cosign -->|Signed Image Signature| DockerImg
    Attest -->|Cryptographic Attestation| Artifacts
    Attest -->|Cryptographic Attestation| DockerImg
    Build -->|Trusted Publishing OIDC| Registries

1. Keyless Signing with Sigstore Cosign:
   • Release binaries, checksums (SHA256SUMS), and Docker images are signed keylessly using Sigstore Cosign.
   • Signatures are tied to GitHub’s OpenID Connect (OIDC) identity (https://token.actions.githubusercontent.com) matching the taleshape-com/shaper repository.
2. SLSA Build Provenance:
   • GitHub Artifact Attestations (actions/attest-build-provenance) generate cryptographic provenance records for all binary builds and container images.
   • Container images are built with mode max provenance and embedded Software Bills of Materials (sbom: true, provenance: mode=max).
3. Trusted Publishing (OIDC):
   • npm Package: Published using --provenance via OIDC Trusted Publishing on npmjs.com.
   • PyPI Package: Published via PEP 740 digital attestations and OIDC Trusted Publishing (no static API tokens stored in CI).

Verifying Release Artifacts

Enterprise evaluators and administrators can verify artifact integrity using the following commands:

Verifying Docker Hub Container Images

cosign verify \
  --certificate-identity-regexp "^https://github.com/taleshape-com/shaper/" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  taleshape/shaper:<version>

Or via GitHub CLI:

gh attestation verify oci://taleshape/shaper:<version> --owner taleshape-com

Verifying Binary Releases & Checksums

# 1. Verify the checksums file signature
cosign verify-blob \
  --bundle SHA256SUMS.cosign.bundle \
  --certificate-identity-regexp "^https://github.com/taleshape-com/shaper/" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  SHA256SUMS

# 2. Validate the downloaded binary against the verified checksums
sha256sum -c SHA256SUMS --ignore-missing

# 3. Verify SLSA build provenance via GitHub CLI
gh attestation verify shaper-linux-amd64 --owner taleshape-com

---

Immutable Release Tags across Registries (npm, Docker, PyPI)

To protect downstream users, consumer applications, and automated deployment pipelines from software supply chain tampering, Shaper enforces strict artifact and release tag immutability across all public distribution registries:

Registry	Published Artifact	Immutability Mechanism & Policy	Security Guarantee
npm	@taleshape/shaper-sdk @taleshape/shaper	Package version immutability; permanent version number retirement on unpublish	A published version number can never be overwritten, modified, or re-published with altered JavaScript/TypeScript code.
Docker Hub	taleshape/shaper:<version>	Fixed cryptographic SHA256 image manifest digests (sha256:...), signed with Sigstore Cosign & SLSA Mode:MAX	Version tags cannot be mutated without invalidating cryptographic Cosign signatures and SLSA provenance attestations.
PyPI	shaper-sdk	Native PyPI strict release immutability policy and PEP 740 OIDC provenance attestations	PyPI permanently prohibits modifying, replacing, or re-uploading distribution files (.whl, .tar.gz) under an existing version number.

Detailed Registry Immutability Architecture

1. npm Version Immutability:

   • The public npm registry enforces permanent package immutability. Once a package version (e.g., @taleshape/shaper-sdk@1.2.0) is published, its contents cannot be altered, overwritten, or re-uploaded.
   • Under npm’s registry unpublish policy, version removal is restricted to an emergency 72-hour window. Even if a version is removed, npm permanently retires that specific version number—it can never be reused, uploaded, or republished by anyone.
   • Downstream consumers running npm ci or npm install are guaranteed deterministic artifacts verified against cryptographic integrity hashes (sha512-...) in package-lock.json.

2. Docker Hub & Container Image Tag Immutability:

   • Release version tags (e.g., taleshape/shaper:0.x.x) correspond to exact, cryptographically immutable OCI manifest digests (sha256:...).
   • Every release image is signed with Sigstore Cosign keyless signatures and accompanied by SLSA Mode:MAX build provenance attestations. Any attempt to modify layers or slide a tag to a different container image invalidates the cryptographic signature, causing automated verification checks in downstream deployment pipelines and Kubernetes admission controllers (e.g., Kyverno, OPA Gatekeeper) to immediately fail.
   • For zero-trust production deployments requiring absolute immutability, deployments can pull directly by the cryptographic SHA256 digest:

     docker run -d taleshape/shaper@sha256:<immutable-manifest-digest>

3. PyPI Release Immutability:

   • The Python Package Index (PyPI) enforces strict, permanent immutability by design. Once a release file (source distribution .tar.gz or built wheel .whl) has been uploaded for a specific version of shaper-sdk, PyPI strictly prohibits deleting, replacing, overwriting, or modifying that file under any circumstances.
   • Any bugfix or security patch requires releasing an incremental version number (e.g., 1.2.1).
   • Packages are published via OIDC Trusted Publishing (eliminating static credentials) and signed with PEP 740 digital attestations cryptographically linking the artifact to the specific GitHub Actions workflow execution.

Threat Vectors Mitigated

• Neutralizes “Tag-Sliding” Attacks: Attackers with compromised publishing credentials cannot quietly replace an existing, trusted release tag with trojanized code or malicious payloads.
• Guarantees Deterministic & Reproducible Builds: Eliminates non-deterministic deployment discrepancies where separate servers pulling the same release version could execute differing code.
• Satisfies Enterprise Compliance Standards: Fulfills supply chain integrity controls outlined in NIST SP 800-218 (Secure Software Development Framework - SSDF), OpenSSF Scorecards, and SOC 2 Type II supply chain verification requirements.

---

Branch Protection & CI Review Controls

To safeguard the codebase against unauthorized or unreviewed modifications:

• Protected Main Branch: Direct pushes to main are restricted. All code changes must be submitted via Pull Requests.
• Mandatory CI Gates: Pull requests cannot be merged until the following automated checks succeed:
  • Frontend validation: npm run all (eslint, tsc typecheck, vitest, production build with --ignore-scripts).
  • Backend validation: go vet ./..., golangci-lint, and unit test execution (go test ./...).
  • Multi-platform cross-compilation builds (Linux amd64/arm64, macOS amd64/arm64).
  • All automated security analysis workflows pass without blocking findings.

---

8. Automated Security Scanning Pipeline

Automated security checks run on every pull request, on every push to main, and on a weekly recurring schedule (Sundays at 03:00 UTC) via .github/workflows/security.yml:

graph LR
    subgraph Triggers["Pipeline Triggers"]
        PR["Pull Requests targeting 'main'"]
        Push["Pushes to 'main'"]
        Cron["Weekly Schedule (Sunday 03:00 UTC)"]
    end

    subgraph Scans["Security Scanning Suite (.github/workflows/security.yml)"]
        CodeQL["GitHub CodeQL (SAST)<br/>• Go (autobuild)<br/>• JavaScript / TypeScript"]
        GoVuln["Go Vulnerability Check<br/>• govulncheck ./..."]
        Gitleaks["Secret Detection<br/>• gitleaks detect --verbose --redact"]
        Zizmor["CI Workflow Security<br/>• zizmor . (GitHub Actions linter)"]
        OSV["Dependency Vulnerability Scan<br/>• osv-scanner -r ."]
    end

    Triggers --> Scans

Scan Matrix & Tooling

1. GitHub CodeQL (Static Application Security Testing - SAST):
   • Scans backend Go and frontend JavaScript/TypeScript code for Common Weakness Enumerations (CWEs), injection vulnerabilities, improper error handling, and unsafe data flows.
2. Go Vulnerability Check (govulncheck):
   • Queries the official Go vulnerability database to identify known CVEs affecting imported Go modules, evaluating call-graph reachability to eliminate false positives.
3. Secret Scanning (Gitleaks):
   • Analyzes git commits, diffs, and repository history (gitleaks detect --verbose --redact) for exposed secrets, private keys, cloud credentials, and API tokens.
4. GitHub Actions Security Analysis (zizmor):
   • Performs static analysis of GitHub Actions workflows to detect security anti-patterns, insecure triggers, dangerous permissions, code injection risks, and secret leakage in CI runners.
5. Open Source Vulnerability Scanner (osv-scanner):
   • Developed by Google, osv-scanner recursively evaluates all project dependency manifests against the distributed Open Source Vulnerabilities (OSV) database.

---

9. Vulnerability Handling & Disclosure

Taleshape is committed to responsible, coordinated vulnerability disclosure.

Supported Versions

Security patches and updates are provided for the latest release and the current main branch:

Version	Security Maintenance
Latest Release	Supported
Current main	Supported
Prior Releases	Not Supported (Upgrade Required)

---

Reporting Channels & Response SLAs

Security vulnerabilities must not be reported via public GitHub issues, discussions, or pull requests.

• Primary Method (Preferred): GitHub Private Vulnerability Reporting via the repository Security Advisories tab.
• Alternative Method: Direct email to hi@taleshape.com.

Response SLAs & Handling Stages

1. Acknowledgment: Receipt of the vulnerability report is acknowledged within 48 hours.
2. Triage & Assessment: The engineering team verifies reproduction, determines severity using CVSS v3.1 scoring, and maintains open communication with the reporter.
3. Patch Development: Fixes are developed in private forks and validated against automated CI security suites.
4. Coordinated Disclosure: A security advisory (GHSA/CVE) is published alongside a patched release, giving appropriate attribution to the reporter (unless anonymity is requested).

For full policy details, consult SECURITY.md.

---

10. Shared Responsibility: Self-Hosted vs. On-Premise Managed Hosting

Security and regulatory compliance follow a shared responsibility model. Depending on whether your organization self-hosts open-source Shaper or engages Taleshape Managed Hosting, operational duties are allocated as follows:

Responsibility Matrix

Responsibility Area	Self-Hosted (Open Source)	Taleshape On-Premise Managed Hosting
Analytical Data Ownership	Customer (100% on-premise)	Customer (100% on-premise — Zero Taleshape data access)
Direct Infrastructure & SSH Access	Customer only	Customer only — Taleshape has zero direct access and no SSH access
Infrastructure & Updates Workflow	Customer manages manually or via internal tooling	Managed entirely through code: Taleshape submits PRs; customer approves every PR
Hardware & Virtual Machines	Customer provisions and manages	Customer provisions host/VM (initial setup); subsequent updates occur solely through code
Application Deployment & Upgrades	Customer tracks and applies releases	Taleshape prepares upgrade PRs for customer review and approval
Security Patches & Vulnerabilities	Customer monitors advisories and patches	Taleshape proactively submits security patch PRs for customer approval
Backup & Disaster Recovery	Built-in: configured by specifying an S3 bucket; Shaper auto-snapshots and restores when needed	Built-in: configured by specifying an S3 bucket; Shaper auto-snapshots and restores when needed (Taleshape assists with configuration)
High Availability & Health Monitoring	Customer monitors system health	Customer monitors system health (Taleshape provides health check and metrics configuration)
Platform Hardening & Configuration	Customer configures security environment variables	Taleshape delivers production-hardened configurations via code PRs
Compliance & Audit Assistance	Customer handles compliance independently	Taleshape provides SOC 2 / ISO 27001 / HIPAA audit support
User & API Key Access Management	Customer manages users and permissions	Customer manages users and permissions
SQL Queries & Dashboard Authoring	Customer authors queries	Customer authors queries (with optional guidance)

---

Taleshape On-Premise Managed Hosting Model

Taleshape offers an On-Premise Managed Hosting service tailored for enterprise security, finance, and healthcare organizations with strict regulatory constraints.

A core security principle of Taleshape Managed Hosting is that Taleshape never has direct infrastructure access:

• Infrastructure Managed Entirely Through Code: Infrastructure configurations, container definitions, and application settings are managed strictly through code (GitOps / Infrastructure-as-Code).
• Updates Exclusively via Code Changes: After the initial VM setup, the system is updated exclusively through code changes.
• Customer Approves Every Pull Request: Taleshape engineers submit version upgrades, security patches, and configuration improvements as Pull Requests to the customer’s repository. The customer has to review and approve each pull request before changes are merged and deployed.
• Zero Direct Access & No SSH: Taleshape has no SSH access, no remote agent backdoors, and no inbound network access to the customer’s infrastructure. Full sovereign operational control remains in the customer’s hands.

graph TD
    subgraph CustomerInfra["Customer Private Infrastructure (VPC / On-Premise Datacenter)"]
        subgraph DataZone["Isolated Data Zone"]
            Warehouse["Internal Databases & Data Warehouse<br/>(PostgreSQL, Snowflake, ClickHouse, S3)"]
        end

        subgraph ShaperDeployment["Shaper Production Cluster"]
            ShaperApp["Shaper Application Nodes<br/>• Self-Contained<br/>• Local DuckDB Execution<br/>• Local State Storage"]
        end

        subgraph CustomerGit["Customer Git Repository & CI/CD Pipeline"]
            Repo["Git Repository & CI/CD<br/>• Customer Approval Gate<br/>• Each PR Requires Customer Sign-off<br/>• Automated Deployment on Merge"]
        end

        S3Backup["Customer S3 Bucket<br/>(Configured via SHAPER_SNAPSHOT_S3_BUCKET<br/>Auto-snapshots & Auto-restore)"]
    end

    subgraph TaleshapeOps["Taleshape Operations (Zero Direct Access)"]
        Ops["Taleshape Engineers<br/>• Infrastructure-as-Code<br/>• Proactive Version & Patch PRs<br/>• No Direct Infrastructure Access<br/>• No SSH Access"]
    end

    Warehouse <-->|"Direct Local Queries (Never leaves customer network)"| ShaperApp
    Ops -->|"Submits Pull Requests (Code Only — No SSH)"| Repo
    Repo -->|"Automated Deploy (Triggered by Customer Approval)"| ShaperApp
    ShaperApp <-->|"Automated Snapshots & Auto-Restore"| S3Backup

Key Guarantees of On-Premise Managed Hosting

1. Zero Direct Access & No SSH:
   • Taleshape never has direct infrastructure access and maintains no SSH access to customer virtual machines or servers.
   • All management is performed entirely through code. After initial VM setup, the system is updated exclusively through code changes.
   • Every single upgrade or configuration change is delivered as a Pull Request that must be reviewed and approved by the customer.
2. Data Remains 100% Within Your Perimeter:
   • Shaper runs directly inside the customer’s cloud VPC (AWS, Azure, GCP) or private physical data center.
   • Analytical queries, data tables, and dashboard outputs execute entirely within the customer’s network boundary.
   • Taleshape has zero access to analytical data, customer database rows, or dashboard contents.
3. Simple, Built-In S3 Backups & Automatic Restore:
   • Backups do not rely on complicated external orchestration pipelines or proprietary backup agents.
   • Backups are simply configured by specifying an S3 bucket (via SHAPER_SNAPSHOT_S3_BUCKET / --snapshot-s3-bucket).
   • Shaper automatically creates snapshots on schedule and automatically restores backups when needed on startup.
   • All backup data remains encrypted and strictly within the customer’s owned S3 bucket.
4. Proactive Upgrades & Patch Management via PR:
   • Taleshape engineers proactively monitor dependencies and upstream security advisories.
   • Security patches and version upgrades are prepared, tested, and submitted as customer-reviewed Pull Requests, minimizing customer operational overhead while maintaining strict change control.
5. Audit Readiness & Compliance Support:
   • Taleshape assists enterprise security teams with vendor risk assessments, penetration test reviews, and compliance mapping for standards including SOC 2 Type II, ISO/IEC 27001, HIPAA, and GDPR.
   • For complete corporate compliance details, clean-room support policies, sub-processors, and our SOC 2 roadmap, see our Corporate Security & Compliance Overview.
   • Healthcare organizations can review and execute our standard Business Associate Agreement (BAA) Template.

---

For inquiries regarding security assessments, penetration testing reports, BAA execution, or on-premise managed hosting, contact the Taleshape security team at security@taleshape.com.