Skip to content

Commit c9b4766

Browse files
hubwritershati-patelgithub-openapi-bot
authored
Update docs for the code scanning API (#17653)
* Add custom media type info and update subsection cross-refs * Update the permissions for GH Apps page * Add temporary JSON files Replace these with the autogenerated ones from github/github, when the associated PR over there is merged. * Change json+sarif to sarif+json * Condition media types section This new section will only become accurate in GHES 3.1 * Add temporary copies of decorated & dereferenced files * Add new endpoints to the permissions page /rest/reference/permissions-required-for-github-apps * Update temp JSON files * Update JSON files * Add github-ae: '*' * Add github-ae: '*' * Add github-ae: '*' * Update content/rest/reference/code-scanning.md * Update JSON files * Update content/github/finding-security-vulnerabilities-and-errors-in-your-code/sarif-support-for-code-scanning.md Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com> * Update content/github/finding-security-vulnerabilities-and-errors-in-your-code/uploading-a-sarif-file-to-github.md Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com> * Update content/rest/reference/code-scanning.md Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com> * Update content/rest/reference/code-scanning.md Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com> * Update content/rest/reference/permissions-required-for-github-apps.md Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com> * Make review comment changes * Remove development mode JSON files * Update OpenAPI Descriptions (#17857) * Update OpenAPI Descriptions * Add decorated OpenAPI schema files * Remove development mode JSON files * Update OpenAPI JSON files (#17869) * Update OpenAPI Descriptions * Add decorated OpenAPI schema files Co-authored-by: github-openapi-bot <security+github-openapi-bot@github.com> * Remove development mode JSON files * Update OpenAPI Descriptions (#17863) * Update OpenAPI Descriptions * Add decorated OpenAPI schema files * Update content/rest/reference/permissions-required-for-github-apps.md Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com> * Update content/rest/reference/permissions-required-for-github-apps.md * Update content/rest/reference/permissions-required-for-github-apps.md * Update content/rest/reference/permissions-required-for-github-apps.md * Update content/rest/reference/permissions-required-for-github-apps.md * Update content/rest/reference/code-scanning.md Co-authored-by: Shati Patel <42641846+shati-patel@users.noreply.github.com> Co-authored-by: github-openapi-bot <69533958+github-openapi-bot@users.noreply.github.com> Co-authored-by: github-openapi-bot <security+github-openapi-bot@github.com>
1 parent 6ce85ac commit c9b4766

20 files changed

Lines changed: 8091 additions & 4191 deletions

‎content/github/finding-security-vulnerabilities-and-errors-in-your-code/sarif-support-for-code-scanning.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Each time the results of a new code scan are uploaded, the results are processed
3232

3333
SARIF files created by the {% data variables.product.prodname_codeql_workflow %} or using the {% data variables.product.prodname_codeql_runner %} include fingerprint data. If you upload a SARIF file using the `upload-sarif` action and this data is missing, {% data variables.product.prodname_dotcom %} attempts to populate the `partialFingerprints` field from the source files. For more information about uploading results, see "[Uploading a SARIF file to {% data variables.product.prodname_dotcom %}](/github/finding-security-vulnerabilities-and-errors-in-your-code/uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions)."
3434

35-
If you upload a SARIF file without fingerprint data using the `/code-scanning/sarifs` API endpoint, the {% data variables.product.prodname_code_scanning %} alerts will be processed and displayed, but users may see duplicate alerts. To avoid seeing duplicate alerts, you should calculate fingerprint data and populate the `partialFingerprints` property before you upload the SARIF file. You may find the script that the `upload-sarif` action uses a helpful starting point: https://github.com/github/codeql-action/blob/main/src/fingerprints.ts. For more information about the API, see "[Upload a SARIF file](/rest/reference/code-scanning#upload-a-sarif-file)."
35+
If you upload a SARIF file without fingerprint data using the `/code-scanning/sarifs` API endpoint, the {% data variables.product.prodname_code_scanning %} alerts will be processed and displayed, but users may see duplicate alerts. To avoid seeing duplicate alerts, you should calculate fingerprint data and populate the `partialFingerprints` property before you upload the SARIF file. You may find the script that the `upload-sarif` action uses a helpful starting point: https://github.com/github/codeql-action/blob/main/src/fingerprints.ts. For more information about the API, see "[Upload an analysis as SARIF data](/rest/reference/code-scanning#upload-an-analysis-as-sarif-data)."
3636

3737
### Validating your SARIF file
3838

‎content/github/finding-security-vulnerabilities-and-errors-in-your-code/uploading-a-sarif-file-to-github.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ You can upload the results using {% data variables.product.prodname_actions %}{%
2525
- {% data variables.product.prodname_actions %} to run the {% data variables.product.prodname_codeql %} action, there is no further action required. The {% data variables.product.prodname_codeql %} action uploads the SARIF file automatically when it completes analysis.
2626
- {% data variables.product.prodname_actions %} to run a SARIF-compatible analysis tool, you could update the workflow to include a final step that uploads the results (see below).
2727
- The {% data variables.product.prodname_codeql_runner %}, to run {% data variables.product.prodname_code_scanning %} in your CI system, by default the runner automatically uploads results to {% data variables.product.prodname_dotcom %} on completion. If you block the automatic upload, when you are ready to upload results you can use the `upload` command (for more information, see "[Running {% data variables.product.prodname_code_scanning %} in your CI system](/github/finding-security-vulnerabilities-and-errors-in-your-code/running-codeql-code-scanning-in-your-ci-system)").
28-
- A tool that generates results as an artifact outside of your repository, you can use the {% data variables.product.prodname_code_scanning %} API to upload the file (for more information, see "[Upload a SARIF file](/rest/reference/code-scanning#upload-a-sarif-file)").
28+
- A tool that generates results as an artifact outside of your repository, you can use the {% data variables.product.prodname_code_scanning %} API to upload the file (for more information, see "[Upload an analysis as SARIF data](/rest/reference/code-scanning#upload-an-analysis-as-sarif-data)").
2929

3030
{% data reusables.code-scanning.not-available %}
3131

@@ -115,4 +115,4 @@ jobs:
115115
- "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/reference/workflow-syntax-for-github-actions)"
116116
- "[Viewing your workflow history](/actions/managing-workflow-runs/viewing-workflow-run-history)"
117117
- "[Running {% data variables.product.prodname_code_scanning %} in your CI system](/github/finding-security-vulnerabilities-and-errors-in-your-code/running-codeql-code-scanning-in-your-ci-system)"
118-
- "[Upload a SARIF file](/rest/reference/code-scanning#upload-a-sarif-file)"
118+
- "[Upload an analysis as SARIF data](/rest/reference/code-scanning#upload-an-analysis-as-sarif-data)"

‎content/rest/reference/code-scanning.md‎

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,97 @@ versions:
1010

1111
{% data reusables.code-scanning.beta %}
1212

13-
The {% data variables.product.prodname_code_scanning %} API lets you retrieve and update code scanning alerts from a repository. You can use the endpoints to create automated reports for the code scanning alerts in an organization or upload analysis results generated using offline code scanning tools. For more information, see "[Finding security vulnerabilities and errors in your code](/github/finding-security-vulnerabilities-and-errors-in-your-code)."
13+
The {% data variables.product.prodname_code_scanning %} API lets you retrieve and update {% data variables.product.prodname_code_scanning %} alerts from a repository. You can use the endpoints to create automated reports for the {% data variables.product.prodname_code_scanning %} alerts in an organization or upload analysis results generated using offline {% data variables.product.prodname_code_scanning %} tools. For more information, see "[Finding security vulnerabilities and errors in your code](/github/finding-security-vulnerabilities-and-errors-in-your-code)."
14+
15+
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
16+
### Custom media type for {% data variables.product.prodname_code_scanning %}
17+
18+
There is one supported custom media type for the {% data variables.product.prodname_code_scanning %} REST API. You can use this with `GET` requests sent to the `/analyses/{analysis_id}` endpoint. When you use this media type with this operation, the response includes a subset of the actual data that was uploaded for the specified analysis, rather than details about the analysis, which is returned when you use the default media type. The response also includes additional data such as the `github/alertNumber` and `github/alertUrl` properties. The data is formatted as [SARIF version 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html).
19+
20+
application/sarif+json
21+
22+
For more information, see "[Media types](/rest/overview/media-types)."
23+
24+
#### Response using the custom media type
25+
26+
This example response is from a `GET` request to the `/analyses/{analysis_id}` endpoint, using `application/sarif+json` as the `Accept` header value. The example has had indendation and line breaks added for readability. For more information about this endpoint, see "[Get a {% data variables.product.prodname_code_scanning %} analysis for a repository](#get-a-code-scanning-analysis-for-a-repository)."
27+
28+
```
29+
{
30+
"runs": [
31+
{
32+
"artifacts": [
33+
{
34+
"location": {
35+
"index": 0,
36+
"uri": "src/promiseUtils.js"
37+
}
38+
},
39+
{
40+
"location": {
41+
"index": 1,
42+
"uri": "main.js"
43+
}
44+
}
45+
],
46+
"conversion": {
47+
"tool": {
48+
"driver": {
49+
"name": "GitHub Code Scanning"
50+
}
51+
}
52+
},
53+
"results": [
54+
{
55+
"correlationGuid": "7f75ba0b-61a9-11eb-b882-b4969152bf2c",
56+
"level": "warning",
57+
"locations": [
58+
{
59+
"physicalLocation": {
60+
"artifactLocation": {
61+
"index": 0,
62+
"uri": "src/promiseUtils.js"
63+
},
64+
"region": {
65+
"endLine": 2,
66+
"startColumn": 1,
67+
"startLine": 2
68+
}
69+
}
70+
}
71+
],
72+
"message": {
73+
"text": "Function resolvingPromise is sometimes invoked as a constructor (for example [here](1)), and sometimes as a normal function (for example [here](2))."
74+
},
75+
"partialFingerprints": {
76+
"primaryLocationLineHash": "5061c3315a741b7d:1"
77+
},
78+
"properties": {
79+
"github/alertNumber": 4,
80+
"github/alertUrl": "https://api.github.com/repos/octocat/hello-world/code-scanning/alerts/4"
81+
}
82+
},
83+
...
84+
],
85+
"tool": {
86+
"driver": {
87+
"name": "CodeQL",
88+
"version": "2.0.0"
89+
}
90+
},
91+
"versionControlProvenance": [
92+
{
93+
"branch": "refs/heads/master",
94+
"repositoryUri": "https://github.com/octocat/hello-world",
95+
"revisionId": "c18c69115354ff0166991962832dc2bd7756e655"
96+
}
97+
]
98+
}
99+
],
100+
"$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
101+
"version": "2.1.0"
102+
}
103+
```
104+
{% endif %}
14105

15106
{% include rest_operations_at_current_path %}

‎content/rest/reference/permissions-required-for-github-apps.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -841,11 +841,27 @@ _Teams_
841841
### Permission on "security events"
842842

843843
- [`GET /repos/:owner/:repo/code-scanning/alerts`](/rest/reference/code-scanning#list-code-scanning-alerts-for-a-repository) (:read)
844-
- [`GET /repos/:owner/:repo/code-scanning/alerts/:alert_id`](/rest/reference/code-scanning#get-a-code-scanning-alert) (:read)
845-
- [`PATCH /repos/:owner/:repo/code-scanning/alerts/:alert_id`](/rest/reference/code-scanning#update-a-code-scanning-alert) (:write)
846-
- [`GET /repos/:owner/:repo/code-scanning/analyses`](/rest/reference/code-scanning#list-recent-code-scanning-analyses-for-a-repository) (:read)
844+
- [`GET /repos/:owner/:repo/code-scanning/alerts/:alert_number`](/rest/reference/code-scanning#get-a-code-scanning-alert) (:read)
845+
- [`PATCH /repos/:owner/:repo/code-scanning/alerts/:alert_number`](/rest/reference/code-scanning#update-a-code-scanning-alert) (:write)
846+
{% endif %}
847+
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
848+
- [`GET /repos/:owner/:repo/code-scanning/alerts/:alert_number/instances`](/rest/reference/code-scanning#list-instances-of-a-code-scanning-alert) (:read)
849+
{% endif %}
850+
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
851+
- [`GET /repos/:owner/:repo/code-scanning/analyses`](/rest/reference/code-scanning#list-code-scanning-analyses-for-a-repository) (:read)
852+
{% endif %}
853+
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
854+
- [`GET /repos/:owner/:repo/code-scanning/analyses/:analysis_id`](/rest/reference/code-scanning#get-a-code-scanning-analysis-for-a-repository) (:read)
855+
{% endif %}
856+
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
857+
- [`DELETE /repos/:owner/:repo/code-scanning/analyses/:analysis_id`](/rest/reference/code-scanning#delete-a-code-scanning-analysis-from-a-repository) (:write)
858+
{% endif %}
859+
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
847860
- [`POST /repos/:owner/:repo/code-scanning/sarifs`](/rest/reference/code-scanning#upload-a-sarif-file) (:write)
848861
{% endif %}
862+
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
863+
- [`GET /repos/:owner/:repo/code-scanning/sarifs/:sarif_id`](/rest/reference/code-scanning#get-information-about-a-sarif-upload) (:read)
864+
{% endif %}
849865

850866
{% if currentVersion == "free-pro-team@latest" %}
851867
### Permission on "self-hosted runners"

0 commit comments

Comments
 (0)