General Use Case

If you leverage Google's GMail (TM) service, you may want an easy way to forward mail to Blue Lantern Security. If you prefer a one-click approach you may want to leverage an Add-on within the GMail UI. This is currently not avaialble on the google marketplace for addons and the code is provided to the user as is with no gaurantees.

Note: One alternative method is to forward the mail as an attachment to the phishing mailbox: [email protected] to file under your personal account, or <account-id>@bluelanternsecurity.io to file under a shared account (see the Email Threat Analyzer doc). The mailbox performs both a static malware check on attachments and a phishing assessment, while the add-on described in this document only runs the phishing assessment.

Where to gather the code

We provide this google appscript which can be copied and deployed on your own GMail account. The script is located at this link: https://script.google.com/d/15ZZNr5Lb9M-FNIUVnA_aYW212ZBQ1ahbOMsZw4W2Q5Fc5U9GXwe5qtcQ/edit?usp=sharing

There are two crtical files:

1. appsscript.json - This file configures the permissions the app needs to run properly, which includes reading a selected email message and the permission to send the data externally to our APIs.
2. Code.gs - This code handles the integration with the UI to allow API key collection/storage and then the handling of sending the desired email to Blue Lantern Security's APIs.

Gmail Add-on — Self-Deployment Guide

The following steps walk you through deploying the Gmail Add-on yourself using Google Apps Script. No special tools or access are required beyond a Google account.

Prerequisites

• A Google account (personal or Workspace)
• Access to Google Apps Script
• Approximately 10–15 minutes

Step 1: Create a New Apps Script Project

1. Go to https://script.google.com.
2. Click New project in the top-left corner.
3. Give the project a name (e.g., Gmail Add-on) by clicking the default title ("Untitled project") at the top.

Step 2: Add the Project Files

Your project needs two files: appsscript.json and Code.gs.

2a. Enable the Manifest File

The appsscript.json file is hidden by default. To show it:

1. In the Apps Script editor, click Project Settings (the gear icon ⚙️ on the left sidebar).
2. Check the box labeled "Show 'appsscript.json' manifest file in editor".
3. Return to the Editor tab (the < > icon).

2b. Replace appsscript.json

1. In the left file panel, click on appsscript.json.
2. Select all existing content and delete it.
3. Paste in the following content:

{
  "timeZone": "America/New_York",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.execute",
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://mail.google.com/"
  ],
  "gmail": {
    "name": "Gmail Add-on",
    "logoUrl": "https://www.gstatic.com/images/icons/material/system/2x/email_black_48dp.png",
    "contextualTriggers": [
      {
        "unconditional": {},
        "onTriggerFunction": "buildAddOn"
      }
    ],
    "primaryColor": "#4285F4",
    "secondaryColor": "#DB4437"
  }
}

2c. Replace Code.gs

1. In the left file panel, click on Code.gs.
2. Select all existing content and delete it.
3. Paste in the full contents of Code.gs from the source project.

Step 3: Save the Project

Press Ctrl+S (Windows/Linux) or Cmd+S (Mac), or click the Save icon (💾) in the toolbar.

Step 4: Deploy as a Gmail Add-on (Test Deployment)

Before publishing, install the add-on for yourself as a test deployment.

1. Click Deploy in the top-right corner.
2. Select Test deployments.
3. In the dialog, click Install.
4. Review and accept the permission prompts (Google will ask you to authorize the scopes defined in appsscript.json).
5. Click Done.

Step 5: Authorize the Add-on

The first time you run the add-on, Google will ask you to grant permissions:

1. Open Gmail in a new tab.
2. Open any email — you should see the add-on icon appear in the right sidebar.
3. Click the add-on icon.
4. If prompted, click Authorize Access and follow the OAuth flow.
5. Grant the requested permissions.

Troubleshooting

Updating the Add-on

If the source project is updated and you receive new file contents:

1. Open your Apps Script project at https://script.google.com.
2. Replace the contents of the relevant file(s) (Code.gs and/or appsscript.json).
3. Save the project.
4. For a test deployment, changes are reflected immediately.
5. For a versioned deployment, go to Deploy → Manage deployments → Edit and create a new version.

Resources

• Google Apps Script Documentation
• Gmail Add-ons Overview
• Manage Add-on Deployments
• clasp CLI Tool — for managing scripts from the command line