C#/Java: Add some more QL Doc to the CaptureModels[Specific] implementation.

michaelnebel · michaelnebel · commit ad27a5a1a618 · 2022-03-29T11:07:57.000+02:00
diff --git a/csharp/ql/src/utils/model-generator/internal/CaptureModels.qll b/csharp/ql/src/utils/model-generator/internal/CaptureModels.qll
@@ -98,6 +98,13 @@ string captureThroughFlow(TargetApi api) {
   )
 }
 
+/**
+ * A TaintTracking Configuration used for tracking flow through APIs.
+ * The sources are the already known existing sources and the sinks are the API return nodes.
+ *
+ * This can be used to generate Source summaries for an API, if the API expose an already known source
+ * via its return (then the API itself becomes a source).
+ */
 private class FromSourceConfiguration extends TaintTracking::Configuration {
   FromSourceConfiguration() { this = "FromSourceConfiguration" }
 
@@ -131,6 +138,13 @@ string captureSource(TargetApi api) {
   )
 }
 
+/**
+ * A TaintTracking Configuration used for tracking flow through APIs.
+ * The sources are the parameters of the API and the fields of the enclosing type.
+ *
+ * This can be used to generate Sink summaries for APIs, if the API propgates a parameter (or enclosing type field)
+ * into an existing known sink (then the API itself becomes a sink).
+ */
 private class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {
   PropagateToSinkConfiguration() { this = "parameters or fields flowing into sinks" }
 
diff --git a/csharp/ql/src/utils/model-generator/internal/CaptureModelsSpecific.qll b/csharp/ql/src/utils/model-generator/internal/CaptureModelsSpecific.qll
@@ -24,6 +24,9 @@ predicate isOwnInstanceAccessNode(ReturnNode node) { node.asExpr() instanceof Th
  */
 string qualifierString() { result = "Argument[Qualifier]" }
 
+/**
+ * Language specific parts of the `PropagateToSinkConfiguration`.
+ */
 class PropagateToSinkConfigurationSpecific extends TaintTracking::Configuration {
   PropagateToSinkConfigurationSpecific() { this = "parameters or fields flowing into sinks" }
 
@@ -34,12 +37,15 @@ class PropagateToSinkConfigurationSpecific extends TaintTracking::Configuration
   }
 }
 
+/**
+ * Gets the CSV input string representation of `source`.
+ */
 string asInputArgument(DataFlow::Node source) {
   exists(int pos |
     pos = source.(DataFlow::ParameterNode).getParameter().getPosition() and
     result = "Argument[" + pos + "]"
   )
   or
   source.asExpr() instanceof FieldAccess and
-  result = "Argument[Qualifier]"
+  result = qualifierString()
 }
diff --git a/java/ql/src/utils/model-generator/internal/CaptureModels.qll b/java/ql/src/utils/model-generator/internal/CaptureModels.qll
@@ -98,6 +98,13 @@ string captureThroughFlow(TargetApi api) {
   )
 }
 
+/**
+ * A TaintTracking Configuration used for tracking flow through APIs.
+ * The sources are the already known existing sources and the sinks are the API return nodes.
+ *
+ * This can be used to generate Source summaries for an API, if the API expose an already known source
+ * via its return (then the API itself becomes a source).
+ */
 private class FromSourceConfiguration extends TaintTracking::Configuration {
   FromSourceConfiguration() { this = "FromSourceConfiguration" }
 
@@ -131,6 +138,13 @@ string captureSource(TargetApi api) {
   )
 }
 
