# Security

<div class="security-breadcrumb">
  <a href="/shaper/docs/">← Back to Documentation</a>
</div>

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](https://duckdb.org)), system metadata database ([SQLite](https://sqlite.org)), and cluster event broker ([NATS JetStream](https://nats.io))—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:

```mermaid
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:

```mermaid
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.

```mermaid
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](https://taleshape.com/shaper/docs/single-sign-on).

> If you are interested in native OpenID Connect (OIDC) or Proxy Header Authentication for your deployment, please [reach out to our team](https://taleshape.com/contact).

---

## 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](https://taleshape.com/shaper/docs/tasks-and-scheduling#disable-tasks-functionality) and [Configuration Options](https://taleshape.com/shaper/docs/configuration-options#no-tasks).

---

### 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`):

```bash
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`)

```ini
# /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:

```mermaid
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:

```mermaid
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
```bash
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:
```bash
gh attestation verify oci://taleshape/shaper:<version> --owner taleshape-com
```

##### Verifying Binary Releases & Checksums
```bash
# 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`<br/>`@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:
     ```bash
     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`](https://github.com/taleshape-com/shaper/blob/main/.github/workflows/security.yml):

```mermaid
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](https://github.com/taleshape-com/shaper/security/advisories/new) via the repository Security Advisories tab.
* **Alternative Method**: Direct email to **[hi@taleshape.com](mailto: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`](https://github.com/taleshape-com/shaper/blob/main/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.

```mermaid
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](https://taleshape.com/shaper/docs/compliance).
   - Healthcare organizations can review and execute our standard [Business Associate Agreement (BAA) Template](https://taleshape.com/legal/baa).

---

*For inquiries regarding security assessments, penetration testing reports, BAA execution, or on-premise managed hosting, contact the Taleshape security team at [security@taleshape.com](mailto:security@taleshape.com).*