Add or change qldocs

rvermeulen · rvermeulen · commit 894b3f2cd400 · 2020-08-17T11:40:08.000+02:00
diff --git a/java/ql/src/semmle/code/java/security/XSS.qll b/java/ql/src/semmle/code/java/security/XSS.qll
@@ -1,3 +1,5 @@
+/** Provides classes to reason about Cross-site scripting (XSS) vulnerabilities. */
+
 import java
 import semmle.code.java.frameworks.Servlets
 import semmle.code.java.frameworks.android.WebView
@@ -6,12 +8,10 @@ import semmle.code.java.frameworks.spring.SpringHttp
 import semmle.code.java.dataflow.DataFlow
 import semmle.code.java.dataflow.TaintTracking2
 
-/*
- * Definitions for XSS sinks
- */
-
+/** A sink that represent a method that outputs data without applying contextual output encoding. */
 abstract class XssSink extends DataFlow::Node { }
 
+/** A sanitizer that neutralizes dangerous characters that can be used to perform a XSS attack. */
 abstract class XssSanitizer extends DataFlow::Node { }
 
 /**
@@ -28,6 +28,7 @@ abstract class XssAdditionalTaintStep extends TaintTracking2::Unit {
   abstract predicate step(DataFlow::Node node1, DataFlow::Node node2);
 }
 
+/** A default sink representing methods susceptible to XSS attacks. */
 private class DefaultXssSink extends XssSink {
   DefaultXssSink() {
     exists(HttpServletResponseSendErrorMethod m, MethodAccess ma |
@@ -96,12 +97,14 @@ private class DefaultXssSink extends XssSink {
   }
 }
 
+/** A default sanitizer that considers numeric and boolean typed data safe for writing to output. */
 private class DefaultXSSSanitizer extends XssSanitizer {
   DefaultXSSSanitizer() {
     this.getType() instanceof NumericType or this.getType() instanceof BooleanType
   }
 }
 
+/** A configuration that tracks data from a servlet writer to an output method. */
 private class ServletWriterSourceToWritingMethodFlowConfig extends TaintTracking2::Configuration {
   ServletWriterSourceToWritingMethodFlowConfig() {
     this = "XSS::ServletWriterSourceToWritingMethodFlowConfig"
@@ -116,6 +119,7 @@ private class ServletWriterSourceToWritingMethodFlowConfig extends TaintTracking
   }
 }
 
+/** A class representing methods that can be used to output data. */
 private class WritingMethod extends Method {
   WritingMethod() {
     getDeclaringType().getASupertype*().hasQualifiedName("java.io", _) and
@@ -127,6 +131,7 @@ private class WritingMethod extends Method {
   }
 }
 
+/** A class representing methods that provides access to an output stream or writer. */
 class ServletWriterSource extends MethodAccess {
   ServletWriterSource() {
     this.getMethod() instanceof ServletResponseGetWriterMethod

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+/** Provides classes to reason about Cross-site scripting (XSS) vulnerabilities. */`
	`2`	`+`
`1`	`3`	`import java`
`2`	`4`	`import semmle.code.java.frameworks.Servlets`
`3`	`5`	`import semmle.code.java.frameworks.android.WebView`
`@@ -6,12 +8,10 @@ import semmle.code.java.frameworks.spring.SpringHttp`
`6`	`8`	`import semmle.code.java.dataflow.DataFlow`
`7`	`9`	`import semmle.code.java.dataflow.TaintTracking2`
`8`	`10`
`9`		`-/*`
`10`		`- * Definitions for XSS sinks`
`11`		`- */`
`12`		`-`
	`11`	`+/** A sink that represent a method that outputs data without applying contextual output encoding. */`
`13`	`12`	`abstract class XssSink extends DataFlow::Node { }`
`14`	`13`
	`14`	`+/** A sanitizer that neutralizes dangerous characters that can be used to perform a XSS attack. */`
`15`	`15`	`abstract class XssSanitizer extends DataFlow::Node { }`
`16`	`16`
`17`	`17`	`/**`
`@@ -28,6 +28,7 @@ abstract class XssAdditionalTaintStep extends TaintTracking2::Unit {`
`28`	`28`	`abstract predicate step(DataFlow::Node node1, DataFlow::Node node2);`
`29`	`29`	`}`
`30`	`30`
	`31`	`+/** A default sink representing methods susceptible to XSS attacks. */`
`31`	`32`	`private class DefaultXssSink extends XssSink {`
`32`	`33`	`DefaultXssSink() {`
`33`	`34`	`exists(HttpServletResponseSendErrorMethod m, MethodAccess ma \|`
`@@ -96,12 +97,14 @@ private class DefaultXssSink extends XssSink {`
`96`	`97`	`}`
`97`	`98`	`}`
`98`	`99`
	`100`	`+/** A default sanitizer that considers numeric and boolean typed data safe for writing to output. */`
`99`	`101`	`private class DefaultXSSSanitizer extends XssSanitizer {`
`100`	`102`	`DefaultXSSSanitizer() {`
`101`	`103`	`this.getType() instanceof NumericType or this.getType() instanceof BooleanType`
`102`	`104`	`}`
`103`	`105`	`}`
`104`	`106`
	`107`	`+/** A configuration that tracks data from a servlet writer to an output method. */`
`105`	`108`	`private class ServletWriterSourceToWritingMethodFlowConfig extends TaintTracking2::Configuration {`
`106`	`109`	`ServletWriterSourceToWritingMethodFlowConfig() {`
`107`	`110`	`this = "XSS::ServletWriterSourceToWritingMethodFlowConfig"`
`@@ -116,6 +119,7 @@ private class ServletWriterSourceToWritingMethodFlowConfig extends TaintTracking`
`116`	`119`	`}`
`117`	`120`	`}`
`118`	`121`
	`122`	`+/** A class representing methods that can be used to output data. */`
`119`	`123`	`private class WritingMethod extends Method {`
`120`	`124`	`WritingMethod() {`
`121`	`125`	`getDeclaringType().getASupertype*().hasQualifiedName("java.io", _) and`
`@@ -127,6 +131,7 @@ private class WritingMethod extends Method {`
`127`	`131`	`}`
`128`	`132`	`}`
`129`	`133`
	`134`	`+/** A class representing methods that provides access to an output stream or writer. */`
`130`	`135`	`class ServletWriterSource extends MethodAccess {`
`131`	`136`	`ServletWriterSource() {`
`132`	`137`	`this.getMethod() instanceof ServletResponseGetWriterMethod`