feat: add hashed token to responses for correlation with GitHub audit logs (#163)

Author: SpencerLN

README.org

@@ -354,6 +354,15 @@ favour =repository_ids= (GitHub repository IDs are immutable) instead of
 =repositories= (GitHub repository names are mutable).
 #+end_quote
 
+#+begin_quote
+NOTE: All token responses (including those from permission sets) include
+=hashed_token=, a base64-encoded SHA-256 hash of the returned token that matches
+GitHub's [[https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token#token-data-in-audit-log-events][audit log]] =hashed_token= field. This value is safe to log and enables
+correlation between Vault-issued tokens and GitHub audit events by searching for
+=hashed_token:"VALUE"=. You can verify the hash yourself with:
+=echo -n TOKEN | openssl dgst -sha256 -binary | base64=.
+#+end_quote
+
 - =installation_id= (int64) — the ID of the app installation.
 - =org_name= (string) — the organisation name.
 - =repositories= ([]string) — a list of the names of the repositories within the

github/client.go

@@ -3,6 +3,8 @@ package github
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -240,6 +242,10 @@ func (c *Client) token(ctx context.Context, tokReq *tokenRequest) (*logical.Resp
 		}
 	}
 
+	if hashedToken, ok := hashedTokenFromValue(resData["token"]); ok {
+		resData["hashed_token"] = hashedToken
+	}
+
 	// Enrich the response with what we know about the installation.
 	tokRes := &logical.Response{Data: resData}
 	tokRes.Data["installation_id"] = tokReq.InstallationID
@@ -274,6 +280,17 @@ func (c *Client) accessTokenURLForInstallationID(installationID int) (*url.URL,
 	return url.ParseRequestURI(fmt.Sprintf(c.accessTokenURLTemplate, installationID))
 }
 
+func hashedTokenFromValue(token any) (string, bool) {
+	tokenStr, ok := token.(string)
+	if !ok || tokenStr == "" {
+		return "", false
+	}
+
+	hash := sha256.Sum256([]byte(tokenStr))
+
+	return base64.StdEncoding.EncodeToString(hash[:]), true
+}
+
 // ListInstallations retrieves a list of App installations associated with the
 // client. It returns a logical.Response containing a map where the keys are
 // account names and the values are corresponding installation IDs. In case of

github/client_test.go

