Add URL Dynamic Analysis

Author: MislavReversingLabs

TitaniumCloud/dynamic_analysis.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "source": [
     "# TitaniumCloud Dynamic Analysis API-s\n",
-    "This notebook demonstrates how to use the Dynamic Analysis API-s, namely the Dynamic Analysis and Dynamic Analysis Report. The first one mentioned here handles submitting a cloud sample to dynamic analysis and the second one handles returning a comprehensive report.\n",
+    "This notebook demonstrates how to use the Dynamic Analysis API-s, namely the Dynamic Analysis and Dynamic Analysis Report. The first one mentioned here handles submitting a cloud sample or a URL to dynamic analysis and the second one handles returning a comprehensive report.\n",
     "**NOTE:** If pasted into a Python file in the displayed order, all code cells can also work as a Python script."
    ],
    "metadata": {
@@ -153,7 +153,7 @@
   {
    "cell_type": "markdown",
    "source": [
-    "### 5. Getting the Dynamic Analysis results\n",
+    "### 5. Getting the Dynamic Analysis results for a sample\n",
     "After the Dynamic Analysis is finished, we can move on to getting the results for our sample."
    ],
    "metadata": {
@@ -300,6 +300,113 @@
     "collapsed": false
    },
    "id": "fa928c5d6108a5cc"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### 7. Submitting a URL for Dynamic Analysis\n",
+    "Apart from submitting only samples for Dynamic Analysis, we can also do the same for URL-s.  \n",
+    "The procedure is, for the most part, the same, with the0 difference being in using a different \"detonate\" method and a different method parameter while fetching the results. To see how it differs from detonation and result fetching for samples, see the examples below.\n",
+    "\n",
+    "**Note:** It is highly recommended **not to open the URL-s** used as examples in this cookbook as many of them may be classified as containing malicious software and/or indicators and can be **harmful for you computer**. For this example, we used a placeholder URL."
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "1b01d3239862ff90"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "detonate3 = dynamic_analysis.detonate_url(\n",
+    "    url_string=\"http://some.example.url./aaa\",\n",
+    "    platform=\"windows10\"\n",
+    ")\n",
+    "\n",
+    "print(detonate3.text)"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "ab411ebc51fe8576"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "The response text that we received tells us the following info:\n",
+    "- The analysis started.\n",
+    "- We got the SHA-1, the Base64 and the actual string of our submitted URL.\n",
+    "- We also got the ID of the started analysis.\n",
+    "\n",
+    "It is useful to save those values since we will be using them to access the URL Dynamic Analysis report."
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "8978610cb7f52f73"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### 8. Getting the Dynamic Analysis results for a URL\n",
+    "To fetch the Dynamic Analysis results for our submitted URL, we can use one of the following as an input parameter:\n",
+    "- The SHA-1 of the URL.\n",
+    "- The URL string itself.\n",
+    "\n",
+    "For demonstration purposes, we will show you how to use both - in the order written above."
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "68d86bc7cc7a7468"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "# Example 1\n",
+    "results_sha1 = dynamic_analysis.get_dynamic_analysis_results(\n",
+    "    url_sha1=\"27c5d0351a92e7be52884c6aa863d25665cb6b32\",\n",
+    "    analysis_id=\"6c8d9c60-2d9c-4c27-bc15-150b7e364d6c\"\n",
+    ")\n",
+    "\n",
+    "# Example 2\n",
+    "results_url = dynamic_analysis.get_dynamic_analysis_results(\n",
+    "    url=\"http://some.example.url./aaa\",\n",
+    "    latest=True\n",
+    ")\n",
+    "\n",
+    "print(results_sha1.text)\n",
+    "print(results_url.text)"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "fb257b06a907e5a5"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Keep in mind that these are all placeholder values that serve only as examples of use. We did not use actual malicious URL-s for security purposes.  \n",
+    "What did we do in these two examples?\n",
+    "\n",
+    "Example 1:\n",
+    "- We used the URL-s SHA-1 as input.\n",
+    "- We used the analysis ID to define which analysis we need.\n",
+    "\n",
+    "Example 2:\n",
+    "- We used the actual URL string as input.\n",
+    "- We stated that we want the latest analysis returned.\n",
+    "\n",
+    "Apart from defining the desired analysis using the `analysis_id` and `latest` parameters, we can also omit them completely and receive a merged report from all the analyses for this URL so far. However, keep in mind that, if the report is not yet ready, you will receive `404` as a status code."
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "e7f2de25dca23fde"
   }
  ],
  "metadata": {