jprdonnelly/docs
1
0
Fork 0
mirror of synced 2026-01-07 09:01:31 -05:00
Code Issues Projects Releases Wiki Activity

Make tables accessible in the Code security focus areas (#35432)

Browse Source 
Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com>
Co-authored-by: Felicity Chapman <felicitymay@github.com>
This commit is contained in:
Laura Coursen
2023-03-10 15:50:31 -06:00
committed by GitHub
parent 3619ffff88
commit 080192fbc1
11 changed files with 284 additions and 285 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
content/billing/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security.md
View File

@@ -107,9 +107,9 @@ The following example timeline demonstrates how active committer count for {% da
| :- | :- | -: |
| <nobr>April 15</nobr> | A member of your enterprise enables {% data variables.product.prodname_GH_advanced_security %} for repository **X**. Repository **X** has 50 committers over the past 90 days. | **50** |
| <nobr>May 1</nobr> | Developer **A** leaves the team working on repository **X**. Developer **A**'s contributions continue to count for 90 days. | **50** | **50** |
| <nobr>August 1</nobr> | Developer **A**'s contributions no longer count towards the licenses required, because 90 days have passed. | <sub>_50 - 1_</sub></br>**49** |
| <nobr>August 15</nobr> | A member of your enterprise enables {% data variables.product.prodname_GH_advanced_security %} for a second repository, repository **Y**. In the last 90 days, a total of 20 developers contributed to that repository. Of those 20 developers, 10 also recently worked on repo **X** and do not require additional licenses. | <sub>_49 + 10_</sub><br/>**59** |
| <nobr>August 16</nobr> | A member of your enterprise disables {% data variables.product.prodname_GH_advanced_security %} for repository **X**. Of the 49 developers who were working on repository **X**, 10 still also work on repository **Y**, which has a total of 20 developers contributing in the last 90 days. | <sub>_49 - 29_</sub><br/>**20** |
| <nobr>August 1</nobr> | Developer **A**'s contributions no longer count towards the licenses required, because 90 days have passed. | 50 - 1 =<br>**49** |
| <nobr>August 15</nobr> | A member of your enterprise enables {% data variables.product.prodname_GH_advanced_security %} for a second repository, repository **Y**. In the last 90 days, a total of 20 developers contributed to that repository. Of those 20 developers, 10 also recently worked on repo **X** and do not require additional licenses. | 49 + 10 =<br>**59** |
| <nobr>August 16</nobr> | A member of your enterprise disables {% data variables.product.prodname_GH_advanced_security %} for repository **X**. Of the 49 developers who were working on repository **X**, 10 still also work on repository **Y**, which has a total of 20 developers contributing in the last 90 days. | 49 - 29 =<br>**20** |
{% note %}

168
content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md
View File

@@ -97,7 +97,7 @@ The file is successfully uploaded as both absolute URIs use the same URI scheme
<!--UI-LINK: When code scanning fails, the error banner shown in the Security > Code scanning alerts view links to this anchor.-->
You can check a SARIF file is compatible with {% data variables.product.prodname_code_scanning %} by testing it against the {% data variables.product.prodname_dotcom %} ingestion rules. For more information, visit the [Microsoft SARIF validator](https://sarifweb.azurewebsites.net/).
You can check a SARIF file is compatible with {% data variables.product.prodname_code_scanning %} by testing it against the {% data variables.product.prodname_dotcom %} ingestion rules. For more information, visit the [Microsoft SARIF validator](https://sarifweb.azurewebsites.net/).
For each `gzip`-compressed SARIF file, SARIF upload supports a maximum size of 10 MB. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.
@@ -105,37 +105,37 @@ For each `gzip`-compressed SARIF file, SARIF upload supports a maximum size of 1
{% ifversion fpt or ghec or ghes > 3.8 %}
| **SARIF data** | **Maximum values** | **Additional limits** |
|----------------------------------|:------------------:|----------------------------------------------------------------------------------|
| Runs per file | 20 | |
| Results per run | 25,000 | Only the top 5,000 results will be included, prioritized by severity. |
| Rules per run | 25,000 | |
| Tool extensions per run | 100 | |
| Thread Flow Locations per result | 10,000 | Only the top 1,000 Thread Flow Locations will be included, using prioritization. |
| Location per result | 1,000 | Only 100 locations will be included. |
| Tags per rule | 20 | Only 10 tags will be included. |
| **SARIF data** | **Maximum values** | **Additional limits** |
|----------------|:------------------:|-----------------------|
| Runs per file | 20 | None |
| Results per run | 25,000 | Only the top 5,000 results will be included, prioritized by severity. |
| Rules per run | 25,000 | None |
| Tool extensions per run | 100 | None |
| Thread Flow Locations per result | 10,000 | Only the top 1,000 Thread Flow Locations will be included, using prioritization. |
| Location per result | 1,000 | Only 100 locations will be included. |
| Tags per rule | 20 | Only 10 tags will be included. |
{% elsif ghes < 3.9 %}
| **SARIF data** | **Maximum values** | **Additional limits** |
|----------------------------------|:------------------:|----------------------------------------------------------------------------------|
| Runs per file | 15 | |
| Results per run | 25,000 | Only the top 5,000 results will be included, prioritized by severity. |
| Rules per run | 25,000 | |
| Tool extensions per run | 100 | |
| Thread Flow Locations per result | 10,000 | Only the top 1,000 Thread Flow Locations will be included, using prioritization. |
| Location per result | 1,000 | Only 100 locations will be included. |
| Tags per rule | 20 | Only 10 tags will be included. |
| **SARIF data** | **Maximum values** | **Additional limits** |
|----------------|:------------------:|-----------------------|
| Runs per file | 15 | None |
| Results per run | 25,000 | Only the top 5,000 results will be included, prioritized by severity. |
| Rules per run | 25,000 | None |
| Tool extensions per run | 100 | None |
| Thread Flow Locations per result | 10,000 | Only the top 1,000 Thread Flow Locations will be included, using prioritization. |
| Location per result | 1,000 | Only 100 locations will be included. |
| Tags per rule | 20 | Only 10 tags will be included. |
{% else %}
| **SARIF data** | **Maximum values** | **Additional limits** |
|----------------------------------|:------------------:|----------------------------------------------------------------------------------|
| Runs per file | 15 | |
| Results per run | 25,000 | Only the top 5,000 results will be included, prioritized by severity. |
| Rules per run | 25,000 | |
| Thread Flow Locations per result | 10,000 | Only the top 1,000 Thread Flow Locations will be included, using prioritization. |
| Location per result | 1,000 | Only 100 locations will be included. | |
| **SARIF data** | **Maximum values** | **Additional limits** |
|----------------|:------------------:|-----------------------|
| Runs per file | 15 | None |
| Results per run | 25,000 | Only the top 5,000 results will be included, prioritized by severity. |
| Rules per run | 25,000 | None |
| Thread Flow Locations per result | 10,000 | Only the top 1,000 Thread Flow Locations will be included, using prioritization. |
| Location per result | 1,000 | Only 100 locations will be included. | None |
{% endif %}
@@ -153,49 +153,49 @@ Any valid SARIF 2.1.0 output file can be uploaded, however, {% data variables.pr
### `sarifLog` object
| Name | Description |
|----|----|
| `$schema` | **Required.** The URI of the SARIF JSON schema for version 2.1.0. For example, `https://json.schemastore.org/sarif-2.1.0.json`. |
| `version` | **Required.** {% data variables.product.prodname_code_scanning_capc %} only supports SARIF version `2.1.0`.
| `runs[]` | **Required.** A SARIF file contains an array of one or more runs. Each run represents a single run of an analysis tool. For more information about a `run`, see the [`run` object](#run-object).
| Name | Required | Description |
|----|----|----|
| `$schema` | {% octicon "check" aria-label="Required" %} | The URI of the SARIF JSON schema for version 2.1.0. For example, `https://json.schemastore.org/sarif-2.1.0.json`. |
| `version` | {% octicon "check" aria-label="Required" %} | {% data variables.product.prodname_code_scanning_capc %} only supports SARIF version `2.1.0`.
| `runs[]` | {% octicon "check" aria-label="Required" %} | A SARIF file contains an array of one or more runs. Each run represents a single run of an analysis tool. For more information about a `run`, see the [`run` object](#run-object).
### `run` object
{% data variables.product.prodname_code_scanning_capc %} uses the `run` object to filter results by tool and provide information about the source of a result. The `run` object contains the `tool.driver` tool component object, which contains information about the tool that generated the results. Each `run` can only have results for one analysis tool.
| Name | Description |
|----|----|
| `tool.driver` | **Required.** A `toolComponent` object that describes the analysis tool. For more information, see the [`toolComponent` object](#toolcomponent-object). |
| `tool.extensions[]` | **Optional.** An array of `toolComponent` objects that represent any plugins or extensions used by the tool during analysis. For more information, see the [`toolComponent` object](#toolcomponent-object). |
| `invocation.workingDirectory.uri` | **Optional.** This field is used only when `checkout_uri` (SARIF upload API only) or `checkout_path` ({% data variables.product.prodname_actions %} only) are not provided. The value is used to convert absolute URIs used in [`physicalLocation` objects](#physicallocation-object) to relative URIs. For more information, see "[Specifying the root for source files](#specifying-the-root-for-source-files)."|
| `results[]` | **Required.** The results of the analysis tool. {% data variables.product.prodname_code_scanning_capc %} displays the results on {% data variables.product.prodname_dotcom %}. For more information, see the [`result` object](#result-object).
| Name | Required | Description |
|----|----|----|
| `tool.driver` | {% octicon "check" aria-label="Required" %} | A `toolComponent` object that describes the analysis tool. For more information, see the [`toolComponent` object](#toolcomponent-object). |
| `tool.extensions[]` | {% octicon "x" aria-label="Optional" %} | An array of `toolComponent` objects that represent any plugins or extensions used by the tool during analysis. For more information, see the [`toolComponent` object](#toolcomponent-object). |
| `invocation.workingDirectory.uri` | {% octicon "x" aria-label="Optional" %} | This field is used only when `checkout_uri` (SARIF upload API only) or `checkout_path` ({% data variables.product.prodname_actions %} only) are not provided. The value is used to convert absolute URIs used in [`physicalLocation` objects](#physicallocation-object) to relative URIs. For more information, see "[Specifying the root for source files](#specifying-the-root-for-source-files)."|
| `results[]` | {% octicon "check" aria-label="Required" %} | The results of the analysis tool. {% data variables.product.prodname_code_scanning_capc %} displays the results on {% data variables.product.prodname_dotcom %}. For more information, see the [`result` object](#result-object).
### `toolComponent` object
| Name | Description |
|----|----|
| `name` | **Required.** The name of the analysis tool. {% data variables.product.prodname_code_scanning_capc %} displays the name on {% data variables.product.prodname_dotcom %} to allow you to filter results by tool. |
| `version` | **Optional.** The version of the analysis tool. {% data variables.product.prodname_code_scanning_capc %} uses the version number to track when results may have changed due to a tool version change rather than a change in the code being analyzed. If the SARIF file includes the `semanticVersion` field, `version` is not used by {% data variables.product.prodname_code_scanning %}. |
| `semanticVersion` | **Optional.** The version of the analysis tool, specified by the Semantic Versioning 2.0 format. {% data variables.product.prodname_code_scanning_capc %} uses the version number to track when results may have changed due to a tool version change rather than a change in the code being analyzed. If the SARIF file includes the `semanticVersion` field, `version` is not used by {% data variables.product.prodname_code_scanning %}. For more information, see "[Semantic Versioning 2.0.0](https://semver.org/)" in the Semantic Versioning documentation. |
| `rules[]` | **Required.** An array of `reportingDescriptor` objects that represent rules. The analysis tool uses rules to find problems in the code being analyzed. For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object). |
| Name | Required | Description |
|----|----|----|
| `name` | {% octicon "check" aria-label="Required" %} | The name of the analysis tool. {% data variables.product.prodname_code_scanning_capc %} displays the name on {% data variables.product.prodname_dotcom %} to allow you to filter results by tool. |
| `version` | {% octicon "x" aria-label="Optional" %} | The version of the analysis tool. {% data variables.product.prodname_code_scanning_capc %} uses the version number to track when results may have changed due to a tool version change rather than a change in the code being analyzed. If the SARIF file includes the `semanticVersion` field, `version` is not used by {% data variables.product.prodname_code_scanning %}. |
| `semanticVersion` | {% octicon "x" aria-label="Optional" %} | The version of the analysis tool, specified by the Semantic Versioning 2.0 format. {% data variables.product.prodname_code_scanning_capc %} uses the version number to track when results may have changed due to a tool version change rather than a change in the code being analyzed. If the SARIF file includes the `semanticVersion` field, `version` is not used by {% data variables.product.prodname_code_scanning %}. For more information, see "[Semantic Versioning 2.0.0](https://semver.org/)" in the Semantic Versioning documentation. |
| `rules[]` | {% octicon "check" aria-label="Required" %} | An array of `reportingDescriptor` objects that represent rules. The analysis tool uses rules to find problems in the code being analyzed. For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object). |
### `reportingDescriptor` object
This is where you store details of the rules that are run during analysis. Information in these objects should change infrequently, typically when you update the tool. For more information, see "[Understanding rules and results](#understanding-rules-and-results)" above.
| Name | Description |
|----|----|
| `id` | **Required.** A unique identifier for the rule. The `id` is referenced from other parts of the SARIF file and may be used by {% data variables.product.prodname_code_scanning %} to display URLs on {% data variables.product.prodname_dotcom %}. |
| `name` | **Optional.** The name of the rule. {% data variables.product.prodname_code_scanning_capc %} displays the name to allow results to be filtered by rule on {% data variables.product.prodname_dotcom %}. |
| `shortDescription.text` | **Required.** A concise description of the rule. {% data variables.product.prodname_code_scanning_capc %} displays the short description on {% data variables.product.prodname_dotcom %} next to the associated results.
| `fullDescription.text` | **Required.** A description of the rule. {% data variables.product.prodname_code_scanning_capc %} displays the full description on {% data variables.product.prodname_dotcom %} next to the associated results. The max number of characters is limited to 1000.
| `defaultConfiguration.level` | **Optional.** Default severity level of the rule. {% data variables.product.prodname_code_scanning_capc %} uses severity levels to help you understand how critical the result is for a given rule. This value can be overridden by the `level` attribute in the `result` object. For more information, see the [`result` object](#result-object). Default: `warning`.
| `help.text` | **Required.** Documentation for the rule using text format. {% data variables.product.prodname_code_scanning_capc %} displays this help documentation next to the associated results.
| `help.markdown` | **Recommended.** Documentation for the rule using Markdown format. {% data variables.product.prodname_code_scanning_capc %} displays this help documentation next to the associated results. When `help.markdown` is available, it is displayed instead of `help.text`.
| `properties.tags[]` | **Optional.** An array of strings. {% data variables.product.prodname_code_scanning_capc %} uses `tags` to allow you to filter results on {% data variables.product.prodname_dotcom %}. For example, it is possible to filter to all results that have the tag `security`.
| `properties.precision` | **Recommended.** A string that indicates how often the results indicated by this rule are true. For example, if a rule has a known high false-positive rate, the precision should be `low`. {% data variables.product.prodname_code_scanning_capc %} orders results by precision on {% data variables.product.prodname_dotcom %} so that the results with the highest `level`, and highest `precision` are shown first. Can be one of: `very-high`, `high`, `medium`, or `low`.
| `properties.problem.severity` | **Recommended.** A string that indicates the level of severity of any alerts generated by a non-security query. This, with the `properties.precision` property, determines whether the results are displayed by default on {% data variables.product.prodname_dotcom %} so that the results with the highest `problem.severity`, and highest `precision` are shown first. Can be one of: `error`, `warning`, or `recommendation`.
| `properties.security-severity` | **Recommended.** A string representing a score that indicates the level of severity, between 0.0 and 10.0, for security queries (`@tags` includes `security`). This, with the `properties.precision` property, determines whether the results are displayed by default on {% data variables.product.prodname_dotcom %} so that the results with the highest `security-severity`, and highest `precision` are shown first. {% data variables.product.prodname_code_scanning_capc %} translates numerical scores as follows: over 9.0 is `critical`, 7.0 to 8.9 is `high`, 4.0 to 6.9 is `medium` and 3.9 or less is `low`.
| Name | Required | Description |
|----|----|----|
| `id` | {% octicon "check" aria-label="Required" %} | A unique identifier for the rule. The `id` is referenced from other parts of the SARIF file and may be used by {% data variables.product.prodname_code_scanning %} to display URLs on {% data variables.product.prodname_dotcom %}. |
| `name` | {% octicon "x" aria-label="Optional" %} | The name of the rule. {% data variables.product.prodname_code_scanning_capc %} displays the name to allow results to be filtered by rule on {% data variables.product.prodname_dotcom %}. |
| `shortDescription.text` | {% octicon "check" aria-label="Required" %} | A concise description of the rule. {% data variables.product.prodname_code_scanning_capc %} displays the short description on {% data variables.product.prodname_dotcom %} next to the associated results.
| `fullDescription.text` | {% octicon "check" aria-label="Required" %} | A description of the rule. {% data variables.product.prodname_code_scanning_capc %} displays the full description on {% data variables.product.prodname_dotcom %} next to the associated results. The max number of characters is limited to 1000.
| `defaultConfiguration.level` | {% octicon "x" aria-label="Optional" %} | Default severity level of the rule. {% data variables.product.prodname_code_scanning_capc %} uses severity levels to help you understand how critical the result is for a given rule. This value can be overridden by the `level` attribute in the `result` object. For more information, see the [`result` object](#result-object). Default: `warning`.
| `help.text` | {% octicon "check" aria-label="Required" %} | Documentation for the rule using text format. {% data variables.product.prodname_code_scanning_capc %} displays this help documentation next to the associated results.
| `help.markdown` |{% octicon "x" aria-label="Optional" %} | **Recommended.** Documentation for the rule using Markdown format. {% data variables.product.prodname_code_scanning_capc %} displays this help documentation next to the associated results. When `help.markdown` is available, it is displayed instead of `help.text`.
| `properties.tags[]` | {% octicon "x" aria-label="Optional" %} | An array of strings. {% data variables.product.prodname_code_scanning_capc %} uses `tags` to allow you to filter results on {% data variables.product.prodname_dotcom %}. For example, it is possible to filter to all results that have the tag `security`.
| `properties.precision` | {% octicon "x" aria-label="Optional" %} | **Recommended.** A string that indicates how often the results indicated by this rule are true. For example, if a rule has a known high false-positive rate, the precision should be `low`. {% data variables.product.prodname_code_scanning_capc %} orders results by precision on {% data variables.product.prodname_dotcom %} so that the results with the highest `level`, and highest `precision` are shown first. Can be one of: `very-high`, `high`, `medium`, or `low`.
| `properties.problem.severity` | {% octicon "x" aria-label="Optional" %} | **Recommended.** A string that indicates the level of severity of any alerts generated by a non-security query. This, with the `properties.precision` property, determines whether the results are displayed by default on {% data variables.product.prodname_dotcom %} so that the results with the highest `problem.severity`, and highest `precision` are shown first. Can be one of: `error`, `warning`, or `recommendation`.
| `properties.security-severity` | {% octicon "x" aria-label="Optional" %} | **Recommended.** A string representing a score that indicates the level of severity, between 0.0 and 10.0, for security queries (`@tags` includes `security`). This, with the `properties.precision` property, determines whether the results are displayed by default on {% data variables.product.prodname_dotcom %} so that the results with the highest `security-severity`, and highest `precision` are shown first. {% data variables.product.prodname_code_scanning_capc %} translates numerical scores as follows: over 9.0 is `critical`, 7.0 to 8.9 is `high`, 4.0 to 6.9 is `medium` and 3.9 or less is `low`.
### `result` object
@@ -203,37 +203,37 @@ Each `result` object contains details for one alert in the codebase. Within the
{% data reusables.code-scanning.upload-sarif-alert-limit %}
| Name | Description |
|----|----|
| `ruleId`| **Optional.** The unique identifier of the rule (`reportingDescriptor.id`). For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object). {% data variables.product.prodname_code_scanning_capc %} uses the rule identifier to filter results by rule on {% data variables.product.prodname_dotcom %}.
| `ruleIndex`| **Optional.** The index of the associated rule (`reportingDescriptor` object) in the tool component `rules` array. For more information, see the [`run` object](#run-object). The allowed range for this property 0 to 2^63 - 1.
| `rule`| **Optional.** A reference used to locate the rule (reporting descriptor) for this result. For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object).
| `level`| **Optional.** The severity of the result. This level overrides the default severity defined by the rule. {% data variables.product.prodname_code_scanning_capc %} uses the level to filter results by severity on {% data variables.product.prodname_dotcom %}.
| `message.text`| **Required.** A message that describes the result. {% data variables.product.prodname_code_scanning_capc %} displays the message text as the title of the result. Only the first sentence of the message will be displayed when visible space is limited.
| `locations[]`| **Required.** The set of locations where the result was detected up to a maximum of 10. Only one location should be included unless the problem can only be corrected by making a change at every specified location. **Note:** At least one location is required for {% data variables.product.prodname_code_scanning %} to display a result. {% data variables.product.prodname_code_scanning_capc %} will use this property to decide which file to annotate with the result. Only the first value of this array is used. All other values are ignored.
| `partialFingerprints`| **Required.** A set of strings used to track the unique identity of the result. {% data variables.product.prodname_code_scanning_capc %} uses `partialFingerprints` to accurately identify which results are the same across commits and branches. {% data variables.product.prodname_code_scanning_capc %} will attempt to use `partialFingerprints` if they exist. If you are uploading third-party SARIF files with the `upload-action`, the action will create `partialFingerprints` for you when they are not included in the SARIF file. For more information, see "[Providing data to track code scanning alerts across runs](#providing-data-to-track-code-scanning-alerts-across-runs)." **Note:** {% data variables.product.prodname_code_scanning_capc %} only uses the `primaryLocationLineHash`.
| `codeFlows[].threadFlows[].locations[]`| **Optional.** An array of `location` objects for a `threadFlow` object, which describes the progress of a program through a thread of execution. A `codeFlow` object describes a pattern of code execution used to detect a result. If code flows are provided, {% data variables.product.prodname_code_scanning %} will expand code flows on {% data variables.product.prodname_dotcom %} for the relevant result. For more information, see the [`location` object](#location-object).
| `relatedLocations[]`| A set of locations relevant to this result. {% data variables.product.prodname_code_scanning_capc %} will link to related locations when they are embedded in the result message. For more information, see the [`location` object](#location-object).
| Name | Required | Description |
|----|----|----|
| `ruleId`| {% octicon "x" aria-label="Optional" %} | The unique identifier of the rule (`reportingDescriptor.id`). For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object). {% data variables.product.prodname_code_scanning_capc %} uses the rule identifier to filter results by rule on {% data variables.product.prodname_dotcom %}.
| `ruleIndex`| {% octicon "x" aria-label="Optional" %} | The index of the associated rule (`reportingDescriptor` object) in the tool component `rules` array. For more information, see the [`run` object](#run-object). The allowed range for this property 0 to 2^63 - 1.
| `rule`| {% octicon "x" aria-label="Optional" %} | A reference used to locate the rule (reporting descriptor) for this result. For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object).
| `level`| {% octicon "x" aria-label="Optional" %} | The severity of the result. This level overrides the default severity defined by the rule. {% data variables.product.prodname_code_scanning_capc %} uses the level to filter results by severity on {% data variables.product.prodname_dotcom %}.
| `message.text`| {% octicon "check" aria-label="Required" %} | A message that describes the result. {% data variables.product.prodname_code_scanning_capc %} displays the message text as the title of the result. Only the first sentence of the message will be displayed when visible space is limited.
| `locations[]`| {% octicon "check" aria-label="Required" %} | The set of locations where the result was detected up to a maximum of 10. Only one location should be included unless the problem can only be corrected by making a change at every specified location. **Note:** At least one location is required for {% data variables.product.prodname_code_scanning %} to display a result. {% data variables.product.prodname_code_scanning_capc %} will use this property to decide which file to annotate with the result. Only the first value of this array is used. All other values are ignored.
| `partialFingerprints`| {% octicon "check" aria-label="Required" %} | A set of strings used to track the unique identity of the result. {% data variables.product.prodname_code_scanning_capc %} uses `partialFingerprints` to accurately identify which results are the same across commits and branches. {% data variables.product.prodname_code_scanning_capc %} will attempt to use `partialFingerprints` if they exist. If you are uploading third-party SARIF files with the `upload-action`, the action will create `partialFingerprints` for you when they are not included in the SARIF file. For more information, see "[Providing data to track code scanning alerts across runs](#providing-data-to-track-code-scanning-alerts-across-runs)." **Note:** {% data variables.product.prodname_code_scanning_capc %} only uses the `primaryLocationLineHash`.
| `codeFlows[].threadFlows[].locations[]`| {% octicon "x" aria-label="Optional" %} | An array of `location` objects for a `threadFlow` object, which describes the progress of a program through a thread of execution. A `codeFlow` object describes a pattern of code execution used to detect a result. If code flows are provided, {% data variables.product.prodname_code_scanning %} will expand code flows on {% data variables.product.prodname_dotcom %} for the relevant result. For more information, see the [`location` object](#location-object).
| `relatedLocations[]`| {% octicon "x" aria-label="Optional" %} | A set of locations relevant to this result. {% data variables.product.prodname_code_scanning_capc %} will link to related locations when they are embedded in the result message. For more information, see the [`location` object](#location-object).
### `location` object
A location within a programming artifact, such as a file in the repository or a file that was generated during a build.
| Name | Description |
|----|----|
| `location.id` | **Optional.** A unique identifier that distinguishes this location from all other locations within a single result object. The allowed range for this property 0 to 2^63 - 1.
| `location.physicalLocation` | **Required.** Identifies the artifact and region. For more information, see the [`physicalLocation`](#physicallocation-object).
| `location.message.text` | **Optional.** A message relevant to the location.
| Name | Required | Description |
|----|----|----|
| `location.id` | {% octicon "x" aria-label="Optional" %} | A unique identifier that distinguishes this location from all other locations within a single result object. The allowed range for this property 0 to 2^63 - 1.
| `location.physicalLocation` | {% octicon "check" aria-label="Required" %} | Identifies the artifact and region. For more information, see the [`physicalLocation`](#physicallocation-object).
| `location.message.text` | {% octicon "x" aria-label="Optional" %} | A message relevant to the location.
### `physicalLocation` object
| Name | Description |
|----|----|
| `artifactLocation.uri`| **Required.** A URI indicating the location of an artifact, usually a file either in the repository or generated during a build. For the best results we recommend that this is a relative path from the root of the GitHub repository being analyzed. For example, `src/main.js`. For more information about artifact URIs, see "[Specifying the root for source files](#specifying-the-root-for-source-files)."|
| `region.startLine` | **Required.** The line number of the first character in the region.
| `region.startColumn` | **Required.** The column number of the first character in the region.
| `region.endLine` | **Required.** The line number of the last character in the region.
| `region.endColumn` | **Required.** The column number of the character following the end of the region.
| Name | Required | Description |
|----|----|----|
| `artifactLocation.uri`| {% octicon "check" aria-label="Required" %} | A URI indicating the location of an artifact, usually a file either in the repository or generated during a build. For the best results we recommend that this is a relative path from the root of the GitHub repository being analyzed. For example, `src/main.js`. For more information about artifact URIs, see "[Specifying the root for source files](#specifying-the-root-for-source-files)."|
| `region.startLine` | {% octicon "check" aria-label="Required" %} | The line number of the first character in the region.
| `region.startColumn` | {% octicon "check" aria-label="Required" %} | The column number of the first character in the region.
| `region.endLine` | {% octicon "check" aria-label="Required" %} | The line number of the last character in the region.
| `region.endColumn` | {% octicon "check" aria-label="Required" %} | The column number of the character following the end of the region.
### `runAutomationDetails` object
@@ -245,9 +245,9 @@ The `runAutomationDetails` object contains information that specifies the identi
{% endnote %}
| Name | Description |
|----|----|
| `id`| **Optional.** A string that identifies the category of the analysis and the run ID. Use if you want to upload multiple SARIF files for the same tool and commit, but performed on different languages or different parts of the code. |
| Name | Required | Description |
|----|----|----|
| `id`| {% octicon "x" aria-label="Optional" %} | A string that identifies the category of the analysis and the run ID. Use if you want to upload multiple SARIF files for the same tool and commit, but performed on different languages or different parts of the code. |
The use of the `runAutomationDetails` object is optional.
@@ -260,8 +260,8 @@ Use the category to distinguish between multiple analyses for the same tool or c
| `id` | category | `run_id` |
|----|----|----|
| my-analysis/tool1/2021-02-01 | my-analysis/tool1 | 2021-02-01
| my-analysis/tool1/ | my-analysis/tool1 | _no `run-id`_
| my-analysis for tool1 | _no category_ | my-analysis for tool1
| my-analysis/tool1/ | my-analysis/tool1 | None
| my-analysis for tool1 | None | my-analysis for tool1
- The run with an `id` of "my-analysis/tool1/2021-02-01" belongs to the category "my-analysis/tool1". Presumably, this is the run from February 2, 2021.
- The run with an `id` of "my-analysis/tool1/" belongs to the category "my-analysis/tool1" but is not distinguished from other runs in that category.

50
content/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md
View File

@@ -66,13 +66,13 @@ You can display the command-line help for any command using the <nobr>`--help`</
| Option | Required | Usage |
|--------|:--------:|-----|
| `<database>` | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the name and location of a directory to create for the {% data variables.product.prodname_codeql %} database. The command will fail if you try to overwrite an existing directory. If you also specify `--db-cluster`, this is the parent directory and a subdirectory is created for each language analyzed.|
| <nobr>`--language`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the identifier for the language to create a database for, one of: `{% data reusables.code-scanning.codeql-languages-keywords %}` (use `javascript` to analyze TypeScript code {% ifversion codeql-kotlin-beta %} and `java` to analyze Kotlin code{% endif %}). When used with <nobr>`--db-cluster`</nobr>, the option accepts a comma-separated list, or can be specified more than once.
| <nobr>`--command`</nobr> | | Recommended. Use to specify the build command or script that invokes the build process for the codebase. Commands are run from the current folder or, where it is defined, from <nobr>`--source-root`</nobr>. Not needed for Python and JavaScript/TypeScript analysis. |
| <nobr>`--db-cluster`</nobr> | | Optional. Use in multi-language codebases to generate one database for each language specified by <nobr>`--language`</nobr>.
| <nobr>`--no-run-unnecessary-builds`</nobr> | | Recommended. Use to suppress the build command for languages where the {% data variables.product.prodname_codeql_cli %} does not need to monitor the build (for example, Python and JavaScript/TypeScript).
| <nobr>`--source-root`</nobr> | | Optional. Use if you run the CLI outside the checkout root of the repository. By default, the `database create` command assumes that the current directory is the root directory for the source files, use this option to specify a different location. |
| <nobr>`--codescanning-config`</nobr> | | Optional (Advanced). Use if you have a configuration file that specifies how to create the {% data variables.product.prodname_codeql %} databases and what queries to run in later steps. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning#using-a-custom-configuration-file)" and "[database create](https://codeql.github.com/docs/codeql-cli/manual/database-create/#cmdoption-codeql-database-create-codescanning-config)." |
| `<database>` | {% octicon "check" aria-label="Required" %} | Specify the name and location of a directory to create for the {% data variables.product.prodname_codeql %} database. The command will fail if you try to overwrite an existing directory. If you also specify `--db-cluster`, this is the parent directory and a subdirectory is created for each language analyzed.|
| <nobr>`--language`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the identifier for the language to create a database for, one of: `{% data reusables.code-scanning.codeql-languages-keywords %}` (use `javascript` to analyze TypeScript code {% ifversion codeql-kotlin-beta %} and `java` to analyze Kotlin code{% endif %}). When used with <nobr>`--db-cluster`</nobr>, the option accepts a comma-separated list, or can be specified more than once.
| <nobr>`--command`</nobr> | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to specify the build command or script that invokes the build process for the codebase. Commands are run from the current folder or, where it is defined, from <nobr>`--source-root`</nobr>. Not needed for Python and JavaScript/TypeScript analysis. |
| <nobr>`--db-cluster`</nobr> | {% octicon "x" aria-label="Optional" %} | Use in multi-language codebases to generate one database for each language specified by <nobr>`--language`</nobr>.
| <nobr>`--no-run-unnecessary-builds`</nobr> | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to suppress the build command for languages where the {% data variables.product.prodname_codeql_cli %} does not need to monitor the build (for example, Python and JavaScript/TypeScript).
| <nobr>`--source-root`</nobr> | {% octicon "x" aria-label="Optional" %} | Use if you run the CLI outside the checkout root of the repository. By default, the `database create` command assumes that the current directory is the root directory for the source files, use this option to specify a different location. |
| <nobr>`--codescanning-config`</nobr> | {% octicon "x" aria-label="Optional" %} | Advanced. Use if you have a configuration file that specifies how to create the {% data variables.product.prodname_codeql %} databases and what queries to run in later steps. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning#using-a-custom-configuration-file)" and "[database create](https://codeql.github.com/docs/codeql-cli/manual/database-create/#cmdoption-codeql-database-create-codescanning-config)." |
For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases)."
@@ -147,16 +147,16 @@ codeql database analyze &lt;database&gt; --format=&lt;format&gt; \
| Option | Required | Usage |
|--------|:--------:|-----|
| `<database>` | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the path for the directory that contains the {% data variables.product.prodname_codeql %} database to analyze. |
| `<packs,queries>` | | Specify {% data variables.product.prodname_codeql %} packs or queries to run. To run the standard queries used for {% data variables.product.prodname_code_scanning %}, omit this parameter. To see the other query suites included in the {% data variables.product.prodname_codeql_cli %} bundle, look in `/<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites`. For information about creating your own query suite, see [Creating CodeQL query suites](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites) in the documentation for the {% data variables.product.prodname_codeql_cli %}.
| <nobr>`--format`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the format for the results file generated by the command. For upload to {% data variables.product.company_short %} this should be: {% ifversion fpt or ghae or ghec %}`sarif-latest`{% else %}`sarifv2.1.0`{% endif %}. For more information, see "[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)."
| <nobr>`--output`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify where to save the SARIF results file.
| <nobr>`--sarif-category`<nobr> | {% octicon "question" aria-label="Required with multiple results sets" %} | Optional for single database analysis. Required to define the language when you analyze multiple databases for a single commit in a repository. Specify a category to include in the SARIF results file for this analysis. A category is used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code.|
| <nobr>`--sarif-add-query-help`</nobr> | | Optional. Use if you want to include any available markdown-rendered query help for custom queries used in your analysis. Any query help for custom queries included in the SARIF output will be displayed in the code scanning UI if the relevant query generates an alert. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli#including-query-help-for-custom-codeql-queries-in-sarif-files)."{% ifversion codeql-packs %}
| `<packs>` | | Optional. Use if you want to include CodeQL query packs in your analysis. For more information, see "[Downloading and using {% data variables.product.prodname_codeql %} packs](#downloading-and-using-codeql-query-packs)."
| <nobr>`--download`</nobr> | | Optional. Use if some of your CodeQL query packs are not yet on disk and need to be downloaded before running queries.{% endif %}
| <nobr>`--threads`</nobr> | | Optional. Use if you want to use more than one thread to run queries. The default value is `1`. You can specify more threads to speed up query execution. To set the number of threads to the number of logical processors, specify `0`.
| <nobr>`--verbose`</nobr> | | Optional. Use to get more detailed information about the analysis process and diagnostic data from the database creation process.
| `<database>` | {% octicon "check" aria-label="Required" %} | Specify the path for the directory that contains the {% data variables.product.prodname_codeql %} database to analyze. |
| `<packs,queries>` | {% octicon "x" aria-label="Optional" %} | Specify {% data variables.product.prodname_codeql %} packs or queries to run. To run the standard queries used for {% data variables.product.prodname_code_scanning %}, omit this parameter. To see the other query suites included in the {% data variables.product.prodname_codeql_cli %} bundle, look in `/<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites`. For information about creating your own query suite, see [Creating CodeQL query suites](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites) in the documentation for the {% data variables.product.prodname_codeql_cli %}.
| <nobr>`--format`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the format for the results file generated by the command. For upload to {% data variables.product.company_short %} this should be: {% ifversion fpt or ghae or ghec %}`sarif-latest`{% else %}`sarifv2.1.0`{% endif %}. For more information, see "[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning)."
| <nobr>`--output`</nobr> | {% octicon "check" aria-label="Required" %} | Specify where to save the SARIF results file.
| <nobr>`--sarif-category`<nobr> | {% octicon "question" aria-label="Required with multiple results sets" %} | Optional for single database analysis. Required to define the language when you analyze multiple databases for a single commit in a repository.<br><br>Specify a category to include in the SARIF results file for this analysis. A category is used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code.|
| <nobr>`--sarif-add-query-help`</nobr> | {% octicon "x" aria-label="Optional" %} | Use if you want to include any available markdown-rendered query help for custom queries used in your analysis. Any query help for custom queries included in the SARIF output will be displayed in the code scanning UI if the relevant query generates an alert. For more information, see "[AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli#including-query-help-for-custom-codeql-queries-in-sarif-files)."{% ifversion codeql-packs %}
| `<packs>` | {% octicon "x" aria-label="Optional" %} | Use if you want to include CodeQL query packs in your analysis. For more information, see "[Downloading and using {% data variables.product.prodname_codeql %} packs](#downloading-and-using-codeql-query-packs)."
| <nobr>`--download`</nobr> | {% octicon "x" aria-label="Optional" %} | Use if some of your CodeQL query packs are not yet on disk and need to be downloaded before running queries.{% endif %}
| <nobr>`--threads`</nobr> | {% octicon "x" aria-label="Optional" %} | Use if you want to use more than one thread to run queries. The default value is `1`. You can specify more threads to speed up query execution. To set the number of threads to the number of logical processors, specify `0`.
| <nobr>`--verbose`</nobr> | {% octicon "x" aria-label="Optional" %} | Use to get more detailed information about the analysis process and diagnostic data from the database creation process.
For more information, see [Analyzing databases with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli)."
@@ -195,12 +195,12 @@ When you have decided on the most secure and reliable method for your CI server,
| Option | Required | Usage |
|--------|:--------:|-----|
| <nobr>`--repository`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the *OWNER/NAME* of the repository to upload data to. The owner must be an organization within an enterprise that has a license for {% data variables.product.prodname_GH_advanced_security %} and {% data variables.product.prodname_GH_advanced_security %} must be enabled for the repository{% ifversion fpt or ghec %}, unless the repository is public{% endif %}. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)."
| <nobr>`--ref`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the name of the `ref` you checked out and analyzed so that the results can be matched to the correct code. For a branch use: `refs/heads/BRANCH-NAME`, for the head commit of a pull request use `refs/pull/NUMBER/head`, or for the {% data variables.product.prodname_dotcom %}-generated merge commit of a pull request use `refs/pull/NUMBER/merge`.
| <nobr>`--commit`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the full SHA of the commit you analyzed.
| <nobr>`--sarif`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the SARIF file to load.{% ifversion ghes or ghae %}
| <nobr>`--github-url`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the URL for {% data variables.product.product_name %}.{% endif %}
| <nobr>`--github-auth-stdin`</nobr> | | Optional. Use to pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
| <nobr>`--repository`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the *OWNER/NAME* of the repository to upload data to. The owner must be an organization within an enterprise that has a license for {% data variables.product.prodname_GH_advanced_security %} and {% data variables.product.prodname_GH_advanced_security %} must be enabled for the repository{% ifversion fpt or ghec %}, unless the repository is public{% endif %}. For more information, see "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)."
| <nobr>`--ref`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the name of the `ref` you checked out and analyzed so that the results can be matched to the correct code. For a branch use: `refs/heads/BRANCH-NAME`, for the head commit of a pull request use `refs/pull/NUMBER/head`, or for the {% data variables.product.prodname_dotcom %}-generated merge commit of a pull request use `refs/pull/NUMBER/merge`.
| <nobr>`--commit`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the full SHA of the commit you analyzed.
| <nobr>`--sarif`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the SARIF file to load.{% ifversion ghes or ghae %}
| <nobr>`--github-url`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the URL for {% data variables.product.product_name %}.{% endif %}
| <nobr>`--github-auth-stdin`</nobr> | {% octicon "x" aria-label="Optional" %} | Use to pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
For more information, see [github upload-results](https://codeql.github.com/docs/codeql-cli/manual/github-upload-results/) in the documentation for the {% data variables.product.prodname_codeql_cli %}.
@@ -228,8 +228,8 @@ Before you can use a {% data variables.product.prodname_codeql %} pack to analyz
| Option | Required | Usage |
|--------|:--------:|-----|
| <nobr>`<scope/name@version:path>`</nobr> | {% octicon "check-circle-fill" aria-label="Required" %} | Specify the scope and name of one or more CodeQL query packs to download using a comma-separated list. Optionally, include the version to download and unzip. By default the latest version of this pack is downloaded. Optionally, include a path to a query, directory, or query suite to run. If no path is included, then run the default queries of this pack. |
| <nobr>`--github-auth-stdin`</nobr> | | Optional. Pass the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API to the CLI via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
| <nobr>`<scope/name@version:path>`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the scope and name of one or more CodeQL query packs to download using a comma-separated list. Optionally, include the version to download and unzip. By default the latest version of this pack is downloaded. Optionally, include a path to a query, directory, or query suite to run. If no path is included, then run the default queries of this pack. |
| <nobr>`--github-auth-stdin`</nobr> | {% octicon "x" aria-label="Optional" %} | Pass the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API to the CLI via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
{% ifversion query-pack-compatibility %}
{% note %}

136
content/code-security/codeql-cli/codeql-cli-reference/sarif-output.md
View File

@@ -37,9 +37,9 @@ This article is intended to be read alongside the detailed SARIF specification.
The output produced for a given specific format type (for example, `sarifv2.1.0`) may change in future {% data variables.product.prodname_codeql %} releases. We will endeavor to maintain backwards compatibility with consumers of the generated SARIF by ensuring that:
* No field which is marked as “Always” being generated will be removed.
* Fields that are marked as always being generated will never be removed.
* The circumstances under which “Optional” fields are generated may change. Consumers of the {% data variables.product.prodname_codeql %} SARIF output should be robust to the presence or absence of these fields.
* For fields that are marked as not always being generated, the circumstances under which the fields are generated may change. Consumers of the {% data variables.product.prodname_codeql %} SARIF output should be robust to the presence or absence of these fields.
New output fields may be added in future releases under the same format type–these are not considered to break backwards compatibility, and consumers should be robust to the presence of newly added fields.
@@ -51,96 +51,96 @@ This details each SARIF component that may be generated, along with any specific
### `sarifLog` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-------------------|------------------------|---------|
| `$schema`| Always| Provides a link to the [SARIF schema](https://github.com/oasis-tcs/sarif-spec/blob/main/Schemata/sarif-schema-2.1.0.json).|
| `version`| Always| The version of the SARIF used to generate the output.|
| `runs`| Always| An array containing a single run object, for one language.|
| `$schema`| {% octicon "check" aria-label="Always" %}| Provides a link to the [SARIF schema](https://github.com/oasis-tcs/sarif-spec/blob/main/Schemata/sarif-schema-2.1.0.json).|
| `version`| {% octicon "check" aria-label="Always" %}| The version of the SARIF used to generate the output.|
| `runs`| {% octicon "check" aria-label="Always" %}| An array containing a single run object, for one language.|
### `run` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-------------------|------------------------|---------|
| `tool`| Always| –|
| `originalUriBaseIds`| Always| A dictionary of `uriBaseIds` to artifactLocations representing the original locations on the analysis machine. At a minimum, this will contain the `%SRCROOT%` `uriBaseId`, which represents the root location on the analysis machine of the source code for the analyzed project. Each `artifactLocation` will contain the `uri` and `description` properties.|
| `artifacts`| Always| An array containing at least one artifact object for every file referenced in a result.|
| `results`| Always| –|
| `newLineSequences`| Always| –|
| `columnKind`| Always| –|
| `properties`| Always| The properties dictionary will contain the `semmle.formatSpecifier`, which identifies the format specifier passed to the {% data variables.product.prodname_codeql_cli %}.|
| `tool`| {% octicon "check" aria-label="Always" %}| None |
| `originalUriBaseIds`| {% octicon "check" aria-label="Always" %}| A dictionary of `uriBaseIds` to artifactLocations representing the original locations on the analysis machine. At a minimum, this will contain the `%SRCROOT%` `uriBaseId`, which represents the root location on the analysis machine of the source code for the analyzed project. Each `artifactLocation` will contain the `uri` and `description` properties.|
| `artifacts`| {% octicon "check" aria-label="Always" %}| An array containing at least one artifact object for every file referenced in a result.|
| `results`| {% octicon "check" aria-label="Always" %}| None |
| `newLineSequences`| {% octicon "check" aria-label="Always" %}| None |
| `columnKind`| {% octicon "check" aria-label="Always" %}| None |
| `properties`| {% octicon "check" aria-label="Always" %}| The properties dictionary will contain the `semmle.formatSpecifier`, which identifies the format specifier passed to the {% data variables.product.prodname_codeql_cli %}.|
### `tool` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-------------------|------------------------|---------|
| `driver`| Always| –|
| `driver`| {% octicon "check" aria-label="Always" %}| None |
### `toolComponent` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|---------------------|-----|
| `name`| Always| Set to “{% data variables.product.prodname_codeql %} command-line toolchain” for output from the {% data variables.product.prodname_codeql_cli %} tools. Note, if the output was generated using a different tool a different `name` is reported, and the format may not be as described here.|
| `organization`| Always| Set to “GitHub”.|
| `version`| Always| Set to the {% data variables.product.prodname_codeql %} release version e.g. “2.0.0”.|
| `rules`| Always| An array of `reportingDescriptor` objects that represent rules. This array will contain, at a minimum, all the rules that were run during this analysis, but may contain rules which were available but not run. For more detail about enabling queries, see `defaultConfiguration`.|
| `name`| {% octicon "check" aria-label="Always" %}| Set to “{% data variables.product.prodname_codeql %} command-line toolchain” for output from the {% data variables.product.prodname_codeql_cli %} tools. Note, if the output was generated using a different tool a different `name` is reported, and the format may not be as described here.|
| `organization`| {% octicon "check" aria-label="Always" %}| Set to “GitHub”.|
| `version`| {% octicon "check" aria-label="Always" %}| Set to the {% data variables.product.prodname_codeql %} release version e.g. “2.0.0”.|
| `rules`| {% octicon "check" aria-label="Always" %}| An array of `reportingDescriptor` objects that represent rules. This array will contain, at a minimum, all the rules that were run during this analysis, but may contain rules which were available but not run. For more detail about enabling queries, see `defaultConfiguration`.|
### `reportingDescriptor` object (for rule)
`reportingDescriptor` objects may be used in multiple places in the SARIF specification. When a `reportingDescriptor` is included in the rules array of a `toolComponent` object it has the following properties.
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `id`| Always| Will contain the `@id` property specified in the query that defines the rule, which is usually of the format `language/rule-name` (for example `cpp/unsafe-format-string`). If your organization defines the `@opaqueid` property in the query it will be used instead.|
| `name`| Always| Will contain the `@id` property specified in the query. See the `id` property above for an example.|
| `shortDescription`| Always| Will contain the `@name` property specified in the query that defines the rule.|
| `fullDescription`| Always| Will contain the `@description` property specified in the query that defines the rule.|
| `defaultConfiguration`| Always| A `reportingConfiguration` object, with the enabled property set to true or false, and a level property set according to the `@severity` property specified in the query that defines the rule. Omitted if the `@severity` property was not specified.|
| `id`| {% octicon "check" aria-label="Always" %}| Will contain the `@id` property specified in the query that defines the rule, which is usually of the format `language/rule-name` (for example `cpp/unsafe-format-string`). If your organization defines the `@opaqueid` property in the query it will be used instead.|
| `name`| {% octicon "check" aria-label="Always" %}| Will contain the `@id` property specified in the query. See the `id` property above for an example.|
| `shortDescription`| {% octicon "check" aria-label="Always" %}| Will contain the `@name` property specified in the query that defines the rule.|
| `fullDescription`| {% octicon "check" aria-label="Always" %}| Will contain the `@description` property specified in the query that defines the rule.|
| `defaultConfiguration`| {% octicon "check" aria-label="Always" %}| A `reportingConfiguration` object, with the enabled property set to true or false, and a level property set according to the `@severity` property specified in the query that defines the rule. Omitted if the `@severity` property was not specified.|
### `artifact` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `location`| Always| An `artifactLocation` object.|
| `index`| Always| The index of the `artifact` object.|
| `contents`| Optionally| If results are generated using the `--sarif-add-file-contents` flag, and the source code is available at the time the SARIF file is generated, then the `contents` property is populated with an `artifactContent` object, with the `text` property set.|
| `location`| {% octicon "check" aria-label="Always" %}| An `artifactLocation` object.|
| `index`| {% octicon "check" aria-label="Always" %}| The index of the `artifact` object.|
| `contents`| {% octicon "x" aria-label="Optionally" %}| If results are generated using the `--sarif-add-file-contents` flag, and the source code is available at the time the SARIF file is generated, then the `contents` property is populated with an `artifactContent` object, with the `text` property set.|
### `artifactLocation` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `uri`| Always| –|
| `index`| Always| –|
| `uriBaseId`| Optionally| If the file is relative to some known abstract location, such as the root source location on the analysis machine, this will be set.|
| `uri`| {% octicon "check" aria-label="Always" %}| None |
| `index`| {% octicon "check" aria-label="Always" %}| None |
| `uriBaseId`| {% octicon "x" aria-label="Optionally" %}| If the file is relative to some known abstract location, such as the root source location on the analysis machine, this will be set.|
### `result` object
The composition of the results is dependent on the options provided to CodeQL. By default, the results are grouped by unique message format string and primary location. Thus, two results that occur at the same location with the same underlying message, will appear as a single result in the output. This behavior can be disabled by using the flag `--ungroup-results`, in which case no results are grouped.
| JSON property name | When is this generated?| Notes|
| JSON property name | Always generated?| Notes|
|-----------------------|--------------------|------|
| `ruleId`| Always| See the description of the `id` property in `reportingDescriptor` object (for rule) .|
| `ruleIndex`| Always| –|
| `message`| Always| A message describing the problem(s) occurring at this location. This message may be a SARIF “Message with placeholder”, containing links that refer to locations in the `relatedLocations` property.|
| `locations`| Always| An array containing a single `location` object.|
| `partialFingerprints`| Always| A dictionary from named fingerprint types to the fingerprint. This will contain, at a minimum, a value for the `primaryLocationLineHash`, which provides a fingerprint based on the context of the primary location.|
| `codeFlows`| Optionally| This array may be populated with one or more `codeFlow` objects if the query that defines the rule for this result is of `@kind path-problem`.|
| `relatedLocations`| Optionally| This array will be populated if the query that defines the rule for this result has a message with placeholder options. Each unique location is included once.|
| `suppressions`| Optionally| If the result is suppressed, then this will contain a single `suppression` object, with the `@kind` property set to `IN_SOURCE`. If this result is not suppressed, but there is at least one result that has a suppression, then this will be set to an empty array, otherwise it will not be set.|
| `ruleId`| {% octicon "check" aria-label="Always" %}| See the description of the `id` property in `reportingDescriptor` object (for rule) .|
| `ruleIndex`| {% octicon "check" aria-label="Always" %}| None |
| `message`| {% octicon "check" aria-label="Always" %}| A message describing the problem(s) occurring at this location. This message may be a SARIF “Message with placeholder”, containing links that refer to locations in the `relatedLocations` property.|
| `locations`| {% octicon "check" aria-label="Always" %}| An array containing a single `location` object.|
| `partialFingerprints`| {% octicon "check" aria-label="Always" %}| A dictionary from named fingerprint types to the fingerprint. This will contain, at a minimum, a value for the `primaryLocationLineHash`, which provides a fingerprint based on the context of the primary location.|
| `codeFlows`| {% octicon "x" aria-label="Optionally" %}| This array may be populated with one or more `codeFlow` objects if the query that defines the rule for this result is of `@kind path-problem`.|
| `relatedLocations`| {% octicon "x" aria-label="Optionally" %}| This array will be populated if the query that defines the rule for this result has a message with placeholder options. Each unique location is included once.|
| `suppressions`| {% octicon "x" aria-label="Optionally" %}| If the result is suppressed, then this will contain a single `suppression` object, with the `@kind` property set to `IN_SOURCE`. If this result is not suppressed, but there is at least one result that has a suppression, then this will be set to an empty array, otherwise it will not be set.|
### `location` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `physicalLocation`| Always| –|
| `id`| Optionally| `location` objects that appear in the `relatedLocations` array of a `result` object may contain the `id` property.|
| `message`| Optionally| `location` objects may contain the `message` property if:</br></br>- They appear in the `relatedLocations` array of a `result` object may contain the `message` property.</br></br>- They appear in the `threadFlowLocation.location` property.|
| `physicalLocation`| {% octicon "check" aria-label="Always" %}| None |
| `id`| {% octicon "x" aria-label="Optionally" %}| `location` objects that appear in the `relatedLocations` array of a `result` object may contain the `id` property.|
| `message`| {% octicon "x" aria-label="Optionally" %}| `location` objects may contain the `message` property if:</br></br>- They appear in the `relatedLocations` array of a `result` object may contain the `message` property.</br></br>- They appear in the `threadFlowLocation.location` property.|
### `physicalLocation` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `artifactLocation`| Always| –|
| `region`| Optionally| If the given `physicalLocation` exists in a text file, such as a source code file, then the `region` property may be present.|
| `contextRegion`| Optionally| May be present if this location has an associated `snippet`.|
| `artifactLocation`| {% octicon "check" aria-label="Always" %}| None |
| `region`| {% octicon "x" aria-label="Optionally" %}| If the given `physicalLocation` exists in a text file, such as a source code file, then the `region` property may be present.|
| `contextRegion`| {% octicon "x" aria-label="Optionally" %}| May be present if this location has an associated `snippet`.|
### `region` object
@@ -154,35 +154,35 @@ Any region produced by {% data variables.product.prodname_codeql %} may be speci
For line/column offset regions, the following properties will be set:
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `startLine`| Always| –|
| `startColumn`| Optionally| Not included if equal to the default value of 1.|
| `endLine`| Optionally| Not included if identical to `startLine`.|
| `endColumn`| Always| –|
| `snippet`| Optionally| –|
| `startLine`| {% octicon "check" aria-label="Always" %}| None |
| `startColumn`| {% octicon "x" aria-label="Optionally" %}| Not included if equal to the default value of 1.|
| `endLine`| {% octicon "x" aria-label="Optionally" %}| Not included if identical to `startLine`.|
| `endColumn`| {% octicon "check" aria-label="Always" %}| None |
| `snippet`| {% octicon "x" aria-label="Optionally" %}| None |
For character offset and length regions, the following properties will be set:
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `charOffset`| Optionally| Provided if `startLine`, `startColumn`, `endLine`, and `endColumn` are not populated.|
| `charLength`| Optionally| Provided if `startLine`, `startColumn`, `endLine`, and `endColumn` are not populated.|
| `snippet`| Optionally| –|
| `charOffset`| {% octicon "x" aria-label="Optionally" %}| Provided if `startLine`, `startColumn`, `endLine`, and `endColumn` are not populated.|
| `charLength`| {% octicon "x" aria-label="Optionally" %}| Provided if `startLine`, `startColumn`, `endLine`, and `endColumn` are not populated.|
| `snippet`| {% octicon "x" aria-label="Optionally" %}| None |
### `codeFlow` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `threadFlows`| Always| –|
| `threadFlows`| {% octicon "check" aria-label="Always" %}| None |
### `threadFlow` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `locations`| Always| –|
| `locations`| {% octicon "check" aria-label="Always" %}| None |
### `threadFlowLocation` object
| JSON property name| When is this generated?| Notes|
| JSON property name| Always generated?| Notes|
|-----------------------|--------------------|------|
| `location`| Always| –|
| `location`| {% octicon "check" aria-label="Always" %}| None |

6
content/code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli.md
View File

@@ -90,7 +90,7 @@ is a list of arguments, where each argument can be:
* a path to a query file
* a path to a directory containing query files
* a path to a query suite file
* the name of a {% data variables.product.prodname_codeql %} query pack
* the name of a {% data variables.product.prodname_codeql %} query pack
* with an optional version range
* with an optional path to a query, directory, or query suite inside the pack
@@ -399,10 +399,10 @@ The SARIF format is designed to represent the output of a broad range of static
analysis tools. For more information, see [SARIF output](/code-security/codeql-cli/codeql-cli-reference/sarif-output).
If you choose to generate results in CSV format, then each line in the output file
corresponds to an alert. Each line is a comma-separated list with the following information:
corresponds to an alert. Each line is a comma-separated list with the following information.
**Property**|**Description**|**Example**
:-----:|:-----:|:-----:
-----|-----|-----
Name | Name of the query that identified the result. | `Inefficient regular expression`
Description | Description of the query.| `A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.`
Severity | Severity of the query.| `error`

22
content/code-security/security-advisories/repository-security-advisories/permission-levels-for-repository-security-advisories.md
View File

@@ -25,17 +25,17 @@ This article applies only to repository-level security advisories. Anyone can co
Action | Write permissions | Admin permissions |
------ | ----------------- | ----------------- |
See a draft security advisory | X | X |
Add collaborators to the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory)") | | X |
Edit and delete any comments in the security advisory | X | X |
Create a temporary private fork in the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)") | | X |
Add changes to a temporary private fork in the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)") | X | X |
Create pull requests in a temporary private fork (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)") | X | X |
Merge changes in the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)") | | X |
Add and edit metadata in the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/publishing-a-repository-security-advisory)") | X | X |
Add and remove credits for a security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/editing-a-repository-security-advisory)") | X | X |
Close the draft security advisory | | X |
Publish the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/publishing-a-repository-security-advisory)") | | X |
See a draft security advisory | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} |
Add collaborators to the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory)") | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |
Edit and delete any comments in the security advisory | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} |
Create a temporary private fork in the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)") | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |
Add changes to a temporary private fork in the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)") | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} |
Create pull requests in a temporary private fork (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)") | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} |
Merge changes in the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)") | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |
Add and edit metadata in the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/publishing-a-repository-security-advisory)") | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} |
Add and remove credits for a security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/editing-a-repository-security-advisory)") | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} |
Close the draft security advisory | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |
Publish the security advisory (see "[AUTOTITLE](/code-security/security-advisories/repository-security-advisories/publishing-a-repository-security-advisory)") | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |
## Further reading

8
content/code-security/security-overview/about-the-security-overview.md
View File

@@ -98,15 +98,15 @@ In addition, you can click **{% octicon "gear" aria-hidden="true" %} Security se
![Screenshot of the security overview for an organization](/assets/images/help/security-overview/security-overview-org-legacy.png)
For each repository in the security overview, you will see icons for each type of security feature and how many alerts there are of each type. If a security feature is not enabled for a repository, the icon for that feature will be grayed out. In addition, a risk score is calculated for each repository based on its code scanning, Dependabot and secret scanning alerts. This score is in beta and should be used with caution. Its algorithm and approach is subject to change.
Each repository in the security overview includes an indicator for each type of security feature and how many alerts there are of each type. If a security feature is not enabled for a repository, the indicator for that feature will be grayed out. In addition, a risk score is calculated for each repository based on its code scanning, Dependabot and secret scanning alerts. This score is in beta and should be used with caution. Its algorithm and approach is subject to change.
| Icon | Meaning |
| Indicator | Meaning |
| -------- | -------- |
| {% octicon "code-square" aria-label="Code scanning alerts" %} | {% data variables.product.prodname_code_scanning_capc %} alerts. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)." |
| {% octicon "key" aria-label="Secret scanning alerts" %} | {% data variables.product.prodname_secret_scanning_caps %} alerts. For more information, see "[AUTOTITLE](/code-security/secret-scanning/about-secret-scanning)." |
| {% octicon "hubot" aria-label="Dependabot alerts" %} | {% data variables.product.prodname_dependabot_alerts %}. For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts)." |
| {% octicon "check" aria-label="Check" %} | The security feature is enabled, but does not raise alerts in this repository. |
| {% octicon "x" aria-label="x" %} | The security feature is not supported in this repository. |
| {% octicon "check" aria-label="Enabled" %} | The security feature is enabled, but does not raise alerts in this repository. |
| {% octicon "x" aria-label="Not supported" %} | The security feature is not supported in this repository. |
{% endif %}

64
content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review.md
View File

@@ -18,7 +18,7 @@ topics:
## About dependency review
{% data reusables.dependency-review.feature-overview %}
{% data reusables.dependency-review.feature-overview %}
For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)" and "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request)."
@@ -44,7 +44,7 @@ Dependency review is available when dependency graph is enabled for {% data vari
{% data reusables.repositories.navigate-to-repo %}
{% data reusables.repositories.sidebar-settings %}
{% data reusables.repositories.navigate-to-code-security-and-analysis %}
1. Under "Configure security and analysis features", check if the dependency graph is enabled.
1. Under "Configure security and analysis features", check if the dependency graph is enabled.
1. If dependency graph is enabled, click **Enable** next to "{% data variables.product.prodname_GH_advanced_security %}" to enable {% data variables.product.prodname_advanced_security %}, including dependency review. The enable button is disabled if your enterprise has no available licenses for {% data variables.product.prodname_advanced_security %}.{% ifversion ghes %}
![Screenshot of "Code security and analysis" features"](/assets/images/enterprise/3.4/repository/code-security-and-analysis-enable-ghas-3.4.png){% endif %}
@@ -59,15 +59,15 @@ The following configuration options are available.
| Option | Required | Usage |
|------------------|-------------------------------|--------|
| `fail-on-severity` | Optional | Defines the threshold for level of severity (`low`, `moderate`, `high`, `critical`).</br>The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. |
| `fail-on-severity` | {% octicon "x" aria-label="Optional" %} | Defines the threshold for level of severity (`low`, `moderate`, `high`, `critical`).</br>The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. |
{%- ifversion dependency-review-action-licenses %}
| `allow-licenses` | Optional | Contains a list of allowed licenses. You can find the possible values for this parameter in the [Licenses](/rest/licenses) page of the API documentation.</br>The action will fail on pull requests that introduce dependencies with licenses that do not match the list.|{% endif %}
| `allow-licenses` | {% octicon "x" aria-label="Optional" %} | Contains a list of allowed licenses. You can find the possible values for this parameter in the [Licenses](/rest/licenses) page of the API documentation.</br>The action will fail on pull requests that introduce dependencies with licenses that do not match the list.|{% endif %}
{%- ifversion dependency-review-action-licenses %}
| `deny-licenses` | Optional | Contains a list of prohibited licenses. You can find the possible values for this parameter in the [Licenses](/rest/licenses) page of the API documentation.</br>The action will fail on pull requests that introduce dependencies with licenses that match the list.|{% endif %}{% ifversion dependency-review-action-fail-on-scopes %}
| `fail-on-scopes` | Optional | Contains a list of strings representing the build environments you want to support (`development`, `runtime`, `unknown`). </br>The action will fail on pull requests that introduce vulnerabilites in the scopes that match the list.|{% endif %}
| `allow-ghsas` | Optional | Contains a list of {% data variables.product.prodname_advisory_database %} IDs that can be skipped during detection. You can find the possible values for this parameter in the [{% data variables.product.prodname_advisory_database %}](https://github.com/advisories). |
| `config-file` | Optional | Specifies a path to a configuration file. The configuration file can be local to the repository or a file located in an external repository.|
| `external-repo-token` | Optional | Specifies a token for fetching the configuration file, if the file resides in a private external repository. The token must have read access to the repository.|
| `deny-licenses` | {% octicon "x" aria-label="Optional" %} | Contains a list of prohibited licenses. You can find the possible values for this parameter in the [Licenses](/rest/licenses) page of the API documentation.</br>The action will fail on pull requests that introduce dependencies with licenses that match the list.|{% endif %}{% ifversion dependency-review-action-fail-on-scopes %}
| `fail-on-scopes` | {% octicon "x" aria-label="Optional" %} | Contains a list of strings representing the build environments you want to support (`development`, `runtime`, `unknown`). </br>The action will fail on pull requests that introduce vulnerabilites in the scopes that match the list.|{% endif %}
| `allow-ghsas` | {% octicon "x" aria-label="Optional" %} | Contains a list of {% data variables.product.prodname_advisory_database %} IDs that can be skipped during detection. You can find the possible values for this parameter in the [{% data variables.product.prodname_advisory_database %}](https://github.com/advisories). |
| `config-file` | {% octicon "x" aria-label="Optional" %} | Specifies a path to a configuration file. The configuration file can be local to the repository or a file located in an external repository.|
| `external-repo-token` | {% octicon "x" aria-label="Optional" %} | Specifies a token for fetching the configuration file, if the file resides in a private external repository. The token must have read access to the repository.|
{% ifversion dependency-review-action-licenses %}
{% tip %}
@@ -79,15 +79,15 @@ The following configuration options are available.
## Configuring the {% data variables.dependency-review.action_name %}
There are two methods of configuring the {% data variables.dependency-review.action_name %}:
- Inlining the configuration options in your workflow file.
There are two methods of configuring the {% data variables.dependency-review.action_name %}:
- Inlining the configuration options in your workflow file.
- Referencing a configuration file in your workflow file.
Notice that all of the examples use a short version number for the action (`v3`) instead of a semver release number (for example, `v3.0.8`). This ensures that you use the most recent minor version of the action.
### Using inline configuration to set up the {% data variables.dependency-review.action_name %}
1. Add a new YAML workflow to your `.github/workflows` folder.
1. Add a new YAML workflow to your `.github/workflows` folder.
{% ifversion ghes %}For `runs-on`, the default label is `self-hosted`. You can replace the default label with the label of any of your runners.{% endif %}
```yaml{:copy}
name: 'Dependency Review'
@@ -106,7 +106,7 @@ Notice that all of the examples use a short version number for the action (`v3`)
- name: Dependency Review
uses: actions/dependency-review-action@v3
```
1. Specify your settings.
1. Specify your settings.
This {% data variables.dependency-review.action_name %} example file illustrates how you can use the available configuration options.
```yaml{:copy}
@@ -126,19 +126,19 @@ Notice that all of the examples use a short version number for the action (`v3`)
- name: Dependency Review
uses: actions/dependency-review-action@v3
with:
# Possible values: "critical", "high", "moderate", "low"
# Possible values: "critical", "high", "moderate", "low"
fail-on-severity: critical
{% ifversion dependency-review-action-licenses %}
# You can only include one of these two options: `allow-licenses` and `deny-licenses`
# ([String]). Only allow these licenses (optional)
# Possible values: Any `spdx_id` value(s) from https://docs.github.com/en/rest/licenses
# Possible values: Any `spdx_id` value(s) from https://docs.github.com/en/rest/licenses
allow-licenses: GPL-3.0, BSD-3-Clause, MIT
# ([String]). Block the pull request on these licenses (optional)
# Possible values: Any `spdx_id` value(s) from https://docs.github.com/en/rest/licenses
# Possible values: Any `spdx_id` value(s) from https://docs.github.com/en/rest/licenses
deny-licenses: LGPL-2.0, BSD-2-Clause
{% endif %}
# ([String]). Skip these {% data variables.product.prodname_advisory_database %} IDs during detection (optional)
# Possible values: Any valid {% data variables.product.prodname_advisory_database %} ID from https://github.com/advisories
# Possible values: Any valid {% data variables.product.prodname_advisory_database %} ID from https://github.com/advisories
allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679
{% ifversion dependency-review-action-fail-on-scopes %}
# ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional)
@@ -170,44 +170,44 @@ Notice that all of the examples use a short version number for the action (`v3`)
with:
# ([String]). Representing a path to a configuration file local to the repository or in an external repository.
# Possible values: An absolute path to a local file or an external file.
config-file: './.github/dependency-review-config.yml'
config-file: './.github/dependency-review-config.yml'
# Syntax for an external file: OWNER/REPOSITORY/FILENAME@BRANCH
config-file: 'github/octorepo/dependency-review-config.yml@main'
# ([Token]) Use if your configuration file resides in a private external repository.
# Possible values: Any GitHub token with read access to the private external repository.
# Possible values: Any GitHub token with read access to the private external repository.
external-repo-token: 'ghp_123456789abcde'
```
1. Create the configuration file in the path you have specified.
1. Create the configuration file in the path you have specified.
This YAML example file illustrates how you can use the available configuration options.
This YAML example file illustrates how you can use the available configuration options.
```yaml{:copy}
# Possible values: "critical", "high", "moderate", "low"
# Possible values: "critical", "high", "moderate", "low"
fail-on-severity: critical
{% ifversion dependency-review-action-licenses %}
# You can only include one of these two options: `allow-licenses` and `deny-licenses`
# ([String]). Only allow these licenses (optional)
# Possible values: Any `spdx_id` value(s) from https://docs.github.com/en/rest/licenses
allow-licenses:
# Possible values: Any `spdx_id` value(s) from https://docs.github.com/en/rest/licenses
allow-licenses:
- GPL-3.0
- BSD-3-Clause
- MIT
# ([String]). Block the pull request on these licenses (optional)
# Possible values: Any `spdx_id` value(s) from https://docs.github.com/en/rest/licenses
deny-licenses:
# Possible values: Any `spdx_id` value(s) from https://docs.github.com/en/rest/licenses
deny-licenses:
- LGPL-2.0
- BSD-2-Clause
{% endif %}
# ([String]). Skip these {% data variables.product.prodname_advisory_database %} IDs during detection (optional)
# Possible values: Any valid {% data variables.product.prodname_advisory_database %} ID from https://github.com/advisories
allow-ghsas:
- GHSA-abcd-1234-5679
# Possible values: Any valid {% data variables.product.prodname_advisory_database %} ID from https://github.com/advisories
allow-ghsas:
- GHSA-abcd-1234-5679
- GHSA-efgh-1234-5679
{% ifversion dependency-review-action-fail-on-scopes %}
# ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional)
# Possible values: "development", "runtime", "unknown"
fail-on-scopes:
- development
fail-on-scopes:
- development
- runtime
{% endif %}
```

54
content/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api.md
View File

@@ -17,11 +17,11 @@ versions:
{% data reusables.dependency-submission.about-dependency-submission %}
Dependencies are submitted to the dependency submission API in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. Snapshots can be generated from your dependencies detected at build time or from a software bill of materials (SBOM). There are {% data variables.product.prodname_actions %} that support either of these use cases. For more information about the Dependency submission API, see the [Dependency submission REST API documentation](/rest/dependency-graph/dependency-submission).
Dependencies are submitted to the dependency submission API in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. Snapshots can be generated from your dependencies detected at build time or from a software bill of materials (SBOM). There are {% data variables.product.prodname_actions %} that support either of these use cases. For more information about the Dependency submission API, see the [Dependency submission REST API documentation](/rest/dependency-graph/dependency-submission).
## Submitting dependencies at build-time
You can use the Dependency submission API in a {% data variables.product.prodname_actions %} workflow to submit dependencies for your project when your project is built.
You can use the Dependency submission API in a {% data variables.product.prodname_actions %} workflow to submit dependencies for your project when your project is built.
### Using pre-made actions
@@ -29,14 +29,14 @@ The simplest way to use the Dependency submission API is by adding a pre-made ac
Ecosystem | Action | Maintained by {% data variables.product.prodname_dotcom %}
--- | --- | --- |
Go | [Go Dependency Submission](https://github.com/marketplace/actions/go-dependency-submission) | **✓** |
Gradle | [Gradle Dependency Submission](https://github.com/marketplace/actions/gradle-dependency-submission) | |
Maven | [Maven Dependency Tree Dependency Submission](https://github.com/marketplace/actions/maven-dependency-tree-dependency-submission) | **✓** |
Mill | [Mill Dependency Submission](https://github.com/marketplace/actions/mill-dependency-submission) | |
Scala | [Sbt Dependency Submission](https://github.com/marketplace/actions/sbt-dependency-submission) | |
Go | [Go Dependency Submission](https://github.com/marketplace/actions/go-dependency-submission) | {% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %} |
Gradle | [Gradle Dependency Submission](https://github.com/marketplace/actions/gradle-dependency-submission) | {% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %} |
Maven | [Maven Dependency Tree Dependency Submission](https://github.com/marketplace/actions/maven-dependency-tree-dependency-submission) | {% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %} |
Mill | [Mill Dependency Submission](https://github.com/marketplace/actions/mill-dependency-submission) | {% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %} |
Scala | [Sbt Dependency Submission](https://github.com/marketplace/actions/sbt-dependency-submission) | {% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %} |
For example, the following [Go Dependency Submission](https://github.com/actions/go-dependency-submission) workflow calculates the dependencies for a Go build-target (a Go file with a `main` function) and submits the list to the Dependency submission API.
For example, the following [Go Dependency Submission](https://github.com/actions/go-dependency-submission) workflow calculates the dependencies for a Go build-target (a Go file with a `main` function) and submits the list to the Dependency submission API.
```yaml
@@ -45,7 +45,7 @@ on:
push:
branches:
- main
# The API requires write permission on the repository to submit dependencies
permissions:
contents: write
@@ -60,11 +60,11 @@ jobs:
steps:
- name: 'Checkout Repository'
uses: {% data reusables.actions.action-checkout %}
- uses: {% data reusables.actions.action-setup-go %}
with:
go-version: ">=1.18.0"
- name: Run snapshot action
uses: actions/go-dependency-submission@v1
with:
@@ -91,48 +91,48 @@ Alternatively, you can write your own action to submit dependencies for your pro
{% data variables.product.product_name %} maintains the [Dependency Submission Toolkit](https://github.com/github/dependency-submission-toolkit), a TypeScript library to help you build your own GitHub Action for submitting dependencies to the Dependency submission API. For more information about writing an action, see "[AUTOTITLE](/actions/creating-actions)".
## Generating and submitting a software bill of materials (SBOM)
## Generating and submitting a software bill of materials (SBOM)
You can use {% data variables.product.prodname_actions %} to generate a software bill of materials (SBOM), a formal, machine-readable inventory of your dependencies and associated information. The following actions will generate an SBOM for your repository and attach it as a workflow artifact which you can download and use in other applications. For more information about downloading workflow artifacts, see "[AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts)."
Action | Details | <nobr>Maintained by {% data variables.product.prodname_dotcom %}</nobr>
--- | --- | ---
[SBOM-generator-action](https://github.com/marketplace/actions/sbom-generator-action) | Uses the information in your dependency graph to generate an SPDX SBOM | **✓** |
[Anchore SBOM Action](https://github.com/marketplace/actions/anchore-sbom-action) | Uses [Syft](https://github.com/anchore/syft) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/anchore/syft#supported-ecosystems) | |
[sbom-tool by Microsoft](https://github.com/microsoft/sbom-tool) | Scans your dependencies and creates an SPDX compatible SBOM | |
[SBOM-generator-action](https://github.com/marketplace/actions/sbom-generator-action) | Uses the information in your dependency graph to generate an SPDX SBOM | {% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %} |
[Anchore SBOM Action](https://github.com/marketplace/actions/anchore-sbom-action) | Uses [Syft](https://github.com/anchore/syft) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/anchore/syft#supported-ecosystems) | {% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %} |
[sbom-tool by Microsoft](https://github.com/microsoft/sbom-tool) | Scans your dependencies and creates an SPDX compatible SBOM | {% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %} |
You can then upload and submit the SBOM to the dependency submission API using one of the following actions so that you can receive {% data variables.product.prodname_dependabot_alerts %} on any dependencies that have known vulnerabilities. Actions that appear in both tables can be configured to both generate and submit an SBOM.
You can then upload and submit the SBOM to the dependency submission API using one of the following actions so that you can receive {% data variables.product.prodname_dependabot_alerts %} on any dependencies that have known vulnerabilities. Actions that appear in both tables can be configured to both generate and submit an SBOM.
Action | Details | <nobr>Maintained by {% data variables.product.prodname_dotcom %}</nobr>
--- | --- | ---
[SPDX Dependency Submission Action](https://github.com/marketplace/actions/spdx-dependency-submission-action) | Uses [Microsoft's SBOM Tool](https://github.com/microsoft/sbom-tool) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/microsoft/component-detection/blob/main/docs/feature-overview.md) | **✓** |
[Anchore SBOM Action](https://github.com/marketplace/actions/anchore-sbom-action) | Uses [Syft](https://github.com/anchore/syft) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/anchore/syft#supported-ecosystems) | |
[SBOM Dependency Submission Action](https://github.com/marketplace/actions/sbom-submission-action)| Uploads a CycloneDX SBOM to the dependency submission API | |
[SPDX Dependency Submission Action](https://github.com/marketplace/actions/spdx-dependency-submission-action) | Uses [Microsoft's SBOM Tool](https://github.com/microsoft/sbom-tool) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/microsoft/component-detection/blob/main/docs/feature-overview.md) | {% octicon "check" aria-label="Maintained by {% data variables.product.prodname_dotcom %}" %} |
[Anchore SBOM Action](https://github.com/marketplace/actions/anchore-sbom-action) | Uses [Syft](https://github.com/anchore/syft) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/anchore/syft#supported-ecosystems) | {% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %} |
[SBOM Dependency Submission Action](https://github.com/marketplace/actions/sbom-submission-action)| Uploads a CycloneDX SBOM to the dependency submission API | {% octicon "x" aria-label="Not maintained by {% data variables.product.prodname_dotcom %}" %} |
For example, the following [SPDX Dependency Submission Action](https://github.com/marketplace/actions/spdx-dependency-submission-action) workflow calculates the dependencies for a repository, generates an exportable SBOM in SPDX 2.2 format, and submits it to the dependency submission API.
For example, the following [SPDX Dependency Submission Action](https://github.com/marketplace/actions/spdx-dependency-submission-action) workflow calculates the dependencies for a repository, generates an exportable SBOM in SPDX 2.2 format, and submits it to the dependency submission API.
```yaml
name: SBOM upload
on:
on:
workflow_dispatch:
push:
push:
branches: ["main"]
jobs:
SBOM-upload:
runs-on: ubuntu-latest
permissions:
permissions:
id-token: write
contents: write
steps:
- uses: {% data reusables.actions.action-checkout %}
- name: Generate SBOM
# generation command documentation: https://github.com/microsoft/sbom-tool#sbom-generation
run: |
# generation command documentation: https://github.com/microsoft/sbom-tool#sbom-generation
run: |
curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
chmod +x $RUNNER_TEMP/sbom-tool
$RUNNER_TEMP/sbom-tool generate -b . -bc . -pn ${{ github.repository }} -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
@@ -140,7 +140,7 @@ jobs:
with:
name: sbom
path: _manifest/spdx_2.2
- name: SBOM upload
- name: SBOM upload
uses: advanced-security/spdx-dependency-submission-action@v0.0.1
with:
filePath: "_manifest/spdx_2.2/"

10
content/get-started/learning-about-github/about-github-advanced-security.md
View File

@@ -38,11 +38,11 @@ A {% data variables.product.prodname_GH_advanced_security %} license provides th
{% ifversion fpt or ghec %}
The table below summarizes the availability of {% data variables.product.prodname_GH_advanced_security %} features for public and private repositories.
| | Public repository | Private repository without {% data variables.product.prodname_advanced_security %} | Private repository with {% data variables.product.prodname_advanced_security %} |
| :-----------------: | :---------------------------: | :--------------------------------------------: | :-----------------------------------------: |
| Code scanning | Yes | No | Yes |
| Secret scanning | Yes | No | Yes |
| Dependency review | Yes | No | Yes |
| | Public repository | Private repository <br>without {% data variables.product.prodname_advanced_security %} | Private repository <br>with {% data variables.product.prodname_advanced_security %} |
| --- | --- | --- | --- |
| Code scanning | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |
| Secret scanning | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |
| Dependency review | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |
{% endif %}
For information about {% data variables.product.prodname_advanced_security %} features that are in development, see "[{% data variables.product.prodname_dotcom %} public roadmap](https://github.com/github/roadmap)." For an overview of all security features, see "[AUTOTITLE](/code-security/getting-started/github-security-features)."