messages.go

Documentation: github.com/google/go-github/v45/github

     1  // Copyright 2016 The go-github AUTHORS. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  // This file provides functions for validating payloads from GitHub Webhooks.
     7  // GitHub API docs: https://developer.github.com/webhooks/securing/#validating-payloads-from-github
     8  
     9  package github
    10  
    11  import (
    12  	"crypto/hmac"
    13  	"crypto/sha1"
    14  	"crypto/sha256"
    15  	"crypto/sha512"
    16  	"encoding/hex"
    17  	"encoding/json"
    18  	"errors"
    19  	"fmt"
    20  	"hash"
    21  	"io"
    22  	"io/ioutil"
    23  	"mime"
    24  	"net/http"
    25  	"net/url"
    26  	"strings"
    27  )
    28  
    29  const (
    30  	// sha1Prefix is the prefix used by GitHub before the HMAC hexdigest.
    31  	sha1Prefix = "sha1"
    32  	// sha256Prefix and sha512Prefix are provided for future compatibility.
    33  	sha256Prefix = "sha256"
    34  	sha512Prefix = "sha512"
    35  	// SHA1SignatureHeader is the GitHub header key used to pass the HMAC-SHA1 hexdigest.
    36  	SHA1SignatureHeader = "X-Hub-Signature"
    37  	// SHA256SignatureHeader is the GitHub header key used to pass the HMAC-SHA256 hexdigest.
    38  	SHA256SignatureHeader = "X-Hub-Signature-256"
    39  	// EventTypeHeader is the GitHub header key used to pass the event type.
    40  	EventTypeHeader = "X-Github-Event"
    41  	// DeliveryIDHeader is the GitHub header key used to pass the unique ID for the webhook event.
    42  	DeliveryIDHeader = "X-Github-Delivery"
    43  )
    44  
    45  var (
    46  	// eventTypeMapping maps webhooks types to their corresponding go-github struct types.
    47  	eventTypeMapping = map[string]string{
    48  		"branch_protection_rule":         "BranchProtectionRuleEvent",
    49  		"check_run":                      "CheckRunEvent",
    50  		"check_suite":                    "CheckSuiteEvent",
    51  		"commit_comment":                 "CommitCommentEvent",
    52  		"content_reference":              "ContentReferenceEvent",
    53  		"create":                         "CreateEvent",
    54  		"delete":                         "DeleteEvent",
    55  		"deploy_key":                     "DeployKeyEvent",
    56  		"deployment":                     "DeploymentEvent",
    57  		"deployment_status":              "DeploymentStatusEvent",
    58  		"discussion":                     "DiscussionEvent",
    59  		"fork":                           "ForkEvent",
    60  		"github_app_authorization":       "GitHubAppAuthorizationEvent",
    61  		"gollum":                         "GollumEvent",
    62  		"installation":                   "InstallationEvent",
    63  		"installation_repositories":      "InstallationRepositoriesEvent",
    64  		"issue_comment":                  "IssueCommentEvent",
    65  		"issues":                         "IssuesEvent",
    66  		"label":                          "LabelEvent",
    67  		"marketplace_purchase":           "MarketplacePurchaseEvent",
    68  		"member":                         "MemberEvent",
    69  		"membership":                     "MembershipEvent",
    70  		"meta":                           "MetaEvent",
    71  		"milestone":                      "MilestoneEvent",
    72  		"organization":                   "OrganizationEvent",
    73  		"org_block":                      "OrgBlockEvent",
    74  		"package":                        "PackageEvent",
    75  		"page_build":                     "PageBuildEvent",
    76  		"ping":                           "PingEvent",
    77  		"project":                        "ProjectEvent",
    78  		"project_card":                   "ProjectCardEvent",
    79  		"project_column":                 "ProjectColumnEvent",
    80  		"public":                         "PublicEvent",
    81  		"pull_request":                   "PullRequestEvent",
    82  		"pull_request_review":            "PullRequestReviewEvent",
    83  		"pull_request_review_comment":    "PullRequestReviewCommentEvent",
    84  		"pull_request_review_thread":     "PullRequestReviewThreadEvent",
    85  		"pull_request_target":            "PullRequestTargetEvent",
    86  		"push":                           "PushEvent",
    87  		"repository":                     "RepositoryEvent",
    88  		"repository_dispatch":            "RepositoryDispatchEvent",
    89  		"repository_import":              "RepositoryImportEvent",
    90  		"repository_vulnerability_alert": "RepositoryVulnerabilityAlertEvent",
    91  		"release":                        "ReleaseEvent",
    92  		"secret_scanning_alert":          "SecretScanningAlertEvent",
    93  		"star":                           "StarEvent",
    94  		"status":                         "StatusEvent",
    95  		"team":                           "TeamEvent",
    96  		"team_add":                       "TeamAddEvent",
    97  		"user":                           "UserEvent",
    98  		"watch":                          "WatchEvent",
    99  		"workflow_dispatch":              "WorkflowDispatchEvent",
   100  		"workflow_job":                   "WorkflowJobEvent",
   101  		"workflow_run":                   "WorkflowRunEvent",
   102  	}
   103  )
   104  
   105  // genMAC generates the HMAC signature for a message provided the secret key
   106  // and hashFunc.
   107  func genMAC(message, key []byte, hashFunc func() hash.Hash) []byte {
   108  	mac := hmac.New(hashFunc, key)
   109  	mac.Write(message)
   110  	return mac.Sum(nil)
   111  }
   112  
   113  // checkMAC reports whether messageMAC is a valid HMAC tag for message.
   114  func checkMAC(message, messageMAC, key []byte, hashFunc func() hash.Hash) bool {
   115  	expectedMAC := genMAC(message, key, hashFunc)
   116  	return hmac.Equal(messageMAC, expectedMAC)
   117  }
   118  
   119  // messageMAC returns the hex-decoded HMAC tag from the signature and its
   120  // corresponding hash function.
   121  func messageMAC(signature string) ([]byte, func() hash.Hash, error) {
   122  	if signature == "" {
   123  		return nil, nil, errors.New("missing signature")
   124  	}
   125  	sigParts := strings.SplitN(signature, "=", 2)
   126  	if len(sigParts) != 2 {
   127  		return nil, nil, fmt.Errorf("error parsing signature %q", signature)
   128  	}
   129  
   130  	var hashFunc func() hash.Hash
   131  	switch sigParts[0] {
   132  	case sha1Prefix:
   133  		hashFunc = sha1.New
   134  	case sha256Prefix:
   135  		hashFunc = sha256.New
   136  	case sha512Prefix:
   137  		hashFunc = sha512.New
   138  	default:
   139  		return nil, nil, fmt.Errorf("unknown hash type prefix: %q", sigParts[0])
   140  	}
   141  
   142  	buf, err := hex.DecodeString(sigParts[1])
   143  	if err != nil {
   144  		return nil, nil, fmt.Errorf("error decoding signature %q: %v", signature, err)
   145  	}
   146  	return buf, hashFunc, nil
   147  }
   148  
   149  // ValidatePayload validates an incoming GitHub Webhook event request body
   150  // and returns the (JSON) payload.
   151  // The Content-Type header of the payload can be "application/json" or "application/x-www-form-urlencoded".
   152  // If the Content-Type is neither then an error is returned.
   153  // secretToken is the GitHub Webhook secret token.
   154  // If your webhook does not contain a secret token, you can pass nil or an empty slice.
   155  // This is intended for local development purposes only and all webhooks should ideally set up a secret token.
   156  //
   157  // Example usage:
   158  //
   159  //     func (s *GitHubEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) {
   160  //       // read signature from request
   161  //       signature := ""
   162  //       payload, err := github.ValidatePayloadFromBody(r.Header.Get("Content-Type"), r.Body, signature, s.webhookSecretKey)
   163  //       if err != nil { ... }
   164  //       // Process payload...
   165  //     }
   166  func ValidatePayloadFromBody(contentType string, readable io.Reader, signature string, secretToken []byte) (payload []byte, err error) {
   167  	var body []byte // Raw body that GitHub uses to calculate the signature.
   168  
   169  	switch contentType {
   170  	case "application/json":
   171  		var err error
   172  		if body, err = ioutil.ReadAll(readable); err != nil {
   173  			return nil, err
   174  		}
   175  
   176  		// If the content type is application/json,
   177  		// the JSON payload is just the original body.
   178  		payload = body
   179  
   180  	case "application/x-www-form-urlencoded":
   181  		// payloadFormParam is the name of the form parameter that the JSON payload
   182  		// will be in if a webhook has its content type set to application/x-www-form-urlencoded.
   183  		const payloadFormParam = "payload"
   184  
   185  		var err error
   186  		if body, err = ioutil.ReadAll(readable); err != nil {
   187  			return nil, err
   188  		}
   189  
   190  		// If the content type is application/x-www-form-urlencoded,
   191  		// the JSON payload will be under the "payload" form param.
   192  		form, err := url.ParseQuery(string(body))
   193  		if err != nil {
   194  			return nil, err
   195  		}
   196  		payload = []byte(form.Get(payloadFormParam))
   197  
   198  	default:
   199  		return nil, fmt.Errorf("webhook request has unsupported Content-Type %q", contentType)
   200  	}
   201  
   202  	// Only validate the signature if a secret token exists. This is intended for
   203  	// local development only and all webhooks should ideally set up a secret token.
   204  	if len(secretToken) > 0 {
   205  		if err := ValidateSignature(signature, body, secretToken); err != nil {
   206  			return nil, err
   207  		}
   208  	}
   209  
   210  	return payload, nil
   211  }
   212  
   213  // ValidatePayload validates an incoming GitHub Webhook event request
   214  // and returns the (JSON) payload.
   215  // The Content-Type header of the payload can be "application/json" or "application/x-www-form-urlencoded".
   216  // If the Content-Type is neither then an error is returned.
   217  // secretToken is the GitHub Webhook secret token.
   218  // If your webhook does not contain a secret token, you can pass nil or an empty slice.
   219  // This is intended for local development purposes only and all webhooks should ideally set up a secret token.
   220  //
   221  // Example usage:
   222  //
   223  //     func (s *GitHubEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) {
   224  //       payload, err := github.ValidatePayload(r, s.webhookSecretKey)
   225  //       if err != nil { ... }
   226  //       // Process payload...
   227  //     }
   228  //
   229  func ValidatePayload(r *http.Request, secretToken []byte) (payload []byte, err error) {
   230  	signature := r.Header.Get(SHA256SignatureHeader)
   231  	if signature == "" {
   232  		signature = r.Header.Get(SHA1SignatureHeader)
   233  	}
   234  
   235  	contentType, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
   236  	if err != nil {
   237  		return nil, err
   238  	}
   239  
   240  	return ValidatePayloadFromBody(contentType, r.Body, signature, secretToken)
   241  }
   242  
   243  // ValidateSignature validates the signature for the given payload.
   244  // signature is the GitHub hash signature delivered in the X-Hub-Signature header.
   245  // payload is the JSON payload sent by GitHub Webhooks.
   246  // secretToken is the GitHub Webhook secret token.
   247  //
   248  // GitHub API docs: https://developer.github.com/webhooks/securing/#validating-payloads-from-github
   249  func ValidateSignature(signature string, payload, secretToken []byte) error {
   250  	messageMAC, hashFunc, err := messageMAC(signature)
   251  	if err != nil {
   252  		return err
   253  	}
   254  	if !checkMAC(payload, messageMAC, secretToken, hashFunc) {
   255  		return errors.New("payload signature check failed")
   256  	}
   257  	return nil
   258  }
   259  
   260  // WebHookType returns the event type of webhook request r.
   261  //
   262  // GitHub API docs: https://docs.github.com/en/developers/webhooks-and-events/events/github-event-types
   263  func WebHookType(r *http.Request) string {
   264  	return r.Header.Get(EventTypeHeader)
   265  }
   266  
   267  // DeliveryID returns the unique delivery ID of webhook request r.
   268  //
   269  // GitHub API docs: https://docs.github.com/en/developers/webhooks-and-events/events/github-event-types
   270  func DeliveryID(r *http.Request) string {
   271  	return r.Header.Get(DeliveryIDHeader)
   272  }
   273  
   274  // ParseWebHook parses the event payload. For recognized event types, a
   275  // value of the corresponding struct type will be returned (as returned
   276  // by Event.ParsePayload()). An error will be returned for unrecognized event
   277  // types.
   278  //
   279  // Example usage:
   280  //
   281  //     func (s *GitHubEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) {
   282  //       payload, err := github.ValidatePayload(r, s.webhookSecretKey)
   283  //       if err != nil { ... }
   284  //       event, err := github.ParseWebHook(github.WebHookType(r), payload)
   285  //       if err != nil { ... }
   286  //       switch event := event.(type) {
   287  //       case *github.CommitCommentEvent:
   288  //           processCommitCommentEvent(event)
   289  //       case *github.CreateEvent:
   290  //           processCreateEvent(event)
   291  //       ...
   292  //       }
   293  //     }
   294  //
   295  func ParseWebHook(messageType string, payload []byte) (interface{}, error) {
   296  	eventType, ok := eventTypeMapping[messageType]
   297  	if !ok {
   298  		return nil, fmt.Errorf("unknown X-Github-Event in message: %v", messageType)
   299  	}
   300  
   301  	event := Event{
   302  		Type:       &eventType,
   303  		RawPayload: (*json.RawMessage)(&payload),
   304  	}
   305  	return event.ParsePayload()
   306  }
   307
View as plain text