google · ZetaTwo · Sep 7, 2023 · Sep 4, 2023 · Sep 5, 2023 · Sep 7, 2023
diff --git a/README.md b/README.md
@@ -7,36 +7,37 @@ This project is not an official Google project. It is not supported by
 Google and Google specifically disclaims all warranties as to its quality,
 merchantability, or fitness for a particular purpose.
 
-
 ### GCP Scanner
 
 ![Logo](misc/gcp_scanner_logo.png?raw=true "Logo of GCP Scanner")
 
 This is a GCP resource scanner that can help determine what level of access certain credentials possess on GCP. The scanner is designed to help security engineers evaluate the impact of a certain VM/container compromise, GCP service account or OAuth2 token key leak.
 
 Currently, the scanner supports the following GCP resources:
-* GCE
-* GCS
-* GKE
-* App Engine
-* Cloud SQL
-* BigQuery
-* Spanner
-* Pub/Sub
-* Cloud Functions
-* BigTable
-* CloudStore
-* KMS
-* Cloud Services
-* The scanner supports SA [impersonation](https://cloud.google.com/iam/docs/impersonating-service-accounts)
+
+- GCE
+- GCS
+- GKE
+- App Engine
+- Cloud SQL
+- BigQuery
+- Spanner
+- Pub/Sub
+- Cloud Functions
+- BigTable
+- CloudStore
+- KMS
+- Cloud Services
+- The scanner supports SA [impersonation](https://cloud.google.com/iam/docs/impersonating-service-accounts)
 
 The scanner supports extracting and using the following types of credentials:
-* GCP VM instance metadata;
-* User credentials stored in gcloud profiles;
-* OAuth2 Refresh Token with cloud-platform scope granted;
-* GCP service account key in JSON format.
 
-The scanner does not rely on any third-party tool (e.g. gcloud). Thus, it can be compiled as a standalone tool and used on a machine with no GCP SDK installed (e.g. a Kubernetes pod). However, please keep in mind that the only OS that is currently supported is Linux. 
+- GCP VM instance metadata;
+- User credentials stored in gcloud profiles;
+- OAuth2 Refresh Token with cloud-platform scope granted;
+- GCP service account key in JSON format.
+
+The scanner does not rely on any third-party tool (e.g. gcloud). Thus, it can be compiled as a standalone tool and used on a machine with no GCP SDK installed (e.g. a Kubernetes pod). However, please keep in mind that the only OS that is currently supported is Linux.
 
 Please note that GCP offers [Policy Analyzer](https://cloud.google.com/policy-intelligence/docs/analyze-iam-policies) to find out which principals (users, service accounts, groups, and domains), have what access to which Google Cloud resources. However, it requires specific permissions on the GCP project and the Cloud Assets API needs to be enabled. If you just have a GCP SA key, access to a previously compromised VM, or an OAUth2 refresh token, gcp_scanner is the best option to use.
 
@@ -50,6 +51,7 @@ gcp-scanner --help
 ```
 
 Alternatively:
+
 ```
 git clone https://github.com/google/gcp_scanner
 cd gcp_scanner
@@ -99,17 +101,30 @@ Required parameters:
 
 Option `-f` requires an additional explanation. In some cases, the service account does not have permissions to explicitly list project names. However, it still might have access to underlying resources if we provide the correct project name. This option is specifically designed to handle such cases.
 
-
 ### Building a standalone binary with PyInstaller
 
 Please replace `google-api-python-client==2.80.0` with `google-api-python-client==1.8.0` in `pyproject.toml`. After that, navigate to the scanner source code directory and use pyinstaller to compile a standalone binary:
 
 `pyinstaller -F --add-data 'roots.pem:grpc/_cython/_credentials/' scanner.py`
 
-
 ### Working with results
 
-The GCP Scanner produces a standard JSON file that can be handled by any JSON Viewer or DB. If you just need a convenient way to grep JSON results, we can recommend [gron](https://github.com/tomnomnom/gron).
+The GCP Scanner produces a standard JSON file that can be handled by any JSON Viewer or DB. We are providing a web-based tool that can help you visualize the results.
+To run the tool, please use the following command:
+
+```
+usage: gcp-scanner-visualizer -p 8080
+
+GCP Scanner Visualizer
+
+options:
+  -h, --help            show this help message and exit
+  -p PORT, --port PORT  Port to listen on default 8080
+```
+
+To know more about how to use the tool, please visit [GCP Scanner Visualizer Usage Guide](./visualization_tool/USAGE.md) page.
+
+If you just need a convenient way to grep JSON results, we can recommend [gron](https://github.com/tomnomnom/gron).
 
 ### Contributing
 

diff --git a/misc/visualization_tool_images/details.webp b/misc/visualization_tool_images/details.webp
diff --git a/misc/visualization_tool_images/expand_role.webp b/misc/visualization_tool_images/expand_role.webp
diff --git a/misc/visualization_tool_images/filter.webp b/misc/visualization_tool_images/filter.webp
diff --git a/misc/visualization_tool_images/iam_policies.webp b/misc/visualization_tool_images/iam_policies.webp
diff --git a/misc/visualization_tool_images/search_resources.webp b/misc/visualization_tool_images/search_resources.webp
diff --git a/misc/visualization_tool_images/search_role.webp b/misc/visualization_tool_images/search_role.webp
diff --git a/misc/visualization_tool_images/sort.webp b/misc/visualization_tool_images/sort.webp
diff --git a/misc/visualization_tool_images/start_page.webp b/misc/visualization_tool_images/start_page.webp
diff --git a/misc/visualization_tool_images/upload.webp b/misc/visualization_tool_images/upload.webp
diff --git a/visualization_tool/USAGE.md b/visualization_tool/USAGE.md
@@ -0,0 +1,66 @@
+# GCP Scanner Visualizer Usage Guide
+
+The GCP Scanner Visualizer is a web-based tool that can help you visualize the results of the GCP Scanner.
+
+## Running the tool
+
+To run the tool, you can use the following command `gcc-scanner-visualizer`. The tool will start a web server on port 8080. You can change the port by using the `-p` option.
+
+Then you can open your browser and navigate to `http://localhost:8080` to use the tool.
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/start_page.webp)
+
+## Uploading the results
+
+To upload the results, head to the `Upload` Section and click on the `Choose File` button. Then select the JSON file that you want to upload and click on the `Plus` icon.
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/upload.webp)
+
+After uploading the result file, the tool will scan the file and append the results to UI.
+
+You can also remove any file by clicking on the `minus` icon next to the file name.
+
+## Viewing the results
+
+There are two main pages in the tool:
+
+### Resources Page
+
+This main page and it shows the list of resources that were found in the result file. You can click on the `Details` button to see more details about the resource.
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/details.webp)
+
+#### Sorting and filtering resources
+
+You can sort the shown resources by their name or creation time. by default, the resources are sorted by their creation date in descending order and you can change the sorting type from the `Sort` Section on the left menu.
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/sort.webp)
+
+The tool provides several options to filter the resources. You can filter the resources by:
+
+- Project
+- Resource Type
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/filter.webp)
+
+#### Searching for resources
+
+You can search for resources by their name in the search bar. The tool will show the resources that contain the search term in their name.
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/search_resources.webp)
+
+### IAM Policy Page
+
+This page shows the list of IAM policies that were found in the result file. The policies are visualized in a table view, which each row represents a single role and the roles names prefixed with the project name.
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/iam_policies.webp)
+
+To see the members of a role, you can click on the icon next to the role name to expand the role.
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/expand_role.webp)
+
+#### Searching for IAM policies
+
+You can search for a member in the IAM policies by using the search bar. The tool will show the policies that contain the email address of the member in the search bar.
+
+![GCP Scanner Visualizer](../misc/visualization_tool_images/search_role.webp)