Updated docs. Added js reachables test

Signed-off-by: Prabhu Subramanian <prabhu@appthreat.com>
AppThreat · Oct 22, 2023 · 1990062 · 1990062
1 parent 799554c
commit 1990062
Show file tree

Hide file tree

Showing 3 changed files with 578 additions and 789 deletions.
diff --git a/.github/workflows/repotests.yml b/.github/workflows/repotests.yml
@@ -76,5 +76,7 @@ jobs:
           npm install -g @cyclonedx/cdxgen --omit=optional
           cdxgen -t java --deep -o java-sec-code/bom.json java-sec-code
           ./atom.sh reachables -o /tmp/java-sec-code.atom -l java $GITHUB_WORKSPACE/repotests/java-sec-code -Dlog4j.configurationFile=log4j2.xml --slice-outfile /tmp/java-sec-code.reachables.json
+          cdxgen -t js -o juice-shop/bom.json juice-shop
+          ./atom.sh reachables -o /tmp/juice-shop.atom -l js $GITHUB_WORKSPACE/repotests/juice-shop -Dlog4j.configurationFile=log4j2.xml --slice-outfile /tmp/juice-shop.reachables.json
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/specification/docs/slices.md b/specification/docs/slices.md
@@ -26,7 +26,7 @@ The mind map below offers an overview.
 
 <img src="./Library%20Usages.png" alt="Usages slice" width="512">
 
-#### Use
+#### How to parse?
 
 1. Parse the usages json.
 2. Iterate over the `objectSlices` array. For each slice store its fileName and lineNumber.
@@ -97,13 +97,17 @@ The mind map below offers an overview.
 
 ### Data flow slice
 
-Data flow slices represent the data-dependency information computed statically from the source code. The full list of `nodes` and `edges` from the
-Data Dependency Graph (DDG) is also made available for custom visualization and traversal purposes. Up to 100 reachable
+Data flow slices represent the data-dependency information computed statically from the source code using Reverse-Reachability Algorithm. The full list of `nodes` and `edges` from the
+Data Dependency Graph (DDG) is also made available for custom visualization and traversal purposes. Up to 50 reachable
 paths are precomputed and made available via the `paths` attribute in the json by the atom cli tool for convenience.
 
 <img src="./Data%20Flows.png" alt="Data Flow slice" width="512">
 
-#### Use
+#### When to use?
+
+It is quite common for organizations to have common libraries and modules in separate repositories, jar files, and other packages. These modules would use external libraries as sinks and might lack any entrypoints (sources). Data flow slicing could work well in theses scenarios where the entrypoints (sources) cannot be identified. The brute-force nature means data-flow slicing would often take significant amount of time compared to usages or reachables slicing.
+
+#### How to parse?
 
 1. Parse the data flow json.
 2. Iterate over the `graph.nodes` array and create a Map for each node with the id as the key and the node as the value.
@@ -132,10 +136,62 @@ The information in a data-flow slice can be used as component evidence in a Cycl
 | columnNumber              | column              | Could be unavailable for certain projects               |
 | parentFileName            | fullFilename        |                                                         |
 
+### Reachables slice
+
+Reachables represent data flows that can originate from an entrypoint (source) and reach an external sink. These potentially represent the paths an adversary could take to reach and exploit a known vulnerability in a third-party library and hence the terms "reachable flows" or "Forward-Reachability". With atom, reachable slices can be generated for Java, Jars, JavaScript, and TypeScript applications.
+
+A necessary pre-requisite is the presence of the Software Bill-of-Materials (SBOM) file in the directory containing the source code. At present, only the SBOM generated by [CycloneDX Generator](https://github.com/CycloneDX/cdxgen) have the precision and depth required for computing reachables.
+
+#### How to parse?
+
+1. Parse the reachables json.
+2. Iterate over the `reachables` array. Each item in this array is an object containing flows (Reachable data-flows) and purls (List of [Package URLs](https://github.com/package-url/purl-spec))
+3. Each item in the flows array is of type `node` similar to the nodes array in the data flow slice above.
+4. Each item in the purls array is of type string
+
+```json
+{
+  "reachables": [
+    {
+      "flows": [
+        {
+          "id": 44,
+          "label": "METHOD_PARAMETER_IN",
+          "name": "this",
+          "fullName": "",
+          "signature": "",
+          "isExternal": false,
+          "code": "this",
+          "typeFullName": "com.example.SpringKafkaDemo.config.KafkaConsumerConfig",
+          "parentMethodName": "consumerFactory",
+          "parentMethodSignature": "org.springframework.kafka.core.ConsumerFactory()",
+          "parentFileName": "src/main/java/com/example/SpringKafkaDemo/config/KafkaConsumerConfig.java",
+          "parentPackageName": "com.example.SpringKafkaDemo.config",
+          "parentClassName": "com.example.SpringKafkaDemo.config.KafkaConsumerConfig",
+          "lineNumber": 36,
+          "columnNumber": null,
+          "tags": "framework-input"
+        }
+      ],
+      "purls": [
+        "pkg:maven/org.springframework.kafka/spring-kafka@2.8.11?type=jar"
+      ]
+    }
+  ]
+}
+```
+
 ## Generate slices
 
 Use the atom cli to generate slices.
 
+### Create a reachables slice for a java project.
+
+```shell
+cdxgen -t java --deep -o bom.json .
+atom reachables -o app.atom --slice-outfile df.json -l java .
+```
+
 ### Create a data flow slice for a java project.
 
 ```shell
@@ -150,4 +206,4 @@ atom usages -o app.atom --slice-outfile usages.json -l java .
 
 ## Develop a custom slicer
 
-Planned for 1.1.0 release
+Planned for 2.0.0 release