{"id":13416269,"url":"https://github.com/notaryproject/notary","last_synced_at":"2025-05-14T15:06:21.404Z","repository":{"id":33990915,"uuid":"37743436","full_name":"notaryproject/notary","owner":"notaryproject","description":"Notary is a project that allows anyone to have trust over arbitrary collections of data","archived":false,"fork":false,"pushed_at":"2024-08-07T19:02:32.000Z","size":41466,"stargazers_count":3273,"open_issues_count":332,"forks_count":521,"subscribers_count":111,"default_branch":"master","last_synced_at":"2025-05-07T14:02:14.547Z","etag":null,"topics":["cncf","docker","trust"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/notaryproject.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-19T20:07:53.000Z","updated_at":"2025-05-05T22:56:07.000Z","dependencies_parsed_at":"2023-12-05T19:25:33.769Z","dependency_job_id":"84abc54a-2a86-4eef-996a-5c72d6752a4e","html_url":"https://github.com/notaryproject/notary","commit_stats":{"total_commits":2188,"total_committers":100,"mean_commits":21.88,"dds":0.7614259597806216,"last_synced_commit":"9d2b3b35929392c9945d976b8bdecbe2f53a299e"},"previous_names":["docker/notary","theupdateframework/notary"],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/notaryproject","download_url":"https://codeload.github.com/notaryproject/notary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254043292,"owners_count":22004917,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cncf","docker","trust"],"created_at":"2024-07-30T21:00:56.233Z","updated_at":"2025-05-14T15:06:21.355Z","avatar_url":"https://github.com/notaryproject.png","language":"Go","readme":"[![GoDoc](https://godoc.org/github.com/theupdateframework/notary?status.svg)](https://godoc.org/github.com/theupdateframework/notary)\n[![Circle CI](https://circleci.com/gh/theupdateframework/notary/tree/master.svg?style=shield)](https://circleci.com/gh/theupdateframework/notary/tree/master) [![CodeCov](https://codecov.io/github/theupdateframework/notary/coverage.svg?branch=master)](https://codecov.io/github/theupdateframework/notary) [![GoReportCard](https://goreportcard.com/badge/theupdateframework/notary)](https://goreportcard.com/report/github.com/theupdateframework/notary)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Ftheupdateframework%2Fnotary.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Ftheupdateframework%2Fnotary?ref=badge_shield)\n\n# Notice\n\nThis repository provides an implementation of \n*[The Update Framework specification](https://github.com/theupdateframework/specification)* \nand all references to `notary` in this repository refer to the implementation of the client \nand server aligning with the [TUF](https://github.com/theupdateframework/specification) specification.\nThe most prominent use of this implementation is in Docker Content Trust (DCT).\nThe first release [v0.1](https://github.com/notaryproject/notary/releases/tag/v0.1) was released in November, 2015.\n\n# Overview\n\nThis repository comprises of a [server](cmd/notary-server) and a [client](cmd/notary) for running and interacting\nwith trusted collections. See the [service architecture](docs/service_architecture.md) documentation\nfor more information.\n\nThe aim is to make the internet more secure by making it easy for people to\npublish and verify content. We often rely on TLS to secure our communications\nwith a web server, which is inherently flawed, as any compromise of the server\nenables malicious content to be substituted for the legitimate content.\n\nPublishers can sign their content offline using keys kept highly\nsecure. Once the publisher is ready to make the content available, they can\npush their signed trusted collection to the `notary` server.\n\nConsumers, having acquired the publisher's public key through a secure channel,\ncan then communicate with any `notary` server or (insecure) mirror, relying\nonly on the publisher's key to determine the validity and integrity of the\nreceived content.\n\n## Goals\n\nThe `notary` client and server is based on [The Update Framework](https://www.theupdateframework.com/), 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:\n\n* **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.\n* **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.\n* **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.\n* **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.\n* **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.\n* **Untrusted Mirrors and Transport**: All of the notary metadata can be mirrored and distributed via arbitrary channels.\n\n## Security\n\nAny security vulnerabilities can be reported to security@docker.com.\n\nSee [service architecture docs](docs/service_architecture.md#threat-model) for more information about our threat model, which details the varying survivability and severities for key compromise as well as mitigations.\n\n### Security Audits\n\nBelow are the two public security audits:\n\n* [August 7, 2018 by Cure53](docs/resources/cure53_tuf_notary_audit_2018_08_07.pdf) covering TUF and the `notary` client and server.\n* [July 31, 2015 by NCC](docs/resources/ncc_docker_notary_audit_2015_07_31.pdf) covering `notary` client and server.\n\n# Getting started with the notary CLI\n\nGet the `notary` client CLI binary from [the official releases page](https://github.com/theupdateframework/notary/releases) or you can [build one yourself](#building-notary).\nThe 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 \u003e= 0.2), and all official releases are associated with GitHub tags.\n\nTo use the notary CLI with Docker hub images, have a look at notary's\n[getting started docs](docs/getting_started.md).\n\nFor more advanced usage, see the\n[advanced usage docs](docs/advanced_usage.md).\n\nTo use the CLI against a local `notary` server rather than against Docker Hub:\n\n1. Ensure that you have [docker and docker-compose](https://docs.docker.com/compose/install/) installed.\n1. `git clone https://github.com/theupdateframework/notary.git` and from the cloned repository path,\n    start up a local `notary` server and signer and copy the config file and testing certs to your\n    local notary config directory:\n\n    ```sh\n    $ docker-compose build\n    $ docker-compose up -d\n    $ mkdir -p ~/.notary \u0026\u0026 cp cmd/notary/config.json cmd/notary/root-ca.crt ~/.notary\n    ```\n\n1. Add `127.0.0.1 notary-server` to your `/etc/hosts`, or if using docker-machine,\n    add `$(docker-machine ip) notary-server`).\n\nYou can run through the examples in the\n[getting started docs](docs/getting_started.md) and\n[advanced usage docs](docs/advanced_usage.md), but\nwithout the `-s` (server URL) argument to the `notary` command since the server\nURL is specified already in the configuration, file you copied.\n\nYou can also leave off the `-d ~/.docker/trust` argument if you do not care\nto use `notary` with Docker images.\n\n## Upgrading dependencies\n\nTo 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.\n\nFollowing procedure should be executed to upgrade a dependency. Preferably keep dependency upgrades in a separate commit from your code changes.\n\n```bash\ngo get -u github.com/spf13/viper\nbuildscripts/circle-validate-vendor.sh\ngit add .\ngit commit -m \"Upgraded github.com/spf13/viper\"\n```\n\nThe `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.\n\n## Building notary\n\nNote that the [latest stable release](https://github.com/theupdateframework/notary/releases) is at the head of the\n[releases branch](https://github.com/theupdateframework/notary/tree/releases).  The master branch is the development\nbranch and contains features for the next release.\n\nPrerequisites:\n\n* Go \u003e= 1.12\n\nSet [```GOPATH```](https://golang.org/doc/code.html#GOPATH). Then, run:\n\n```bash\n$ export GO111MODULE=on\n$ go get github.com/theupdateframework/notary\n# build with pkcs11 support by default to support yubikey\n$ go install -tags pkcs11 github.com/theupdateframework/notary/cmd/notary\n$ notary\n```\n\nTo build the server and signer, run `docker-compose build`.\n\n## License\n\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Ftheupdateframework%2Fnotary.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Ftheupdateframework%2Fnotary?ref=badge_large)\n","funding_links":[],"categories":["Container Operations","Go","Containers","docker","Identity, signing and provenance","Artifact signing and attestation"],"sub_categories":["Security","Supply chain beyond libraries","Threat modelling"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotaryproject%2Fnotary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotaryproject%2Fnotary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotaryproject%2Fnotary/lists"}