From 5068453f689cfd789cad149c12c7fa03d36df353 Mon Sep 17 00:00:00 2001 From: Alexey Menshutin Date: Wed, 6 Mar 2024 14:15:32 +0300 Subject: [PATCH] Add documentation for taint configuration (#223) --- jacodb-taint-configuration/README.md | 3 ++ .../jacodb/taint/configuration/Position.kt | 24 +++++++++++ .../jacodb/taint/configuration/TaintAction.kt | 19 +++++++++ .../taint/configuration/TaintCondition.kt | 42 +++++++++++++++++++ 4 files changed, 88 insertions(+) create mode 100644 jacodb-taint-configuration/README.md diff --git a/jacodb-taint-configuration/README.md b/jacodb-taint-configuration/README.md new file mode 100644 index 000000000..5a16c1d75 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/Position.kt b/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/Position.kt index b5b625608..7fe6c2f8a 100644 --- a/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/Position.kt +++ b/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/Position.kt @@ -23,31 +23,55 @@ fun interface PositionResolver { 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 { diff --git a/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/TaintAction.kt b/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/TaintAction.kt index 9b9506958..6f65ce9cd 100644 --- a/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/TaintAction.kt +++ b/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 accept(visitor: TaintActionVisitor): 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 accept(visitor: TaintActionVisitor): 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 accept(visitor: TaintActionVisitor): 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 accept(visitor: TaintActionVisitor): R = visitor.visit(this) } +/** + * Removes a particular [mark] from the [position]. + */ @Serializable @SerialName("RemoveMark") data class RemoveMark( diff --git a/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/TaintCondition.kt b/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/TaintCondition.kt index e037856de..0d2aec523 100644 --- a/jacodb-taint-configuration/src/main/kotlin/org/jacodb/taint/configuration/TaintCondition.kt +++ b/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 accept(conditionVisitor: ConditionVisitor): R = conditionVisitor.visit(this) } +/** + * A conjunction of the [args]. + */ @Serializable @SerialName("And") data class And( @@ -87,6 +96,9 @@ data class And( override fun accept(conditionVisitor: ConditionVisitor): R = conditionVisitor.visit(this) } +/** + * A disjunction of the [args]. + */ @Serializable @SerialName("Or") data class Or( @@ -95,6 +107,10 @@ data class Or( override fun accept(conditionVisitor: ConditionVisitor): 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 accept(conditionVisitor: ConditionVisitor): 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 accept(conditionVisitor: ConditionVisitor): 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 accept(conditionVisitor: ConditionVisitor): 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 accept(conditionVisitor: ConditionVisitor): 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 accept(conditionVisitor: ConditionVisitor): 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 accept(conditionVisitor: ConditionVisitor): 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 accept(conditionVisitor: ConditionVisitor): 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 accept(conditionVisitor: ConditionVisitor): R = conditionVisitor.visit(this) } +/** + * A condition that a value at the [position] matches exactly with the [type]. + */ @Serializable @SerialName("TypeMatches") data class TypeMatches(