doc: CLI spec for trust policy management (DO NOT REVIEW) #505

yizha1 · 2023-01-12T13:05:31Z

Update:

Introduce new CLI command to manage trust policy

Signed-off-by: Yi Zha yizha1@microsoft.com

Signed-off-by: Yi Zha <yizha1@microsoft.com>

codecov-commenter · 2023-01-12T13:08:18Z

Codecov Report

Merging #505 (f72dea3) into main (1281179) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #505   +/-   ##
=======================================
  Coverage   29.57%   29.57%           
=======================================
  Files          26       26           
  Lines        1515     1515           
=======================================
  Hits          448      448           
  Misses       1050     1050           
  Partials       17       17

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

Signed-off-by: Yi Zha <yizha1@microsoft.com>

specs/commandline/policy.md

Signed-off-by: Yi Zha <yizha1@microsoft.com>

priteshbandi · 2023-01-31T22:12:43Z

specs/commandline/policy.md

+
+An example of `trustpolicy.json`:
+
+```json


Do we need json example in this doc when we already have link to specification which contains similar json?

Suggested change

```json

```jsonc

priteshbandi · 2023-01-31T22:47:43Z

specs/commandline/policy.md

+                "level": "strict"
+                "override" : {
+                     "expiry" : "log",
+                     "authenticity": "log"


A couple of suggestions, if we want to display policy in this doc:

First example should be simple and should not contain overrides.

For override, please only show expiry. Adding override for authenticity has major security implications.

Prod trust policy should be first and then dev

We should show wildcard policy

priteshbandi · 2023-01-31T23:02:00Z

specs/commandline/policy.md

+      --scope              stringArray   repository URIs to which the policy applies (default ["*"])
+      --trust-store        stringArray   trust stores in format "<trust_store_type>:<trust_store_name>"
+      --verification-level string        verification level, options: "strict", "permissive", "audit", "skip" (default "strict")
+      --x509-cert          stringArray   paths to x509 certificate file that certificate subject is retrieved from


How are expecting user to use use --x509-cert? IMO software publisher will distribute software and share the identity(not the certificate) that consumer needs to trust.

@priteshbandi The --x509-cert here is designed for one scenario: Users have the certificate file, not the identity, then with this flag, notation policy command can retrieve the identity from the certificate file for the users. One question for your case: If it is the identity shared to users, how can users add certificate file using notation cert add command?

priteshbandi · 2023-01-31T23:03:13Z

specs/commandline/policy.md

+      --trust-store        stringArray   trust stores in format "<trust_store_type>:<trust_store_name>"
+      --verification-level string        verification level, options: "strict", "permissive", "audit", "skip" (default "strict")
+      --x509-cert          stringArray   paths to x509 certificate file that certificate subject is retrieved from
+      --x509-id            stringArray   trust identities, user trusted x509 certificate subjects


should we rename this to --trusted-identity

priteshbandi · 2023-01-31T23:08:52Z

specs/commandline/policy.md

+### notation policy delete
+
+```text
+Delete trust policies. User cannot delete all the trust policies, at least one trust policy should be configured for signature verification.


user cannot delete all the trust policies, at least one trust policy should be configured for signature verification.
Instead of restricting it should add a disclaimer that for signature verification, notation needs at least one trust-policy?

priteshbandi · 2023-01-31T23:33:52Z

specs/commandline/policy.md

+
+The execution fails in one of below cases:
+
+- Version doesn't support. Currently only `1.0` version is supported.


Suggested change

- Version doesn't support. Currently only `1.0` version is supported.

- Unsupported Version. Currently only `1.0` version is supported.

priteshbandi · 2023-01-31T23:34:08Z

specs/commandline/policy.md

+The execution fails in one of below cases:
+
+- Version doesn't support. Currently only `1.0` version is supported.
+- The trust policy name exists.


Suggested change

- The trust policy name exists.

- A trust policy with same name already exists.

priteshbandi · 2023-01-31T23:51:28Z

specs/commandline/policy.md

