Merge pull request #68 from piyarathnalakmali/master

Added documentation for Google Sheets Sync and Note Type modifications

docs/features.rst

@@ -228,6 +228,19 @@ Last Reviewed By
 
 Notes
     Stores information pertinent to the flaw or the mitigation.
+    Initially there isn't a way to categorize notes added for Findings. Admin can introduce a new attribute to notes as         'note-type' which can categorize notes.
+    To enable note-types go to System Settings, select Note Types and add new note-types to Dojo.
+
+    Note-type
+        A note-type has 4 attributes.
+
+        - Name
+        - Description
+        - is_active - This has to be true to assign the note-type to a note.
+        - is_single - If true, only one note of that note-type can exist for a Finding.
+        - is_mandatory - If true, a Finding has to have at least one note from the note-type in order to close it.
+
+    If note-types are enabled, User has to first select the note-type from the "Note Type" drop down and then add the           contents of the note.
 
 .. _finding_pics:
 
@@ -666,3 +679,68 @@ When importing a report using the APIv2 api/v2/import-scan/:
     * skip_duplicates : if true, duplicates are not inserted at all
     * close_old_findings : if true, findings  that are not duplicates and that were in the previous scan of the same type (example ZAP) for the same product (or engagement in case of  "Deduplication on engagement") and that are not present in the new scan are closed (Inactive, Verified, Mitigated)
     * if skip_duplicates and close_old_findings are both false, not deduplication is done
+
+Google Sheets Sync
+------------------
+With the Google Sheets sync feature, DefectDojo allow the users to export all the finding details of each test into a separate Google Spreadsheet. Users can review and edit finding details via Google Spreadsheets. Also, they can add new notes to findings and edit existing notes using the Google Spreadsheet. After reviewing and updating the finding details in the Google Spreadsheet, the user can import (sync) all the changes done via the Google Spreadsheet into DefectDojo database.
+
+Configuration
+`````````````
+Creating a project and a Service Account
+ 1. Go to the `Service Accounts page <https://console.developers.google.com/iam-admin/serviceaccounts/>`_.
+ 2. Create a new project for DefectDojo and select it.
+ 3. Click **+CREATE SERVICE ACCOUNT**, enter a name and description for the service account. You can use the default service account ID, or choose a different, unique one. When done click Create.
+ 4. The **Service account permissions (optional)** section that follows is not required. Click **Continue**.
+ 5. On the **Grant users access to this service account** screen, scroll down to the **Create key** section. Click **+Create key**.
+ 6. In the side panel that appears, select the format for your key as **JSON**
+ 7. Click **Create**. Your new public/private key pair is generated and downloaded to your machine.
+
+Enabling the required APIs 
+ 1. Go to the `Google API Console <https://console.developers.google.com//>`_.
+ 2. From the projects list, select the project created for DefectDojo.
+ 3. If the APIs & services page isn't already open, open the console left side menu and select **APIs & services**, and then select **Library**.
+ 4. **Google Sheets API** and **Google Drive API** should be enabled. Click the API you want to enable. If you need help finding the API, use the search field.
+ 5. Click **ENABLE**.
+
+Configurations in DefectDojo
+ 1. Click 'Configuration' from the left hand menu.
+ 2. Click 'Google Sheets Sync'.
+ 3. Fill the form.
+
+    .. image:: _static/google_sheets_sync_1.png
+       :alt: Google Sheets Sync Configuration Page
+
+    a. Upload the downloaded json file into the **Upload Credentials file** field.
+    b. Drive Folder Id
+
+       a. Create a folder inside the Google drive of the same gmail account used to create the service account.
+       b. Get the **client_email** from the downloaded json file and share the created drive folder with client_email giving **edit access**.
+       c. Extract the folder id from the URL and insert it as the **Drive Folder Id**.
+
+          .. image:: _static/google_sheets_sync_2.png
+             :alt: Extracting Drive Folder ID
+
+    c. Tick the **Enable Service** check box. (**Optional** as this has no impact on the configuration, but you must set it to true inorder to use the feature. Service can be enabled or disabled at any point after the configuration using this check box)
+    d. For each field in the finding table there are two related entries in the form.
+
+       a. In the drop down, select Hide if the column needs to be hidden in the Google Sheet, else select any other option based on the length of the entry that goes under the column.
+       b. If the column needs to be protected in the Google Sheet, tick the check box. Otherwise leave it unchecked. 
+ 4. Click 'Submit'.
+
+Admin has the privilege to revoke the access given to DefectDojo to access Google Sheets and Google Drive data by simply clicking the **Revoke Access** button.
+
+Using Google Sheets Sync Feature
+````````````````````````````````
+Before a user can export a test to a Google Spreadsheet, admin must Configure Google Sheets Sync and **Enable** sync feature.Depending on whether a Google Spreadsheet exists for the test or not, the User interface displayed will be different.
+
+If a Google Spreadsheet does not exist for the Test:
+
+.. image:: _static/google_sheets_sync_3.png
+  :alt: Create Google Sheet Button 
+
+If a Google Spreadsheet is already created for the Test:
+
+.. image:: _static/google_sheets_sync_4.png
+  :alt: Sync Google Sheet Button
+
+After creating a Google Spreadsheet, users can review and edit Finding details using the Google Sheet. If any change is done in the Google Sheet users can click the **Sync Google Sheet** button to get those changes into DefectDojo.