shipzy
Get started

Security

The safest system is one where we never hold anything worth stealing. This page explains how shipzy is built around that, what it is allowed to do in your account, and where its limits are.

The short version. shipzy runs on your machine and in your AWS account. We operate no servers, no accounts and no database, so there is no shipzy backend that could be breached to reach your sites, your code or your keys.

What runs where

PlaceWhat runs there
Your machineThe CLI, the optional local dashboard, and local builds. It uses your own AWS profile.
Your AWS accountThe sites, the CDN, builds, the two functions, and your secrets. Everything uses roles scoped to that stack.
GitHubYour repository, and a webhook that calls your own function URL.
Servers we operateNone. The CLI is delivered through the npm registry and nothing phones home.

Permissions: what shipzy is allowed to do

An administrator key works, but it is far more than the tool needs. We publish a policy that allows only what shipzy does, and a script that creates a user with it:

  • CloudFormation stacks, S3 buckets, Lambda functions and IAM roles whose names start with the stack name;
  • CloudFront, CodeBuild, certificates, Route 53 records, and the stack’s own parameters and two secrets;
  • nothing else: not your other buckets, not other IAM users or access keys, not other services.

Download the policy and the script, and read them before you run anything. We checked the policy with the AWS policy simulator, and by running setup, deploys (local, remote and GitHub), domains, rollback, delete and destroy with a user that has only this policy.

Inside the stack, three roles do the work, and each can only reach this stack’s own resources:

RoleCan
BuildRead and write the sites bucket, read its source, invoke the publish function, read the GitHub token and this stack’s parameters, and write its own logs
EngineRead and write the sites bucket and the routing table
WebhookRead project history, read the webhook secret, and start builds on this project

Secrets and tokens

  • No long-lived keys are stored by shipzy. The CLI uses your AWS profile, and everything in AWS uses roles.
  • Your GitHub token lives in Secrets Manager and is passed to git in a request header, never in a URL, so it cannot show up in error output.
  • Environment variables are stored as encrypted parameters. Their values are never printed, returned by the dashboard, or written to a log, and they travel to a process by environment or standard input, never on a command line.
  • The webhook secret is generated in your account and never printed. If it is ever exposed, one command replaces it.

The webhook

The webhook URL is public by design, so the protection is GitHub’s HMAC-SHA256 signature, checked in constant time against a secret from your account. A request without a valid signature gets a 401 and starts nothing.

For pull request previews, only branches of the same repository are built, because a build receives your project’s variables and a fork’s code must never see them. Before a preview goes live, the publish function asks GitHub whether the pull request is still open and still at that commit, so a late or superseded build never goes live.

Your files

Both buckets are private, and visitors only reach your files through CloudFront. The sites bucket allows distributions in the same AWS account to read it, and nothing outside the account can.

The local dashboard

  • It listens on 127.0.0.1 only, so it is not reachable from your network.
  • Every launch has a random token. Opening the printed address signs your browser in with a cookie, and requests need that cookie, a matching Host header (against DNS rebinding) and, for changes, a matching Origin (against cross-site requests).
  • Every value from the browser is validated before it becomes an argument, and commands are run as argument lists, never through a shell.
  • A GitHub login made through the dashboard is held in the memory of the running process and is never written to disk or sent to the browser.

Honest limits

Early preview. shipzy has not had an independent security audit. Read the code (it is open source), and start with a throwaway AWS account if you are cautious.
  • Builds run your code. CodeBuild executes your project’s install and build scripts in your account, with the build role’s permissions. Only build code you trust.
  • The CLI policy can create roles named for the stack. Someone holding that key could attach extra rights to such a role. Treat the key as sensitive, do not share it, and prefer a short-lived profile where you can.
  • AWS has no hard spending cap. A traffic spike or an attack can raise your bill. Create an AWS Budget alert for the account. A guided alarm in shipzy init is planned.
  • The local dashboard trusts your machine. Anyone who can use your browser session while it runs has your AWS access through it. Stop it when you are done.
  • The dashboard’s GitHub login asks for the repo scope. That is broader than a token limited to one repository. If you prefer the narrower one, paste a token instead.

Verify it yourself

shipzy is open source under the Apache-2.0 license. The CLI package is a single bundled file with no runtime dependencies, which keeps what you install small enough to read. Everything it creates is a plain CloudFormation stack you can inspect, change or delete, and shipzy destroy removes all of it.

More detail on each part is in limits and roadmap and AWS setup.