C#/Java: Make configurations private and sprinkle some QL Doc.

michaelnebel · michaelnebel · commit 79fd2e6a407b · 2022-03-29T11:07:57.000+02:00
diff --git a/csharp/ql/src/utils/model-generator/CaptureSinkModels.qll b/csharp/ql/src/utils/model-generator/CaptureSinkModels.qll
@@ -1,6 +1,6 @@
 private import CaptureSinkModelsSpecific
 
-class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {
+private class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {
   PropagateToSinkConfiguration() { this = "parameters or fields flowing into sinks" }
 
   override predicate isSink(DataFlow::Node sink) { sinkNode(sink, _) }
@@ -10,6 +10,9 @@ class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific
   }
 }
 
+/**
+ * Gets the sink model(s) of `api`, if there is flow from a parameter to an existing known sink.
+ */
 string captureSink(TargetApi api) {
   exists(DataFlow::Node src, DataFlow::Node sink, PropagateToSinkConfiguration config, string kind |
     config.hasFlow(src, sink) and
diff --git a/csharp/ql/src/utils/model-generator/CaptureSourceModels.qll b/csharp/ql/src/utils/model-generator/CaptureSourceModels.qll
@@ -1,7 +1,7 @@
 private import CaptureSourceModelsSpecific
 private import ModelGeneratorUtils
 
-class FromSourceConfiguration extends TaintTracking::Configuration {
+private class FromSourceConfiguration extends TaintTracking::Configuration {
   FromSourceConfiguration() { this = "FromSourceConfiguration" }
 
   override predicate isSource(DataFlow::Node source) { sourceNode(source, _) }
@@ -22,6 +22,9 @@ class FromSourceConfiguration extends TaintTracking::Configuration {
   }
 }
 
+/**
+ * Gets the source model(s) of `api`, if there is flow from an existing known source to the return of `api`.
+ */
 string captureSource(TargetApi api) {
   exists(DataFlow::Node source, DataFlow::Node sink, FromSourceConfiguration config, string kind |
     config.hasFlow(source, sink) and
diff --git a/csharp/ql/src/utils/model-generator/CaptureSummaryModels.qll b/csharp/ql/src/utils/model-generator/CaptureSummaryModels.qll
@@ -36,7 +36,7 @@ private class TaintStore extends DataFlow::FlowState {
  *
  * This can be used to generate Flow summaries for APIs from parameter to return.
  */
-class ThroughFlowConfig extends TaintTracking::Configuration {
+private class ThroughFlowConfig extends TaintTracking::Configuration {
   ThroughFlowConfig() { this = "ThroughFlowConfig" }
 
   override predicate isSource(DataFlow::Node source, DataFlow::FlowState state) {
diff --git a/csharp/ql/src/utils/model-generator/CaptureSummaryModelsSpecific.qll b/csharp/ql/src/utils/model-generator/CaptureSummaryModelsSpecific.qll
@@ -8,8 +8,17 @@ import semmle.code.csharp.dataflow.internal.DataFlowImplCommon
 import semmle.code.csharp.dataflow.internal.DataFlowPrivate
 import ModelGeneratorUtils
 
+/**
+ * Gets the enclosing callable of `ret`.
+ */
 Callable returnNodeEnclosingCallable(ReturnNodeExt ret) { result = getNodeEnclosingCallable(ret) }
 
+/**
+ * Holds if `node` is an own instance access.
+ */
 predicate isOwnInstanceAccessNode(ReturnNode node) { node.asExpr() instanceof ThisAccess }
 
+/**
+ * Gets the CSV string representation of the qualifier.
+ */
 string qualifierString() { result = "Argument[Qualifier]" }
diff --git a/csharp/ql/src/utils/model-generator/ModelGeneratorUtilsSpecific.qll b/csharp/ql/src/utils/model-generator/ModelGeneratorUtilsSpecific.qll
@@ -5,6 +5,9 @@ private import semmle.code.csharp.commons.Collections
 private import semmle.code.csharp.dataflow.internal.DataFlowImplCommon
 private import semmle.code.csharp.dataflow.internal.DataFlowDispatch
 
+/**
+ * Holds if it is relevant to generate models for `api`.
+ */
 predicate isRelevantForModels(Callable api) { not api instanceof MainMethod }
 
 /**
diff --git a/java/ql/src/utils/model-generator/CaptureSinkModels.qll b/java/ql/src/utils/model-generator/CaptureSinkModels.qll
@@ -1,6 +1,6 @@
 private import CaptureSinkModelsSpecific
 
-class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {
+private class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {
   PropagateToSinkConfiguration() { this = "parameters or fields flowing into sinks" }
 
   override predicate isSink(DataFlow::Node sink) { sinkNode(sink, _) }
@@ -10,6 +10,9 @@ class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific
   }
 }
 
+/**
+ * Gets the sink model(s) of `api`, if there is flow from a parameter to an existing known sink.
+ */
 string captureSink(TargetApi api) {
   exists(DataFlow::Node src, DataFlow::Node sink, PropagateToSinkConfiguration config, string kind |
     config.hasFlow(src, sink) and
diff --git a/java/ql/src/utils/model-generator/CaptureSourceModels.qll b/java/ql/src/utils/model-generator/CaptureSourceModels.qll
@@ -1,7 +1,7 @@
 private import CaptureSourceModelsSpecific
 private import ModelGeneratorUtils
 
-class FromSourceConfiguration extends TaintTracking::Configuration {
+private class FromSourceConfiguration extends TaintTracking::Configuration {
   FromSourceConfiguration() { this = "FromSourceConfiguration" }
 
   override predicate isSource(DataFlow::Node source) { sourceNode(source, _) }
@@ -22,6 +22,9 @@ class FromSourceConfiguration extends TaintTracking::Configuration {
   }
 }
 
+/**
+ * Gets the source model(s) of `api`, if there is flow from an existing known source to the return of `api`.
+ */
 string captureSource(TargetApi api) {
   exists(DataFlow::Node source, DataFlow::Node sink, FromSourceConfiguration config, string kind |
     config.hasFlow(source, sink) and
diff --git a/java/ql/src/utils/model-generator/CaptureSummaryModels.qll b/java/ql/src/utils/model-generator/CaptureSummaryModels.qll
@@ -36,7 +36,7 @@ private class TaintStore extends DataFlow::FlowState {
  *
  * This can be used to generate Flow summaries for APIs from parameter to return.
  */
-class ThroughFlowConfig extends TaintTracking::Configuration {
+private class ThroughFlowConfig extends TaintTracking::Configuration {
   ThroughFlowConfig() { this = "ThroughFlowConfig" }
 
   override predicate isSource(DataFlow::Node source, DataFlow::FlowState state) {
diff --git a/java/ql/src/utils/model-generator/CaptureSummaryModelsSpecific.qll b/java/ql/src/utils/model-generator/CaptureSummaryModelsSpecific.qll
@@ -10,12 +10,21 @@ import semmle.code.java.dataflow.internal.DataFlowPrivate
 import semmle.code.java.dataflow.InstanceAccess
 import ModelGeneratorUtils
 
+/**
+ * Gets the enclosing callable of `ret`.
+ */
 Callable returnNodeEnclosingCallable(ReturnNodeExt ret) {
   result = getNodeEnclosingCallable(ret).asCallable()
 }
 
+/**
+ * Holds if `node` is an own instance access.
+ */
 predicate isOwnInstanceAccessNode(ReturnNode node) {
   node.asExpr().(ThisAccess).isOwnInstanceAccess()
 }
 
+/**
+ * Gets the CSV string representation of the qualifier.
+ */
 string qualifierString() { result = "Argument[-1]" }
diff --git a/java/ql/src/utils/model-generator/ModelGeneratorUtilsSpecific.qll b/java/ql/src/utils/model-generator/ModelGeneratorUtilsSpecific.qll
@@ -36,6 +36,9 @@ private predicate isJdkInternal(CompilationUnit cu) {
   cu.getPackage().getName() = ""
 }
 
+/**
+ * Holds if it is relevant to generate models for `api`.
+ */
 predicate isRelevantForModels(Callable api) {
   not isInTestFile(api.getCompilationUnit().getFile()) and
   not isJdkInternal(api.getCompilationUnit()) and

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`private import CaptureSinkModelsSpecific`
`2`	`2`
`3`		`-class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {`
	`3`	`+private class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {`
`4`	`4`	`PropagateToSinkConfiguration() { this = "parameters or fields flowing into sinks" }`
`5`	`5`
`6`	`6`	`override predicate isSink(DataFlow::Node sink) { sinkNode(sink, _) }`
`@@ -10,6 +10,9 @@ class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific`
`10`	`10`	`}`
`11`	`11`	`}`
`12`	`12`
	`13`	`+/**`
	`14`	+ * Gets the sink model(s) of `api`, if there is flow from a parameter to an existing known sink.
	`15`	`+ */`
`13`	`16`	`string captureSink(TargetApi api) {`
`14`	`17`	`exists(DataFlow::Node src, DataFlow::Node sink, PropagateToSinkConfiguration config, string kind \|`
`15`	`18`	`config.hasFlow(src, sink) and`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ private class TaintStore extends DataFlow::FlowState {`
`36`	`36`	`*`
`37`	`37`	`* This can be used to generate Flow summaries for APIs from parameter to return.`
`38`	`38`	`*/`
`39`		`-class ThroughFlowConfig extends TaintTracking::Configuration {`
	`39`	`+private class ThroughFlowConfig extends TaintTracking::Configuration {`
`40`	`40`	`ThroughFlowConfig() { this = "ThroughFlowConfig" }`
`41`	`41`
`42`	`42`	`override predicate isSource(DataFlow::Node source, DataFlow::FlowState state) {`
Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,9 @@ private predicate isJdkInternal(CompilationUnit cu) {`
`36`	`36`	`cu.getPackage().getName() = ""`
`37`	`37`	`}`
`38`	`38`
	`39`	`+/**`
	`40`	+ * Holds if it is relevant to generate models for `api`.
	`41`	`+ */`
`39`	`42`	`predicate isRelevantForModels(Callable api) {`
`40`	`43`	`not isInTestFile(api.getCompilationUnit().getFile()) and`
`41`	`44`	`not isJdkInternal(api.getCompilationUnit()) and`