https://ratify.dev/assets/js/408d4fa2.44b7116f.js

1"use strict";(globalThis.webpackChunkratify=globalThis.webpackChunkratify||[]).push([[2568],{28453(e,i,n){n.d(i,{R:()=>s,x:()=>c});var r=n(96540);const o={},t=r.createContext(o);function s(e){const i=r.useContext(t);return r.useMemo(function(){return"function"==typeof e?e(i):{...i,...e}},[i,e])}function c(e){let i;return i=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:s(e.components),r.createElement(t.Provider,{value:i},e.children)}},99605(e,i,n){n.r(i),n.d(i,{assets:()=>l,contentTitle:()=>c,default:()=>h,frontMatter:()=>s,metadata:()=>r,toc:()=>a});const r=JSON.parse('{"id":"reference/providers","title":"Store/Verifier Providers","description":"The framework uses a provider model for extensibility to support different types of referrer stores and verifiers. It supports two types of providers.","source":"@site/versioned_docs/version-1.1/reference/providers.md","sourceDirName":"reference","slug":"/reference/providers","permalink":"/docs/1.1/reference/providers","draft":false,"unlisted":false,"editUrl":"https://github.com/ratify-project/ratify-web/blob/main/versioned_docs/version-1.1/reference/providers.md","tags":[],"version":"1.1","frontMatter":{},"sidebar":"tutorialSidebar","previous":{"title":"Performance at Scale","permalink":"/docs/1.1/reference/performance"},"next":{"title":"Framework Overview","permalink":"/docs/1.1/reference/ratify-framework-overview"}}');var o=n(74848),t=n(28453);const s={},c="Store/Verifier Providers",l={},a=[{value:"How is the Policy Provider used in Ratify execution?",id:"how-is-the-policy-provider-used-in-ratify-execution",level:2},{value:"Rego Policy Provider",id:"rego-policy-provider",level:2},{value:"Rego Policy Usage",id:"rego-policy-usage",level:3},{value:"Rego Policy Samples",id:"rego-policy-samples",level:3},{value:"Config Policy Provider",id:"config-policy-provider",level:2},{value:"Config Policy Examples:",id:"config-policy-examples",level:3},{value:"Notational Conventions",id:"notational-conventions",level:2}];function d(e){const i={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",ul:"ul",...(0,t.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(i.header,{children:(0,o.jsx)(i.h1,{id:"storeverifier-providers",children:"Store/Verifier Providers"})}),"\n",(0,o.jsx)(i.p,{children:"The framework uses a provider model for extensibility to support different types of referrer stores and verifiers. It supports two types of providers."}),"\n",(0,o.jsxs)(i.p,{children:["Built-In/Internal providers are available in the source of the framework and are registered during startup using the ",(0,o.jsx)(i.code,{children:"init"})," function. Referrer store using ",(0,o.jsx)(i.a,{href:"https://github.com/oras-project/oras",children:"ORAS"})," and signature verification using ",(0,o.jsx)(i.a,{href:"https://github.com/notaryproject/notation",children:"notation"})," are currently available as the built-in providers in the framework and are managed by the framework."]}),"\n",(0,o.jsxs)(i.p,{children:["External/Plugin providers are external to the source and process of the framework. They are registered as binaries that implement the plugin specification for the corresponding provider. The framework will locate these binaries in the configured paths and invoke them by passing the required parameters as per the specification. ",(0,o.jsx)(i.a,{href:"https://github.com/ratify-project/ratify/tree/main/plugins/verifier/sbom",children:"SBOM"})," verification and signature verification using ",(0,o.jsx)(i.a,{href:"https://github.com/ratify-project/ratify/tree/main/plugins/verifier/cosign",children:"cosign"})," libraries are examples of the providers that are implemented as plugins."]}),"\n",(0,o.jsx)(i.h1,{id:"policy-providers",children:"Policy Providers"}),"\n",(0,o.jsxs)(i.p,{children:["Ratify implements an extensible policy provider interface allowing for different policy providers to be created and registered. The policy provider to be used is determined by the policy plugin specified in the ",(0,o.jsx)(i.code,{children:"policy"})," section of the configuration."]}),"\n",(0,o.jsxs)(i.p,{children:["Currently, Ratify supports a Configuration based Policy Provider named ",(0,o.jsx)(i.co

1de,{children:"configPolicy"}),"."]}),"\n",(0,o.jsx)(i.h2,{id:"how-is-the-policy-provider-used-in-ratify-execution",children:"How is the Policy Provider used in Ratify execution?"}),"\n",(0,o.jsx)(i.p,{children:'The executor is the "glue" that links all Ratify plugin-based components such as the verifiers, referrer stores, and policy providers. The policy provider is primarily invoked for each reference artifact discovered AFTER a configured verifier is found that can be used to verify that particular artifacy type. If a reference artifact is found that does not have a corresponding verifier configured that can perform verification, the executor will ignore this artifact. As a result, this unverifiable artifact will NOT influence the final overall verification success determined by the policy provider.'}),"\n",(0,o.jsx)(i.h2,{id:"rego-policy-provider",children:"Rego Policy Provider"}),"\n",(0,o.jsxs)(i.p,{children:["The Rego Policy Provider is a built-in policy provider that uses ",(0,o.jsx)(i.a,{href:"https://www.openpolicyagent.org/",children:"Open Policy Agent"})," (OPA) and ",(0,o.jsx)(i.a,{href:"https://www.openpolicyagent.org/docs/latest/policy-language/",children:"Rego"})," to implement a policy provider. The Rego Policy Provider is a plugin that is registered with Ratify and is invoked by the executor to determine the overall verification success if required. The Rego Policy Provider is configured using the ",(0,o.jsx)(i.code,{children:"policy"})," section of the configuration."]}),"\n",(0,o.jsx)(i.pre,{children:(0,o.jsx)(i.code,{className:"language-json",children:'"policy": {\n    "version": "1.0.0",\n    "plugin": {\n        "name": "regoPolicy",\n        "policyPath": "",\n        "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[c

1ount(path) - 1] == \\"isSuccess\\"\\n}",\n        "passthroughEnabled": false\n    }\n},\n'})}),"\n",(0,o.jsxs)(i.ul,{children:["\n",(0,o.jsxs)(i.li,{children:["The ",(0,o.jsx)(i.code,{children:"name"})," field is REQUIRED and MUST match the name of the registered policy provider."]}),"\n",(0,o.jsxs)(i.li,{children:["One of ",(0,o.jsx)(i.code,{children:"policyPath"})," and ",(0,o.jsx)(i.code,{children:"policy"})," fields MUST be specified.","\n",(0,o.jsxs)(i.ul,{children:["\n",(0,o.jsxs)(i.li,{children:[(0,o.jsx)(i.code,{children:"policyPath"}),": path to the Rego policy file. The file MUST be a valid Rego policy file."]}),"\n",(0,o.jsxs)(i.li,{children:[(0,o.jsx)(i.code,{children:"policy"}),": Rego policy as a string. The string MUST be a valid Rego policy."]}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(i.li,{children:["The ",(0,o.jsx)(i.code,{children:"passthroughEnabled"})," field is optional, which defaults to be ",(0,o.jsx)(i.code,{children:"false"})," if not provided, in thise case, Ratify will return the verification results with the decision to Gatekeeper. If ",(0,o.jsx)(i.code,{children:"passthroughEnabled"})," is set to ",(0,o.jsx)(i.code,{children:"true"}),", the executor will NOT make the decision but only pass the verification results to Gatekeeper for making the decision."]}),"\n"]}),"\n",(0,o.jsx)(i.h3,{id:"rego-policy-usage",children:"Rego Policy Usage"}),"\n",(0,o.jsx)(i.p,{children:"Ratify embeds OPA engine inside the executor to provide a built-in policy provider. There are 2 approaches to enable this feature as an add-on service."}),"\n",(0,o.jsxs)(i.ol,{children:["\n",(0,o.jsxs)(i.li,{children:["Set the helm chart value of ",(0,o.jsx)(i.code,{children:"policy.useRego"})," to ",(0,o.jsx)(i.code,{children:"true"})," while deploying Ratify."]}),"\n",(0,o.jsx)(i.li,{children:"Apply a Policy Custom Resource with Rego Policy if the service is up. e.g."}),"\n"]}),"\n",(0,o.jsx)(i.pre,{children:(0,o.jsx)(i.code,{className:"language-bash",children:"kubectl apply -f ./config/samples/policy/config_v1alpha1_policy_rego.yaml\n"})}),"\n",(0,o.jsxs)(i.p,{children:["And if Ratify is used as command line tool, users MUST provide a config with Rego Policy. Check ",(0,o.jsx)(i.code,{children:"test/bats/tests/config/config_rego_policy_notation_leaf_cert.json"})," as an example."]}),"\n",(0,o.jsx)(i.p,{children:"Note that verification results returned are different while switching Rego policy/config policy."}),"\n",(0,o.jsxs)(i.p,{children:["When Rego Policy is selected, the Verification Response follows ",(0,o.jsx)(i.code,{children:"1.0.0"})," version. ",(0,o.jsx)(i.a,{href:"/docs/1.1/reference/verification-result-version#1.0.0",children:"1.0.0"})," provides definition and example usage of the response."]}),"\n",(0,o.jsx)(i.h3,{id:"rego-policy-samples",children:"Rego Policy Samples"}),"\n",(0,o.jsxs)(i.p,{children:["Check out ",(0,o.jsx)(i.a,{href:"/docs/1.1/reference/rego-templates",children:"rego templates"})," for more details on writing your own policy and provided samples."]}),"\n",(0,o.jsx)(i.h2,{id:"config-policy-provider",children:"Config Policy Provider"}),"\n",(0,o.jsx)(i.pre,{children:(0,o.jsx)(i.code,{children:'...\n"policy": {\n    "version": "1.0.0",\n    "plugin": {\n        "name": "configPolicy",\n        "artifactVerificationPolicies": {\n            "application/vnd.cncf.notary.signature": "any"\n        }\n    }\n},\n...\n'})}),"\n",(0,o.jsxs)(i.ul,{children:["\n",(0,o.jsxs)(i.li,{children:["The ",(0,o.jsx)(i.code,{children:"name"})," field is REQUIRED and MUST match the name of the registered policy provider"]}),"\n",(0,o.jsxs)(i.li,{children:[(0,o.jsx)(i.code,{children:"artifactVerificationPolicies"}),": map of artifact type to policy; each entry in the map's policy must be satisfied for Ratify to return true.","\n",(0,o.jsxs)(i.ul,{children:["\n",(0,o.jsxs)(i.li,{children:[(0,o.jsx)(i.code,{children:"any"}),": policy that REQUIRES at least one artifact of specified type to verify to ",(0,o.jsx)(i.code,{children:"true"})]}),"\n",(0,o.jsxs)(i.li,{children:[(0,o.jsx)(i.code,{children:"all"}),": policy that REQUIRES all artifacts of specified type to verify to `true``"]}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(i.li,{children:["Default policy:","\n",(0,o.jsxs)(i.ul,{children:["\n",(0,o.jsxs)(i.li,{children:["\n",(0,o.jsxs)(i.p,{children:["The ",(0,o.jsx)(i.co

1de,{children:"default"})," policy applies to unspecified artifact types. The ",(0,o.jsx)(i.code,{children:"default"})," policy is set to ",(0,o.jsx)(i.code,{children:"all"}),". Thus, all unspecified artifact types must have all successful verification results for an overall success result."]}),"\n"]}),"\n",(0,o.jsxs)(i.li,{children:["\n",(0,o.jsxs)(i.p,{children:["The ",(0,o.jsx)(i.code,{children:"default"})," policy can be overridden to ",(0,o.jsx)(i.code,{children:"any"})," in the map:"]}),"\n",(0,o.jsx)(i.pre,{children:(0,o.jsx)(i.code,{children:'...\n"policy": {\n    "version": "1.0.0",\n    "plugin": {\n        "name": "configPolicy",\n        "artifactVerificationPolicies": {\n            "default": "any"\n        }\n    }\n},\n...\n'})}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,o.jsx)(i.h3,{id:"config-policy-examples",children:"Config Policy Examples:"}),"\n",(0,o.jsxs)(i.ul,{children:["\n",(0,o.jsxs)(i.li,{children:["Require all reference artifacts associated with subject image to be verify successfully:","\n",(0,o.jsx)(i.pre,{children:(0,o.jsx)(i.code,{children:'...\n"policy": {\n    "version": "1.0.0",\n    "plugin": {\n        "name": "configPolicy"\n    }\n},\n...\n'})}),"\n"]}),"\n",(0,o.jsxs)(i.li,{children:["Require at least one reference artifact of the same type to verify succesfully. (relaxes the default policy to 'any'):","\n",(0,o.jsx)(i.pre,{children:(0,o.jsx)(i.code,{children:'...\n"policy": {\n    "version": "1.0.0",\n    "plugin": {\n        "name": "configPolicy",\n        "artifactVerificationPolicies": {\n            "default": "any"\n        }\n    }\n},\n...\n'})}),"\n"]}),"\n",(0,o.jsxs)(i.li,{children:["For a specific artifact type, relax requirement so only one success is needed for artifacts of that type:","\n",(0,o.jsx)(i.pre,{children:(0,o.jsx)(i.code,{children:'...\n"policy": {\n    "version": "1.0.0",\n    "plugin": {\n        "name": "configPolicy",\n        "artifactVerificationPolicies": {\n            "application/vnd.cncf.notary.signature": "any"\n        }\n    }\n},\n...\n'})}),"\n"]}),"\n"]}),"\n",(0,o.jsxs)(i.p,{children:["The Verification response follows ",(0,o.jsx)(i.code,{children:"0.1.0"})," version. Check definition and examples in ",(0,o.jsx)(i.a,{href:"/docs/1.1/reference/verification-result-version#0.1.0",children:"0.1.0"}),"."]}),"\n",(0,o.jsx)(i.h2,{id:"notational-conventions",children:"Notational Conventions"}),"\n",(0,o.jsxs)(i.p,{children:['The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in ',(0,o.jsx)(i.a,{href:"http://tools.ietf.org/html/rfc2119",children:"RFC 2119"}),"."]}),"\n",(0,o.jsxs)(i.p,{children:['The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the ',(0,o.jsx)(i.a,{href:"http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18",children:"rationale for the C99 standard"}),"."]})]})}function h(e={}){const{wrapper:i}={...(0,t.R)(),...e.components};return i?(0,o.jsx)(i,{...e,children:(0,o.jsx)(d,{...e})}):d(e)}}}]);