Global flag that outputs minimum policy HCL required for an operation

api/client.go

@@ -142,6 +142,14 @@ type Config struct {
 	// with the same client. Cloning a client will not clone this value.
 	OutputCurlString bool
 
+	// OutputPolicy causes the actual request to return an error of type
+	// *OutputPolicyError. Type asserting the error message will display
+	// an example of the required policy HCL needed for the operation.
+	//
+	// Note: It is not thread-safe to set this and make concurrent requests
+	// with the same client. Cloning a client will not clone this value.
+	OutputPolicy bool
+
 	// curlCACert, curlCAPath, curlClientCert and curlClientKey are used to keep
 	// track of the name of the TLS certs and keys when OutputCurlString is set.
 	// Cloning a client will also not clone those values.
@@ -577,6 +585,7 @@ func (c *Client) CloneConfig() *Config {
 	newConfig.Logger = c.config.Logger
 	newConfig.Limiter = c.config.Limiter
 	newConfig.OutputCurlString = c.config.OutputCurlString
+	newConfig.OutputPolicy = c.config.OutputPolicy
 	newConfig.SRVLookup = c.config.SRVLookup
 	newConfig.CloneHeaders = c.config.CloneHeaders
 	newConfig.CloneToken = c.config.CloneToken
@@ -768,6 +777,24 @@ func (c *Client) SetOutputCurlString(curl bool) {
 	c.config.OutputCurlString = curl
 }
 
+func (c *Client) OutputPolicy() bool {
+	c.modifyLock.RLock()
+	defer c.modifyLock.RUnlock()
+	c.config.modifyLock.RLock()
+	defer c.config.modifyLock.RUnlock()
+
+	return c.config.OutputPolicy
+}
+
+func (c *Client) SetOutputPolicy(isSet bool) {
+	c.modifyLock.RLock()
+	defer c.modifyLock.RUnlock()
+	c.config.modifyLock.Lock()
+	defer c.config.modifyLock.Unlock()
+
+	c.config.OutputPolicy = isSet
+}
+
 // CurrentWrappingLookupFunc sets a lookup function that returns desired wrap TTLs
 // for a given operation and path.
 func (c *Client) CurrentWrappingLookupFunc() WrappingLookupFunc {
@@ -1001,6 +1028,7 @@ func (c *Client) clone(cloneHeaders bool) (*Client, error) {
 		Logger:           config.Logger,
 		Limiter:          config.Limiter,
 		OutputCurlString: config.OutputCurlString,
+		OutputPolicy:     config.OutputPolicy,
 		AgentAddress:     config.AgentAddress,
 		SRVLookup:        config.SRVLookup,
 		CloneHeaders:     config.CloneHeaders,
@@ -1132,6 +1160,7 @@ func (c *Client) rawRequestWithContext(ctx context.Context, r *Request) (*Respon
 	backoff := c.config.Backoff
 	httpClient := c.config.HttpClient
 	outputCurlString := c.config.OutputCurlString
+	outputPolicy := c.config.OutputPolicy
 	logger := c.config.Logger
 	c.config.modifyLock.RUnlock()
 
@@ -1176,6 +1205,14 @@ START:
 		return nil, LastOutputStringError
 	}
 
+	if outputPolicy {
+		LastOutputPolicyError = &OutputPolicyError{
+			Request:     req,
+			VaultClient: c,
+		}
+		return nil, LastOutputPolicyError
+	}
+
 	req.Request = req.Request.WithContext(ctx)
 
 	if backoff == nil {
@@ -1268,6 +1305,7 @@ func (c *Client) httpRequestWithContext(ctx context.Context, r *Request) (*Respo
 	limiter := c.config.Limiter
 	httpClient := c.config.HttpClient
 	outputCurlString := c.config.OutputCurlString
+	outputPolicy := c.config.OutputPolicy
 	if c.headers != nil {
 		for header, vals := range c.headers {
 			for _, val := range vals {
@@ -1278,10 +1316,13 @@ func (c *Client) httpRequestWithContext(ctx context.Context, r *Request) (*Respo
 	c.config.modifyLock.RUnlock()
 	c.modifyLock.RUnlock()
 
-	// OutputCurlString logic relies on the request type to be retryable.Request as
+	// OutputCurlString and OutputPolicy logic relies on the request type to be retryable.Request
 	if outputCurlString {
 		return nil, fmt.Errorf("output-curl-string is not implemented for this request")
 	}
+	if outputPolicy {
+		return nil, fmt.Errorf("output-policy is not implemented for this request")
+	}
 
 	req.URL.User = r.URL.User
 	req.URL.Scheme = r.URL.Scheme

api/client_test.go

@@ -477,6 +477,7 @@ func TestClone(t *testing.T) {
 			parent.SetLimiter(5.0, 10)
 			parent.SetMaxRetries(5)
 			parent.SetOutputCurlString(true)
+			parent.SetOutputPolicy(true)
 			parent.SetSRVLookup(true)
 
 			if tt.headers != nil {

api/output_policy.go

@@ -0,0 +1,197 @@
+package api
+
+import (
+	"bytes"
+	"fmt"
+	"regexp"
+	"strings"
+
+	retryablehttp "github.com/hashicorp/go-retryablehttp"
+	"github.com/hashicorp/vault/sdk/helper/jsonutil"
+)
+
+const (
+	ErrOutputPolicyRequest = "output policy request"
+)
+
+var LastOutputPolicyError *OutputPolicyError
+
+type OutputPolicyError struct {
+	*retryablehttp.Request
+	VaultClient     *Client
+	parsingError    error
+	parsedHCLString string
+}
+
+func (d *OutputPolicyError) Error() string {
+	if d.parsedHCLString == "" {
+		d.parseRequest()
+		if d.parsingError != nil {
+			return d.parsingError.Error()
+		}
+	}
+
+	return ErrOutputPolicyRequest
+}
+
+// Builds a sample policy document from the request
+func (d *OutputPolicyError) parseRequest() {
+	capabilities := []string{}
+	switch d.Request.Method {
+	case "GET":
+		capabilities = append(capabilities, "read")
+	case "LIST":
+		capabilities = append(capabilities, "list")
+	case "POST", "PUT":
+		capabilities = append(capabilities, "create")
+		capabilities = append(capabilities, "update")
+	case "PATCH":
+		capabilities = append(capabilities, "patch")
+	case "DELETE":
+		capabilities = append(capabilities, "delete")
+	}
+
+	// trim the Vault address and v1 from the front of the path
+	url := d.Request.URL.String()
+	apiAddrPrefix := fmt.Sprintf("%sv1/", d.VaultClient.config.Address)
+	path := strings.Trim(url, apiAddrPrefix)
+
+	// determine whether to add sudo capability
+	needsSudo, err := isSudoPath(d.VaultClient, path)
+	if err != nil {
+		d.parsingError = err
+		return
+	}
+	if needsSudo {
+		capabilities = append(capabilities, "sudo")
+	}
+
+	capStr := strings.Join(capabilities, `", "`)
+	d.parsedHCLString = fmt.Sprintf(
+		`path "%s" {
+  capabilities = ["%s"]
+}`, path, capStr)
+}
+
+func (d *OutputPolicyError) HCLString() string {
+	if d.parsedHCLString == "" {
+		d.parseRequest()
+	}
+	return d.parsedHCLString
+}
+
+// Determine whether the given path requires the sudo capability
+func isSudoPath(client *Client, path string) (bool, error) {
+	sudoPaths, err := getSudoPaths(client)
+	if err != nil {
+		return false, fmt.Errorf("unable to retrieve list of paths that require sudo capability: %v", err)
+	}
+	if sudoPaths == nil || len(sudoPaths) < 1 {
+		// OpenAPI spec did not return any paths that require sudo for
+		// some reason, but the user probably still shouldn't see an error.
+		return false, nil
+	}
+
+	// Return early if the path is clearly one of the sudo paths.
+	if _, ok := sudoPaths[path]; ok {
+		return true, nil
+	}
+
+	// Some sudo paths have templated fields in them.
+	// (e.g. sys/revoke-prefix/{prefix})
+	// The keys in the sudoPaths map are actually regular expressions,
+	// so we can check if our path matches against them.
+	for sudoPath := range sudoPaths {
+		r, err := regexp.Compile(fmt.Sprintf("^%s$", sudoPath))
+		if err != nil {
+			continue
+		}
+
+		match := r.Match([]byte(fmt.Sprintf("/%s", path))) // the OpenAPI response has a / in front of each path
+		if match {
+			return true, nil
+		}
+	}
+
+	return false, nil
+}
+
+func getSudoPaths(client *Client) (map[string]bool, error) {
+	// We don't want to use a wrapping call or any special flags here
+	// so save any custom value and restore after.
+	currentWrappingLookupFunc := client.CurrentWrappingLookupFunc()
+	client.SetWrappingLookupFunc(nil)
+	defer client.SetWrappingLookupFunc(currentWrappingLookupFunc)
+	currentOutputCurlString := client.OutputCurlString()
+	client.SetOutputCurlString(false)
+	defer client.SetOutputCurlString(currentOutputCurlString)
+	currentOutputPolicy := client.OutputPolicy()
+	client.SetOutputPolicy(false)
+	defer client.SetOutputPolicy(currentOutputPolicy)
+
+	r := client.NewRequest("GET", "/v1/sys/internal/specs/openapi")
+	resp, err := client.RawRequest(r)
+	if resp != nil {
+		defer resp.Body.Close()
+	}
+	if err != nil {
+		return nil, fmt.Errorf("unable to retrieve sudo endpoints: %v", err)
+	}
+
+	var buf bytes.Buffer
+	_, err = buf.ReadFrom(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("unable to read response body from OpenAPI: %v", err)
+	}
+	if buf.Len() == 0 {
+		return nil, fmt.Errorf("OpenAPI response had no content")
+	}
+
+	oasInfo := make(map[string]interface{})
+	if err := jsonutil.DecodeJSONFromReader(&buf, &oasInfo); err != nil {
+		return nil, fmt.Errorf("unable to decode JSON from OpenAPI response: %v", err)
+	}
+
+	paths, ok := oasInfo["paths"]
+	if !ok {
+		return nil, fmt.Errorf("OpenAPI response did not include paths")
+	}
+
+	pathsMap, ok := paths.(map[string]interface{})
+	if !ok {
+		return nil, fmt.Errorf("OpenAPI response did not return valid paths")
+	}
+
+	sudoPaths := make(map[string]bool) // this could be a slice, but we're just making it a map so we can do quick lookups for the paths that don't have any templating
+	for pathName, pathInfo := range pathsMap {
+		pathInfoMap, ok := pathInfo.(map[string]interface{})
+		if !ok {
+			continue
+		}
+
+		if sudo, ok := pathInfoMap["x-vault-sudo"]; ok {
+			if sudo == true {
+				// Since many paths have templated fields like {name},
+				// our list of sudo paths will actually be a list of
+				// regular expressions that we can match against.
+				pathRegex := buildPathRegexp(pathName)
+				sudoPaths[pathRegex] = true
+			}
+		}
+	}
+
+	return sudoPaths, nil
+}
+
+// Replaces any template fields in a path with the characters ".+" so that
+// we can later allow any characters to match those fields.
+func buildPathRegexp(pathName string) string {
+	templateFields := []string{"{path}", "{header}", "{prefix}", "{name}", "{type}"}
+	pathWithRegexPatterns := pathName
+	for _, field := range templateFields {
+		r, _ := regexp.Compile(field)
+		pathWithRegexPatterns = r.ReplaceAllString(pathWithRegexPatterns, ".+")
+	}
+
+	return pathWithRegexPatterns
+}

api/output_policy_test.go

@@ -0,0 +1,91 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestIsSudoPath(t *testing.T) {
+	handler := func(w http.ResponseWriter, req *http.Request) {
+		w.Write([]byte(
+			`{
+				"paths": {
+					"/sudo/path": {
+						"x-vault-sudo": true
+					},
+					"/not/a/sudo/path": {
+						"x-vault-sudo": false
+					},
+					"not/a/sudo/path/either": {},
+					"/sudo/path/with/template/{name}": {
+						"x-vault-sudo": true
+					},
+					"/sudo/path/with/nested/template/{prefix}/too": {
+						"x-vault-sudo": true
+					},
+					"/sudo/path/with/multiple/templates/{type}/{header}": {
+						"x-vault-sudo": true
+					}
+				}
+			}`,
+		))
+	}
+
+	config, ln := testHTTPServer(t, http.HandlerFunc(handler))
+	defer ln.Close()
+
+	config.Address = strings.ReplaceAll(config.Address, "127.0.0.1", "localhost")
+	client, err := NewClient(config)
+	if err != nil {
+		t.Fatalf("err: %s", err)
+	}
+
+	client.SetToken("foo")
+
+	client.SetOutputPolicy(true)
+
+	testCases := []struct {
+		path     string
+		expected bool
+	}{
+		{
+			"secret/foo", // not in the openAPI response at all
+			false,
+		},
+		{
+			"sudo/path",
+			true,
+		},
+		{
+			"not/a/sudo/path",
+			false,
+		},
+		{
+			"not/a/sudo/path/either",
+			false,
+		},
+		{
+			"sudo/path/with/template/foo",
+			true,
+		},
+		{
+			"sudo/path/with/nested/template/foo/too",
+			true,
+		},
+		{
+			"sudo/path/with/multiple/templates/foo/bar",
+			true,
+		},
+	}
+
+	for _, tc := range testCases {
+		res, err := isSudoPath(client, tc.path)
+		if err != nil {
+			t.Fatalf("error checking if path is sudo: %v", err)
+		}
+		if res != tc.expected {
+			t.Fatalf("expected isSudoPath to return %v for path %s but it returned %v", tc.expected, tc.path, res)
+		}
+	}
+}