code-scanning.go

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

     1  // Copyright 2020 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  package github
     7  
     8  import (
     9  	"context"
    10  	"fmt"
    11  	"strconv"
    12  	"strings"
    13  )
    14  
    15  // CodeScanningService handles communication with the code scanning related
    16  // methods of the GitHub API.
    17  //
    18  // GitHub API docs: https://docs.github.com/en/rest/code-scanning
    19  type CodeScanningService service
    20  
    21  // Rule represents the complete details of GitHub Code Scanning alert type.
    22  type Rule struct {
    23  	ID                    *string  `json:"id,omitempty"`
    24  	Severity              *string  `json:"severity,omitempty"`
    25  	Description           *string  `json:"description,omitempty"`
    26  	Name                  *string  `json:"name,omitempty"`
    27  	SecuritySeverityLevel *string  `json:"security_severity_level,omitempty"`
    28  	FullDescription       *string  `json:"full_description,omitempty"`
    29  	Tags                  []string `json:"tags,omitempty"`
    30  	Help                  *string  `json:"help,omitempty"`
    31  }
    32  
    33  // Location represents the exact location of the GitHub Code Scanning Alert in the scanned project.
    34  type Location struct {
    35  	Path        *string `json:"path,omitempty"`
    36  	StartLine   *int    `json:"start_line,omitempty"`
    37  	EndLine     *int    `json:"end_line,omitempty"`
    38  	StartColumn *int    `json:"start_column,omitempty"`
    39  	EndColumn   *int    `json:"end_column,omitempty"`
    40  }
    41  
    42  // Message is a part of MostRecentInstance struct which provides the appropriate message when any action is performed on the analysis object.
    43  type Message struct {
    44  	Text *string `json:"text,omitempty"`
    45  }
    46  
    47  // MostRecentInstance provides details of the most recent instance of this alert for the default branch or for the specified Git reference.
    48  type MostRecentInstance struct {
    49  	Ref             *string   `json:"ref,omitempty"`
    50  	AnalysisKey     *string   `json:"analysis_key,omitempty"`
    51  	Environment     *string   `json:"environment,omitempty"`
    52  	State           *string   `json:"state,omitempty"`
    53  	CommitSHA       *string   `json:"commit_sha,omitempty"`
    54  	Message         *Message  `json:"message,omitempty"`
    55  	Location        *Location `json:"location,omitempty"`
    56  	Classifications []string  `json:"classifications,omitempty"`
    57  }
    58  
    59  // Tool represents the tool used to generate a GitHub Code Scanning Alert.
    60  type Tool struct {
    61  	Name    *string `json:"name,omitempty"`
    62  	GUID    *string `json:"guid,omitempty"`
    63  	Version *string `json:"version,omitempty"`
    64  }
    65  
    66  // Alert represents an individual GitHub Code Scanning Alert on a single repository.
    67  //
    68  // GitHub API docs: https://docs.github.com/en/rest/code-scanning
    69  type Alert struct {
    70  	Number             *int                  `json:"number,omitempty"`
    71  	Repository         *Repository           `json:"repository,omitempty"`
    72  	RuleID             *string               `json:"rule_id,omitempty"`
    73  	RuleSeverity       *string               `json:"rule_severity,omitempty"`
    74  	RuleDescription    *string               `json:"rule_description,omitempty"`
    75  	Rule               *Rule                 `json:"rule,omitempty"`
    76  	Tool               *Tool                 `json:"tool,omitempty"`
    77  	CreatedAt          *Timestamp            `json:"created_at,omitempty"`
    78  	UpdatedAt          *Timestamp            `json:"updated_at,omitempty"`
    79  	FixedAt            *Timestamp            `json:"fixed_at,omitempty"`
    80  	State              *string               `json:"state,omitempty"`
    81  	ClosedBy           *User                 `json:"closed_by,omitempty"`
    82  	ClosedAt           *Timestamp            `json:"closed_at,omitempty"`
    83  	URL                *string               `json:"url,omitempty"`
    84  	HTMLURL            *string               `json:"html_url,omitempty"`
    85  	MostRecentInstance *MostRecentInstance   `json:"most_recent_instance,omitempty"`
    86  	Instances          []*MostRecentInstance `json:"instances,omitempty"`
    87  	DismissedBy        *User                 `json:"dismissed_by,omitempty"`
    88  	DismissedAt        *Timestamp            `json:"dismissed_at,omitempty"`
    89  	DismissedReason    *string               `json:"dismissed_reason,omitempty"`
    90  	InstancesURL       *string               `json:"instances_url,omitempty"`
    91  }
    92  
    93  // ID returns the ID associated with an alert. It is the number at the end of the security alert's URL.
    94  func (a *Alert) ID() int64 {
    95  	if a == nil {
    96  		return 0
    97  	}
    98  
    99  	s := a.GetHTMLURL()
   100  
   101  	// Check for an ID to parse at the end of the url
   102  	if i := strings.LastIndex(s, "/"); i >= 0 {
   103  		s = s[i+1:]
   104  	}
   105  
   106  	// Return the alert ID as a 64-bit integer. Unable to convert or out of range returns 0.
   107  	id, err := strconv.ParseInt(s, 10, 64)
   108  	if err != nil {
   109  		return 0
   110  	}
   111  
   112  	return id
   113  }
   114  
   115  // AlertListOptions specifies optional parameters to the CodeScanningService.ListAlerts
   116  // method.
   117  type AlertListOptions struct {
   118  	// State of the code scanning alerts to list. Set to closed to list only closed code scanning alerts. Default: open
   119  	State string `url:"state,omitempty"`
   120  
   121  	// Return code scanning alerts for a specific branch reference. The ref must be formatted as heads/<branch name>.
   122  	Ref string `url:"ref,omitempty"`
   123  
   124  	ListOptions
   125  }
   126  
   127  // AnalysesListOptions specifies optional parameters to the CodeScanningService.ListAnalysesForRepo method.
   128  type AnalysesListOptions struct {
   129  	// Return code scanning analyses belonging to the same SARIF upload.
   130  	SarifID *string `url:"sarif_id,omitempty"`
   131  
   132  	// Return code scanning analyses for a specific branch reference. The ref can be formatted as refs/heads/<branch name> or simply <branch name>.
   133  	Ref *string `url:"ref,omitempty"`
   134  
   135  	ListOptions
   136  }
   137  
   138  // ScanningAnalysis represents an individual GitHub Code Scanning ScanningAnalysis on a single repository.
   139  //
   140  // GitHub API docs: https://docs.github.com/en/rest/code-scanning
   141  type ScanningAnalysis struct {
   142  	ID           *int64     `json:"id,omitempty"`
   143  	Ref          *string    `json:"ref,omitempty"`
   144  	CommitSHA    *string    `json:"commit_sha,omitempty"`
   145  	AnalysisKey  *string    `json:"analysis_key,omitempty"`
   146  	Environment  *string    `json:"environment,omitempty"`
   147  	Error        *string    `json:"error,omitempty"`
   148  	Category     *string    `json:"category,omitempty"`
   149  	CreatedAt    *Timestamp `json:"created_at,omitempty"`
   150  	ResultsCount *int       `json:"results_count,omitempty"`
   151  	RulesCount   *int       `json:"rules_count,omitempty"`
   152  	URL          *string    `json:"url,omitempty"`
   153  	SarifID      *string    `json:"sarif_id,omitempty"`
   154  	Tool         *Tool      `json:"tool,omitempty"`
   155  	Deletable    *bool      `json:"deletable,omitempty"`
   156  	Warning      *string    `json:"warning,omitempty"`
   157  }
   158  
   159  // SarifAnalysis specifies the results of a code scanning job.
   160  //
   161  // GitHub API docs: https://docs.github.com/en/rest/code-scanning
   162  type SarifAnalysis struct {
   163  	CommitSHA   *string    `json:"commit_sha,omitempty"`
   164  	Ref         *string    `json:"ref,omitempty"`
   165  	Sarif       *string    `json:"sarif,omitempty"`
   166  	CheckoutURI *string    `json:"checkout_uri,omitempty"`
   167  	StartedAt   *Timestamp `json:"started_at,omitempty"`
   168  	ToolName    *string    `json:"tool_name,omitempty"`
   169  }
   170  
   171  // SarifID identifies a sarif analysis upload.
   172  //
   173  // GitHub API docs: https://docs.github.com/en/rest/code-scanning
   174  type SarifID struct {
   175  	ID  *string `json:"id,omitempty"`
   176  	URL *string `json:"url,omitempty"`
   177  }
   178  
   179  // ListAlertsForOrg lists code scanning alerts for an org.
   180  //
   181  // You must use an access token with the security_events scope to use this endpoint. GitHub Apps must have the security_events
   182  // read permission to use this endpoint.
   183  //
   184  // GitHub API docs: https://docs.github.com/en/rest/code-scanning#list-code-scanning-alerts-for-an-organization
   185  func (s *CodeScanningService) ListAlertsForOrg(ctx context.Context, org string, opts *AlertListOptions) ([]*Alert, *Response, error) {
   186  	u := fmt.Sprintf("orgs/%v/code-scanning/alerts", org)
   187  	u, err := addOptions(u, opts)
   188  	if err != nil {
   189  		return nil, nil, err
   190  	}
   191  
   192  	req, err := s.client.NewRequest("GET", u, nil)
   193  	if err != nil {
   194  		return nil, nil, err
   195  	}
   196  
   197  	var alerts []*Alert
   198  	resp, err := s.client.Do(ctx, req, &alerts)
   199  	if err != nil {
   200  		return nil, resp, err
   201  	}
   202  
   203  	return alerts, resp, nil
   204  }
   205  
   206  // ListAlertsForRepo lists code scanning alerts for a repository.
   207  //
   208  // Lists all open code scanning alerts for the default branch (usually master) and protected branches in a repository.
   209  // You must use an access token with the security_events scope to use this endpoint. GitHub Apps must have the security_events
   210  // read permission to use this endpoint.
   211  //
   212  // GitHub API docs: https://docs.github.com/en/rest/code-scanning#list-code-scanning-alerts-for-a-repository
   213  func (s *CodeScanningService) ListAlertsForRepo(ctx context.Context, owner, repo string, opts *AlertListOptions) ([]*Alert, *Response, error) {
   214  	u := fmt.Sprintf("repos/%v/%v/code-scanning/alerts", owner, repo)
   215  	u, err := addOptions(u, opts)
   216  	if err != nil {
   217  		return nil, nil, err
   218  	}
   219  
   220  	req, err := s.client.NewRequest("GET", u, nil)
   221  	if err != nil {
   222  		return nil, nil, err
   223  	}
   224  
   225  	var alerts []*Alert
   226  	resp, err := s.client.Do(ctx, req, &alerts)
   227  	if err != nil {
   228  		return nil, resp, err
   229  	}
   230  
   231  	return alerts, resp, nil
   232  }
   233  
   234  // GetAlert gets a single code scanning alert for a repository.
   235  //
   236  // You must use an access token with the security_events scope to use this endpoint.
   237  // GitHub Apps must have the security_events read permission to use this endpoint.
   238  //
   239  // The security alert_id is the number at the end of the security alert's URL.
   240  //
   241  // GitHub API docs: https://docs.github.com/en/rest/code-scanning#get-a-code-scanning-alert
   242  func (s *CodeScanningService) GetAlert(ctx context.Context, owner, repo string, id int64) (*Alert, *Response, error) {
   243  	u := fmt.Sprintf("repos/%v/%v/code-scanning/alerts/%v", owner, repo, id)
   244  
   245  	req, err := s.client.NewRequest("GET", u, nil)
   246  	if err != nil {
   247  		return nil, nil, err
   248  	}
   249  
   250  	a := new(Alert)
   251  	resp, err := s.client.Do(ctx, req, a)
   252  	if err != nil {
   253  		return nil, resp, err
   254  	}
   255  
   256  	return a, resp, nil
   257  }
   258  
   259  // UploadSarif uploads the result of code scanning job to GitHub.
   260  //
   261  // For the parameter sarif, you must first compress your SARIF file using gzip and then translate the contents of the file into a Base64 encoding string.
   262  // You must use an access token with the security_events scope to use this endpoint. GitHub Apps must have the security_events
   263  // write permission to use this endpoint.
   264  //
   265  // GitHub API docs: https://docs.github.com/en/rest/code-scanning#upload-an-analysis-as-sarif-data
   266  func (s *CodeScanningService) UploadSarif(ctx context.Context, owner, repo string, sarif *SarifAnalysis) (*SarifID, *Response, error) {
   267  	u := fmt.Sprintf("repos/%v/%v/code-scanning/sarifs", owner, repo)
   268  
   269  	req, err := s.client.NewRequest("POST", u, sarif)
   270  	if err != nil {
   271  		return nil, nil, err
   272  	}
   273  
   274  	sarifID := new(SarifID)
   275  	resp, err := s.client.Do(ctx, req, sarifID)
   276  	if err != nil {
   277  		return nil, resp, err
   278  	}
   279  
   280  	return sarifID, resp, nil
   281  }
   282  
   283  // ListAnalysesForRepo lists code scanning analyses for a repository.
   284  //
   285  // Lists the details of all code scanning analyses for a repository, starting with the most recent.
   286  // You must use an access token with the security_events scope to use this endpoint.
   287  // GitHub Apps must have the security_events read permission to use this endpoint.
   288  //
   289  // GitHub API docs: https://docs.github.com/en/rest/code-scanning#list-code-scanning-analyses-for-a-repository
   290  func (s *CodeScanningService) ListAnalysesForRepo(ctx context.Context, owner, repo string, opts *AnalysesListOptions) ([]*ScanningAnalysis, *Response, error) {
   291  	u := fmt.Sprintf("repos/%v/%v/code-scanning/analyses", owner, repo)
   292  	u, err := addOptions(u, opts)
   293  	if err != nil {
   294  		return nil, nil, err
   295  	}
   296  
   297  	req, err := s.client.NewRequest("GET", u, nil)
   298  	if err != nil {
   299  		return nil, nil, err
   300  	}
   301  
   302  	var analyses []*ScanningAnalysis
   303  	resp, err := s.client.Do(ctx, req, &analyses)
   304  	if err != nil {
   305  		return nil, resp, err
   306  	}
   307  
   308  	return analyses, resp, nil
   309  }
   310  
   311  // GetAnalysis gets a single code scanning analysis for a repository.
   312  //
   313  // You must use an access token with the security_events scope to use this endpoint.
   314  // GitHub Apps must have the security_events read permission to use this endpoint.
   315  //
   316  // The security analysis_id is the ID of the analysis, as returned from the ListAnalysesForRepo operation.
   317  //
   318  // GitHub API docs: https://docs.github.com/en/rest/code-scanning#get-a-code-scanning-analysis-for-a-repository
   319  func (s *CodeScanningService) GetAnalysis(ctx context.Context, owner, repo string, id int64) (*ScanningAnalysis, *Response, error) {
   320  	u := fmt.Sprintf("repos/%v/%v/code-scanning/analyses/%v", owner, repo, id)
   321  
   322  	req, err := s.client.NewRequest("GET", u, nil)
   323  	if err != nil {
   324  		return nil, nil, err
   325  	}
   326  
   327  	analysis := new(ScanningAnalysis)
   328  	resp, err := s.client.Do(ctx, req, analysis)
   329  	if err != nil {
   330  		return nil, resp, err
   331  	}
   332  
   333  	return analysis, resp, nil
   334  }
   335
View as plain text