{"id":13848161,"url":"https://github.com/philips-labs/dct-notary-admin","last_synced_at":"2025-04-30T06:07:48.303Z","repository":{"id":37987838,"uuid":"229924354","full_name":"philips-labs/dct-notary-admin","owner":"philips-labs","description":"To manage Docker Content Trust and Notary certificates","archived":false,"fork":false,"pushed_at":"2025-04-17T06:38:20.000Z","size":3432,"stargazers_count":12,"open_issues_count":23,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-30T06:07:41.732Z","etag":null,"topics":["codesigning","dct","docker","hacktoberfest","notary"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philips-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-12-24T10:49:27.000Z","updated_at":"2025-04-17T06:38:23.000Z","dependencies_parsed_at":"2023-02-12T19:01:14.249Z","dependency_job_id":"dce4944d-f0db-4319-b4f5-af4b8f4ba0f2","html_url":"https://github.com/philips-labs/dct-notary-admin","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips-labs%2Fdct-notary-admin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips-labs%2Fdct-notary-admin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips-labs%2Fdct-notary-admin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philips-labs%2Fdct-notary-admin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philips-labs","download_url":"https://codeload.github.com/philips-labs/dct-notary-admin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251651233,"owners_count":21621716,"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":["codesigning","dct","docker","hacktoberfest","notary"],"created_at":"2024-08-04T19:00:43.974Z","updated_at":"2025-04-30T06:07:48.282Z","avatar_url":"https://github.com/philips-labs.png","language":"Go","funding_links":[],"categories":["Repositories"],"sub_categories":[],"readme":"# Docker Content Trust - Notary Admin\n\n[![Continuous Integration](https://github.com/philips-labs/dct-notary-admin/workflows/Continuous%20Integration/badge.svg)](https://github.com/philips-labs/dct-notary-admin/actions?query=workflow%3A\"Continuous+Integration\"+branch%3Adevelop)\n[![codecov](https://codecov.io/gh/philips-labs/dct-notary-admin/branch/develop/graph/badge.svg)](https://codecov.io/gh/philips-labs/dct-notary-admin)\n\nThis API and webapp add the capability to manage your Docker Content Trust and notary certificates.\n\nIt allows you to create new **Target** certificates for your Docker repositories, as well authorizing delegates for the repository.\n\nThis way the certificates can be stored in a secured environment where backups are managed.\n\nThis project makes use of a [Notary sandbox][notaryforksandbox] which is an in progress development setup, which is intended to be contributed [upstream][notary]. The [Fork][notaryfork] is by no means a hard Fork of [Notary][notary] and is solely there to bridge a period of time to get this back in the upstream.\n\n## API endpoints\n\n| HTTP Method | URL                                                                                                                          | description                                    |\n| ----------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |\n| GET         | [https://localhost:8443/ping](https://localhost:8443/ping)                                                                   | return pong                                    |\n| GET         | [https://localhost:8443/targets](https://localhost:8443/targets)                                                             | retrieves all target keys                      |\n| POST        | [https://localhost:8443/targets](https://localhost:8443/targets)                                                             | creates a new target and keys                  |\n| GET         | [https://localhost:8443/targets/{id}](https://localhost:8443/targets/{id})                                                   | retrieves a single target key                  |\n| GET         | [https://localhost:8443/targets/{id}/delegations](https://localhost:8443/targets/{id}/delegations)                           | retrieves all delegate keys for a given target |\n| POST        | [https://localhost:8443/targets/{id}/delegations](https://localhost:8443/targets/{id}/delegations)                           | add a new delegation to the given target       |\n| DELETE      | [https://localhost:8443/targets/{id}/delegations/{delegation}](https://localhost:8443/targets/{id}/delegations/{delegation}) | remove a delegation from the given target      |\n\n## Prerequisites\n\nFor a easier development workflow it is recommended to install **CMake**. To interact with [Hashicorp Vault] the `vault cli` is convenient.\n\n| platform | install                  | url                              |\n| -------- | ------------------------ | -------------------------------- |\n| Windows  | `choco install -y cmake` | [cmake-3.16.2-win64-x64.msi]     |\n| MacOSX   | `brew install cmake`     | [cmake-3.16.2-Darwin-x86_64.dmg] |\n| Windows  | `choco install -y vault` | [vault_1.4.2_windows_amd64.zip]  |\n| MacOSX   | `brew install vault`     | [vault_1.4.2_darwin_amd64.zip]   |\n\n### Accept Self signed certs in Google Chrome\n\nFor Google Chrome to accept the selfsigned certificates please enable the option `allow-insecure-localhost` by navigating to [](chrome://flags/#allow-insecure-localhost) in your address bar.\n\nTo only allow for the current certificate that is blocked type `thisisunsafe` with focus on the `Your connection is not private` page, the page will autorefresh once the full phrase is typed. In older versions of chrome you had to type `badidea` or `danger`.\n\n## Run the sandbox\n\nTo run in an isolated environment to do some testing you should run the sandbox. The sandbox connects to a notary server and registry in the docker-compose setup.\n\nInitializing the notary git submodule.\n\n```bash\ngit submodule update --init --recursive\n```\n\nBuild the sandbox\n\n```bash\nmake build-sandbox\n```\n\nRun the sandbox\n\n```bash\nmake run-sandbox\n```\n\nTo provision the notary sandbox with some signed images you can use the `bootstrap-sandbox` make target (optional).\n\n```bash\nmake bootstrap-sandbox\n```\n\nTo play with the notary and docker trust cli you can open the shell for the sandbox. [Signing docker images using docker content trust](https://marcofranssen.nl/signing-docker-images-using-docker-content-trust/)\n\n```bash\ndocker-compose -f notary/docker-compose.sandbox.yml -f docker-compose.yml exec sandbox sh\n```\n\nTo shutdown the sandbox you can run the `stop-sandbox` make target.\n\n```bash\nmake stop-sandbox\n```\n\n## Run vault development server\n\nTo boot the [Hashicorp Vault](https://www.vaultproject.io/) development server run the following. Requires vault installed, (e.g. `brew install vault`).\n\n```bash\ndocker-compose -f vault/docker-compose.dev.yml up -d\nvault/prepare.sh dev\n```\n\n`prepare.sh` boots vault server and provisions the secret engine with required policies, secret engines etc.\n\nThe vault admin dashboard is available at [http://localhost:8200].\n\nThe token can be found in the server logs.\n\n```bash\ndocker-compose -f vault/docker-compose.dev.yml logs | grep \"Root Token\"\n```\n\n## Build binary (api)\n\n```bash\nmake build\n```\n\n## Test\n\nTo run the tests, make sure to run `make stop-sandbox` first (tests are also reusing the same sandbox which require a clean env).\n\n```bash\nmake test\n```\n\nRun the tests with coverage.\n\n```bash\nmake coverage-out\n```\n\nCheck the coverage report in your browser.\n\n```bash\nmake coverage-html\n```\n\n## Run\n\n\u003e The API utilizes Hashicorp vault to generate and store passwords for private keys. The endpoint to Hashicorp vault can be configured via the environment variable `VAULT_ADDR` or as a commandline flag. The default value points to [http://localhost:8200] (the address of the development server).\n\n### API Server\n\nNow you can start the API server as following:\n\n```bash\n# environment variable\nexport VAULT_ADDR=http://localhost:8200\nbin/dctna-server --config .notary/config.json\n```\n\nAlternatively you provide the vault server address as parameter.\n\n```bash\n# commandline option\nbin/dctna-server --vault-addr http://localhost:8200 --config .notary/config.json\n```\n\n\u003e **NOTE:** you can pass the sandbox `.notary/config.json` as above, without this setting the default notary folder will be used (`$USER/.natary/config.json`).\n\nOr via the Make shorthand which also builds the solution, which will use the sandbox config for notary.\n\n```bash\nmake run\n```\n\n\u003e **NOTE:** via make we will also use our sandboxed `.notary/config.json` automatically to prevent you from messing arround with your current notary (Production) settings.\n\n### Web Frontend\n\n```bash\ncd web\nyarn install \u0026\u0026 yarn start\n```\n\n## Testing end to end\n\nNow you can create new targets for signing docker images [http://localhost:3000] using the webinterface.\n\nE.g.:\n\n- Target: `localhost:5000/nginx`\n- Target: `localhost:5000/stuff`\n\nThen on one of the targets we will authorize our personal delegation key. If you don't have one yet you can generate it via the docker trust cli.\n\n```bash\ndocker trust key generate johndoe --dir ~/.docker/trust\n```\n\nThen simply copy the contents of the public key to your clipboard.\n\n```bash\ncat ~/.docker/trust/johndoe.pub | pbcopy\n```\n\nIn the webinterface you can now add your delegation on the target `localhost:5000/nginx`.\n\n| name     | key                      |\n| -------- | ------------------------ |\n| john_doe | paste_clipboard_contents |\n\nNow to be able to sign an image all signing keys have to be available on your local system. In Notary v2 this will be improved to also be able to work with remote signing keys. You will only need the passphrase for your delegation key.\n\nThis will now allow us to sign docker images for `localhost:5000/nginx`. In below example we first pull an image from the public registry. Then tag it to push to our sandbox registry. Then we enable content trust and configure our sandbox notary endpoint. Upon pushing to the repository you will be prompted for the password of your signing delegation key. Please note if you haven't added your delegation key in dctna, you will not be able to sign.\n\n```bash\ndocker pull nginx:alpine\ndocker tag nginx:alpine localhost:5000/nginx:alpine\nexport DOCKER_CONTENT_TRUST=1 DOCKER_CONTENT_TRUST_SERVER=https://localhost:4443\ndocker push localhost:5000/nginx:alpine\n```\n\n[cmake-3.16.2-win64-x64.msi]: https://github.com/Kitware/CMake/releases/download/v3.16.2/cmake-3.16.2-win64-x64.msi \"Download cmake-3.16.2-win64-x64.msi\"\n[cmake-3.16.2-darwin-x86_64.dmg]: https://github.com/Kitware/CMake/releases/download/v3.16.2/cmake-3.16.2-Darwin-x86_64.dmg \"Download cmake-3.16.2-Darwin-x86_64.dmg\"\n[Hashicorp Vault]: https://vaultproject.io \"Manage secrets and protect sensitive data\"\n[vault_1.4.2_windows_amd64.zip]: https://releases.hashicorp.com/vault/1.4.2/vault_1.4.2_windows_amd64.zip \"Download vault_1.4.2_windows_amd64.zip\"\n[vault_1.4.2_darwin_amd64.zip]: https://releases.hashicorp.com/vault/1.4.2/vault_1.4.2_darwin_amd64.zip \"Download vault_1.4.2_darwin_amd64.zip\"\n[notary]: https://github.com/theupdateframework/notary \"Notary is a project that allows anyone to have trust over arbitrary collections of data\"\n[notaryfork]: https://github.com/philips-labs/notary/blob/feature/sandbox \"This Fork is only to support the submodule which contains the sandbox setup\"\n[notaryforksandbox]: https://github.com/philips-labs/notary/blob/feature/sandbox/docker-compose.sandbox.yml \"Notary docker-compose sandbox setup\"\n[http://localhost:8200]: http://localhost:8200 \"Vault address\"\n[http://localhost:3000]: http://localhost:3000 \"DCTNA dashboard address\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilips-labs%2Fdct-notary-admin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilips-labs%2Fdct-notary-admin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilips-labs%2Fdct-notary-admin/lists"}