README Edit

COLLAB_MODE.md

@@ -10,7 +10,8 @@
 ## Collaboration mode
 
 PoiEx allows for real-time synchronization of findings and comments with other users. This mode requires a MongoDB instance shared across all collaborators. See the MongoDB section below for how to deploy a MongoDB instance.  
-Once you have a shared MongoDB instance ready, set your name in _Settings > Extensions > PoiEx > Author Name_ and the database URI, which should be the same across all collaborators.  
+
+Once you have a shared MongoDB instance ready, set your name in _Settings > Extensions > PoiEx > Author Name_ and the database URI, which should be the same across all collaborators. <br> 
 To create a project, the Project Manager should open the desired codebase in VS Code, then click _Init project_ in the PoiEx tab. If the project is encrypted, the automatically generated secret should be sent via a secure channel to all collaborators.  
 To open an existing project, a collaborator should:
  - Ensure PoiEx is connected to the same MongoDB instance as the project manager
@@ -22,13 +23,15 @@ To open an existing project, a collaborator should:
 
 After this, all findings and notes will be synchronized in real-time across all collaborators.
 
-### MongoDB (optional)
-PoiEx supports real-time project synchronization between multiple collaborators.  
-To enable collaboration features all collaborators should connect to a common MongoDB instance.
-All collaborators should have read and write access to the database configured in the `poiex.collab.database` field of the VSCode settings. To enable collaboration features set `poiex.collab.enabled` to `true` and `poiex.collab.uri` to the MongoDB URI. Optionally, update `poiex.collab.database` if using a database name different from the default value. If credentials are required to connect to the database, the extension will prompt the user for credentials.  
-The extension supports an auto-delete feature, if `poiex.collab.expireAfter` is set to a value higher than 0, it will configure MongoDB to automatically delete projects that are not accessed for the specified number of seconds. The project expiration value is reset each time one of the collaborators accesses the project. The expiration value does not affect project data that is saved locally. If a project is not found on the remote database (because it never existed, or has expired) the extension will push the local version to the remote database.
+### Shared MongoDB Instance
+
+To enable collaboration features all collaborators should connect to a common MongoDB instance.<br>
+All collaborators should have read and write access to the database configured in the `poiex.collab.database` field of the VSCode settings. To enable collaboration features set `poiex.collab.enabled` to `true` and `poiex.collab.uri` to the MongoDB URI. <br>
+Optionally, update `poiex.collab.database` if using a database name different from the default value. If credentials are required to connect to the database, the extension will prompt the user for credentials. <br>
+The extension supports an auto-delete feature, if `poiex.collab.expireAfter` is set to a value higher than `0`, it will configure MongoDB to automatically delete projects that are not accessed for the specified number of seconds. The project expiration value is reset each time one of the collaborators accesses the project. The expiration value does not affect project data that is saved locally. <br>
+If a local project is not found on the remote database, the extension will push the local version to the remote database.
 
-MongoDB deployment steps on Ubuntu 22.04:
+Example MongoDB deployment steps on Ubuntu 22.04:
 
 ```bash
 export ADMIN_USERNAME="username"
@@ -65,4 +68,11 @@ mongosh -u "$ADMIN_USERNAME" -p "$ADMIN_PASSWORD" --authenticationDatabase "admi
 mongosh -u "$ADMIN_USERNAME" -p "$ADMIN_PASSWORD" --authenticationDatabase "admin" <<< "var x = rs.conf(); x.members[0].host = \"$FQDN:27017\"; rs.reconfig(x);"
 ```
 
-After deployment create additional user(s) for the extension collaborators. Each user should have read/write access to one common database. Each collaborator should enter the same MongoDB URI, and database name in the extension settings.
+**Security Note**: *The given deployment script is intended for plug&play purposes to test the extension and its collaboration capabilities. For production-safe usages, configure an hardened MongoDB instance machine depending on your needs by following the best practices (see the [documentation](https://www.mongodb.com/docs/manual/administration/security-checklist/))*
+
+After deployment create additional user(s) for the extension collaborators. Each user should have read/write access to one common database. Each collaborator should enter the same MongoDB URI and database name in the extension settings.
+### Security Model
+
+Since the tool is intended internal usage, currently the MongoDB users (testers) are required to have read and write permissions on the configured database. <br>
+Consequently, everyone in the team can list, add or destroy projects. <br>
+As previously described, per-project symmetric encryption keys are created and they must be shared among peers participating to an activity in order to decrypt and read the stored data. In this way the confidentiality is project-oriented.

README.md

@@ -4,51 +4,69 @@
 
 **PoiEx** is an experimental VS Code extension built to identify and visualize the Points Of Intersection between a web application and the underlying infrastructure.  
 
+Since it was designed to simplify manual code review activities, it was also packed with: [Semgrep](https://semgrep.dev/) support, notes taking and collaboration capabilities.
+
 </br>
 <p align="center">
     <img src="images/logo-1.png" width="30%" alt="PoiEx logo">
 </p>
 </br>
 
+Read the launch post on our [Doyensec blog](https://blog.doyensec.com/2024/01/25/poiex-release.html) for practical examples and tips.
+
 ## Try it out!
 
 Download and install the VSIX extension from GitHub Releases. Make sure you have [Semgrep](https://semgrep.dev/) installed before running PoiEx.
 
-## Point of Intersection
+## Points of Intersection Explorer
 
-A Point of Intersection (PoI) marks where your code interacts with underlying infrastructure, revealing connections between the implemented logic and the Infrastructure as Code (IaC). PoiEx identifies and visualizes PoIs, allowing testers and cloud security specialists to better understand and identify security vulnerabilities in your cloud applications.
+A Point of Intersection (PoI) marks where your code interacts with underlying infrastructure, revealing connections between the implemented logic and the Infrastructure as Code (IaC). PoiEx identifies and visualizes PoIs, allowing testers and cloud security specialists to better understand and identify security vulnerabilities in your cloud applications.<br><br>
+The extension relies on [Inframap](https://github.com/cycloidio/inframap/) to generate an interactive IaC diagram. Each entity in the diagram is clickable to reveal the PoIs, semgrep results and the IaC definition linked to the selected entity. By then clicking on a PoI, the user can jump to the relevant code section.<br>
 
-## Basic usage
+Below an example infrastructure diagram generation and PoIs exploration.
+![IaC Diagrams](images/animation-diagram.gif)
 
-PoiEx allows users to scan the application code and the IaC definition at the same time, generating results in a nice and user-friendly view. Users can navigate the infrastructure diagram and quickly jump to the relevant application code sections where the selected infrastructure resource is used. Additionally, PoiEx provides for advanced collaboration capabilities, notes taking using the VS Code Comments API and integration with [Semgrep](https://semgrep.dev/), allowing PoiEx to be used also as a standalone Semgrep extension without any of the IaC-specific features.
+**Note**: If you do not have a Terraform IaC definition file but you have access to the live infrastructure, you can use reverse-terraforming tools such as [terraformer](https://github.com/GoogleCloudPlatform/terraformer) to generate an IaC file from existing infrastructure.<br>
 
-### IaC Diagrams and IaC-app linking
+### Core Features
 
-PoiEx relies on [Inframap](https://github.com/cycloidio/inframap/) to generate an interactive IaC diagram. Each entity in the diagram is clickable, and reveals PoIs that are linked to the selected entity. By then clicking on a PoI, PoiEx jumps to the relevant code section. If you do not have a Terraform IaC definition file but you have access to the live infrastructure, you can use reverse-terraforming tools such as [terraformer](https://github.com/GoogleCloudPlatform/terraformer) to generate an IaC file from existing infrastructure.
+PoiEx allows users to:
+
+- Scan the application's code and the IaC definition at the same time with [Semgrep](https://semgrep.dev/), generating explorable results in a user-friendly view inside VS Code's Problems section
 
-![IaC Diagrams](images/animation-diagram.gif)
-*IaC Diagrams*
+- Visualize the infrastructure diagram generated with [Inframap](https://github.com/cycloidio/inframap/). Additionally, the diagram is enhanced to be interactive, each entity in the diagram is clickable and reveals the enumerated PoIs that are linked to the selected entity. By then clicking on a PoI, it jumps to the relevant code section to review the code in which it is embedded. 
+
+- Take notes using the VS Code Comments API, allowing it to be used also as a standalone code-analysis tool
+
+- Collaborate with other reviewers on encrypted projects pushed to a [MongoDB](https://www.mongodb.com/) instance
+
+### Supported CSPs & Languages
 
-### Semgrep integration
+A custom set of semgrep rules has been developed. Each pair of language and Cloud Service Provider (CSP) needs a different ruleset, as a rule is generally able to match only one language and one CSP. 
 
+The table below summarizes the currently supported CSPs and languages
+![[images/supported-lang-csp.png]]
+
+### Enhancing Reviews With PoIEx
+Non-IaC related features were added to support manual reviews in different ways. Such functionalities are unrelated to the cloud infrastructure analysis and they are usable in any code review activity.<br>
+Below are attached few examples, please refer to the  [launch blogpost](https://blog.doyensec.com/2024/01/25/poiex-release.html) for detailed use cases.
+#### 1. Standalone Semgrep Integration
+Scan the application's code and the IaC definition at the same time with [Semgrep](https://semgrep.dev/), generating explorable results in a user-friendly view inside VS Code's Problems section. The semgrep ruleset is fully customizable via direct arguments in the settings page.
+
+It is also possible to flag the findings as `false positive`,`hot` or `resolved` and have them synced in collaboration mode.
 ![Semgrep integration](images/feature-findings.png)
-*Integration with Semgrep*
 
-### Notes taking
+#### 2. Notes taking
+It is possible to start comment threads directly within the codebase to add details and reactions.
 
-![Collaborative comments](images/feature-comments.png)
-*Collaborative comments*
+![[images/threadExample.png]]
 
 When collaboration mode is disabled, each project is stored in a local SQLite database. In this mode, projects are not synchronized or shared across different collaborators.
 
-## Collaboration mode
-PoiEx allows for real-time synchronization of findings and comments with other users. This mode requires a MongoDB instance shared across all collaborators.  
-Collaboration mode is described in [COLLAB_MODE.md](./COLLAB_MODE.md).
-
+#### 3. Collaboration With Peers
+PoiEx allows for real-time synchronization of findings and comments with other users. This mode requires a MongoDB instance shared across all collaborators.  Read more in the  [collaboration guide](./COLLAB_MODE.md).
 ## Extension Settings
 
-This extension contributes the following settings:
-
 * `poiex.enableIaC`: Enable IaC features of this extension 
 * `poiex.authorName`: Author name for comments
 * `poiex.semgrepArgs`: Semgrep command line arguments
@@ -58,8 +76,8 @@ This extension contributes the following settings:
 * `poiex.collab.database`: Name of the MongoDB database
 * `poiex.collab.expireAfter`: Auto-delete comments on the remote database after a certain amount of seconds (set to 0 to disable)
 
-## Release Notes
+## Credits
 
-### 1.0.0
+This project was made with love in the [Doyensec Research island](https://doyensec.com/research.html) by [Michele Lizzit](https://www.linkedin.com/in/michelelizzit/) for his master thesis at ETH Zurich under the mentoring of [Francesco Lacerenza](https://twitter.com/lacerenza_fra).
 
-First release
+Download the last [realease](https://github.com/doyensec/PoiEx/releases) and contribute with a star, [bug reports or suggestions](https://github.com/doyensec/PoiEx/issues).