restructure shared characteristics module; add framework support for sanitizers

Author: Stephan Brandauer

java/ql/src/Telemetry/AutomodelEndpointCharacteristics.qll

@@ -25,6 +25,9 @@ module CandidatesImpl implements SharedCharacteristics::CandidateSig {
     t instanceof AutomodelEndpointTypes::NegativeSinkType
   }
 
+  // Sanitizers are currently not modeled in MaD. TODO: check if this has large negative impact.
+  predicate isSanitizer(Endpoint e, EndpointType t) { none() }
+
   string getLocationString(Endpoint e) { result = e.getLocation().toString() }
 
   predicate isKnownLabel(string label, string humanReadableLabel, EndpointType type) {

java/ql/src/Telemetry/AutomodelExtractNegativeExamples.ql

@@ -5,7 +5,7 @@
  * @kind problem
  * @severity info
  * @id java/ml-powered/non-sink
- * @tags automodel extract negative-examples
+ * @tags automodel extract examples negative
  */
 
 import AutomodelEndpointCharacteristics

java/ql/src/Telemetry/AutomodelExtractPositiveExamples.ql

@@ -5,7 +5,7 @@
  * @kind problem
  * @severity info
  * @id java/ml-powered/known-sink
- * @tags automodel extract positive-examples
+ * @tags automodel extract examples positive
  */
 
 private import java

java/ql/src/Telemetry/AutomodelSharedCharacteristics.qll

@@ -4,11 +4,19 @@ float highConfidence() { result = 0.9 }
 
 float mediumConfidence() { result = 0.6 }
 
+/**
+ * A specification of how to  instantiate the shared characteristics for a given candidate class.
+ *
+ * The `CandidateSig` implementation specifies a type to use for Endpoints (eg., `ParameterNode`), as well as a type
+ * to label endpoint classes (the `EndpointType`). One of the endpoint classes needs to be a 'negative' class, meaning
+ *   "not any of the other known endpoint types".
+ */
 signature module CandidateSig {
   class Endpoint;
 
   class EndpointType;
 
+  /** The string representing the file+range of the endpoint. */
   string getLocationString(Endpoint e);
 
   /**
@@ -22,6 +30,11 @@ signature module CandidateSig {
    */
   predicate isNegative(EndpointType t);
 
+  /**
+   * Should hold for any endpoint that is a flow sanitizer.
+   */
+  predicate isSanitizer(Endpoint e, EndpointType t);
+
   /**
    * Should hold for any endpoint that is a sink of the given (known or unknown) label.
    */
@@ -37,11 +50,23 @@ signature module CandidateSig {
    *
    * This is a helper function to extract and export needed information about each endpoint in the sink candidate query
    * as well as the queries that extract positive and negative examples for the prompt / training set. The metadata is
-   * extracted as a string in the format of a Python dictionary.
+   * extracted as a string in the format of a Python dictionary, eg.:
+   *
+   *     `{'Package': 'com.foo.util', 'Type': 'HelperClass', ... }`.
+   *
+   * The meta data will be passed on to the machine learning code by the extraction queries.
    */
   predicate hasMetadata(Endpoint e, string metadata);
 }
 
+/**
+ * A set of shared characteristics for a given candidate class.
+ *
+ * This module is language-agnostic, although the `CandidateSig` module will be language-specific.
+ *
+ * The language specific implementation can also further extend the behaviour of this module by adding additional
+ *   implementations of endpoint characteristics exported by this module.
+ */
 module SharedCharacteristics<CandidateSig Candidate> {
   predicate isNegative(Candidate::EndpointType e) { Candidate::isNegative(e) }
 
@@ -159,20 +184,6 @@ module SharedCharacteristics<CandidateSig Candidate> {
     }
   }
 
-  /**
-   * Endpoints identified as sinks by the MaD modeling are sinks with maximal confidence.
-   */
-  private class KnownSinkCharacteristic extends SinkCharacteristic {
-    string madLabel;
-    Candidate::EndpointType endpointType;
-
-    KnownSinkCharacteristic() { Candidate::isKnownLabel(madLabel, this, endpointType) }
-
-    override predicate appliesToEndpoint(Candidate::Endpoint e) { Candidate::isSink(e, madLabel) }
-
-    override Candidate::EndpointType getSinkType() { result = endpointType }
-  }
-
   /**
    * A high-confidence characteristic that indicates that an endpoint is not a sink of any type. These endpoints can be
    * used as negative samples for training or for a few-shot prompt.
@@ -190,33 +201,6 @@ module SharedCharacteristics<CandidateSig Candidate> {
     }
   }
 
-  /**
-   * A negative characteristic that indicates that an endpoint is not part of the source code for the project being
-   * analyzed.
-   *
-   * WARNING: These endpoints should not be used as negative samples for training, because they are not necessarily
-   * non-sinks. They are merely not interesting sinks to run through the ML model.
-   */
-  private class IsExternalCharacteristic extends LikelyNotASinkCharacteristic {
-    IsExternalCharacteristic() { this = "external" }
-
-    override predicate appliesToEndpoint(Candidate::Endpoint e) {
-      not exists(Candidate::getLocationString(e))
-    }
-  }
-
-  /**
-   * A negative characteristic that indicates that an endpoint was manually modeled as a neutral model.
-   *
-   * TODO: It may be necessary to turn this into a LikelyNotASinkCharacteristic, pending answers to the definition of a
-   * neutral model (https://github.com/github/codeql-java-team/issues/254#issuecomment-1435309148).
-   */
-  private class NeutralModelCharacteristic extends NotASinkCharacteristic {
-    NeutralModelCharacteristic() { this = "known non-sink" }
-
-    override predicate appliesToEndpoint(Candidate::Endpoint e) { Candidate::isNeutral(e) }
-  }
-
   /**
    * A medium-confidence characteristic that indicates that an endpoint is unlikely to be a sink of any type. These
    * endpoints can be excluded from scoring at inference time, both to save time and to avoid false positives. They should
@@ -256,4 +240,42 @@ module SharedCharacteristics<CandidateSig Candidate> {
       confidence = mediumConfidence()
     }
   }
+
+  /**
+   * Contains default implementations that are derived solely from the `CandidateSig` implementation.
+   */
+  private module DefaultCharacteristicImplementations {
+    /**
+     * Endpoints identified as sinks by the `CandidateSig` implementation are sinks with maximal confidence.
+     */
+    private class KnownSinkCharacteristic extends SinkCharacteristic {
+      string madLabel;
+      Candidate::EndpointType endpointType;
+
+      KnownSinkCharacteristic() { Candidate::isKnownLabel(madLabel, this, endpointType) }
+
+      override predicate appliesToEndpoint(Candidate::Endpoint e) { Candidate::isSink(e, madLabel) }
+
+      override Candidate::EndpointType getSinkType() { result = endpointType }
+    }
+
+    /**
+     * A negative characteristic that indicates that an endpoint was manually modeled as a neutral model.
+     */
+    private class NeutralModelCharacteristic extends NotASinkCharacteristic {
+      NeutralModelCharacteristic() { this = "known non-sink" }
+
+      override predicate appliesToEndpoint(Candidate::Endpoint e) { Candidate::isNeutral(e) }
+    }
+
+    /**
+     * A negative characteristic that indicates that an endpoint is not part of the source code for the project being
+     * analyzed.
+     */
+    private class IsSanitizerCharacteristic extends NotASinkCharacteristic {
+      IsSanitizerCharacteristic() { this = "external" }
+
+      override predicate appliesToEndpoint(Candidate::Endpoint e) { Candidate::isSanitizer(e, _) }
+    }
+  }
 }