notary

Notary is a project that allows anyone to have trust over arbitrary collections of data

3,275

517

3,275

332

View on GitHub

Top Related Projects

python-tuf

1,666

Python reference implementation of The Update Framework (TUF)

cosign

5,023

Code signing and transparency for containers and binaries

distribution

9,729

The toolkit to pack, ship, store, and deliver container content

grype

10,113

A vulnerability scanner for container images and filesystems

Quick Overview

Notary is an open-source project that provides a framework for secure content distribution and verification. It aims to enhance the security of software supply chains by enabling developers to digitally sign and verify content, ensuring its integrity and authenticity.

Pros

Enhances software supply chain security
Supports multiple content types and signing methods
Integrates well with existing container registries and CI/CD pipelines
Provides a flexible and extensible architecture

Cons

Requires additional infrastructure setup and maintenance
Learning curve for teams new to content signing and verification
Limited adoption compared to some alternative solutions
Documentation could be more comprehensive for advanced use cases

Code Examples

Signing content using Notary:

package main

import (
    "github.com/theupdateframework/notary/client"
    "github.com/theupdateframework/notary/trustpinning"
)

func main() {
    repo, err := client.NewFileCachedRepository(
        "path/to/trust_dir",
        "gun",
        "https://notary-server.example.com",
        nil,
        trustpinning.TrustPinConfig{},
        nil,
    )
    if err != nil {
        // Handle error
    }

    targets, err := repo.ListTargets()
    if err != nil {
        // Handle error
    }

    // Sign and publish changes
    err = repo.Publish()
    if err != nil {
        // Handle error
    }
}

Verifying content using Notary:

package main

import (
    "github.com/theupdateframework/notary/client"
    "github.com/theupdateframework/notary/trustpinning"
)

func main() {
    repo, err := client.NewFileCachedRepository(
        "path/to/trust_dir",
        "gun",
        "https://notary-server.example.com",
        nil,
        trustpinning.TrustPinConfig{},
        nil,
    )
    if err != nil {
        // Handle error
    }

    target, err := repo.GetTargetByName("target_name", nil)
    if err != nil {
        // Handle error
    }

    // Verify the target
    if target != nil {
        // Content is verified
    } else {
        // Content verification failed
    }
}

Getting Started

To get started with Notary:

Install Notary:

go get github.com/theupdateframework/notary

Set up a Notary server and signer:
```
docker-compose up -d
```

Initialize a Notary repository:

repo, err := client.NewFileCachedRepository(
    "path/to/trust_dir",
    "gun",
    "https://notary-server.example.com",
    nil,
    trustpinning.TrustPinConfig{},
    nil,
)

Start signing and verifying content using the Notary client library as shown in the code examples above.

Competitor Comparisons

python-tuf

1,666

Python reference implementation of The Update Framework (TUF)

Pros of python-tuf

More flexible and language-agnostic, as it's a Python implementation of TUF
Easier to integrate into existing Python projects
Actively maintained with regular updates and community support

Cons of python-tuf

Limited to Python ecosystem, potentially less suitable for non-Python projects
May require more setup and configuration compared to Notary's Docker-centric approach

Code Comparison

python-tuf example:

from tuf import repository_tool as rt

repository = rt.create_new_repository("repository")
repository.root.add_verification_key(public_root_key)
repository.snapshot.add_verification_key(public_snapshot_key)
repository.timestamp.add_verification_key(public_timestamp_key)
repository.write()

Notary example:

package main

import (
    "github.com/theupdateframework/notary"
    "github.com/theupdateframework/notary/trustpinning"
)

func main() {
    repo, _ := notary.NewFileCachedRepository(...)
    targets, _ := repo.ListTargets()
}

The code examples demonstrate the different approaches and languages used by each project. python-tuf focuses on repository creation and key management, while Notary emphasizes trust pinning and target listing in its Go implementation.

cosign

5,023

Code signing and transparency for containers and binaries

Pros of Cosign

Simpler and more lightweight, focusing specifically on container image signing
Integrates well with modern cloud-native ecosystems and Kubernetes
Supports keyless signing using ephemeral keys and identity providers