+
+```json
+{
+  "name": "wabbit-networks-dev",                              
+  "registryScopes": [ "*" ],                                  
+  "signatureVerification": {                                  
+      "level": "strict"
+  },
+  "trustStores": [ "ca:wabbit-networks-dev" ],                
+  "trustedIdentities": [                                      
+      "*"
+  ]
+}


IMO we don't need to display both json and text format for each variation of a command, its making doc large and doesnt adds much value.

priteshbandi · 2023-01-31T23:54:26Z

specs/commandline/policy.md

+- Version doesn't support. Currently only `1.0` version is supported.
+- The trust policy name doesn't exists.
+- More than one trust policy that uses a global scope, that is, the value of `registryScopes` is `["*"]`.
+- The values of `trustIdentities` overlap. For example, the following two identity values are overlapping:
+  - "C=US, ST=WA, O=wabbit-network.io, OU=org1"
+  - "C=US, ST=WA, O=wabbit-network.io"


IMO this is redundant information and can be removed.

priteshbandi · 2023-01-31T23:55:19Z

specs/commandline/policy.md

+name: wabbit-network-dev
+registryScopes: ["dev.wabbitnetworks.io/net-monitor"]
+
+name: wabbit-network-prod
+registryScopes: ["prod.wabbitnetworks.io/net-monitor"]


Should we use tree based representation here?

shizhMSFT · 2023-02-10T06:33:04Z

specs/notation-cli.md

 | [plugin](./commandline/plugin.md)           | Manage plugins                            |
+| [policy](./commandline/policy.md)           | Manage trust policies                  |
 | [sign](./commandline/sign.md)               | Sign artifacts                            |


shizhMSFT · 2023-02-10T13:33:19Z

specs/commandline/policy.md

+
+Upon successful execution, the added trust policy is printed out. For example:
+
+In text format


Do we really need text format for the notation policy command set? To be honest, the text format is less readable than the json format for a human.

shizhMSFT · 2023-02-10T13:35:25Z

specs/commandline/policy.md

+  list, ls
+
+Flags:
+      --details                 list the details of trust policies


We could have something like --raw or --export to print the trustpolicy.json file directly.

yizha1 · 2023-02-13T01:57:53Z

Based on the community discussion, move this PR out of rc.2, and I will update it to phase-1 later for rc.3

doc: CLI spec for trust policy mgmt

04bd773

Signed-off-by: Yi Zha <yizha1@microsoft.com>

yizha1 added 6 commits January 13, 2023 19:35

doc: update per discussion results

d023d8f

Signed-off-by: Yi Zha <yizha1@microsoft.com>

doc: update per discussion

091a851

Signed-off-by: Yi Zha <yizha1@microsoft.com>

doc: update add and update commands

a705deb

Signed-off-by: Yi Zha <yizha1@microsoft.com>

doc: update list comments

11f4165

Signed-off-by: Yi Zha <yizha1@microsoft.com>

doc: update list comments

74664b5

Signed-off-by: Yi Zha <yizha1@microsoft.com>

doc: resolve conficts

c7dc80b

Signed-off-by: Yi Zha <yizha1@microsoft.com>

yizha1 marked this pull request as ready for review January 14, 2023 05:45

yizha1 requested review from vaninrao10, priteshbandi, FeynmanZhou, iamsamirzon, JeyJeyGao, patrickzheng200, shizhMSFT and toddysm January 14, 2023 05:46

yizha1 added documentation Improvements or additions to documentation spec Specifications to define the product requirements labels Jan 14, 2023

yizha1 modified the milestones: RC-3, RC-2 Jan 14, 2023

yizha1 self-assigned this Jan 14, 2023

doc: remove empty line

465cbe0

Signed-off-by: Yi Zha <yizha1@microsoft.com>

JeyJeyGao reviewed Jan 16, 2023

View reviewed changes

specs/commandline/policy.md Outdated Show resolved Hide resolved

specs/commandline/policy.md Outdated Show resolved Hide resolved

specs/commandline/policy.md Outdated Show resolved Hide resolved

patrickzheng200 reviewed Jan 16, 2023

View reviewed changes

doc: update per comments

22e9128

Signed-off-by: Yi Zha <yizha1@microsoft.com>

yizha1 requested review from JeyJeyGao and patrickzheng200 January 17, 2023 08:59

doc: update per comments

f72dea3

Signed-off-by: Yi Zha <yizha1@microsoft.com>

priteshbandi reviewed Jan 31, 2023

View reviewed changes

shizhMSFT reviewed Feb 10, 2023

View reviewed changes

yizha1 removed this from the RC-2 milestone Feb 13, 2023

yizha1 changed the title ~~doc: CLI spec for trust policy management~~ doc: CLI spec for trust policy management (DO NOT REVIEW) Feb 25, 2023

yizha1 closed this Nov 27, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: CLI spec for trust policy management (DO NOT REVIEW) #505

doc: CLI spec for trust policy management (DO NOT REVIEW) #505

yizha1 commented Jan 12, 2023

codecov-commenter commented Jan 12, 2023 •

edited

Loading

priteshbandi Jan 31, 2023

priteshbandi Jan 31, 2023

priteshbandi Jan 31, 2023

yizha1 Feb 7, 2023

priteshbandi Jan 31, 2023

priteshbandi Jan 31, 2023

priteshbandi Jan 31, 2023

priteshbandi Jan 31, 2023

priteshbandi Jan 31, 2023

priteshbandi Jan 31, 2023

priteshbandi Jan 31, 2023

shizhMSFT Feb 10, 2023

shizhMSFT Feb 10, 2023

shizhMSFT Feb 10, 2023

yizha1 commented Feb 13, 2023


		The execution fails in one of below cases:

		- Version doesn't support. Currently only `1.0` version is supported.

	- Version doesn't support. Currently only `1.0` version is supported.
	- Unsupported Version. Currently only `1.0` version is supported.

	- The trust policy name exists.
	- A trust policy with same name already exists.


		Upon successful execution, the added trust policy is printed out. For example:

		In text format

doc: CLI spec for trust policy management (DO NOT REVIEW) #505

doc: CLI spec for trust policy management (DO NOT REVIEW) #505

Conversation

yizha1 commented Jan 12, 2023

codecov-commenter commented Jan 12, 2023 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yizha1 commented Feb 13, 2023

codecov-commenter commented Jan 12, 2023 •

edited

Loading