+/**
+ * A TaintTracking Configuration used for tracking flow through APIs.
+ * The sources are the parameters of the API and the fields of the enclosing type.
+ *
+ * This can be used to generate Sink summaries for APIs, if the API propgates a parameter (or enclosing type field)
+ * into an existing known sink (then the API itself becomes a sink).
+ */
 private class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {
   PropagateToSinkConfiguration() { this = "parameters or fields flowing into sinks" }
 
diff --git a/java/ql/src/utils/model-generator/internal/CaptureModelsSpecific.qll b/java/ql/src/utils/model-generator/internal/CaptureModelsSpecific.qll
@@ -30,6 +30,9 @@ predicate isOwnInstanceAccessNode(ReturnNode node) {
  */
 string qualifierString() { result = "Argument[-1]" }
 
+/**
+ * Language specific parts of the `PropagateToSinkConfiguration`.
+ */
 class PropagateToSinkConfigurationSpecific extends TaintTracking::Configuration {
   PropagateToSinkConfigurationSpecific() { this = "parameters or fields flowing into sinks" }
 
@@ -45,12 +48,15 @@ class PropagateToSinkConfigurationSpecific extends TaintTracking::Configuration
   }
 }
 
+/**
+ * Gets the CSV input string representation of `source`.
+ */
 string asInputArgument(DataFlow::Node source) {
   exists(int pos |
     source.(DataFlow::ParameterNode).isParameterOf(_, pos) and
     result = "Argument[" + pos + "]"
   )
   or
   source.asExpr() instanceof FieldAccess and
-  result = "Argument[-1]"
+  result = qualifierString()
 }

Original file line number	Diff line number	Diff line change
`@@ -98,6 +98,13 @@ string captureThroughFlow(TargetApi api) {`
`98`	`98`	`)`
`99`	`99`	`}`
`100`	`100`
	`101`	`+/**`
	`102`	`+ * A TaintTracking Configuration used for tracking flow through APIs.`
	`103`	`+ * The sources are the already known existing sources and the sinks are the API return nodes.`
	`104`	`+ *`
	`105`	`+ * This can be used to generate Source summaries for an API, if the API expose an already known source`
	`106`	`+ * via its return (then the API itself becomes a source).`
	`107`	`+ */`
`101`	`108`	`private class FromSourceConfiguration extends TaintTracking::Configuration {`
`102`	`109`	`FromSourceConfiguration() { this = "FromSourceConfiguration" }`
`103`	`110`
`@@ -131,6 +138,13 @@ string captureSource(TargetApi api) {`
`131`	`138`	`)`
`132`	`139`	`}`
`133`	`140`
	`141`	`+/**`
	`142`	`+ * A TaintTracking Configuration used for tracking flow through APIs.`
	`143`	`+ * The sources are the parameters of the API and the fields of the enclosing type.`
	`144`	`+ *`
	`145`	`+ * This can be used to generate Sink summaries for APIs, if the API propgates a parameter (or enclosing type field)`
	`146`	`+ * into an existing known sink (then the API itself becomes a sink).`
	`147`	`+ */`
`134`	`148`	`private class PropagateToSinkConfiguration extends PropagateToSinkConfigurationSpecific {`
`135`	`149`	`PropagateToSinkConfiguration() { this = "parameters or fields flowing into sinks" }`
`136`	`150`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,9 @@ predicate isOwnInstanceAccessNode(ReturnNode node) { node.asExpr() instanceof Th`
`24`	`24`	`*/`
`25`	`25`	`string qualifierString() { result = "Argument[Qualifier]" }`
`26`	`26`
	`27`	`+/**`
	`28`	+ * Language specific parts of the `PropagateToSinkConfiguration`.
	`29`	`+ */`
`27`	`30`	`class PropagateToSinkConfigurationSpecific extends TaintTracking::Configuration {`
`28`	`31`	`PropagateToSinkConfigurationSpecific() { this = "parameters or fields flowing into sinks" }`
`29`	`32`
`@@ -34,12 +37,15 @@ class PropagateToSinkConfigurationSpecific extends TaintTracking::Configuration`
`34`	`37`	`}`
`35`	`38`	`}`
`36`	`39`
	`40`	`+/**`
	`41`	+ * Gets the CSV input string representation of `source`.
	`42`	`+ */`
`37`	`43`	`string asInputArgument(DataFlow::Node source) {`
`38`	`44`	`exists(int pos \|`
`39`	`45`	`pos = source.(DataFlow::ParameterNode).getParameter().getPosition() and`
`40`	`46`	`result = "Argument[" + pos + "]"`
`41`	`47`	`)`
`42`	`48`	`or`
`43`	`49`	`source.asExpr() instanceof FieldAccess and`
`44`		`- result = "Argument[Qualifier]"`
	`50`	`+ result = qualifierString()`
`45`	`51`	`}`
Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,9 @@ predicate isOwnInstanceAccessNode(ReturnNode node) {`
`30`	`30`	`*/`
`31`	`31`	`string qualifierString() { result = "Argument[-1]" }`
`32`	`32`
	`33`	`+/**`
	`34`	+ * Language specific parts of the `PropagateToSinkConfiguration`.
	`35`	`+ */`
`33`	`36`	`class PropagateToSinkConfigurationSpecific extends TaintTracking::Configuration {`
`34`	`37`	`PropagateToSinkConfigurationSpecific() { this = "parameters or fields flowing into sinks" }`
`35`	`38`
`@@ -45,12 +48,15 @@ class PropagateToSinkConfigurationSpecific extends TaintTracking::Configuration`
`45`	`48`	`}`
`46`	`49`	`}`
`47`	`50`
	`51`	`+/**`
	`52`	+ * Gets the CSV input string representation of `source`.
	`53`	`+ */`
`48`	`54`	`string asInputArgument(DataFlow::Node source) {`
`49`	`55`	`exists(int pos \|`
`50`	`56`	`source.(DataFlow::ParameterNode).isParameterOf(_, pos) and`
`51`	`57`	`result = "Argument[" + pos + "]"`
`52`	`58`	`)`
`53`	`59`	`or`
`54`	`60`	`source.asExpr() instanceof FieldAccess and`
`55`		`- result = "Argument[-1]"`
	`61`	`+ result = qualifierString()`
`56`	`62`	`}`