Skip to content

Commit 4f35aa6

Browse files
shizhMSFTshizhMSFT
committed
docs: update README.md
Signed-off-by: Shiwei Zhang <[email protected]>
1 parent f5e81f8 commit 4f35aa6

File tree

1 file changed

+150
-0
lines changed

1 file changed

+150
-0
lines changed

‎README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,152 @@
11
# docker-ratify
2+
23
A docker plugin wrapper for ratify
4+
5+
## Prerequisite
6+
7+
`docker-ratify` plugin requires [ratify](https://github.com/ratify-project/ratify/releases) being installed and available in `PATH`.
8+
9+
If you have already added `~/bin/` to `PATH`, you may run the following command to install `ratify v1.2.0` on Linux:
10+
```bash
11+
curl -L https://github.com/ratify-project/ratify/releases/download/v1.2.0/ratify_1.2.0_Linux_amd64.tar.gz | tar xvzC ~/bin/ ratify
12+
```
13+
14+
## Installation
15+
16+
Run the following command to install on Linux:
17+
```bash
18+
mkdir -p ~/.docker/cli-plugins
19+
curl -L https://github.com/shizhMSFT/docker-ratify/releases/download/v0.1.0/docker-ratify_0.1.0_linux_amd64.tar.gz | tar xvzC ~/.docker/cli-plugins/ docker-ratify
20+
```
21+
22+
Help information can be reviewed by
23+
24+
```bash
25+
docker help
26+
```
27+
28+
## Example for pulling Images with Ratify
29+
30+
A config file is required for using ratify. Here we use an example config file:
31+
32+
```bash
33+
cat > config.json <<EOF
34+
{
35+
"executor": {},
36+
"store": {
37+
"version": "1.0.0",
38+
"plugins": [
39+
{
40+
"name": "oras",
41+
"cosignEnabled": true
42+
}
43+
]
44+
},
45+
"policy": {
46+
"version": "1.0.0",
47+
"plugin": {
48+
"name": "regoPolicy",
49+
"policyPath": "",
50+
"policy": "package ratify.policy\ndefault valid := false\nvalid {\n not failed_verify(input)\n}\nfailed_verify(reports) {\n [path, value] := walk(reports)\n value == false\n path[count(path) - 1] == \"isSuccess\"\n}"
51+
}
52+
},
53+
"verifier": {
54+
"version": "1.0.0",
55+
"plugins": [
56+
{
57+
"name": "notation",
58+
"artifactTypes": "application/vnd.cncf.notary.signature",
59+
"verificationCerts": [
60+
"./root.crt"
61+
],
62+
"trustPolicyDoc": {
63+
"version": "1.0",
64+
"trustPolicies": [
65+
{
66+
"name": "default",
67+
"registryScopes": [
68+
"*"
69+
],
70+
"signatureVerification": {
71+
"level": "strict"
72+
},
73+
"trustStores": [
74+
"ca:certs"
75+
],
76+
"trustedIdentities": [
77+
"*"
78+
]
79+
}
80+
]
81+
}
82+
}
83+
]
84+
}
85+
}
86+
EOF
87+
```
88+
89+
The above config uses `root.crt` as the trust anchor for ratification. Run the following command to download the root cert:
90+
91+
```bash
92+
curl -Lo root.crt "http://www.microsoft.com/pkiops/certs/Microsoft%20Supply%20Chain%20RSA%20Root%20CA%202022.crt"
93+
```
94+
95+
Now, we can pull an image with ratification:
96+
97+
```console
98+
$ docker ratify pull -c config.json mcr.microsoft.com/oss/deislabs/ratify-base:v1.2.0
99+
INFO[0000] Setting log level to info
100+
INFO[0000] selected default auth provider: dockerConfig
101+
INFO[0000] defaultPluginPath set to /home/shizh/.ratify/plugins
102+
INFO[0000] selected policy provider: regopolicy
103+
INFO[0001] Resolve of the image completed successfully the digest is sha256:80dd14af4a7a676c962d0ca0f6e3b11a77b77826532fc863ea626317b158559c component-type=executor go.version=go1.21.10
104+
INFO[0002] Trust policy configuration: &{Name:default RegistryScopes:[*] SignatureVerification:{VerificationLevel:strict Override:map[]} TrustStores:[ca:certs] TrustedIdentities:[*]} component-type=verifier go.version=go1.21.10
105+
INFO[0002] 1 notation verification certificates loaded from path './root.crt'
106+
WARN[0002] Invalid path '/home/shizh/.ratify/ratify-certs/notation/truststore' skipped, error lstat /home/shizh/.ratify/ratify-certs/notation/truststore: no such file or directory
107+
INFO[0002] 0 notation verification certificates loaded from path '/home/shizh/.ratify/ratify-certs/notation/truststore'
108+
INFO[0002] Resolve of the image completed successfully the digest is sha256:ac86395350279f460c6bc08eb7875583c7365c423ebf9a7ac5a7a0f86f87924e component-type=executor go.version=go1.21.10
109+
INFO[0002] Resolve of the image completed successfully the digest is sha256:664dbce8187af59ee9a156b10f1ae66c0ab74b2d356bcce6ae3bfbffc90ddcf2 component-type=executor go.version=go1.21.10
110+
INFO[0002] Resolve of the image completed successfully the digest is sha256:f281be7185446aa5bd346b3ee859061c95199830cfd42ce289cda2994205076f component-type=executor go.version=go1.21.10
111+
INFO[0002] Resolve of the image completed successfully the digest is sha256:6557162adb2a50ac98b52477ce8959858ba3bafbb94f346fcf764ac0c2aa8346 component-type=executor go.version=go1.21.10
112+
INFO[0002] Resolve of the image completed successfully the digest is sha256:d93c4208945899f65c50f03024892a6f106344a0759eb1168e43d497d1582e40 component-type=executor go.version=go1.21.10
113+
INFO[0002] Trust policy configuration: &{Name:default RegistryScopes:[*] SignatureVerification:{VerificationLevel:strict Override:map[]} TrustStores:[ca:certs] TrustedIdentities:[*]} component-type=verifier go.version=go1.21.10
114+
INFO[0002] 1 notation verification certificates loaded from path './root.crt'
115+
WARN[0002] Invalid path '/home/shizh/.ratify/ratify-certs/notation/truststore' skipped, error lstat /home/shizh/.ratify/ratify-certs/notation/truststore: no such file or directory
116+
INFO[0002] 0 notation verification certificates loaded from path '/home/shizh/.ratify/ratify-certs/notation/truststore'
117+
INFO[0002] Trust policy configuration: &{Name:default RegistryScopes:[*] SignatureVerification:{VerificationLevel:strict Override:map[]} TrustStores:[ca:certs] TrustedIdentities:[*]} component-type=verifier go.version=go1.21.10
118+
INFO[0002] 1 notation verification certificates loaded from path './root.crt'
119+
WARN[0002] Invalid path '/home/shizh/.ratify/ratify-certs/notation/truststore' skipped, error lstat /home/shizh/.ratify/ratify-certs/notation/truststore: no such file or directory
120+
INFO[0002] 0 notation verification certificates loaded from path '/home/shizh/.ratify/ratify-certs/notation/truststore'
121+
INFO[0002] Resolve of the image completed successfully the digest is sha256:9a330411e967bde20bd41702fa6cdb32ab27183f53cd3a17af3ebac41d3112b2 component-type=executor go.version=go1.21.10
122+
mcr.microsoft.com/oss/deislabs/ratify-base@sha256:80dd14af4a7a676c962d0ca0f6e3b11a77b77826532fc863ea626317b158559c: Pulling from oss/deislabs/ratify-base
123+
b2ce0e066077: Pull complete
124+
e8d9a567199d: Pull complete
125+
058cf3d8c2ba: Pull complete
126+
b6824ed73363: Pull complete
127+
7c12895b777b: Pull complete
128+
33e068de2649: Pull complete
129+
5664b15f108b: Pull complete
130+
27be814a09eb: Pull complete
131+
4aa0ea1413d3: Pull complete
132+
da7816fa955e: Pull complete
133+
9aee425378d2: Pull complete
134+
0c4c7572df33: Pull complete
135+
dff9a998dfb4: Pull complete
136+
e03239cfd5d3: Pull complete
137+
Digest: sha256:80dd14af4a7a676c962d0ca0f6e3b11a77b77826532fc863ea626317b158559c
138+
Status: Downloaded newer image for mcr.microsoft.com/oss/deislabs/ratify-base@sha256:80dd14af4a7a676c962d0ca0f6e3b11a77b77826532fc863ea626317b158559c
139+
mcr.microsoft.com/oss/deislabs/ratify-base@sha256:80dd14af4a7a676c962d0ca0f6e3b11a77b77826532fc863ea626317b158559c
140+
```
141+
142+
Pulling an image without signatures will fail:
143+
144+
```console
145+
$ docker ratify pull -c config.json mcr.microsoft.com/mcr/hello-world:latest
146+
INFO[0000] Setting log level to info
147+
INFO[0000] selected default auth provider: dockerConfig
148+
INFO[0000] defaultPluginPath set to /home/shizh/.ratify/plugins
149+
INFO[0000] selected policy provider: regopolicy
150+
INFO[0000] Resolve of the image completed successfully the digest is sha256:92c7f9c92844bbbb5d0a101b22f7c2a7949e40f8ea90c8b3bc396879d95e899a component-type=executor go.version=go1.21.10
151+
Error: no ratifications found
152+
```

0 commit comments

Comments
 (0)