Cons of Cosign

Less mature and battle-tested compared to Notary
Limited to container image signing, while Notary supports broader use cases
Lacks some advanced features like delegation and threshold signing

Code Comparison

Cosign signing example:

cosign sign --key cosign.key my-registry.example.com/my-image:tag

Notary signing example:

notary init example.com/repository
notary add example.com/repository v1 file.txt
notary publish example.com/repository

Key Differences

Cosign is designed for simplicity and ease of use in container workflows
Notary offers a more comprehensive trust framework for various content types
Cosign leverages existing standards like OIDC for keyless signing
Notary provides a more traditional PKI-based approach to signing and verification

Both projects aim to enhance software supply chain security, but Cosign focuses on container-specific use cases, while Notary offers a broader, more flexible trust system for various content types.

distribution

9,729

The toolkit to pack, ship, store, and deliver container content

Pros of Distribution

More active development with frequent updates and contributions
Broader scope, focusing on overall container distribution and registry functionality
Larger community and wider adoption in the Docker ecosystem

Cons of Distribution

More complex codebase due to its broader feature set
Potentially steeper learning curve for new contributors
Less focused on security-specific features compared to Notary

Code Comparison

Distribution (Go):

func (bs *blobStore) ServeBlob(ctx context.Context, w http.ResponseWriter, r *http.Request, dgst digest.Digest) error {
    desc, err := bs.statter.Stat(ctx, dgst)
    if err != nil {
        return err
    }
    return bs.serveLocal(ctx, w, r, desc)
}

Notary (Go):

func (s *NonCachingServer) GetTimestamp(gun string) ([]byte, int, error) {
    cachedTS, err := s.getCachedTimestamp(gun)
    if err == nil {
        return cachedTS, http.StatusOK, nil
    }
    return nil, http.StatusNotFound, err
}

Both projects use Go and focus on different aspects of container management. Distribution handles broader registry functionality, while Notary specializes in signing and verifying content within a registry.

grype

10,113

A vulnerability scanner for container images and filesystems

Pros of Grype

Focused specifically on vulnerability scanning for container images and filesystems
Faster scanning and lower resource usage
More frequent updates to vulnerability database

Cons of Grype

Limited to vulnerability scanning, lacks broader content trust features
Does not provide signing or verification capabilities
Less integration with container registries and distribution systems

Code Comparison

Grype (vulnerability scanning):

match, err := matcher.Match(pkg, vulnerability)
if err != nil {
    return fmt.Errorf("failed to match package: %w", err)
}

Notary (content trust):

targets, err := repo.ListTargets()
if err != nil {
    return nil, err
}
for _, tgt := range targets {
    // Process targets
}

Summary

Grype is a specialized tool for vulnerability scanning in containers and filesystems, offering fast and efficient scans with frequent database updates. Notary, on the other hand, provides a broader set of content trust features, including signing and verification capabilities, with deeper integration into container ecosystems. While Grype excels in its focused area, Notary offers a more comprehensive approach to securing container content across the distribution pipeline.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Notice

This repository provides an implementation of The Update Framework specification and all references to notary in this repository refer to the implementation of the client and server aligning with the TUF specification. The most prominent use of this implementation is in Docker Content Trust (DCT). The first release v0.1 was released in November, 2015.

Overview

This repository comprises of a server and a client for running and interacting with trusted collections. See the service architecture documentation for more information.

The aim is to make the internet more secure by making it easy for people to publish and verify content. We often rely on TLS to secure our communications with a web server, which is inherently flawed, as any compromise of the server enables malicious content to be substituted for the legitimate content.

Publishers can sign their content offline using keys kept highly secure. Once the publisher is ready to make the content available, they can push their signed trusted collection to the notary server.

Consumers, having acquired the publisher's public key through a secure channel, can then communicate with any notary server or (insecure) mirror, relying only on the publisher's key to determine the validity and integrity of the received content.

Goals

The notary client and server is based on The Update Framework, a secure general design for the problem of software distribution and updates. By using TUF, the notary client and server achieves a number of key advantages:

Survivable Key Compromise: Content publishers must manage keys in order to sign their content. Signing keys may be compromised or lost so systems must be designed in order to be flexible and recoverable in the case of key compromise. TUF's notion of key roles is utilized to separate responsibilities across a hierarchy of keys such that loss of any particular key (except the root role) by itself is not fatal to the security of the system.
Freshness Guarantees: Replay attacks are a common problem in designing secure systems, where previously valid payloads are replayed to trick another system. The same problem exists in the software update systems, where old signed can be presented as the most recent. Notary makes use of timestamping on publishing so that consumers can know that they are receiving the most up to date content. This is particularly important when dealing with software update where old vulnerable versions could be used to attack users.
Configurable Trust Thresholds: Oftentimes there are a large number of publishers that are allowed to publish a particular piece of content. For example, open source projects where there are a number of core maintainers. Trust thresholds can be used so that content consumers require a configurable number of signatures on a piece of content in order to trust it. Using thresholds increases security so that loss of individual signing keys doesn't allow publishing of malicious content.
Signing Delegation: To allow for flexible publishing of trusted collections, a content publisher can delegate part of their collection to another signer. This delegation is represented as signed metadata so that a consumer of the content can verify both the content and the delegation.
Use of Existing Distribution: Notary's trust guarantees are not tied at all to particular distribution channels from which content is delivered. Therefore, trust can be added to any existing content delivery mechanism.
Untrusted Mirrors and Transport: All of the notary metadata can be mirrored and distributed via arbitrary channels.

Security

Any security vulnerabilities can be reported to security@docker.com.

See service architecture docs for more information about our threat model, which details the varying survivability and severities for key compromise as well as mitigations.

Security Audits

Below are the two public security audits:

August 7, 2018 by Cure53 covering TUF and the notary client and server.
July 31, 2015 by NCC covering notary client and server.

Getting started with the notary CLI

Get the notary client CLI binary from the official releases page or you can build one yourself. The version of the notary server and signer should be greater than or equal to notary CLI's version to ensure feature compatibility (ex: CLI version 0.2, server/signer version >= 0.2), and all official releases are associated with GitHub tags.

To use the notary CLI with Docker hub images, have a look at notary's getting started docs.

For more advanced usage, see the advanced usage docs.

To use the CLI against a local notary server rather than against Docker Hub:

Ensure that you have docker and docker-compose installed.
git clone https://github.com/theupdateframework/notary.git and from the cloned repository path, start up a local notary server and signer and copy the config file and testing certs to your local notary config directory:
```
$ docker-compose build
$ docker-compose up -d
$ mkdir -p ~/.notary && cp cmd/notary/config.json cmd/notary/root-ca.crt ~/.notary
```
Add 127.0.0.1 notary-server to your /etc/hosts, or if using docker-machine, add $(docker-machine ip) notary-server).

You can run through the examples in the getting started docs and advanced usage docs, but without the -s (server URL) argument to the notary command since the server URL is specified already in the configuration, file you copied.

You can also leave off the -d ~/.docker/trust argument if you do not care to use notary with Docker images.

Upgrading dependencies

To prevent mistakes in vendoring the go modules a buildscript has been added to properly vendor the modules using the correct version of Go to mitigate differences in CI and development environment.

Following procedure should be executed to upgrade a dependency. Preferably keep dependency upgrades in a separate commit from your code changes.

go get -u github.com/spf13/viper
buildscripts/circle-validate-vendor.sh
git add .
git commit -m "Upgraded github.com/spf13/viper"

The buildscripts/circle-validate-vendor.sh runs go mod tidy and go mod vendor using the given version of Go to prevent differences if you are for example running on a different version of Go.

Building notary

Note that the latest stable release is at the head of the releases branch. The master branch is the development branch and contains features for the next release.

Prerequisites:

Go >= 1.12

Set GOPATH. Then, run:

$ export GO111MODULE=on
$ go get github.com/theupdateframework/notary
# build with pkcs11 support by default to support yubikey
$ go install -tags pkcs11 github.com/theupdateframework/notary/cmd/notary
$ notary

To build the server and signer, run docker-compose build.

License

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot