in-toto/witness in-toto/witness

  • Stars
    star
    409
  • Rank 105,709 (Top 3 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created almost 3 years ago
  • Updated about 1 month ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
in-toto/witness
github

in-toto

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Witness is a pluggable framework for software supply chain risk management. It automates, normalizes, and verifies software artifact provenance.

OpenSSF -Scorecard


Witness is a pluggable framework for supply chain security

asciicast

Witness - Secure Your Supply Chain

Witness is a pluggable framework for supply chain security that creates an evidence trail of the entire software development life cycle (SDLC) to ensure the integrity of your software from source to target. It supports most major CI and infrastructure providers, and uses a secure PKI distribution system to enhance security and mitigate against software supply chain attack vectors.

Witness works by wrapping commands executed in a continuous integration process, providing an evidence trail of every action in the software development life cycle (SDLC). This allows for a detailed and verifiable record of how the software was built, who built it, and what tools were used. This evidence can be used to evaluate policy compliance and detect any potential tampering or malicious activity and ensure only authorized users or machines completes a step of the process. Additionally, Witness's attestation system is pluggable and offers support for most major CI and infrastructure providers, making it a versatile and flexible solution for securing software supply chains. Furthermore, the use of a secure PKI distribution system and the ability to verify Witness metadata further enhances the security of the process and helps mitigate against many software supply chain attack vectors.

NOTE: the attestor code has been split into repo https://github.com/testifysec/go-witness

Witness enables you to:

  • Verify who built the software, how it was built and what tools were used
  • Detect any potential tampering or malicious activity
  • Ensure that only authorized users or machines complete each step of the process
  • Distribute attestations and policy across air gaps

Witness is a pluggable framework for supply chain security

  • It creates an evidence trail of the entire software development life cycle (SDLC) that can be used to evaluate policy compliance and detect any potential tampering or malicious activity.
  • It is designed to run in both containerized and non-containerized environments and does not require elevated privileges.
  • It supports most major CI and infrastructure providers, making it a versatile and flexible solution for securing software supply chains.
  • It uses a secure PKI distribution system and allows for verification of Witness metadata to further enhance security and mitigate against software supply chain attack vectors.

Key Features

  • Implementation of the in-toto specification including ITE-5, ITE-6, and ITE-7, and an embedded rego policy engine for build policy enforcement.
  • Support for keyless signing with Sigstore and SPIFFE/SPIRE, and uploading attestation evidence to the Archivista server.
  • Support for RFC3161 compatible timestamp authorities
  • Experimental support for process tracing and process tampering prevention.
  • Verifies file integrity between CI steps and across air gap.
  • Support for Darwin, Windows, and ARM architectures.
  • Can use Archivista as an attestation store.
  • Integrations with GitLab, GitHub, AWS, and GCP.

How it works

  • Witness wraps commands executed during a continuous integration process to create an evidence trail of the entire software development life cycle (SDLC)
  • It records secure hashes of materials, artifacts, and events that occur during the CI process
  • This evidence can be used to evaluate policy compliance, detect tampering or malicious activity, and ensure only authorized users or machines complete a step of the process
  • Witness's attestation system is pluggable and supports most major CI and infrastructure providers
  • It uses a secure PKI distribution system and can verify Witness metadata to enhance security and mitigate against many software supply chain attack vectors
  • Witness is an implementation of the in-toto specification, including ITE-5, ITE-6, and ITE-7, and includes an embedded rego policy engine for build policy enforcement with Open Policy Agent
  • It can run in both containerized and non-containerized environments without requiring elevated privileges
  • It supports keyless signing with Sigstore and SPIFFE/SPIRE and uploading attestation evidence to the Archivista server
  • It offers experimental support for tracing and process tampering prevention and can verify file integrity between CI steps and across air gap
  • It supports Darwin, Windows, and ARM architectures and can use Archivista as an attestation store
  • Overall, Witness acts as a comprehensive framework for automated governance, providing a robust solution for securing the software supply chain.

Witness Examples

Media

Usage

  • Run - Runs the provided command and records attestations about the execution.
  • Sign - Signs the provided file with the provided key.
  • Verify - Verifies a witness policy.

TOC

Quick Start

Download the Binary

Download from the releases page or use the install script to download the latest release.

Releases

bash <(curl -s https://raw.githubusercontent.com/in-toto/witness/main/install-witness.sh)

Create a Keypair

Witness supports keyless signing with SPIRE!

openssl genpkey -algorithm ed25519 -outform PEM -out testkey.pem
openssl pkey -in testkey.pem -pubout > testpub.pem

Create a Witness configuration

  • This file generally resides in your source code repository along with the public keys generated above.
  • .witness yaml is the default location for the configuration file
  • witness help will show all configuration options
  • command-line arguments overrides configuration file values.
## .witness.yaml

run:
    signer-file-key-path: testkey.pem
    trace: false
verify:
    attestations:
        - "test-att.json"
    policy: policy-signed.json
    publickey: testpub.pem

Record attestations for a build step

  • The -a {attestor} flag allows you to define which attestors run
  • ex. -a maven -a gcp -a gitlab would be used for a maven build running on a GitLab runner on GCP.
  • Defining step names is important, these will be used in the policy.
  • This should happen as a part of a CI step
witness run --step build -o test-att.json -- go build -o=testapp .

View the attestation data in the signed DSSE Envelope

  • This data can be stored and retrieved from Archivista
  • This is the data that is evaluated against the Rego policy
cat test-att.json | jq -r .payload | base64 -d | jq

Create a Policy File

Look here for full documentation on Witness Policies.

  • Make sure to replace the keys in this file with the ones from the step above (sed command below).
  • Rego policies should be base64 encoded
  • Steps are bound to keys. Policy can be written to check the certificate data. For example, we can require a step is signed by a key with a specific CN attribute.
  • Witness will require all attestations to succeed
  • Witness will evaluate the rego policy against the JSON object in the corresponding attestor
## policy.json

{
  "expires": "2023-12-17T23:57:40-05:00",
  "steps": {
    "build": {
      "name": "build",
      "attestations": [
        {
          "type": "https://witness.dev/attestations/material/v0.1",
          "regopolicies": []
        },
        {
          "type": "https://witness.dev/attestations/command-run/v0.1",
          "regopolicies": []
        },
        {
          "type": "https://witness.dev/attestations/product/v0.1",
          "regopolicies": []
        }
      ],
      "functionaries": [
        {
          "publickeyid": "{{PUBLIC_KEY_ID}}"
        }
      ]
    }
  },
  "publickeys": {
    "{{PUBLIC_KEY_ID}}": {
      "keyid": "{{PUBLIC_KEY_ID}}",
      "key": "{{B64_PUBLIC_KEY}}"
    }
  }
}

Replace the variables in the policy

id=`sha256sum testpub.pem | awk '{print $1}'` && sed -i "s/{{PUBLIC_KEY_ID}}/$id/g" policy.json
pubb64=`cat testpub.pem | base64 -w 0` && sed -i "s/{{B64_PUBLIC_KEY}}/$pubb64/g" policy.json

Sign The Policy File

Keep this key safe, its owner will control the policy gates.

witness sign -f policy.json --signer-file-key-path testkey.pem --outfile policy-signed.json

Verify the Binary Meets Policy Requirements

This process works across air-gap as long as you have the signed policy file, correct binary, and public key or certificate authority corresponding to the private key that signed the policy. witness verify will return a non-zero exit and reason in the case of failure. Success will be silent with a 0 exit status for policies that require multiple steps, multiple attestations are required.

witness verify -f testapp -a test-att.json -p policy-signed.json -k testpub.pem

Witness Attestors

What is a witness attestor?

Witness attestors are pieces of code that assert facts about a system and store those facts in a versioned schema. Each attestor has a Name, Type, and RunType. The Type is a versioned string corresponding to the JSON schema of the attestation. For example, the AWS attestor is defined as follows:

  Name    = "aws"
  Type    = "https://witness.dev/attestations/aws/v0.1"
  RunType = attestation.PreRunType

The attestation types are used when we evaluate policy against these attestations.

Attestor Security Model

Attestations are only as secure as the data that feeds them. Where possible cryptographic material should be validated, evidence of validation should be included in the attestation for out-of-band validation.

Examples of cryptographic validation is found in the GCP, AWS, and GitLab attestors.

Attestor Life Cycle

  • Pre-material: Pre-material attestors run before any other attestors. These attestors generally collect information about the environment.

  • Material: Material attestors run after any prematerial attestors and prior to any execute attestors. Generally these collect information about state that may change after any execute attestors, such as file hashes.

  • Execute:: Execute attestors run after any material attestors and generally record information about some command or process that is to be executed.

  • Product: Product attestors run after any execute attestors and generally record information about what changed during the execute lifecycle step, such as changed or created files.

  • Post-product: Post-product attestors run after product attestors and generally record some additional information about specific products, such as OCI image information from a saved image tarball.

Attestation Lifecycle

Attestor Types

Pre-material Attestors

  • AWS - Attestor for AWS Instance Metadata
  • GCP - Attestor for GCP Instance Identity Service
  • GitLab - Attestor for GitLab Pipelines
  • Git - Attestor for Git Repository
  • Maven Attestor for Maven Projects
  • Environment - Attestor for environment variables (be careful with this - there is no way to mask values yet)
  • JWT - Attestor for JWT Tokens

Material Attestors

  • Material - Records secure hashes of files in current working directory

Execute Attestors

  • CommandRun - Records traces and metadata about the actual process being run

Product Attestors

  • Product - Records secure hashes of files produced by commandrun attestor (only detects new files)

Post-product Attestors

  • OCI - Attestor for tar'd OCI images

AttestationCollection

An attestationCollection is a collection of attestations that are cryptographically bound together. Because the attestations are bound together, we can trust that they all happened as part of the same attesation life cycle. Witness policy defines which attestations are required.

Attestor Subjects

Attestors define subjects that act as lookup indexes. The attestationCollection can be looked up by any of the subjects defined by the attestors.

Witness Policy

What is a witness policy?

A witness policy is a signed document that encodes the requirements for an artifact to be validated. A witness policy includes public keys for trusted functionaries, which attestations must be found, and rego policy to evaluate against the attestation meta-data.

A witness policy allows administrators to trace the compliance status of an artifact at any point during its lifecycle.

Witness Verification

Verification Lifecycle

Using SPIRE for Keyless Signing

Witness can consume ephemeral keys from a SPIRE node agent. Configure witness with the flag --spiffe-socket to enable keyless signing.

During the verification process witness will use a source of trusted time such as a timestamp from a timestamp authority to make a determination on certificate validity. The SPIRE certificate only needs to remain valid long enough for a timestamp to be created.

Support

TestifySec Provides support for witness and other CI security tools. Contact Us

More Repositories

1

in-toto

in-toto is a framework to protect supply chain integrity.
Python
868
star
2

attestation

in-toto Attestation Framework
Go
225
star
3

in-toto-golang

A Go implementation of in-toto. in-toto is a framework to protect software supply chain integrity.
Go
128
star
4

demo

Securing Alice's, Bob's and Carl's software supply chain using in-toto
Python
83
star
5

community

in-toto is a framework to secure the software supply chain.
62
star
6

archivista

Archivista is a graph and storage service for in-toto attestations. Archivista enables the discovery and retrieval of attestations for software artifacts.
Go
56
star
7

specification

Specification and other related documents.
Python
37
star
8

in-toto-rs

A rust implementation of in-toto
Rust
32
star
9

supply-chain-compromises

22
star
10

go-witness

Go implementation of witness
Go
21
star
11

ITE

in-toto Enhancements
19
star
12

scai-demos

Software Supply Chain Attribute Integrity (SCAI) Demos and CLI tools
Go
18
star
13

attestation-verifier

Prototype in-toto attestation verifier based on ITE-10 and ITE-11 layouts
Go
15
star
14

friends

Friends of in-toto! A place to record integrations and adoptions of the in-toto specification.
Python
12
star
15

in-toto-java

A Java implementation of in-toto runlib
Java
12
star
16

kubectl-in-toto

Go
11
star
17

github-action

in-toto provenance github action
JavaScript
8
star
18

in-toto-webhook

Go
8
star
19

apt-transport-in-toto

in-toto transport for apt
Python
8
star
20

Dockerfiles

Dockerfile
5
star
21

totoify-grafeas

Python
4
star
22

in-toto-testing

Python
3
star
23

in-toto.io

The in-toto website and documentation
HTML
2
star
24

layout-web-tool

A flask app that helps to create, modify and visualize in-toto layouts.
Python
2
star
25

image-resources

This repo contains image-related resources for in-toto
1
star
26

in-toto-inspections

A set of common in-toto inspections
Python
1
star
27

ite-4-demo

Python
1
star
28

demo-jekyll

Metadata and scripts to secure a basic jekyll supply chain with in-toto and grafeas
Shell
1
star