Merge pull request github#15235 from github/docs-11486-security-severity

felicitymay · web-flow · commit e408078eaaa5 · 2024-01-12T09:21:08.000Z
Replace blog link with link to GitHub user docs
diff --git a/docs/codeql/writing-codeql-queries/metadata-for-codeql-queries.rst b/docs/codeql/writing-codeql-queries/metadata-for-codeql-queries.rst
@@ -8,16 +8,16 @@ Metadata tells users important information about CodeQL queries. You must includ
 About query metadata
 --------------------
 
-Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a QLDoc comment. 
-This metadata tells the CodeQL :ref:`extension for VS Code <codeql-for-visual-studio-code>` and the `Code scanning feature in GitHub <https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql>`__ how to handle the query and display its results correctly. 
+Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a QLDoc comment.
+This metadata tells the CodeQL :ref:`extension for VS Code <codeql-for-visual-studio-code>` and the `Code scanning feature in GitHub <https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql>`__ how to handle the query and display its results correctly.
 It also gives other users information about what the query results mean. For more information on query metadata, see the `query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__ in our `open source repository <https://github.com/github/codeql>`__ on GitHub.
 
 .. pull-quote::
 
     Note
 
     The exact metadata requirement depends on how you are going to run your query. For more information, see the section on query metadata in ":doc:`About CodeQL queries <about-codeql-queries>`."
-    
+
 Metadata properties
 -------------------
 
@@ -49,7 +49,7 @@ The following properties are supported by all query files:
 |                       | | ``warning``             |                                                                                                                                                                                                                                                                                                                                                                       |
 |                       | | ``recommendation``      |                                                                                                                                                                                                                                                                                                                                                                       |
 +-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``@security-severity``| ``<score>``               | Defines the level of severity, between 0.0 and 10.0, for queries with ``@tags security``. For more information about calculating ``@security-severity``, see the `GitHub changelog <https://gh.io/2021-07-19-codeql-security-severity>`__.                                                                                                                            |
+| ``@security-severity``| ``<score>``               | Defines the level of severity, between 0.0 and 10.0, for queries with ``@tags security``. For more information, see the `GitHub user documentation <https://docs.github.com/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels>`__.                                               |
 +-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 Example
diff --git a/docs/query-metadata-style-guide.md b/docs/query-metadata-style-guide.md
@@ -117,7 +117,7 @@ Alert queries (`@kind problem` or `path-problem`) support two further properties
   * `error`–an issue that is likely to cause incorrect program behavior, for example a crash or vulnerability.
   * `warning`–an issue that indicates a potential problem in the code, or makes the code fragile if another (unrelated) part of code is changed.
   * `recommendation`–an issue where the code behaves correctly, but it could be improved.
-* `@security-severity`-defines the level of severity, between 0.0 and 10.0, for queries with `@tags security`. For more information about calculating `@security-severity`, see the [GitHub changelog](https://github.blog/changelog/2021-07-19-codeql-code-scanning-new-severity-levels-for-security-alerts/).  
+* `@security-severity`-defines the level of severity, between 0.0 and 10.0, for queries with `@tags security`. For more information about how this value is calculated and then used in code scanning analysis, see [About alert severity and security severity levels](https://docs.github.com/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels) in the GitHub user documentation.
 
 ## Query tags `@tags`
 
@@ -155,7 +155,10 @@ If your query is a security query, use one or more `@tags` to associate it with
 ||`external/cwe/cwe-036` |
 ||`external/cwe/cwe-073` |
 
-When you tag a query like this, the associated CWE pages from [MITRE.org](https://cwe.mitre.org/index.html) will automatically appear in the reference section of its associated qhelp file.
+When you tag a query like this, the associated CWE pages from [MITRE.org](https://cwe.mitre.org/index.html) will automatically appear in the references section of its associated qhelp file.
+
+> [!NOTE]
+> The automatic addition of CWE reference links works only if the qhelp file already contains a `<references>` section.
 
 #### Metric/summary `@tags`
 
@@ -175,14 +178,14 @@ The select clause of each alert query defines the alert message that is displaye
 * Program element references should be in 'single quotes' to distinguish them from ordinary words. Quotes are not needed around substitutions (`$@`).
 * Avoid constant alert message strings and include some context, if possible. For example, `The class 'Foo' is duplicated as 'Bar'.` is preferable to `This class is duplicated here.`
 * If a reference to the current location can't be avoided use "this location" instead of "here". For example, `Bad thing at this location.` is preferable to `Bad thing here.`. This avoids the "click here" anti-pattern.
-* For path queries, if possible, try to follow the template: `This path depends on a [user-provided value].`, or alternatively (if the first option doesn't work) `[User-provided value] flows to this location and is used in a path.`. 
+* For path queries, if possible, try to follow the template: `This path depends on a [user-provided value].`, or alternatively (if the first option doesn't work) `[User-provided value] flows to this location and is used in a path.`.
 * Taint tracking queries generally have a sink that "depends on" the source, and dataflow queries generally have a source that "flows to" the sink.
 
 ### Links in alert messages
 
 * Where you reference another program element, link to it if possible using a substitution (`$@`). Links should be used inline in the sentence, rather than as parenthesised lists or appositions.
-* Avoid using link texts that don't describe what they link to. For example, rewrite `This sensitive data is written to a logfile unescaped [here]` to `This sensitive data is [written to a logfile unescaped]`. 
-* Make link text as concise and precise as possible. For example, avoid starting a link text with an indefinite article (a, an). `Path construction depends on a [user-provided value]` is preferable to `Path construction depends on [a user-provided value]`. (Where the square brackets indicate a link.) See [the W3C guide on link texts](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) for further information. 
+* Avoid using link texts that don't describe what they link to. For example, rewrite `This sensitive data is written to a logfile unescaped [here]` to `This sensitive data is [written to a logfile unescaped]`.
+* Make link text as concise and precise as possible. For example, avoid starting a link text with an indefinite article (a, an). `Path construction depends on a [user-provided value]` is preferable to `Path construction depends on [a user-provided value]`. (Where the square brackets indicate a link.) See [the W3C guide on link texts](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) for further information.
 * When a message contains multiple links, construct a sentence that has the most variable link (that is, the link with most targets) last. For further information, see [Defining the results of a query](https://codeql.github.com/docs/writing-codeql-queries/defining-the-results-of-a-query/).
 
 For examples of select clauses and alert messages, see the query source files at the following pages:
@@ -203,5 +206,3 @@ The `select` clause of a summary metric query must have one of the following res
   - This indicates a metric without a specific location in the codebase, for example the total lines of code in a codebase.
 - A code `entity` followed by a `number`
   - This indicates a metric with a specific location in the codebase, for example the lines of code within a file. The `entity` here must have a valid location in the source code.
-
-
