From 12c443003c8bcdd3ba379fc06880e9a455136e35 Mon Sep 17 00:00:00 2001 From: Nikita Stroganov Date: Tue, 31 Jan 2023 11:28:24 +0300 Subject: [PATCH 01/11] Add the first version of taint analysis config format --- docs/TaintAnalysis.md | 63 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/TaintAnalysis.md diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md new file mode 100644 index 0000000000..f5d9b013d9 --- /dev/null +++ b/docs/TaintAnalysis.md @@ -0,0 +1,63 @@ +# Taint Analysis + +## Configuration + +- Each method description can contain the key `conditions` (optionally). +- Keys like `add-to` or `remove-from` may contain a list of values or only one value. + Possible values: + - this + - arg1 + - arg2 + - ... + - return +- Fully qualified name of the method may be determined in parts. + +**Example:** + +```YAML +sources: + com: + abc.method1: + add-to: [this, return] + marks: nullable + bca.method2: + add-to: return + marks: [sensitive-data, sql-injection] + +passes: + com.abc.method2: + conditions: + this: "some string" # value: bool, int, float or string + arg0: + not: "" + arg1: # type + arg2: [1, 2, 3] # arg2 should be equal to one of: 1, 2 or 3 + arg3: + not: [4, 5, 6] + arg4: [, ] + arg5: + not: [, ] + return: false + get-from: [this, arg1, arg3] + add-to: [return] + marks: sensitive-data + +cleaners: + java.lang.String.isEmpty: + conditions: + return: true + remove-from: this + marks: [sensitive-data, sql-injection] + com.company.method8: + remove-from: [arg1, return] + marks: nullable + +sinks: + org.example: + log: + check-in: arg1 + marks: [sensitive-data, nullable] + sink0: + check-in: [arg1, arg3] + marks: nullable +``` \ No newline at end of file From 09d84ecc37e7f695d0a5f8debf60aa5576c01784 Mon Sep 17 00:00:00 2001 From: Nikita Stroganov Date: Tue, 31 Jan 2023 11:36:49 +0300 Subject: [PATCH 02/11] Add info for marks key --- docs/TaintAnalysis.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index f5d9b013d9..740aa83dee 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -3,13 +3,14 @@ ## Configuration - Each method description can contain the key `conditions` (optionally). -- Keys like `add-to` or `remove-from` may contain a list of values or only one value. +- Keys like `add-to` or `remove-from` can contain a list of values or only one value. Possible values: - this - arg1 - arg2 - ... - return +- The `marks` key can also contain a list of marks or only one mark. - Fully qualified name of the method may be determined in parts. **Example:** From f6433bc4e0bb13f5845178bfe6f991239b734654 Mon Sep 17 00:00:00 2001 From: Nikita Stroganov Date: Tue, 31 Jan 2023 15:07:28 +0300 Subject: [PATCH 03/11] small fixes --- docs/TaintAnalysis.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index 740aa83dee..d369a33c84 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -20,7 +20,7 @@ sources: com: abc.method1: add-to: [this, return] - marks: nullable + marks: xss bca.method2: add-to: return marks: [sensitive-data, sql-injection] @@ -51,14 +51,14 @@ cleaners: marks: [sensitive-data, sql-injection] com.company.method8: remove-from: [arg1, return] - marks: nullable + marks: xss sinks: org.example: log: - check-in: arg1 - marks: [sensitive-data, nullable] + check: arg1 + marks: sensitive-data sink0: - check-in: [arg1, arg3] - marks: nullable + check: [arg1, arg3] + marks: [sql-injection, xss] ``` \ No newline at end of file From 19a756698fd50db0478a7a30b9d01a9ae9c36a25 Mon Sep 17 00:00:00 2001 From: Nikita Stroganov Date: Tue, 31 Jan 2023 17:29:05 +0300 Subject: [PATCH 04/11] Rewrite TaintAnalysis doc --- docs/TaintAnalysis.md | 211 ++++++++++++++++++++++++++++++++---------- 1 file changed, 163 insertions(+), 48 deletions(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index d369a33c84..6c13a468d9 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -2,63 +2,178 @@ ## Configuration -- Each method description can contain the key `conditions` (optionally). -- Keys like `add-to` or `remove-from` can contain a list of values or only one value. - Possible values: - - this - - arg1 - - arg2 - - ... - - return -- The `marks` key can also contain a list of marks or only one mark. -- Fully qualified name of the method may be determined in parts. +### Basic + +- There are 4 sections: sources, passes, cleaners and sinks. Each of them contains a list of methods descriptions (rules). Fully qualified name of the method can be written in one line, or it can be defined by nested parts — first the package names, then the class name, and finally the method name. Note that, regular expressions in names are not supported. +- Each rule can contain a method signature — a list of argument types (in compile-time): `signature: [, _, ]` + - name of the type is written in `<>`. + - `_` means any type. +- Also, the rule can contain runtime conditions that must be met for this rule to trigger. Here you can set specific values of method arguments or their runtime types. More details about the `conditions` key below. +- The `signature` and `conditions` fields are optional. If you do not specify them, the rule will be triggered on any method call. +- Если для одного вызова метода выполняется несколько правил, они будут применены все в некотором порядке. +- If several rules are suitable for one method call, they will all be applied in some kind of order. + +### Sources + +- The `add-to` field specifies which objects the `marks` will be added to. You can specify only one value here or a whole list. Possible values: + - `this` + - `arg1` + - `arg2` + - ... + - `return` +- The `marks` field specifies which `marks` to add to objects from `add-to`. You can also specify only one mark here or a whole list. **Example:** -```YAML +```yaml sources: - com: - abc.method1: - add-to: [this, return] - marks: xss - bca.method2: - add-to: return - marks: [sensitive-data, sql-injection] + - com: + - abc: + - method1: + signature: [ _, _, ] + add-to: return + marks: xss + - method1: + signature: [ , _, ] + add-to: [ this, return ] + marks: sql-injection + - bca.method2: + add-to: return + marks: [ sensitive-data, xss ] + - org.example.method3: + add-to: [ this, arg1, arg3 ] + marks: sensitive-data +``` +### Passes + +- The `get-from` field specifies the sources of `marks`. +- The `add-to` field specifies which objects to add a mark to, if any element from `get-from` has one. +- The `marks` field specifies the actual marks that can passed from one object to another. +- For all the keys listed above, there can be only one value or a whole list of values. Also, it's true for similar keys in the sections below. + +**Example:** + +```yaml passes: - com.abc.method2: - conditions: - this: "some string" # value: bool, int, float or string - arg0: - not: "" - arg1: # type - arg2: [1, 2, 3] # arg2 should be equal to one of: 1, 2 or 3 - arg3: - not: [4, 5, 6] - arg4: [, ] - arg5: - not: [, ] - return: false - get-from: [this, arg1, arg3] - add-to: [return] - marks: sensitive-data + - com.abc.method2: + get-from: [ this, arg1, arg3 ] + add-to: [ arg2, return ] + marks: sensitive-data +``` +### Cleaners + +- The `remove-from` field specifies which objects to remove `marks` from. +- The `marks` field specifies the marks to be removed. + +**Example:** + +```yaml cleaners: - java.lang.String.isEmpty: - conditions: - return: true - remove-from: this - marks: [sensitive-data, sql-injection] - com.company.method8: - remove-from: [arg1, return] - marks: xss + - com.example.pack.method7: + remove-from: this + marks: [ sensitive-data, sql-injection ] +``` + +### Sinks +- The `check` field specifies which objects will be checked for `marks`. +- When one of the `marks` is found in one of the objects from the `check`, the analysis will report the problem found. + +**Example:** + +```yaml sinks: - org.example: - log: - check: arg1 + - org.example: + - log: + check: arg1 + marks: sensitive-data + - method17: + check: [ arg1, arg3 ] + marks: [ sql-injection, xss ] +``` + +### Conditions + +- The `conditions` field specifies runtime conditions for arguments (`arg1`, `arg2`, ...). Conditions can also be specified for `this` and `return` (if that makes sense). +- The rule is triggered if all the specified conditions are met. +- The condition can check a specific value or runtime type. +- Values can be set for the following types: boolean, int, float or string. +- The full name of the type must be specified in triangular brackets `<>`. + +**Example:** + +```yaml +conditions: + this: # this should be java.lang.String + arg1: "test" # the first argument should be equal to "test" + arg2: 227 + arg3: 227.001 + return: true # return value should be equal to `true` +``` + +- Values and types can be negated using the `not` key, as well as combined using lists (`or` semantics). +- Nesting is allowed. + +**Example:** + +```yaml +conditions: + this: [ "in", "out" ] # this should be equal to one of: "in" or "out" + arg1: [ , ] # arg1 should be int or float + arg2: { not: 0 } # arg2 should not be equal to 0 + arg3: + not: [ 1, 2, 3, 5, 8 ] # should not be equal to any of the listed numbers + arg4: [ "", { not: } ] # should be empty string or int +``` + +### Overall example + +```yaml +sources: + - com: + - abc: + - method1: + signature: [ _, _, ] + add-to: return + marks: xss + - method1: + signature: [ , _, ] + add-to: [ this, return ] + marks: sql-injection + - bca.method2: + conditions: + this: + not: "in" + add-to: return + marks: [ sensitive-data, xss ] + +passes: + - com.abc.method2: + get-from: [ this, arg1, arg3 ] + add-to: return marks: sensitive-data - sink0: - check: [arg1, arg3] - marks: [sql-injection, xss] + - org.example.method3: + conditions: + arg1: { not: "" } + get-from: arg1 + add-to: [ this, return ] + marks: sql-injection + +cleaners: + - com.example.pack.method7: + conditions: + return: true + remove-from: this + marks: [ sensitive-data, sql-injection ] + +sinks: + - org.example: + - log: + check: arg1 + marks: sensitive-data + - method17: + check: [ arg1, arg3 ] + marks: [ sql-injection, xss ] ``` \ No newline at end of file From a038228867e69e58545c2c30d15920f78c6d6007 Mon Sep 17 00:00:00 2001 From: Nikita Stroganov Date: Tue, 31 Jan 2023 17:41:02 +0300 Subject: [PATCH 05/11] Fix typos in basic section --- docs/TaintAnalysis.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index 6c13a468d9..af1f355c4a 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -4,13 +4,12 @@ ### Basic -- There are 4 sections: sources, passes, cleaners and sinks. Each of them contains a list of methods descriptions (rules). Fully qualified name of the method can be written in one line, or it can be defined by nested parts — first the package names, then the class name, and finally the method name. Note that, regular expressions in names are not supported. -- Each rule can contain a method signature — a list of argument types (in compile-time): `signature: [, _, ]` +- There are 4 sections: sources, passes, cleaners and sinks. Each of them contains a list of methods descriptions (rules). Fully qualified method names can be written in one line, or it can be defined by nested parts — first the package names, then the class name, and finally the method name. Note that regular expressions in names are not supported. +- Each rule can contain a method signature — a list of argument types (in compile-time): `signature: [ , _, ]` - name of the type is written in `<>`. - `_` means any type. -- Also, the rule can contain runtime conditions that must be met for this rule to trigger. Here you can set specific values of method arguments or their runtime types. More details about the `conditions` key below. -- The `signature` and `conditions` fields are optional. If you do not specify them, the rule will be triggered on any method call. -- Если для одного вызова метода выполняется несколько правил, они будут применены все в некотором порядке. +- Also, the rule can contain runtime conditions that must be met for triggering this rule. Here you can set specific values of method arguments or their runtime types. More detailed information about the `conditions` is given below. +- The `signature` and `conditions` fields are optional. If you do not specify them, the rule will be triggered on any call of the method. - If several rules are suitable for one method call, they will all be applied in some kind of order. ### Sources From bbb064fb56cfd073ba885ba347def647dbbee7d3 Mon Sep 17 00:00:00 2001 From: Nikita Stroganov Date: Tue, 31 Jan 2023 17:53:22 +0300 Subject: [PATCH 06/11] Fix other typos --- docs/TaintAnalysis.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index af1f355c4a..4e8289604a 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -14,7 +14,7 @@ ### Sources -- The `add-to` field specifies which objects the `marks` will be added to. You can specify only one value here or a whole list. Possible values: +- The `add-to` field specifies which objects will be marked. You can specify only one value here or a whole list. Possible values: - `this` - `arg1` - `arg2` @@ -47,7 +47,7 @@ sources: ### Passes - The `get-from` field specifies the sources of `marks`. -- The `add-to` field specifies which objects to add a mark to, if any element from `get-from` has one. +- The `add-to` field specifies which objects will be marked, if any element from `get-from` has any mark. - The `marks` field specifies the actual marks that can passed from one object to another. - For all the keys listed above, there can be only one value or a whole list of values. Also, it's true for similar keys in the sections below. @@ -95,7 +95,7 @@ sinks: ### Conditions -- The `conditions` field specifies runtime conditions for arguments (`arg1`, `arg2`, ...). Conditions can also be specified for `this` and `return` (if that makes sense). +- The `conditions` field specifies runtime conditions for arguments (`arg1`, `arg2`, ...). Conditions can also be specified for `this` and `return` (if it makes sense). - The rule is triggered if all the specified conditions are met. - The condition can check a specific value or runtime type. - Values can be set for the following types: boolean, int, float or string. @@ -107,8 +107,8 @@ sinks: conditions: this: # this should be java.lang.String arg1: "test" # the first argument should be equal to "test" - arg2: 227 - arg3: 227.001 + arg2: 227 # int + arg3: 227.001 # float return: true # return value should be equal to `true` ``` @@ -124,7 +124,7 @@ conditions: arg2: { not: 0 } # arg2 should not be equal to 0 arg3: not: [ 1, 2, 3, 5, 8 ] # should not be equal to any of the listed numbers - arg4: [ "", { not: } ] # should be empty string or int + arg4: [ "", { not: } ] # should be an empty string or not a string at all ``` ### Overall example From 3d4f34284a4658de24bb27a0ccf930e816eee6bf Mon Sep 17 00:00:00 2001 From: Nikita Stroganov Date: Wed, 1 Feb 2023 13:36:34 +0300 Subject: [PATCH 07/11] Add usage examples --- docs/TaintAnalysis.md | 72 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index 4e8289604a..cbc766ebb3 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -5,7 +5,7 @@ ### Basic - There are 4 sections: sources, passes, cleaners and sinks. Each of them contains a list of methods descriptions (rules). Fully qualified method names can be written in one line, or it can be defined by nested parts — first the package names, then the class name, and finally the method name. Note that regular expressions in names are not supported. -- Each rule can contain a method signature — a list of argument types (in compile-time): `signature: [ , _, ]` +- Each rule can contain a method signature — a list of argument types (at compile-time): `signature: [ , _, ]` - name of the type is written in `<>`. - `_` means any type. - Also, the rule can contain runtime conditions that must be met for triggering this rule. Here you can set specific values of method arguments or their runtime types. More detailed information about the `conditions` is given below. @@ -175,4 +175,72 @@ sinks: - method17: check: [ arg1, arg3 ] marks: [ sql-injection, xss ] -``` \ No newline at end of file +``` + +## Usage examples + +- `java.lang.System.getenv` is a source of the mark "environment". But there are two overloads of this method: with one string parameter and no parameters at all. We want to describe only the first overload: + + ```yaml + sources: + - java.lang.System.getenv: + signature: [ ] + add-to: return + marks: environment + ``` + +- `java.lang.String.concat` is a pass-through only if `this` is marked and not equal to `""` or if `arg1` is marked and not equal to `""`: + + ```yaml + passes: + - java.lang.String: + - concat: + conditions: + this: { not: "" } + get-from: this + add-to: return + marks: sensitive-data + - concat: + conditions: + arg1: { not: "" } + get-from: arg1 + add-to: return + marks: sensitive-data + ``` + +- `java.lang.String.isEmpty` is a cleaner only if it returns `true`: + + ```yaml + cleaners: + - java.lang.String.isEmpty: + conditions: + return: true + remove-from: this + marks: [ sql-injection, xss ] + ``` + +- Suppose that the method `org.example.util.unsafe` is a sink for the mark "environment" if the second argument is an `Integer` and equal to zero: + + ```yaml + sinks: + - org.example.util.unsafe: + signature: [ _, ] + conditions: + arg2: 0 + check: arg2 + marks: environment + ``` + + The configuration above checks the type at compile-time, but sometimes we want to check the type at runtime: + + ```yaml + sinks: + - org.example.util.unsafe: + conditions: + arg2: + not: [ { not: 0 }, { not: } ] + check: arg2 + marks: environment + ``` + + Perhaps explicit `and` for `conditions` will be added in the future. From 023cc3a341c1f9fdf7c51623f8b400fd56087581 Mon Sep 17 00:00:00 2001 From: Nikita Stroganov Date: Thu, 2 Feb 2023 16:24:26 +0300 Subject: [PATCH 08/11] Add null condition example --- docs/TaintAnalysis.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index cbc766ebb3..a5c2752a62 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -109,6 +109,7 @@ conditions: arg1: "test" # the first argument should be equal to "test" arg2: 227 # int arg3: 227.001 # float + arg4: null # null return: true # return value should be equal to `true` ``` From 9caaeaf9395de571c084e27ddc7e2fae4c4fd354 Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Fri, 3 Feb 2023 13:13:56 +0300 Subject: [PATCH 09/11] TaintAnalysis.md reviewed for linguistic and formatting issues --- docs/TaintAnalysis.md | 131 ++++++++++++++++++++++++++++-------------- 1 file changed, 88 insertions(+), 43 deletions(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index a5c2752a62..30ca725724 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -1,26 +1,42 @@ -# Taint Analysis +# Taint analysis ## Configuration -### Basic +There are four _rule types_: sources, passes, cleaners and sinks. -- There are 4 sections: sources, passes, cleaners and sinks. Each of them contains a list of methods descriptions (rules). Fully qualified method names can be written in one line, or it can be defined by nested parts — first the package names, then the class name, and finally the method name. Note that regular expressions in names are not supported. -- Each rule can contain a method signature — a list of argument types (at compile-time): `signature: [ , _, ]` - - name of the type is written in `<>`. - - `_` means any type. -- Also, the rule can contain runtime conditions that must be met for triggering this rule. Here you can set specific values of method arguments or their runtime types. More detailed information about the `conditions` is given below. -- The `signature` and `conditions` fields are optional. If you do not specify them, the rule will be triggered on any call of the method. -- If several rules are suitable for one method call, they will all be applied in some kind of order. +Each rule type contains +* a method name, +* a method description, +* a method signature (optional), +* runtime conditions (optional). -### Sources +### Method name -- The `add-to` field specifies which objects will be marked. You can specify only one value here or a whole list. Possible values: - - `this` - - `arg1` - - `arg2` - - ... - - `return` -- The `marks` field specifies which `marks` to add to objects from `add-to`. You can also specify only one mark here or a whole list. +Fully qualified _method names_ can be written in one line. + +One can also define a full _method name_ using nested structure: the package name is specified first, +then the class name appears, and finally there is the method name itself. + +Note that regular expressions in names are not supported. + +### Method description + +Method description constitutes the essence of a rule. +Here are method descriptions for the rules of each type: sources, passes, cleaners and sinks. + +#### Sources + +The `add-to` field specifies the objects to be marked. +You can specify only one value here or a whole list. + +Possible values are: +* `this` +* `arg1` +* `arg2` +* ... +* `return` + +The `marks` field specifies the `marks` that should be added to the objects from the `add-to` list. You can also specify only one mark here or a whole list. **Example:** @@ -44,12 +60,16 @@ sources: marks: sensitive-data ``` -### Passes +#### Passes + +The `get-from` field specifies the sources of `marks`. + +The `add-to` field specifies the objects that will be marked if any element from `get-from` has any mark. -- The `get-from` field specifies the sources of `marks`. -- The `add-to` field specifies which objects will be marked, if any element from `get-from` has any mark. -- The `marks` field specifies the actual marks that can passed from one object to another. -- For all the keys listed above, there can be only one value or a whole list of values. Also, it's true for similar keys in the sections below. +The `marks` field specifies the actual marks that can be passed from one object to another. + +For all the keys listed above, there can be only one value or a whole list of values. +This is also true for similar keys in the sections below. **Example:** @@ -61,10 +81,11 @@ passes: marks: sensitive-data ``` -### Cleaners +#### Cleaners + +The `remove-from` field specifies the objects the `marks` should be removed from. -- The `remove-from` field specifies which objects to remove `marks` from. -- The `marks` field specifies the marks to be removed. +The `marks` field specifies the marks to be removed. **Example:** @@ -75,10 +96,11 @@ cleaners: marks: [ sensitive-data, sql-injection ] ``` -### Sinks +#### Sinks + +The `check` field specifies the objects that will be checked for `marks`. -- The `check` field specifies which objects will be checked for `marks`. -- When one of the `marks` is found in one of the objects from the `check`, the analysis will report the problem found. +When one of the `marks` is found in one of the objects from the `check`, the analysis will report the problem found. **Example:** @@ -93,13 +115,35 @@ sinks: marks: [ sql-injection, xss ] ``` -### Conditions +### Method signature (optional) -- The `conditions` field specifies runtime conditions for arguments (`arg1`, `arg2`, ...). Conditions can also be specified for `this` and `return` (if it makes sense). -- The rule is triggered if all the specified conditions are met. -- The condition can check a specific value or runtime type. -- Values can be set for the following types: boolean, int, float or string. -- The full name of the type must be specified in triangular brackets `<>`. +Each rule can contain a method `signature` — a list of _argument types_ (at compile time): + +`signature: [ , _, ]` + +Please note that +- the type name is written in `<>`, +- `_` means any type. + +### Runtime conditions (optional) + +The rule can also contain _runtime conditions_ that must be met to trigger this rule. + +For check, you can set: +* the specific values of method arguments +* or their runtime types. + +Values can be set for the following types: `boolean`, `int`, `float` or `string`. + +The full type name must be specified in the angle brackets `<>`. + +If you do not specify `conditions`, the rule will be triggered by any call of the method. + +If several rules are suitable for one method call, they will all be applied in some kind of order. + +The `conditions` field specifies runtime conditions for arguments (`arg1`, `arg2`, ...). Conditions can also be specified for `this` and `return` (if it makes sense). + +The rule is triggered if all the specified conditions are met. **Example:** @@ -113,14 +157,15 @@ conditions: return: true # return value should be equal to `true` ``` -- Values and types can be negated using the `not` key, as well as combined using lists (`or` semantics). -- Nesting is allowed. +Values and types can be negated using the `not` key, as well as combined using lists (`or` semantics). + +Nesting is allowed. **Example:** ```yaml conditions: - this: [ "in", "out" ] # this should be equal to one of: "in" or "out" + this: [ "in", "out" ] # this should be equal to either "in" or "out" arg1: [ , ] # arg1 should be int or float arg2: { not: 0 } # arg2 should not be equal to 0 arg3: @@ -180,7 +225,7 @@ sinks: ## Usage examples -- `java.lang.System.getenv` is a source of the mark "environment". But there are two overloads of this method: with one string parameter and no parameters at all. We want to describe only the first overload: +`java.lang.System.getenv` is a source of the "environment" mark. There are two overloads of this method: with one string parameter and no parameters at all. We want to describe only the first overload: ```yaml sources: @@ -190,7 +235,7 @@ sinks: marks: environment ``` -- `java.lang.String.concat` is a pass-through only if `this` is marked and not equal to `""` or if `arg1` is marked and not equal to `""`: +`java.lang.String.concat` is a pass-through only if `this` is marked and not equal to `""`, or if `arg1` is marked and not equal to `""`: ```yaml passes: @@ -209,7 +254,7 @@ sinks: marks: sensitive-data ``` -- `java.lang.String.isEmpty` is a cleaner only if it returns `true`: +`java.lang.String.isEmpty` is a cleaner only if it returns `true`: ```yaml cleaners: @@ -220,7 +265,7 @@ sinks: marks: [ sql-injection, xss ] ``` -- Suppose that the method `org.example.util.unsafe` is a sink for the mark "environment" if the second argument is an `Integer` and equal to zero: +Suppose that the `org.example.util.unsafe` method is a sink for the "environment" mark if the second argument is an `Integer` and equal to zero: ```yaml sinks: @@ -232,7 +277,7 @@ sinks: marks: environment ``` - The configuration above checks the type at compile-time, but sometimes we want to check the type at runtime: +The configuration above checks the type at compile-time, but sometimes we want to check the type at runtime: ```yaml sinks: @@ -244,4 +289,4 @@ sinks: marks: environment ``` - Perhaps explicit `and` for `conditions` will be added in the future. +Perhaps explicit `and` for `conditions` will be added in the future. From 4a4d1f1dd7cb3ee05dac3708e1a1a7cca6b0506a Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Fri, 3 Feb 2023 13:41:38 +0300 Subject: [PATCH 10/11] Doc structure revised --- docs/TaintAnalysis.md | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index 30ca725724..c2894784a1 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -4,11 +4,9 @@ There are four _rule types_: sources, passes, cleaners and sinks. -Each rule type contains +The rule of each type contains * a method name, -* a method description, -* a method signature (optional), -* runtime conditions (optional). +* a method description. ### Method name @@ -38,7 +36,7 @@ Possible values are: The `marks` field specifies the `marks` that should be added to the objects from the `add-to` list. You can also specify only one mark here or a whole list. -**Example:** +Example: ```yaml sources: @@ -71,7 +69,7 @@ The `marks` field specifies the actual marks that can be passed from one object For all the keys listed above, there can be only one value or a whole list of values. This is also true for similar keys in the sections below. -**Example:** +Example: ```yaml passes: @@ -87,7 +85,7 @@ The `remove-from` field specifies the objects the `marks` should be removed from The `marks` field specifies the marks to be removed. -**Example:** +Example: ```yaml cleaners: @@ -102,7 +100,7 @@ The `check` field specifies the objects that will be checked for `marks`. When one of the `marks` is found in one of the objects from the `check`, the analysis will report the problem found. -**Example:** +Example: ```yaml sinks: @@ -115,9 +113,11 @@ sinks: marks: [ sql-injection, xss ] ``` -### Method signature (optional) +For all the rule types, method descriptions can optionally contain +* a method signature, +* runtime conditions. -Each rule can contain a method `signature` — a list of _argument types_ (at compile time): +Method `signature` (optional) is a list of _argument types_ (at compile time): `signature: [ , _, ]` @@ -125,11 +125,9 @@ Please note that - the type name is written in `<>`, - `_` means any type. -### Runtime conditions (optional) +Runtime `conditions` (optional) are conditions that must be met to trigger this rule. -The rule can also contain _runtime conditions_ that must be met to trigger this rule. - -For check, you can set: +To check the conformity to conditions, you can set: * the specific values of method arguments * or their runtime types. @@ -145,7 +143,7 @@ The `conditions` field specifies runtime conditions for arguments (`arg1`, `arg2 The rule is triggered if all the specified conditions are met. -**Example:** +Example: ```yaml conditions: @@ -161,7 +159,7 @@ Values and types can be negated using the `not` key, as well as combined using l Nesting is allowed. -**Example:** +Example: ```yaml conditions: From 575289f0b92243fd8055c2da2ef352d30918a7ee Mon Sep 17 00:00:00 2001 From: Olga Naumenko <64418523+olganaumenko@users.noreply.github.com> Date: Fri, 3 Feb 2023 14:10:54 +0300 Subject: [PATCH 11/11] Minor structure revision --- docs/TaintAnalysis.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/TaintAnalysis.md b/docs/TaintAnalysis.md index c2894784a1..2e098c21f2 100644 --- a/docs/TaintAnalysis.md +++ b/docs/TaintAnalysis.md @@ -1,12 +1,14 @@ # Taint analysis +[//]: # (TODO) + ## Configuration There are four _rule types_: sources, passes, cleaners and sinks. The rule of each type contains * a method name, -* a method description. +* a method description ### Method name @@ -112,11 +114,14 @@ sinks: check: [ arg1, arg3 ] marks: [ sql-injection, xss ] ``` +*** For all the rule types, method descriptions can optionally contain * a method signature, * runtime conditions. +**Signature** + Method `signature` (optional) is a list of _argument types_ (at compile time): `signature: [ , _, ]` @@ -125,6 +130,8 @@ Please note that - the type name is written in `<>`, - `_` means any type. +**Conditions** + Runtime `conditions` (optional) are conditions that must be met to trigger this rule. To check the conformity to conditions, you can set: