Merge pull request #12935 from michaelnebel/neutralkindsdocs

Java: Update customizing library models for java documentation.

Author: michaelnebel

docs/codeql/codeql-language-guides/customizing-library-models-for-java.rst

@@ -35,7 +35,7 @@ The CodeQL library for Java exposes the following extensible predicates:
 - **sourceModel**\(package, type, subtypes, name, signature, ext, output, kind, provenance). This is used for **source** models.
 - **sinkModel**\(package, type, subtypes, name, signature, ext, input, kind, provenance). This is used for **sink** models.
 - **summaryModel**\(package, type, subtypes, name, signature, ext, input, output, kind, provenance). This is used for **summary** models.
-- **neutralModel**\(package, type, name, signature, provenance). This is used for **neutral** models, which only have minor impact on the data flow analysis.
+- **neutralModel**\(package, type, name, signature, kind, provenance). This is used for **neutral** models, which only have minor impact on the data flow analysis.
 
 The extensible predicates are populated using data extensions specified in YAML files.
 
@@ -236,7 +236,7 @@ That is, the first row models that there is value flow from the elements of the
 
 Example: Add a **neutral** method
 ----------------------------------
-In this example we will show how to model the **now** method as being neutral.
+In this example we will show how to model the **now** method as being neutral with respect to flow.
 A neutral model is used to define that there is no flow through a method.
 Note that the neutral model for the **now** method is already added to the CodeQL Java analysis.
 
@@ -247,7 +247,7 @@ Note that the neutral model for the **now** method is already added to the CodeQ
        ...
    }
 
-We need to add a tuple to the **neutralModel**\(package, type, name, signature, provenance) extensible predicate. To do this, add the following to a data extension file:
+We need to add a tuple to the **neutralModel**\(package, type, name, signature, kind, provenance) extensible predicate. To do this, add the following to a data extension file:
 
 .. code-block:: yaml
 
@@ -256,17 +256,18 @@ We need to add a tuple to the **neutralModel**\(package, type, name, signature,
        pack: codeql/java-all
        extensible: neutralModel
      data:
-       - ["java.time", "Instant", "now", "()", "manual"]
+       - ["java.time", "Instant", "now", "()", "summary", "manual"]
 
 
 Since we are adding a neutral model, we need to add tuples to the **neutralModel** extensible predicate.
-The first five values identify the callable (in this case a method) to be modeled as a neutral and the fifth value is the provenance (origin) of the neutral.
+The first four values identify the callable (in this case a method) to be modeled as a neutral, the fifth value is the kind, and the sixth value is the provenance (origin) of the neutral.
 
 - The first value **java.time** is the package name.
 - The second value **Instant** is the class (type) name.
 - The third value **now** is the method name.
 - The fourth value **()** is the method input type signature.
-- The fifth value **manual** is the provenance of the neutral.
+- The fifth value **summary** is the kind of the neutral.
+- The sixth value **manual** is the provenance of the neutral.
 
 .. _reference-material:
 
@@ -354,13 +355,14 @@ The following kinds are supported:
 - **taint**: This means the output is not necessarily equal to the input, but it was derived from the input in an unrestrictive way. An attacker who controls the input will have significant control over the output as well.
 - **value**: This means that the output equals the input or a copy of the input such that all of its properties are preserved.
 
-neutralModel(package, type, name, signature, provenance)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+neutralModel(package, type, name, signature, kind, provenance)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This extensible predicate is not typically needed externally, but included here for completeness.
 It only has minor impact on the data flow analysis.
 Manual neutrals are considered high confidence dispatch call targets and can reduce the number of dispatch call targets during data flow analysis (a performance optimization).
 
+- **kind**: Kind of the neutral. For neutrals the kind can be **summary**, **source**, or **sink** to indicate that the callable is neutral with respect to flow (no summary), source (is not a source) or sink (is not a sink).
 - **provenance**: Provenance (origin) of the flow through.
 
 .. _access-paths: