Merge pull request #32 from RefactorSecurity/feat-breadcrumbs

Add Breadcrumbs feature

Author: v8vito

README.md

@@ -12,9 +12,9 @@
 
 ---
 
-Security Notes allows the creation of notes within source files, which can be replied to, reacted to using emojis, and assigned statuses such as "TODO", "Vulnerable" and "Not Vulnerable".
+Security Notes allows the creation of notes within source files, which can be replied to, reacted to using emojis, and assigned statuses such as "TODO", "Vulnerable" and "Not Vulnerable". Also, it allows importing the output from SAST tools (such as semgrep, bandit and brakeman), into notes, making the processing of the findings much easier.
 
-Also, it allows importing the output from SAST tools (such as semgrep, bandit and brakeman), into notes, making the processing of the findings much easier.
+Use the **Breadcrumbs** feature to track complex implementations accross different source files. This way you will be able to visualize how a feature works, and export it so you can share your analysis with others.  
 
 Finally, collaborate with others by using a centralized database for notes that will be automatically synced in **real-time**! Create a note locally, and it will be automatically pushed to whoever is working with you on the project.
 
@@ -42,25 +42,15 @@ Security Notes allows the creation of notes within source files, which can be re
 
 By default your notes are backed up in a JSON file once you close VSCode. Once you open the project again, saved comments are loaded and shown on the UI.
 
-## Collaboration Mode
-
-Because chasing bugs with friends is more fun :)
-
-Security Notes allows sharing of notes in real-time with other users. To do so, it leverages the RethinkDB real-time database.
-
-First, make sure you have a RethinkDB database instance up and running. Then set your author name, and the database connection information in the extension's settings, and you are ready to go! Please see the section below for more details).
-
-Collaboration mode in action:
+## Breadcrumb Trails
 
-![Demo for collaboration](images/demo-collaboration.gif)
+Breadcrumbs let you capture the path you follow while reverse-engineering a feature. Start a trail with `Security Notes: Create Breadcrumb Trail`, highlight the snippets you visit, and run `Security Notes: Add Breadcrumb to Trail` to drop "crumbs" along the way. Each crumb stores the code selection, file/line information, and an optional note.
 
-### Setting up the RethinkDB database
+![Breadcrumbs view showing a trail](images/breadcrumbs-1.png)
 
-We recommend following instructions in RethinkDB [installation guide](https://rethinkdb.com/docs/install/). Additionally, following [hardening steps](https://rethinkdb.com/docs/security/#wrapper), such as setting a password for the `admin` user and setting up SSL/TLS, are strongly encouraged.
+Open the **Breadcrumbs** view from the Security Notes activity bar to see an interactive diagram of the active trail. Click any crumb in the diagram to jump back to that snippet in the editor, or switch trails from the dropdown to review other investigations. Trails are stored locally in `.security-notes-breadcrumbs.json` so you can revisit them later, and you can export the active trail to a Markdown report (via `Security Notes: Export Breadcrumb Trail` or the Export button) ready to paste into docs or reports.
 
-Naturally, you will want to collaborate with remote peers. To do so in a secure way, we recommend setting up access to RethinkDB via SSH or through a VPN like [Tailscale](http://tailscale.com). This way, you avoid having to expose the instance to any network, and also ensuring information in transit is encrypted.
-
-> **Important Notices:** When collaborating with others, ensure that all VSCode instances open the project from the same relative location. For example, if the source code repository you're reviewing has a directory structure like `source_code/app/src`, all peers should open VScode at the same level. Security Notes will store note location using relative paths, so they should be consistent. Also, after enabling the collaboration setting, VSCode would need to be restarted/reloaded for the change to have effect.
+![Markdown export of a Breadcrumb](images/breadcrumbs-2.png)
 
 ## Importing SAST results
 
@@ -91,6 +81,26 @@ gosec -fmt=json -out=gosec-results.json ./...
 semgrep scan --json -o semgrep-results.json --config=auto .
 ```
 
+## Collaboration Mode
+
+Because chasing bugs with friends is more fun :)
+
+Security Notes allows sharing of notes in real-time with other users. To do so, it leverages the RethinkDB real-time database.
+
+First, make sure you have a RethinkDB database instance up and running. Then set your author name, and the database connection information in the extension's settings, and you are ready to go! Please see the section below for more details).
+
+Collaboration mode in action:
+
+![Demo for collaboration](images/demo-collaboration.gif)
+
+### Setting up the RethinkDB database
+
+We recommend following instructions in RethinkDB [installation guide](https://rethinkdb.com/docs/install/). Additionally, following [hardening steps](https://rethinkdb.com/docs/security/#wrapper), such as setting a password for the `admin` user and setting up SSL/TLS, are strongly encouraged.
+
+Naturally, you will want to collaborate with remote peers. To do so in a secure way, we recommend setting up access to RethinkDB via SSH or through a VPN like [Tailscale](http://tailscale.com). This way, you avoid having to expose the instance to any network, and also ensuring information in transit is encrypted.
+
+> **Important Notices:** When collaborating with others, ensure that all VSCode instances open the project from the same relative location. For example, if the source code repository you're reviewing has a directory structure like `source_code/app/src`, all peers should open VScode at the same level. Security Notes will store note location using relative paths, so they should be consistent. Also, after enabling the collaboration setting, VSCode would need to be restarted/reloaded for the change to have effect.
+
 ## Exporting notes in popular formats
 
 Currently we only support exporting notes to Markdown, but other formats such as HTML are coming soon.

images/breadcrumbs-1.png

@@ -80,6 +80,34 @@
       {
         "command": "security-notes.saveNotesToFile",
         "title": "Security-Notes: Save Notes to Local Database"
+      },
+      {
+        "command": "security-notes.breadcrumbs.createTrail",
+        "title": "Security Notes: Create Breadcrumb Trail"
+      },
+      {
+        "command": "security-notes.breadcrumbs.selectTrail",
+        "title": "Security Notes: Select Active Breadcrumb Trail"
+      },
+      {
+        "command": "security-notes.breadcrumbs.addCrumb",
+        "title": "Security Notes: Add Breadcrumb to Trail"
+      },
+      {
+        "command": "security-notes.breadcrumbs.removeCrumb",
+        "title": "Security Notes: Remove Breadcrumb Crumb"
+      },
+      {
+        "command": "security-notes.breadcrumbs.editCrumbNote",
+        "title": "Security Notes: Edit Breadcrumb Note"
+      },
+      {
+        "command": "security-notes.breadcrumbs.showTrailDiagram",
+        "title": "Security Notes: Show Breadcrumb Diagram"
+      },
+      {
+        "command": "security-notes.breadcrumbs.exportTrail",
+        "title": "Security Notes: Export Breadcrumb Trail"
       }
     ],
     "configuration": {
@@ -95,6 +123,11 @@
           "description": "Local database file path.",
           "default": ".security-notes.json"
         },
+        "security-notes.breadcrumbs.localDatabase": {
+          "type": "string",
+          "description": "Local database file path for breadcrumb trails.",
+          "default": ".security-notes-breadcrumbs.json"
+        },
         "security-notes.collab.enabled": {
           "type": "boolean",
           "description": "Enable collaboration via RethinkDB.",
@@ -225,6 +258,13 @@
           "group": "inline@2",
           "when": "commentController == security-notes"
         }
+      ],
+      "editor/context": [
+        {
+          "command": "security-notes.breadcrumbs.addCrumb",
+          "group": "navigation@10",
+          "when": "editorHasSelection"
+        }
       ]
     },
     "views": {
@@ -238,6 +278,11 @@
           "type": "webview",
           "name": "Export Notes",
           "id": "export-notes-view"
+        },
+        {
+          "type": "webview",
+          "name": "Breadcrumbs",
+          "id": "breadcrumbs-view"
         }
       ]
     },
@@ -275,4 +320,4 @@
     "rethinkdb": "^2.4.2",
     "uuid": "^9.0.0"
   }
-}
+}