@@ -19,11 +19,12 @@ import (
 )
 
 const (
-	testRepo1   = "vault-plugin-secrets-github"
-	testRepo2   = "hashitalkaunz"
-	testRepoID1 = 223704264
-	testRepoID2 = 360447594
-	testToken   = "ghs_1aRGyjpfMQ98l0rnji5dstEEg10rOY3lenzG"
+	testRepo1     = "vault-plugin-secrets-github"
+	testRepo2     = "hashitalkaunz"
+	testRepoID1   = 223704264
+	testRepoID2   = 360447594
+	testToken     = "ghs_1aRGyjpfMQ98l0rnji5dstEEg10rOY3lenzG"
+	testTokenHash = "p/q8OhHzX3aiPGHBmqq6IfTS1bYVqOCj1ct2oSJekGg=" // echo -n testToken | openssl dgst -sha256 -binary | base64
 )
 
 var (
@@ -147,6 +148,7 @@ func TestClient_Token(t *testing.T) {
 			}),
 			res: &logical.Response{
 				Data: map[string]any{
+					"hashed_token":    testTokenHash,
 					"token":           testToken,
 					"installation_id": testInsID1,
 					"expires_at":      testTokenExp,
@@ -193,6 +195,7 @@ func TestClient_Token(t *testing.T) {
 			}),
 			res: &logical.Response{
 				Data: map[string]any{
+					"hashed_token":    testTokenHash,
 					"token":           testToken,
 					"installation_id": testInsID1,
 					"expires_at":      testTokenExp,
@@ -316,6 +319,7 @@ func TestClient_Token(t *testing.T) {
 			}),
 			res: &logical.Response{
 				Data: map[string]any{
+					"hashed_token":    testTokenHash,
 					"token":           testToken,
 					"installation_id": testInsID1,
 					"expires_at":      testTokenExp,
@@ -360,6 +364,7 @@ func TestClient_Token(t *testing.T) {
 			}),
 			res: &logical.Response{
 				Data: map[string]any{
+					"hashed_token":    testTokenHash,
 					"token":           testToken,
 					"installation_id": testInsID1,
 					"expires_at":      testTokenExp,
@@ -464,6 +469,7 @@ func TestClient_Token(t *testing.T) {
 			if tc.res != nil && tc.res.Data != nil {
 				assert.Equal(t, res.Data["expires_at"], tc.res.Data["expires_at"])
 				assert.Equal(t, res.Data["token"], tc.res.Data["token"])
+				assert.Equal(t, res.Data["hashed_token"], tc.res.Data["hashed_token"])
 
 				if _, ok := tc.res.Data["permissions"]; ok {
 					testPerms := tc.res.Data["permissions"].(map[string]string)
@@ -476,7 +482,6 @@ func TestClient_Token(t *testing.T) {
 					resRepos := res.Data["repositories"].([]any)
 					assert.Equal(t, len(resRepos), len(testRepos))
 				}
-				assert.Equal(t, res.Data["token"], tc.res.Data["token"])
 			}
 		})
 	}

github/integration_test.go

@@ -368,6 +368,8 @@ func testCreateTokenByInstallationID(t *testing.T) {
 		assert.Assert(t, resData["token"] != "")
 		assert.Assert(t, resData["expires_at"] != "")
 	}
+
+	assertHashedTokenMatchesToken(t, resData)
 }
 
 func testCreateTokenByOrgName(t *testing.T) {
@@ -396,6 +398,8 @@ func testCreateTokenByOrgName(t *testing.T) {
 		assert.Assert(t, resData["token"] != "")
 		assert.Assert(t, resData["expires_at"] != "")
 	}
+
+	assertHashedTokenMatchesToken(t, resData)
 }
 
 func testCreatePermissionSetToken(t *testing.T) {
@@ -423,6 +427,8 @@ func testCreatePermissionSetToken(t *testing.T) {
 		assert.Assert(t, resData["token"] != "")
 		assert.Assert(t, resData["expires_at"] != "")
 	}
+
+	assertHashedTokenMatchesToken(t, resData)
 }
 
 func testRevokeTokens(t *testing.T) {
@@ -473,6 +479,24 @@ func testCreateTokenByInstallationIDWithConstraints(t *testing.T) {
 		assert.Assert(t, resData["token"] != "")
 		assert.Assert(t, resData["expires_at"] != "")
 	}
+
+	assertHashedTokenMatchesToken(t, resData)
+}
+
+func assertHashedTokenMatchesToken(t *testing.T, resData map[string]any) {
+	t.Helper()
+
+	token, ok := resData["token"].(string)
+	assert.Assert(t, ok, "response missing token string: %#v", resData)
+	assert.Assert(t, token != "")
+
+	hashedToken, ok := resData["hashed_token"].(string)
+	assert.Assert(t, ok, "response missing hashed_token string: %#v", resData)
+	assert.Assert(t, hashedToken != "")
+
+	expectedHash, ok := hashedTokenFromValue(token)
+	assert.Assert(t, ok)
+	assert.Equal(t, hashedToken, expectedHash)
 }
 
 func vaultDo(

github/path_token_permission_set_test.go

@@ -78,6 +78,7 @@ func testBackendPathTokenPermissionSetWrite(t *testing.T, op logical.Operation)
 		assert.Assert(t, r != nil)
 		assert.Equal(t, r.Data["expires_at"].(string), testTokenExp)
 		assert.Equal(t, r.Data["token"].(string), testToken)
+		assert.Equal(t, r.Data["hashed_token"].(string), testTokenHash)
 	})
 
 	t.Run("MissingInstallationID", func(t *testing.T) {

github/path_token_test.go

@@ -69,6 +69,7 @@ func testBackendPathTokenWrite(t *testing.T, op logical.Operation) {
 		assert.Assert(t, r != nil)
 		assert.Equal(t, r.Data["expires_at"].(string), testTokenExp)
 		assert.Equal(t, r.Data["token"].(string), testToken)
+		assert.Equal(t, r.Data["hashed_token"].(string), testTokenHash)
 	})
 
 	t.Run("FailedClient", func(t *testing.T) {