Documentation for signed pipelines

data/nav.yml

@@ -255,6 +255,8 @@
           path: "pipelines/build-retention"
         - name: "Public pipelines"
           path: "pipelines/public-pipelines"
+        - name: "Signed pipelines"
+          path: "pipelines/signed-pipelines"
         - name: "Using build meta-data"
           path: "pipelines/build-meta-data"
         - name: "Managing log output"

pages/pipelines/command_step.md

@@ -175,6 +175,21 @@ _Optional attributes:_
       Available types: <code>automatic</code>, <code>manual</code>
     </td>
   </tr>
+  <tr>
+    <td><code>signature</code></td>
+    <td>
+      Signs the pipeline upload for extra security<br>
+      <code>- label: "signed build"<br>
+      &nbsp;&nbsp;command: "run-signed-build.sh"<br>
+      &nbsp;&nbsp;&nbsp;&nbsp;signature:<br>
+      &nbsp;&nbsp;&nbsp;&nbsp; value: "Some signature"<br>
+      &nbsp;&nbsp;&nbsp;&nbsp; version: "2"<br>
+      &nbsp;&nbsp;&nbsp;&nbsp; hashing_algorithm: "hmac-sha256"<br>
+      &nbsp;&nbsp;&nbsp;&nbsp; signed_keys:<br>
+      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - "command"<br>
+      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - "env"<code>
+    </td>
+  </tr>
   <tr>
     <td><code>skip</code></td>
     <td>
@@ -295,7 +310,7 @@ Conditions on retries can be specified. For example, it's possible to set steps
     command: "deploy.sh"
     branches: "main"
     retry:
-      manual: 
+      manual:
         allowed: false
         reason: "Deploys shouldn't be retried"
 ```
@@ -502,6 +517,49 @@ To set `cancel_on_build_failing: true` for all jobs in a Build:
 
  -->
 
+ ## Signature attributes
+
+ <table>
+  <tr>
+    <td><code>value</code></td>
+    <td>
+      Placeholder
+    </td>
+  </tr>
+  <tr>
+    <td><code>version</code></td>
+    <td>
+      Placeholder
+    </td>
+  </tr>
+  <tr>
+    <td><code>hashing_algorithm</code></td>
+    <td>
+      Placeholder
+    </td>
+  </tr>
+  <tr>
+    <td><code>signed_keys</code></td>
+    <td>
+      Placeholder
+    </td>
+  </tr>
+</table>
+
+ ```yml
+ steps:
+  - label: "Signed pipeline"
+    command: "run-signed-pipeline.sh"
+    signature:
+      value: "Some signature"
+      version: "2"
+      hashing_algorithm: "hmac-sha256"
+      signed_keys:
+         - "command"
+         - "env"
+ ```
+ {: codeblock-file="pipeline.yml"}
+
 ## Example
 
 

pages/pipelines/signed_pipelines.md

@@ -0,0 +1,49 @@
+# Signed pipelines
+
+handy links for writing docs:
+https://3.basecamp.com/3453178/buckets/27608512/messages/5774300120
+https://3.basecamp.com/3453178/buckets/27608512/messages/5725400045
+
+
+We know that builds and deploys can be run on highly privileged machines, and that an attacker convincing that machine to run a malicious command could compromise production infrastructure.
+As customer secuirty is paramount to Buildkite, and we wish to ensure thata all customers are immune by default from our control plane being compromised.
+
+Signed pipelines allow users to sign the pipelines they upload, which means that agents can refuse to run jobs that are not signed by a trusted public key. This makes it impossible for Buildkite (or an attacker thereof) to tamper with the workload that Buildkite orchestrates onto customer infrastructure.
+
+* link to best practices?
+* mention exisitng tool on github? https://github.com/buildkite/buildkite-signed-pipeline
+* Maybe this should live in security? Not sure
+
+Sensitive data, such as source code and secrets, remain within your own environment and are not seen by Buildkite. We are aware that many customers invest heavily in configuring their agents to reject jobs that don't match some set of expectations, such as pipeline/repo/branch filtering, limiting to in-repo scripts not arbitrary commands etc.
+
+
+
+We know that customers choose Buildkite because our hybrid model gives them a world-class SaaS control plane while keeping most of the trust/risk behind their firewall on their own infrastructure. We encourage customers to not trust Buildkite's control plane, but the tools to do that (agent hooks, allow-listing etc) aren't ergonomic nor robust.
+
+Cryptographically signing and verifying build steps by default would close a big gap in our “you don't even need to trust our servers” story. And if we were ever breached, it could save our customers and enough of our reputation to survive.
+
+Customers can optionally sign pipeline uploads using just the buildkite-agent
+The buildkite-agent can optionally verify job signatures, and reject jobs if they don't have the right signature
+A malicious actor using buildkite to target an attack against one of our customers cannot successfully run malicious actions on customer agents
+
+Making a pipeline public provides read-only public/anonymous access to:
+
+Targets for signed pipelines includes
+
+- Command
+- Pipeline build logs
+- Environment variables from the uploaded pipeline
+- Plugins
+
+
+## Pretty diagram of agent/bk interaction with signed pipeline?
+
+## Attack Scenarios (maybe)
+
+Make a pipeline public in the _Pipeline Settings_ in the _General_ tab:
+
+<%= image "settings.png", width: 1960/2, height: 630/2, alt: "Public pipeline settings" %>
+
+## Random headings we might use:
+
+## Handy links about signutures/signing