Add documentation for taint configuration (#223)

jacodb-taint-configuration/README.md

@@ -0,0 +1,3 @@
+# Module jacodb-configuration
+
+A module that contains a format suitable for taint configuration of static analyses. 

jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/Position.kt

@@ -23,31 +23,55 @@ fun interface PositionResolver<out R> {
     fun resolve(position: Position): R
 }
 
+/**
+ * A representation of a position of tainted data.
+ */
 @Serializable
 sealed interface Position
 
+/**
+ * Represents an argument of a method call.
+ * Numeration starts from zero, `this` parameter is not included.
+ *
+ * For instance, `obj.foo(a, b)` -> `a := Argument(0)`, `b := Argument(1)`
+ */
 @Serializable
 @SerialName("Argument")
 data class Argument(@SerialName("number") val index: Int) : Position
 
+/**
+ * Represents any argument of a method call except `this` instance,
+ * This is a short form for a set of [Argument]s with all indices of the method parameters.
+ */
 @Serializable
 @SerialName("AnyArgument")
 object AnyArgument : Position {
     override fun toString(): String = javaClass.simpleName
 }
 
+/**
+ * Represents `this` argument of a method call.
+ */
 @Serializable
 @SerialName("This")
 object This : Position {
     override fun toString(): String = javaClass.simpleName
 }
 
+/**
+ * Represents the resulting value of a method call.
+ * It is for regularly returned objects only, and it is not suitable for thrown exceptions.
+ */
 @Serializable
 @SerialName("Result")
 object Result : Position {
     override fun toString(): String = javaClass.simpleName
 }
 
+/**
+ * Represents any element of the collection (string, array, list, etc.),
+ * returned as a result from a method call.
+ */
 @Serializable
 @SerialName("ResultAnyElement")
 object ResultAnyElement : Position {

jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/TaintAction.kt

@@ -46,6 +46,13 @@ val actionModule = SerializersModule {
 
 // TODO add marks for aliases (if you pass an object and return it from the function)
 
+/**
+ * Copies all the marks from the [from] object to the [to].
+ * As a result, all marks from the initial object will be copied into the target object.
+ * If some marks were present only in the [to] object, they remain unchanged.
+ *
+ * Behaviour should be the same as if [CopyMark] is applied to every existing mark.
+ */
 @Serializable
 @SerialName("CopyAllMarks")
 data class CopyAllMarks(
@@ -55,6 +62,9 @@ data class CopyAllMarks(
     override fun <R> accept(visitor: TaintActionVisitor<R>): R = visitor.visit(this)
 }
 
+/**
+ * Adds the [mark] to the [to] object if it is present in the [from] object.
+ */
 @Serializable
 @SerialName("CopyMark")
 data class CopyMark(
@@ -65,6 +75,9 @@ data class CopyMark(
     override fun <R> accept(visitor: TaintActionVisitor<R>): R = visitor.visit(this)
 }
 
+/**
+ * Assigns the [mark] to the [position].
+ */
 @Serializable
 @SerialName("AssignMark")
 data class AssignMark(
@@ -74,6 +87,9 @@ data class AssignMark(
     override fun <R> accept(visitor: TaintActionVisitor<R>): R = visitor.visit(this)
 }
 
+/**
+ * Removes all the marks from the [position].
+ */
 @Serializable
 @SerialName("RemoveAllMarks")
 data class RemoveAllMarks(
@@ -82,6 +98,9 @@ data class RemoveAllMarks(
     override fun <R> accept(visitor: TaintActionVisitor<R>): R = visitor.visit(this)
 }
 
+/**
+ * Removes a particular [mark] from the [position].
+ */
 @Serializable
 @SerialName("RemoveMark")
 data class RemoveMark(

jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/TaintCondition.kt

@@ -63,6 +63,9 @@ val conditionModule = SerializersModule {
     }
 }
 
+/**
+ * A constant true condition.
+ */
 @Serializable
 @SerialName("ConstantTrue")
 object ConstantTrue : Condition {
@@ -71,6 +74,9 @@ object ConstantTrue : Condition {
     override fun toString(): String = javaClass.simpleName
 }
 
+/**
+ * A negation of the [arg].
+ */
 @Serializable
 @SerialName("Not")
 data class Not(
@@ -79,6 +85,9 @@ data class Not(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A conjunction of the [args].
+ */
 @Serializable
 @SerialName("And")
 data class And(
@@ -87,6 +96,9 @@ data class And(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A disjunction of the [args].
+ */
 @Serializable
 @SerialName("Or")
 data class Or(
@@ -95,6 +107,10 @@ data class Or(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that an object at the [position] is a constant value,
+ * not an environment variable or a method parameter.
+ */
 @Serializable
 @SerialName("IsConstant")
 data class IsConstant(
@@ -103,6 +119,9 @@ data class IsConstant(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that an object at the [position] matches with the [typeMatcher].
+ */
 @Serializable
 @SerialName("IsType")
 data class IsType(
@@ -112,6 +131,9 @@ data class IsType(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that an object at the [position] contains an annotation matching with the [typeMatcher].
+ */
 @Serializable
 @SerialName("AnnotationType")
 data class AnnotationType(
@@ -121,6 +143,9 @@ data class AnnotationType(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that a value at the [position] is equal to a [value].
+ */
 @Serializable
 @SerialName("ConstantEq")
 data class ConstantEq(
@@ -130,6 +155,10 @@ data class ConstantEq(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that a value at the [position] is less than a [value].
+ * The meaning of `less` is specific for each type of the [ConstantValue].
+ */
 @Serializable
 @SerialName("ConstantLt")
 data class ConstantLt(
@@ -139,6 +168,10 @@ data class ConstantLt(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that a value at the [position] is greater than a [value].
+ * The meaning of `greater` is specific for each type of the [ConstantValue].
+ */
 @Serializable
 @SerialName("ConstantGt")
 data class ConstantGt(
@@ -148,6 +181,9 @@ data class ConstantGt(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that a value at the [position] is matching with the [pattern].
+ */
 @Serializable
 @SerialName("ConstantMatches")
 data class ConstantMatches(
@@ -166,6 +202,9 @@ data class SourceFunctionMatches(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that a value at the [position] contains the [mark].
+ */
 @Serializable
 @SerialName("ContainsMark")
 data class ContainsMark(
@@ -175,6 +214,9 @@ data class ContainsMark(
     override fun <R> accept(conditionVisitor: ConditionVisitor<R>): R = conditionVisitor.visit(this)
 }
 
+/**
+ * A condition that a value at the [position] matches exactly with the [type].
+ */
 @Serializable
 @SerialName("TypeMatches")
 data class TypeMatches(