Ifds unit management refactoring #130 (#161)

Author: volivan239

jacodb-analysis/README.md

@@ -17,8 +17,9 @@ The analysis entry point is the [runAnalysis] method. To call it, you have to pr
 * `graph` — an application graph that is used for analysis. To obtain this graph, one should call the [newApplicationGraphForAnalysis] method.
 * `unitResolver` — an object that groups methods into units. Choose one from `UnitResolversLibrary`.
 Note that, in general, larger units mean more precise but also more resource-consuming analysis.
-* `ifdsUnitRunner` — an [IfdsUnitRunner] instance, which is used to analyze each unit. This is what defines concrete analysis.
-  Ready-to-use runners are located in `RunnersLibrary`.
+* `ifdsUnitRunnerFactory` — an [IfdsUnitRunnerFactory] instance, that can create runners. Runners are used to analyze each unit. 
+So this factory is what define concrete analysis.
+  Ready-to-use runner factories are located in `RunnersLibrary`.
 * `methods` — a list of methods to analyze.
 
 For example, to detect the unused variables in the given `analyzedClass` methods, you may run the following code
@@ -31,9 +32,9 @@ val applicationGraph = runBlocking {
 
 val methodsToAnalyze = analyzedClass.declaredMethods
 val unitResolver = MethodUnitResolver
-val runner = UnusedVariableRunner
+val runnerFactory = UnusedVariableRunnerFactory
 
-runAnalysis(applicationGraph, unitResolver, runner, methodsToAnalyze)
+runAnalysis(applicationGraph, unitResolver, runnerFactory, methodsToAnalyze)
 ```
 
 ## Implemented runners
@@ -47,29 +48,28 @@ By now, the following runners are implemented:
 
 ## Implementing your own analysis
 
-To implement a simple one-pass analysis, use [IfdsBaseUnitRunner].
+To implement a simple one-pass analysis, use [IfdsBaseUnitRunnerFactory].
 To instantiate it, you need an [AnalyzerFactory] instance, which is an object that can create [Analyzer] via
 [JcApplicationGraph].
 
 To instantiate an [Analyzer] interface, you have to specify the following:
 
 * `flowFunctions`, which describe the dataflow facts and their transmissions during the analysis;
 
-* how these facts produce vulnerabilities, i.e., you have to implement `getSummaryFacts` and 
-  `getSummaryFactsPostIfds` methods.
+* semantics for these dataflow facts, i.e. how these facts produce vulnerabilities, summaries, etc. 
+This should be done by implementing `handleNewEdge`, `handleNewCrossUnitCall` and `handleIfdsResult` methods.
 
-To implement bidirectional analysis, you may use composite [SequentialBidiIfdsUnitRunner] and [ParallelBidiIfdsUnitRunner].
+To implement bidirectional analysis, you may use composite [BidiIfdsUnitRunnerFactory].
 
 <!--- MODULE jacodb-analysis -->
 <!--- INDEX org.jacodb.analysis -->
 
 [runAnalysis]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis/run-analysis.html
 [newApplicationGraphForAnalysis]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.graph/new-application-graph-for-analysis.html
-[IfdsUnitRunner]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-ifds-unit-runner/index.html
+[IfdsUnitRunnerFactory]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-ifds-unit-runner-factory/index.html
 [JcClasspath]: https://jacodb.org/docs/jacodb-api/org.jacodb.api/-jc-classpath/index.html
-[IfdsBaseUnitRunner]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-ifds-base-unit-runner/index.html
+[IfdsBaseUnitRunnerFactory]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-ifds-base-unit-runner-factory/index.html
 [AnalyzerFactory]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-analyzer-factory/index.html
 [Analyzer]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-analyzer/index.html
 [JcApplicationGraph]: https://jacodb.org/docs/jacodb-api/org.jacodb.api.analysis/-jc-application-graph/index.html
-[SequentialBidiIfdsUnitRunner]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-sequential-bidi-ifds-unit-runner/index.html
-[ParallelBidiIfdsUnitRunner]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-parallel-bidi-ifds-unit-runner/index.html
+[BidiIfdsUnitRunnerFactory]: https://jacodb.org/docs/jacodb-analysis/org.jacodb.analysis.engine/-bidi-ifds-unit-runner-factory/index.html

jacodb-analysis/src/main/kotlin/org/jacodb/analysis/AnalysisMain.kt

@@ -19,9 +19,9 @@ package org.jacodb.analysis
 
 import kotlinx.serialization.Serializable
 import mu.KLogging
-import org.jacodb.analysis.engine.IfdsUnitManager
-import org.jacodb.analysis.engine.IfdsUnitRunner
-import org.jacodb.analysis.engine.Summary
+import org.jacodb.analysis.engine.IfdsUnitRunnerFactory
+import org.jacodb.analysis.engine.MainIfdsUnitManager
+import org.jacodb.analysis.engine.SummaryStorage
 import org.jacodb.analysis.engine.UnitResolver
 import org.jacodb.analysis.engine.VulnerabilityInstance
 import org.jacodb.analysis.graph.newApplicationGraphForAnalysis
@@ -45,14 +45,14 @@ data class AnalysisConfig(val analyses: Map<String, AnalysesOptions>)
  * Usually built by [newApplicationGraphForAnalysis].
  *
  * @param unitResolver instance of [UnitResolver] which splits all methods into groups of methods, called units.
- * Units are analyzed concurrently, one unit will be analyzed with one call to [IfdsUnitRunner.run] method.
+ * Units are analyzed concurrently, one unit will be analyzed with one call to [IfdsUnitRunnerFactory.newRunner] method.
  * In general, larger units mean more precise, but also more resource-consuming analysis, so [unitResolver] allows
  * to reach compromise.
- * It is guaranteed that [Summary] passed to all units is the same, so they can share information through it.
+ * It is guaranteed that [SummaryStorage] passed to all units is the same, so they can share information through it.
  * However, the order of launching and terminating analysis for units is an implementation detail and may vary even for
  * consecutive calls of this method with same arguments.
  *
- * @param ifdsUnitRunner an [IfdsUnitRunner] instance that will be launched for each unit.
+ * @param ifdsUnitRunnerFactory an [IfdsUnitRunnerFactory] instance that will be launched for each unit.
  * This is the main argument that defines the analysis.
  *
  * @param methods the list of method for analysis.
@@ -66,9 +66,9 @@ data class AnalysisConfig(val analyses: Map<String, AnalysesOptions>)
 fun runAnalysis(
     graph: JcApplicationGraph,
     unitResolver: UnitResolver<*>,
-    ifdsUnitRunner: IfdsUnitRunner,
+    ifdsUnitRunnerFactory: IfdsUnitRunnerFactory,
     methods: List<JcMethod>,
     timeoutMillis: Long = Long.MAX_VALUE
 ): List<VulnerabilityInstance> {
-    return IfdsUnitManager(graph, unitResolver, ifdsUnitRunner, methods, timeoutMillis).analyze()
+    return MainIfdsUnitManager(graph, unitResolver, ifdsUnitRunnerFactory, methods, timeoutMillis).analyze()
 }

jacodb-analysis/src/main/kotlin/org/jacodb/analysis/engine/AbstractAnalyzer.kt

@@ -0,0 +1,80 @@
+/*
+ *  Copyright 2022 UnitTestBot contributors (utbot.org)
+ * <p>
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ * <p>
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package org.jacodb.analysis.engine
+
+import org.jacodb.api.analysis.JcApplicationGraph
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Handlers of [AbstractAnalyzer] produce some common events like new [SummaryEdgeFact]s, new [CrossUnitCallFact]s, etc.
+ * Inheritors may override all these handlers, and also they can extend them by calling the super-method and adding
+ * their own event
+ *
+ * @property verticesWithTraceGraphNeeded For all vertices added to this set,
+ * a [TraceGraphFact] will be produced at [handleIfdsResult]
+ *
+ * @property isMainAnalyzer Iff this property is set to true, handlers will
+ * 1. Produce [NewSummaryFact] events with [SummaryEdgeFact]s and [CrossUnitCallFact]s
+ * 2. Will produce [EdgeForOtherRunnerQuery] for each cross-unit call
+ *
+ * Usually this should be set to true for forward analyzers (which are expected to tell anything they found),
+ * but in backward analyzers this should be set to false
+ */
+abstract class AbstractAnalyzer(private val graph: JcApplicationGraph) : Analyzer {
+    protected val verticesWithTraceGraphNeeded: MutableSet<IfdsVertex> = ConcurrentHashMap.newKeySet()
+
+    abstract val isMainAnalyzer: Boolean
+
+    /**
+     * If the edge is start-to-end and [isMainAnalyzer] is true,
+     * produces a [NewSummaryFact]  with this summary edge.
+     * Otherwise, returns empty list.
+     */
+    override fun handleNewEdge(edge: IfdsEdge): List<AnalysisDependentEvent> {
+        return if (isMainAnalyzer && edge.v.statement in graph.exitPoints(edge.method)) {
+            listOf(NewSummaryFact(SummaryEdgeFact(edge)))
+        } else {
+            emptyList()
+        }
+    }
+
+    /**
+     * If [isMainAnalyzer] is set to true, produces a [NewSummaryFact] with given [fact]
+     * and also produces [EdgeForOtherRunnerQuery]
+     */
+    override fun handleNewCrossUnitCall(fact: CrossUnitCallFact): List<AnalysisDependentEvent> {
+        return if (isMainAnalyzer) {
+            verticesWithTraceGraphNeeded.add(fact.callerVertex)
+            listOf(NewSummaryFact(fact), EdgeForOtherRunnerQuery(IfdsEdge(fact.calleeVertex, fact.calleeVertex)))
+        } else {
+            emptyList()
+        }
+    }
+
+    /**
+     * Produces trace graphs for all vertices added to [verticesWithTraceGraphNeeded]
+     */
+    override fun handleIfdsResult(ifdsResult: IfdsResult): List<AnalysisDependentEvent> {
+        val traceGraphs = verticesWithTraceGraphNeeded.map {
+            ifdsResult.resolveTraceGraph(it)
+        }
+
+        return traceGraphs.map {
+            NewSummaryFact(TraceGraphFact(it))
+        }
+    }
+}

…/jacodb/analysis/engine/FlowFunctions.kt …acodb/analysis/engine/AnalyzerFactory.ktjacodb-analysis/src/main/kotlin/org/jacodb/analysis/engine/FlowFunctions.kt renamed to jacodb-analysis/src/main/kotlin/org/jacodb/analysis/engine/AnalyzerFactory.kt jacodb-analysis/src/main/kotlin/org/jacodb/analysis/engine/FlowFunctions.kt renamed to jacodb-analysis/src/main/kotlin/org/jacodb/analysis/engine/AnalyzerFactory.kt

@@ -56,51 +56,48 @@ interface FlowFunctionsSpace {
 }
 
 /**
- * [Analyzer] interface describes how facts are propagated and how vulnerabilities are produced by these facts during
- * the run of tabulation algorithm by [IfdsBaseUnitRunner].
- *
- * There are two methods that can turn facts into vulnerabilities or other [SummaryFact]s: [getSummaryFacts] and
- * [getSummaryFactsPostIfds]. First is called during the analysis, each time a new path edge is found, and second
- * is called only after all path edges were found.
- * While some analyses really need full set of facts to find vulnerabilities, most analyses can report [SummaryFact]s
- * right after some fact is reached, so [getSummaryFacts] is a recommended way to report vulnerabilities when possible.
+ * [Analyzer] interface describes how facts are propagated and how [AnalysisDependentEvent]s are produced by these facts during
+ * the run of tabulation algorithm by [BaseIfdsUnitRunner].
  *
  * Note that methods and properties of this interface may be accessed concurrently from different threads,
  * so the implementations should be thread-safe.
  *
  * @property flowFunctions a [FlowFunctionsSpace] instance that describes how facts are generated and propagated
  * during run of tabulation algorithm.
- *
- * @property saveSummaryEdgesAndCrossUnitCalls when true, summary edges and cross-unit calls will be automatically
- * saved to summary (usually this property is true for forward analyzers and false for backward analyzers).
  */
 interface Analyzer {
     val flowFunctions: FlowFunctionsSpace
 
-    val saveSummaryEdgesAndCrossUnitCalls: Boolean
-        get() = true
+    /**
+     * This method is called by [BaseIfdsUnitRunner] each time a new path edge is found.
+     *
+     * @return [AnalysisDependentEvent]s that are produced by this edge.
+     * Usually these are [NewSummaryFact] events with [SummaryEdgeFact] or [VulnerabilityLocation] facts
+     */
+    fun handleNewEdge(edge: IfdsEdge): List<AnalysisDependentEvent>
 
     /**
-     * This method is called by [IfdsBaseUnitRunner] each time a new path edge is found.
+     * This method is called by [BaseIfdsUnitRunner] each time a new cross-unit called is observed.
      *
-     * @return [SummaryFact]s that are produced by this edge, that need to be saved to summary.
+     * @return [AnalysisDependentEvent]s that are produced by this [fact].
      */
-    fun getSummaryFacts(edge: IfdsEdge): List<SummaryFact> = emptyList()
+    fun handleNewCrossUnitCall(fact: CrossUnitCallFact): List<AnalysisDependentEvent>
 
     /**
-     * This method is called once by [IfdsBaseUnitRunner] when the propagation of facts is finished
+     * This method is called once by [BaseIfdsUnitRunner] when the propagation of facts is finished
      * (normally or due to cancellation).
      *
-     * @return [SummaryFact]s that can be obtained after the facts propagation was completed.
+     * @return [AnalysisDependentEvent]s that should be processed after the facts propagation was completed
+     * (usually these are some [NewSummaryFact]s).
      */
-    fun getSummaryFactsPostIfds(ifdsResult: IfdsResult): List<SummaryFact> = emptyList()
+    fun handleIfdsResult(ifdsResult: IfdsResult): List<AnalysisDependentEvent>
 }
 
 /**
  * A functional interface that allows to produce [Analyzer] by [JcApplicationGraph].
  *
- * It simplifies instantiation of [IfdsUnitRunner]s because this way you don't have to pass graph and reversed
- * graph to [Analyzer]s directly, relying on runner to do it by itself.
+ * It simplifies instantiation of [IfdsUnitRunnerFactory]s because this way you don't have to pass graph and reversed
+ * graph to analyzers' constructors directly, relying on runner to do it by itself.
  */
 fun interface AnalyzerFactory {
     fun newAnalyzer(graph: JcApplicationGraph): Analyzer