Overview

Goby has built-in expansion capabilities. Under the extension API blessing, the goby-supported parts can be customized or enhanced.

This document includes following items:
• How to build, run, debug, test and release extensions.
• How to use goby’s extensions and API better.
Guidelines and code example which help you get started quickly.

What can extensions do?

If you want to have a general overview of all APIs, please refer to the function overview. The extension has included code example and guide.

How to build an extension?

It’s not easy to make a good extension. Let’s take a look at what each chapter of this tutorial can do:
Get started We will give you a "Hello World" example to get started.
Extension development Contains various extension development processes, such as testing, packaging and publishing etc.
Extension functions We disassembled goby’s API into several parts to help you get the development details for each scene.
Example Includes code example and guide. Detailing specific API usage.
Appendix Including the details of goby API, contributors and other extra information.

Get started

Your first extension

In this section, you will learn some basic concepts.Please install debug goby first (Windows MacOS Linux). After that, you need to download a project from (helloWorld). Unzip it under directory goby/extensions then start goby.

Click "Start scan", you will find a hello button at the top of the pop-up window, click the button, if another pop-up windows with "Hello world" appears. Congratulations! You have finished this Step.

Extension Development

Now let’s change the pop-up information:
• Make sure you are in the "goby/extensions/helloWorld/src/" directory
• Edit file "extension.js", replace "helloWorld" in function "goby.showInformationMessage" with "helloGoby"
• Restart goby, click the hello button.

Now you should seen the changed information:

Use JavaScript

In the document we mainly use JavaScript to develop goby extensions.

Resolving extension structure

In last section, you have learned create a new basic extension by yourself. But how does it work?

The next two concepts will help you:
Publishing configuration:goby expands the fields of package.json (extension list) to facilitate the development of extensions.
Goby API:your extension code depends on various JavaScript API.

In general, your extension is to extend the goby’s function by combining publishing content configuration and goby API. You can find appropriate contributions and goby API for your extensions in the "Overview of extension functions".

Now let’s take a look of the example code in "helloWorld", And how the two concepts we mentioned above are applied.

Extension directory structure

        
          ├── .gitignore          // Ignore build output and node_modules 
          ├── README.md           // Help document
          ├── CHANGELOG.md        // Update log file
          ├── src
          │   └── extension.js    // Source code
          ├── package.json        // extension configuration list
        
      

Now let’s concentrate on the key parts of the extension——package.json and extensions.js

extension list

Every goby extension must contain package.json, That is the extension configuration list. Package.json includes some of Node.js keywords. Such as scripts, dependencies, also added some goby unique fields, such as publisher, initEvents, contributes etc. All this could be found in reference of extension list. We only introduce some important fields in this section.

name: The extension’s name.
publisher: The publisher’s name. Goby will combine "publisher" and "name" as a extension’s ID.
main: The main entrance of extension.
initEventscontributes: Initialize event and publish configurations.
engines: Describes the lowest version of goby that this extension depends on.

        
          {
            "name": "helloWorld",
            "publisher": "goby",
            "description": "helloWorld by goby",
            "version": "0.1.0",
            "icon": "",
            "engines": "1.6.170",
            "initEvents": "",
            "main": "./src/extension.js",
            "contributes": {
              "views": {
                "scanDia": [
                  {
                    "command": "hello",
                    "title": "hello"
                  }
                ]
              }
            },
            "scripts": {},
            "devDependencies": {},
            "dependencies": {}
          }
        
      

Extension’s entry file

Entry file need to export function activate, When the extension is installed successfully, this function will be executed.

        
          function activate (content) {
            goby.registerCommand('hello', function (content) {
              goby.showInformationMessage("helloWorld");
            });
          }
          
          exports.activate = activate;
        
      

Summary

In this section, you learned how to create, run and debug extensions, and also learned the basic concepts of goby extension development. But this is only a beginner's guide. how to develop extensions will be explained in further detail in later sections.

Extension development

Testing extensions

The development version of goby provides running and debugging capabilities for extension development. Just put your extension into the goby/extensions directory, and start goby.

You can click the view button, choose toggle developer tools to open the console.

Publishing

Functions:
• User registration
• Packing
• Publishing
• Deleting

User registration

Before publishing, you should register first.

Packing

We only accept ".zip" format packages currently, you can convert it and upload by yourself or use automatic packaging (Please refer to the next section, we will tell you how to pack your extensions).

Warning: the entire extension folder must be packaged when packaging, that means after performing automatic decompression, make sure that the directory structure of the entire extension is complete.

Publishing

After login, you can publish your extensions from personal center-Extensions management, when zip archive uploaded, we will have specialized personnel to review, after passing the review, the extension will appear in the market list.

Deleting

You can delete extension in the personal center.

Packaging extensions

As mentioned before, when the goby extension is submitted, only zip format upload is supported. As for JavaScript, there are many optional packaging tools. This section mainly demonstrates the use of jszip for packaging.

1. Install the jszip package first

        
          npm install jszip
        
      

2. Then, create build.js in your extension directory

        
          var JSZip = require('jszip');
          var fs = require('fs');
          var path = require("path");
          var zip = new JSZip();

          // packaging files
          zip.file("package.json", fs.readFileSync(__dirname+"/package.json"));
          zip.file("CHANGELOG.md", fs.readFileSync(__dirname + "/CHANGELOG.md"));
          zip.file("README.md", fs.readFileSync(__dirname + "/README.md"));

          // package files in the folder
          var src = zip.folder("src");
          src.file("extension.js", fs.readFileSync(__dirname + "/src/extension.js"));

          // compress
          zip.generateAsync({
            // select nodebuffer as the compression type,it will return the value of zip file in callback functions ,and then use fs to save to local disk.
            type: "nodebuffer"
          }).then(function (content) {
            let zip = '.zip';
            // write into disk
            fs.writeFile(__dirname + zip, content, function (err) {
              if (!err) {
                // if written successfully
                console.log('压缩成功');
              } else {
                console.log('压缩失败');
              }
            });
          });
        
      

3. Finally, execute the packaging command in the extension directory. You will see the packaged zip file in goby/extensions.

        
          node ./build.js
        
      

Additionally, jszip is just one of the packaging methods, you can choose your favorite instead.

Extension Functions

Overview

Goby provides some methods for extensions to extend the capabilities. But sometimes it is not easy to find the appropriate publishing configuration and goby API. This section contains following parts:

• Available function for extension.
• Some inspiration

However, we will also tell you some limit, such as: extensions cannot modify the underlying DOM of goby UI.

Common Functions

Common functions are the core functions you may use in any extension.

Including:

• Registration order
• Configure the entry point for views
• Use custom views
• Configure extension settings
• Notifications
• Event Notifications

Extension workbench

The extension workbench is the view entry point that user can customized, it can enhance the function of goby. For example, you can add new button on the pop-up window. By clicking the corresponding button. You can also import specify IP from other location, adding buttons on the banner list interface, or sending HTTP packet to current IP, even create a custom HTML page for easy use.

Inspiration
• Customize the operation buttons and interactive behaviors at the top of the scan pop-up window
• Customize the operation buttons and interactive behaviors of the banner list of the IP details page
• Use "goby.showIframeDia" method to display custom page content

Limit

The extension does not have permission to access the underlying DOM of the goby UI, and it is forbidden to add custom CSS and HTML fragments to the goby UI.

Common functions

Common functions are very important to your extensions. Almost all extensions will use these functions more or less. This section will briefly introduce them for you.

Commands

Commands are the core of extension, for all the entry points of your customized view, the functions bound to it must be commands.

The goby.registerCommond is indispensable for all extensions to register commands.

View entry point

Users can customize the buttons at the top of the pop-up window, You can also customize the toolbar extension buttons. Currently goby cannot support much, you can see more in contributions.views.

Custom view

In many cases, only configuring the view entry point is not enough for users. For example, you want to display a custom page which is searchable by clicking the button on the pop-up window, and let the user operate (edit, select) by himself. You need to use a custom view to achieve. Currently goby provides the following APIs to display custom pages:

• Use the goby.showIframeDia method to display the content of a custom page. In goby, your page will be embedded in a pop-up window for display. The title, width and height of the window can be set by parameters.

• You can also use the goby.showPagemethod to display the content of a custom page. Goby will embed your page on the right side and this page can run in the background.

Extension settings

Most extensions will be open for users. If you have this requirement, just fill in the relevant configuration items in contributions.configuration.

At the same time, you can get the extension configuration item from goby.getConfiguration, you can also modify it from goby.setConfiguration.

Notification

Almost all extensions need to prompt users at some point. Goby provides 4 APIs to display information of different importance.

goby.showInformationMessage
goby.showWarningMessage
goby.showErrorMessage
goby.showSuccessMessage

Event Notifications

In many cases, extensions need to participate in the scanning process and trigger some events when the scanning status changes, or obtain real time scan data. At this time, you can bind event notifications by goby.bindEvent.

Extension workbench

Workbench refers to the entire goby UI, the current configurable parts are as follows:

• Pop-up scan page - scanDia
• Scan result page - scanRes
• Drop-down menu - moreOptions (Deprecated in:v 1.8.237)
• IP detail page - ipDetail
• The title bar of the banner list - bannerTop
• Vulnerability list - vulList
• Webfinder page - webfinder
• Left navigation - page-leftNav (New in:v 1.8.225   Deprecated in:v 1.8.237)
• toolbar - toolbar (New in:v 1.8.230  )

Pop-up scan page - scanDia

Modify contributes.views.scanDia in the extension list to add custom components to the top of the pop-up scan page. As shown below:

There is also a simple example for learning about the specific use of scanDia, see the next scanDia part below for more details.

Scan result page - scanRes

Drop-down menu - moreOptions

Deprecated in:v 1.8.237

By modifying contributions.views.scanRes.moreOptions in the extension list, you can add custom components to the drop-down menu of the scan results, and the same components will also appear in the asset list and vulnerability list pages. As shown below:

There is also a simple example for learning about the specific use of moreOptions, see the next scanRes part below for more details.

IP detail page - ipDetail

The title bar of the banner list - bannerTop

Modifying contributions.views.ipDetail.bannerTop in the extension list to add custom components to the title bar of the banner list of the IP details page. As shown below:

There is also a simple example for learning about the specific use of bannertTop, see the next ipDetail part below for more details.

Vulnerability list - vulList

Modify the contributions.views.vulList in the extension list to add custom components to the pages related to the vulnerability list. As shown below:

There is also a simple example for learning about the specific use of vulList, see the next ipDetail part below for more details.

Webfinder page - webfinder

Modify the contributions.views.webfinder in the extension list to add custom components to the pages related to the webfinder page. As shown below:

There is also a simple example for learning about the specific use of webfinder, see the next webfinder part below for more details.

Left navigation page - leftNav

New in:v 1.8.225   Deprecated in:v 1.8.237

You can configure contributes.views.leftNav in the extension list to add custom components to the left navigation bar. The specific location is as follows:

There is also a example for learning about the specific use of Left-nav, see the left navigation page for details.

toolbar - toolbar

New in:v 1.8.230  

Modify contributes.views.toolbar in the extension list to add custom components to the toolbar. The specific location is as follows:

There is also a simple example for learning about the specific use of toolbar, see the next scanDia part below for more details.。

Extension example

Overview

In the extension function section, document introduced what extension can do. This section details each function and provides detailed code examples.

In this section you will learn:
• List of goby APIs used
• List of contributions (published content configuration) used
• Gif or image of the sample extension

Pop-up scan page - scanDia

The configuration of the scan pop-up window allows users to customize the processing and operation of scan. This example is mainly to add a button in the scan pop-up window, click to display a custom page. In this page, you can perform FOFA query, get the scanned object, and import IP and port from object.

Download link

FOFA

Goby API used

goby.registerCommand
goby.showIframeDia
goby.closeIframeDia
goby.getConfiguration
goby.showConfigurationDia
goby.addScanIps
goby.addScanPorts
goby.showInformationMessage
goby.showErrorMessage
goby.showSuccessMessage

Example

First, you need to register the command to be triggered by the custom component.

        
          function activate(content) {
            goby.registerCommand('fofa', function () {
              // get extension configuration
              let config = goby.getConfiguration();
              let email = config.email.default;
              let key = config.key.default;
              if (email && key) {
                let path = __dirname + "/fofa.html"
                // display custom page
                goby.showIframeDia(path, "fofa查询", "666", "500");
              } else {
                // display extension pop-up configuration
                goby.showConfigurationDia();
              }
            });
          }
          
          exports.activate = activate;
        
      

Second, you need to configure the corresponding view entry point in package.json, function name is contributions.views.scanDia, and fill in the required fields(title, command, icon).

        
          {
            "contributes": {
              "views": {
                "scanDia": [
                  {
                    "command": "fofa",
                    "title": "FOFA",
                    "icon": "src/assets/img/fofa.png"
                  }
                ]
              }  
            }
          }
        
      

Third, because we have used FOFA for collecting, we need to add FOFA account and key to configuration files, just modify contributes.configuration in package.json.

        
          {
            "contributes": {
              "configuration": {
                "email": {
                  "type": "string",
                  "default": "",
                  "description": "fofa email"
                },
                "key": {
                  "type": "string",
                  "default": "",
                  "description": "fofa key"
                }
              }
            }
          }
        
      

Fourth, after using the custom component, to display the specific interface, you can use goby.showIframeDia to transfer the html page.

Attention! When using the goby API object in a custom HTML page, it must be obtained through the "parent.goby" function.

If you want know more, you can download the code to view the details.

The final effect is shown below:

Scan result page - scanRes.moreOptions

Deprecated in:v 1.8.237

This page allows users to customize the processing and operation of the scanned results. Let's look at a simple example below. This example is used to add a button in the drop-down menu on the scan result page, the button can export selected items to csv file.

Download link

ExportCsv

Goby API used

goby.registerCommand
goby.showIframeDia
goby.closeIframeDia
goby.getTaskId
goby.getAsset
goby.showInformationMessage
goby.showErrorMessage
goby.showSuccessMessage

Example

First, you need to register the command to be triggered by the custom component.

        
          function activate(content) {	
            goby.registerCommand('ExportCsv', function () {
              let path = __dirname + "/index.html"
              goby.showIframeDia(path, "导出", "334", "210");
            });
          }
          
          exports.activate = activate;
        
      

Second, you need to configure the corresponding view entry point in package.json, function name is contributes.views.scanRes.moreOptions, and fill in the required fields(title, command, icon).

        
          {
            "views": {
              "scanRes": {
                "moreOptions": [
                  {
                    "command": "ExportCsv",
                    "title": "ExportCsv",
                    "icon": "src/assets/img/import.png"
                  }
                ]
              }
            }
          }
        
      

Third, after using the custom component, to display the specific interface, you can use goby.showIframeDia to transfer the html page.

If you want know more, you can download the code to view the details.

The final effect is shown below:

IP detail page - ipDetail.bannerTop

This page allows users to customize the processing and operation of the IP details page. Let's look at a simple example below. This example is mainly to add a button in the banner list of the IP details page, click it to send HTTP packets.

Download link

Http

Goby API used

goby.registerCommand
goby.showIframeDia

Example

First, you need to register the command to be triggered by the custom component.

        
          function activate(content) {
            goby.registerCommand('http', function (content) {
              let path = __dirname + "/http.html?hostinfo=" + content.hostinfo;
              goby.showIframeDia(path, "http发包", "441", "188");
            });
          }
          
          exports.activate = activate;
         
      

Second, you need to configure the corresponding view entry point in package.json, function name is contributes.views.ipDetail.bannerTop, and fill in the required fields(title, command, icon).

        
          "contributes": {
            "views": {
             "ipDetail": {
                "bannerTop": [
                  {
                    "command": "http",
                    "title": "Http发包",
                    "icon": "src/assets/img/http.png"
                  }
                ]
             }
            }
           }
        
      

Third, after using the custom component, to display the specific interface, you can use goby.showIframeDia to transfer the html page.

If you want know more, you can download the code to view the details.

The final effect is shown below:

Vulnerability list - vulList

This page allows users to customize the processing and operation of the vulnerability. Let’s look at a simple example. This example is mainly based on whether the current vulnerability name is in the custom list, display the MSF utilization button dynamically. Click the button to call the local Metasploit framework to detect the vulnerability.

Download link

MSF Sploit

Goby API used

goby.registerCommand
goby.getConfiguration
goby.setConfiguration
goby.showInformationMessage
goby.showErrorMessage

Example

First, you need to register the command to be triggered by the custom component. Different from the previous examples is that the callback command controls the component’s visibility. It is bound to the visible field of views and determines whether to display the component according to the returned Boolean value.

        
          let cp = require('child_process');
          const os = require('os');
          const fs = require('fs');

          function activate (content) {
              // msf correspondence
              let identical = {
                  "Eternalblue/DOUBLEPULSAR MS17-010 SMB RCE": "exploit/windows/smb/ms17_010_eternalblue"
              };

              // Click to trigger the command
              goby.registerCommand('msf', function (content) {
                  let config = goby.getConfiguration();
                  console.log(config)
                  let ip = content.hostinfo.split(':')[0];
                  let arr = ['C:/metasploit-framework/bin/msfconsole.bat', 'D:/metasploit-framework/bin/msfconsole.bat', 'C:/metasploit-framework/msfconsole'];

                  let urlDefault = '';
                  if (config.url.default) {
                      urlDefault = config.url.default
                  } else {
                      let isExistence = arr.filter(v => {
                          return fs.existsSync(v)
                      })
                      urlDefault = isExistence[0];
                      goby.setConfiguration("url", urlDefault)
                  }

                  if (!urlDefault) return goby.showInformationMessage('Please set the plug-in installation path');

                  let url = `${urlDefault} -x "use ${identical[content.name]}; set rhosts ${ip} ; run"`
                  if (os.type() == 'Windows_NT') {
                      //windows
                      cp.exec(`start ${url}`)
                  } else if (os.type() == 'Darwin') {
                      //mac
                      cp.exec(`osascript -e 'tell application "Terminal" to do script "${url}"'`)
                  } else if (os.type() == 'Linux') {
                      //Linux
                      cp.exec(`bash -c "${url}"`)
                  }
              });

              // callback command controls the visibility
              goby.registerCommand('msf_visi', function (content) {
                if (identical[content.name]) return true;
                return false;
              });
          }

          exports.activate = activate;
        
      

Second, you need to configure the corresponding view entry point in package.json, function name is contributes.views.vulList, and fill in the required fields(title, command and callback command).

        
          "contributes": {
            "views": {
              "vulList": [
                {
                  "command": "msf",
                  "title": "MSF",
                  "visible": "msf_visi"
                }
              ]
            }
          }
        
      

Third, because it will call the local Metasploit, you need to modify the configuration which contains Metasploit’s installation path. Just add path to contributes.configuration in package.json.

        
          "contributes": {
            "configuration": {
              "url": {
                "type": "string",
                "default": "",
                "description": "请输入插件地址"
              }
            }
          }
        
      

If you want know more, you can download the code to view the details.

The final effect is shown below:

Webfinder page - webfinder

The webfinder page allows users to customize the processing and operation of the scanned web list. Let’s look at a simple example. In this example, just click the button on the webfinder page to display hostinfo.

Download link

Webfinder

Goby API used

goby.registerCommand
goby.showIframeDia
goby.closeIframeDia

Example

First, you need to register the command to be triggered by the custom component.

        
          function activate(content) {
            goby.registerCommand('webfinder', function (content) {
              let path = __dirname + "/index.html?hostinfo=" + content.hostinfo;
              goby.showIframeDia(path, "webfinder", "441", "188");
            });
          }

          exports.activate = activate;
        
      

Second, you need to configure the corresponding view entry point in package.json, function name is contributes.views.webfinder, and fill in the required fields(title, command).

        
          "contributes": {
            "views": {
            "webfinder": [
                {
                  "command": "webfinder",
                  "title": "webfinder",
                  "icon": "src/assets/img/logo.png"
                }
              ]
            }
          }
        
      

If you want know more, you can download the code to view the details.

The final effect is shown below:

Left navigation page - leftNav

New in:v 1.8.225   Deprecated in:v 1.8.237

The navigation page on the left allows users to execute the extensions globally to perform custom processing and operations during the process. We will show you an example. This example is mainly on the left navigation page, click the button to call the showPage API and the bindEvent API on the custom page,so that you can get data and filter them.

Download link

Database Asset

Goby API used

goby.registerCommand
goby.showPage
goby.bindEvent
goby.changeBadge

Example

First, you need to register the command to be triggered by the custom component.

        
          function activate(content) {
            goby.registerCommand('left-nav',function(){
              goby.showPage('./assets/index.html',true);	
            })
          }
          
          exports.activate = activate;
        
      

Secondly, you need to configure the corresponding view entry point in package.json which is also called contributions.views.leftNav, then edit the title and corresponding command you want.

        
          "contributes": {
            "views": {
            "leftNav": [
                {
                  "command": "left-nav",
                  "title": "Database",
                  "icon": "src/assets/img/logo.png"
                }
              ]
            }
          }
        
      

Thirdly, after clicking the custom component, you can use goby.showPage to display the user-defined interface, This function can also use to pass the html page path. Both absolute path and relative path are supported. The second parameter is whether to run this page in the background.

          
          goby.showPage('./assets/index.html',true);	
        
      

Attention: when using the goby API object in the custom page provided by goby.showPage, there is no need to obtain it through parent.goby(This function is not recommended here).

Fourth, because goby.bindEvent is called in the showPage function, this command needs to be configured in initEvents parameters in package.json.

        
          {
            "name": "Database Asset",
            "publisher": "Goby Team",
            "description": "实时统计扫描过程中有数据库(目前仅支持mysql,redis,MongoDB,Elasticsearch)资产的ip信息,并且可以查看详情",
            "initEvents": ["left-nav"]
          }
        
      

Fifth, when the scan started, filter the returned data, display the corresponding data, and call goby.changeBadge to display the summary of current task.

Currently, the first parameter only supports leftNav, the second parameter is the command corresponding to the marked position, and the third parameter is the content displayed by Badge.

        
          //num is the amount of eligible data
          
          goby.changeBadge('leftNav','left-nav',num);
        
      

If you want know more, you can download the code to view the details.

The final effect is shown below:

toolbar - toolbar

New in:v 1.8.230  

The configuration of the toolbar allows users to call the extensions globally. Let's look at a simple example below. This example is mainly to add a button in the toolbar, click the operation to generate a task queue.

Download link

Task Queue

Goby API used

goby.registerCommand
goby.showIframeDia
goby.getScanState
goby.bindEvent
goby.startScan
goby.getPortList
goby.getVulnerabilityList
goby.getOrderList

Example

First, you need to register the command to be triggered by the custom component.

	    
			function activate(content) {
				goby.registerCommand('addTask', function (content) {
					let path = require('path');
					let url = path.join(__dirname,'./assets/taskQueue.html');
					goby.showIframeDia(url,'Task Queue',666,600);
				});
			}
      
			exports.activate = activate;
	    
	  

Second, you need to configure the corresponding view entry point in package.json, function name is contributions.views.toolbar, and fill in the required fields(title, command, icon).

	    
			"contributes": {
				"views": {
					"toolbar": [
						{
							"command": "addTask",
							"title": "Task Queue ",
							"icon": "src/assets/img/logo2.png",
							"tips":"Task Queue"
						}
					]
				}
			}
	    
	  

Fourth, after using the custom component, to display the specific interface, you can use goby.showIframeDia to transfer the html page.

If you want know more, you can download the code to view the details.

The final effect is shown below:

Appendix

Goby API

About commands

The goby API is a series of JavaScript APIs provided for goby extension developers. All goby APIs are as follow:

registerCommand

Registration command, the command name of different extensions can be the same.

Watch the video to learn more

Request
Parameter Type Default Required Description
name String Yes Name of command
callback(content) Function Yes The callback function of the command. The callback function will return the value of content, and varies according to the views (view entry point) bound by the command
callback(content)
views(view Entry Point) Existence Type Example Description
scanDia False
scanRes.moreOptions False Deprecated in:v 1.8.237
toolbar False
ipDetail.bannerTop True Object { hostinfo: "80.241.214.220:25", port: "25", protocol: "smtp" } hostinfo: host information;
port: port;
protocol: protocol
vulList True Object { "hostinfo":"127.0.0.1", "name":"Eternalblue/DOUBLEPULSAR MS17-010 SMB RCE", "filename":"smb_ms17_010.json", "level":"3", "vulurl":"", "keymemo":"", "hasexp":false } hostinfo: host information;
name: Vulnerability name;
filename: Vulnerability file name;
level: Threat level;
vulurl: vulnerability link location

About UI

showIframeDia

Show the pop-up window of the embedded iframe.

If you need to use goby API in a custom html page, you must call parent.goby to get the instance object.

Request
Parameter Type Default value Required Description
url String Yes Source address of iframe
title String No Title of iframe
width Number 666 No Width of iframe
height Number auto No Height of iframe,the maximum height is 500, if exceeds show scroll bar

closeIframeDia

Close the pop-up window.

showPage

New in 1.8.225+

The custom page provided by showPage does not need to use parent.goby to obtain the instance object, goby can be used directly.

Watch the video to learn more

Request
Parameter Type Default Value Required Description
url String Yes The url of the custom page supports absolute and relative paths. If you need an absolute path, you can use __dirname and __filename to get the current directory and file path for splicing
background Boolean false N whether the opened page is running in the background, if it is true, the page will not be reloaded every time when access the page, otherwise not.

openExternal

New in 1.8.225+

Open the url link in the browser

Watch the video to learn more

Request
Parameter Type Default Value Required Description
url String Yes The url link in browser, the link must contain http, https, localhost or file protocol.

changeBadge

New in 1.8.225+

Modify the number or status of the button or icon

Watch the video to learn more

Request
Parameter Type Default Value Required Description
placement String Yes marked position,v 1.8.225-v 1.8.230 only supports leftNav,v 1.8.237+ only supports toolbar.
command String Yes The command corresponding to the mark position, if it is the mark of the extension's entry point, the command will bind to entry point's command.
content String | Number No Mark the displayed content, support Number and String. String can pass html fragments, the default is empty.

flashFrame

New in v 1.8.239+

Starts or stops flashing the window to attract user's attention

Request
Parameter Type Default Required Description
isFlash Boolean Yes true:Starts flashing the window ;false: stops flashing the window

isFocused

New in v 1.8.239+

Whether the Goby window is focused

Response
Response Type Example Description
isFocused Boolean true | false true:Goby window is focused; false:Goby window is not focused

About configuration

getConfiguration

Get the configuration of the current extension.

Request
Parameter Type Default Value Required Description
name String No The obtained extension configuration field name
Response
Response Type Description
value Object/String Show the requested configuration of extension, if name is NULL show all

setConfiguration

Modify the configuration of current extension.

Request
Parameter Type Default Value Required Description
name String Yes The extension name you want to modify
value String Yes The extension value you want to modify

showConfigurationDia

The pop-up windows to show all configurations.

About notification

showInformationMessage

Show information message for users.

Request
Parameter Type Default value Required Description
message String Yes Display information content

showWarningMessage

Show warning message for users.

Request
Parameter Type Default value Required Description
message String Yes Display information content

showErrorMessage

Show error message for users.

Request
Parameter Type Default value Required Description
message String Yes Display information content

showSuccessMessage

Show success message for users.

Request
Parameter Type Default value Required Description
message String Yes Display information content

About task

getTaskId

Get current task ID

Response
Response Type Description
taskId String Current task ID

getScanState

New in 1.8.230+

Get current scan status

Response
Response Type Example Description
scanState Object {state:0,progress:100} state:current scan status,0:Not started;1:Scanning;2:Scan complete;3:Scanning is stopping;4:Scanning aborted (pause);5:Exception found
progress:current task progress

getAsset

Get all asset data of the current task.

Request
Parameter Type Default value Required Description
taskId String Yes Task ID
callback(result) Function Yes The callback function of asset data, result is all asset data of the current task
callback(result)
Property Type Description
statusCode Number Status code, 200 is OK
messages String Status information
data Object/null Object of asset data, if there is no data, return unll
result.data
Property Type Description
taskId String Task ID
query_total Object Total information for assets query
total Object Asset data statistics
ips Object Assets list
callback(result) return code example
        
            {
              "statusCode": 200,
              "messages": "",
              "data": {
                "taskId": "20200509004148",
                "query_total": {
                  "ips": 7,
                  "ports": 11,
                  "protocols": 13,
                  "assets": 8,
                  "vulnerabilities": 0,
                  "dist_ports": 11,
                  "dist_protocols": 12,
                  "dist_assets": 6,
                  "dist_vulnerabilities": 0
                },
                "total": {
                  "assets": 8,
                  "ips": 7,
                  "ports": 11,
                  "vulnerabilities": 0,
                  "allassets": 0,
                  "allips": 0,
                  "allports": 0,
                  "allvulnerabilities": 0,
                  "scan_ips": 0,
                  "scan_ports": 0
                },
                "ips": [{
                  "ip": "192.168.31.213",
                  "mac": "d4:61:9d:63:62:06",
                  "os": "",
                  "hostname": "",
                  "ports": null,
                  "protocols": {},
                  "tags": [{
                    "rule_id": "10000011",
                    "product": "Apple_Device",
                    "company": "Apple",
                    "level": "1",
                    "category": "Server",
                    "parent_category": "Network Device",
                    "soft_hard": "1"
                  }],
                  "vulnerabilities": null,
                  "screenshots": null,
                  "favicons": null,
                  "hostnames": [""]
                }]
              }
            }
        
      

addScanIps

Add ips to scan array.

Request
Parameter Type Default value Required Description
ips Array Yes Ips array you want to add
type Number Yes The way of adding;0 is append, 1 is overwrite

addScanPorts

Add ports to scan array.

Request
Parameter Type Default value Required Description
ports Array Yes Ports array you want to add
type Number Yes The way of adding;0 is append, 1 is overwrite

getPortList

New in 1.8.230+

Get the list of goby's built-in and custom ports

Response
Response Type Description
portList Promise This is a Promise object. You can capture the data of success and failure through 'then' and 'catch' respectively, or it can be obtained through 'async' and 'await' in es8.

Example of returning Promise object data (partial)

	  	
			{
				statusCode:200,	        //Status code, 200 is OK
				message:"",		//Status information
				data:[
					{
						type:"Minimal",
						value:"21,22,80,U:137,U:161,443,445,U:1900,3306,3389,U:5353,8080"
					},
					{
						type:"Backdoor Check",
						value:"50050"
					}
				]
			}
		
	  

getVulnerabilityList

New in 1.8.230+

Get the list of built-in and custom vulnerabilities in goby

Response
Response Type Description
vulnerabilityList Promise This is a Promise object. You can capture the data of success and failure through 'then' and 'catch' respectively, or it can be obtained through 'async' and 'await' in es8.

Example of returning Promise object data (partial)

	  	
			{
				statusCode:200,	        //Status code, 200 is OK
				message:"",		//Status information
				data:[
					"General Poc",	//General Poc
					"Brute Force",	//Brute Force
					"Web Application Vulnerability",	//Web Application Vulnerability
					"Application Vulnerability",		//Application Vulnerability
					"All",	//all vulnerability
					"Disabled",	//disable function
					"ACME mini_httpd Arbitrary File Read (CVE-2018-18778)"
				]
			}
		
	  

In v 1.8.268+,Update the data information of the Promise object

Return Promise object data example (partial)

	  	
        {
          statusCode:200,   //Status code, 200 is OK
          message:"",	    //Status information
          data:[
            {
              "name":"General Poc",		//General Poc
              "vulnerabilityType":"0"		//Vulnerability scan type
            },
            {
              "name":"Brute Force",		//Brute Force
              "vulnerabilityType":"1"		//Vulnerability scan type
            },
            {
              "name":"Web Application Vulnerability",	//Web Application Vulnerability
              "vulnerabilityType":"4"			//Vulnerability scan type
            },
            {
              "name":"Application Vulnerability",	//Application Vulnerability
              "vulnerabilityType":"5"			//Vulnerability scan type
            },
            {
              "name":"All",             //All vulnerabilities
              "vulnerabilityType":"2" 	//Vulnerability scan type
            },
            {
              "name":"Disabled",        //Disabled
              "vulnerabilityType":"-1" 	//Vulnerability scan type
            },
            {
              "name":"ACME mini_httpd Arbitrary File Read (CVE-2018-18778)",
              "vulnerabilityType":"3"
            }
          ]
        }
	  		
	  

getOrderList

New in 1.8.230+

Get a list of scan sequences

Response
Response Type Description
OrderList Promise This is a Promise object. You can capture the data of success and failure through 'then' and 'catch' respectively, or it can be obtained through 'async' and 'await' in es8.

返回Promise对象数据示例

	  	
			{
				statusCode:200,     //Status code, 200 is OK
				message:"",	    //Status information
				data:[
					"Assets first", 	//assets first
					"Simultaneously"	//scan simultaneously
				]
			}
		
	  

startScan

New in 1.8.230+

Start a new task

Request
Parameter Type Default Value Required Description
Options Object Yes Information needed to start a scan task
Options
Property Type Default Value Required Description
ip Array Yes The ip or domain name of the task
port String Yes Scan task port, use "," to connect to different ports
vulnerability String General Poc No Vulnerabilities in task
order String Assets first No Scan sequence of task
taskName String No The name of the task

In v 1.8.268+ Options add vulnerabilityType and update vulnerability

Options
Parameter Type Default Value Required Description
vulnerabilityType Number 0 Yes Types of scan vulnerabilities
vulnerability Object {} No When vulnerabilityType is 3, this parameter is valid, and multiple vulnerabilities in the parameter can be selected, for example:{"Elasticsearch unauthorized":null,"Harbor Default Credentials":null},the value is currently only null
Response
Response Type Description
data Promise This is a Promise object. You can capture the data of success and failure through 'then' and 'catch' respectively, or it can be obtained through 'async' and 'await' in es8.
Example of returning Promise object data
	  		
				{
					statusCode:200,	//Status code, 200 is OK
					messages:"",	//Status information
					data:{
						taskId: "20201207192026"
					}
				}
	  		
	  

stopScan

New in 1.8.230+

Stop current scan

Response
Response Type Description
data Promise Returned information when scan stop,This is a Promise object. You can capture the data of success and failure through 'then' and 'catch' respectively, or it can be obtained through 'async' and 'await' in es8.
Example of returning Promise object data
	  		
				{
  
					statusCode:200,	//Status code, 200 is OK
					messages:"",	//Status information
					data:{
						taskId:"20201207192026"
					}
				}
	  		
	  

Event notification

bindEvent

New in 1.8.225+

Binding event notification

Watch the video to learn more

Request
Parameter Type Default Value Required Description
type String Yes Type of notification included︰onApp,onPort,onProtocol,onVulnerable,onStartScan,onEndScan,onBackIndex,onPauseScan,onContinueScan,onRescan,onRescanVulnerability
callback(content) Function Yes The callback function of the binding event, different types and content data are also different
Example of callback(content) Return data

The following types are related to the scanned data, and the content data returned is as follows:

type:onAPP, return App-related data

        
          {
            "hostinfo":"127.0.0.1:443",   
            "product":"Bootstrap"         
          }
        
      

type:onPort, return port-related data

        
          {
            "URL":"",
            "addition":"",
            "baseprotocol":"tcp",
            "ip":"127.0.0.1",
            "port":"80",
            "protocol":""
          }
        
      

type:onPortocol, return protocol-related data

        
          {
            "hostinfo":"127.0.0.1:80",
            "protocol":"http"
          }
        
      

type:onVulnerable, return vulnerable-related data

        
          {
            "hostinfo":"http://127.0.0.1",
            "vulnerable":false
          }
        
      

The following types are related to the scanning status, and the corresponding content data returned are consistent. Examples are as follows

type : onStartScan start scan

type : onEndScan stop scan

type : onPauseScan pause scan

type : onContinueScan continue scan

type : onBackIndex back to index page

type : onRescan restart scan

type : onRescanVulnerability restart vulnerability scan

        
          {
            "taskId":"20201113102303",  //task id
            "taskName":""               //task name
          }
        
      

type:onError,When an error occurs in Goby, return the error-related data

New in 1.8.239+

	  	
	  	  {
	  	    "taskId":"20201113102303",  //task id
	  	    "taskName":""               //task name
	        "statusCode":"501",         //Status code
	        "message":"service error"   //error message
	  	  }
	  	
	  

type : onChangeLang, When the Goby language changes, return to the current language

New in 1.8.292+

	    	
	  EN
	  	
	    

Language related

getLang

Get the current language of Goby

New in 1.8.292+

Response
Response Type Description
lang String Goby current language, for example: EN, CN, DE, JA, KO, FR

Publishing configuration

The publishing configuration is the contributions field in the extension list package.json, the format is JSON, this field contains two parts:

• configuration
• views

configuration

The content configured in the configuration allows user to modify the options you allow from the "extension settings".

Example

        
          "configuration": {
            "email": {
              "type": "string",
              "default": "",
              "description": "fofa email"
            },
            "key": {
              "type": "string",
              "default": "",
              "description": "fofa key"
            }
          }
        
      

You can use goby.getConfiguration to get configurations.

Extensions Settings

Your configuration content also determines the display mode in the goby settings UI.

Configuration field description

Field Type Description
Name String The Name of the configured JSON object is the position of 1 in the image, indicating the configured field name
Value Object The value of name

Value

Field Type Description
type String The type of configuration item, currently only supports String
default String The value of the configuration item, it is the position of 2 in the image
description String The description of the configuration item, it is the position of 3 in the image, the tips of the content will be displayed when you pass it
fromDialog Boolean Whether the configuration parameter can be set by reading the file path

views

Views are user-configurable entry points for custom views. The currently configurable UI parts are as follows:

• Pop-up scan page - scanDia
• Scan result page - scanRes
• Drop-down menu - moreOptions (Deprecated in:v 1.8.237)
• IP detail page - ipDetail
• The title bar of the banner list - bannerTop
• Vulnerability list - vulList
• Webfinder page - webfinder
• Left navigation page - LeftNav (New in:v 1.8.225   Deprecated in:v 1.8.237)
• toolbar - toolbar (New in:v 1.8.230)

Configuration field description

Field Type Default value Required Description
command String Yes Commands binding to views
title String No The text content displayed by the custom component
icon String No The text icon displayed by the custom component
tips String Displayed the default title, if the title field does not exist, display the extension name instead No The displayed tips when swipe over custom components
visible String Display No Commands that controls the display of custom components, Return true to display, return false to not display

Initialization

After the extension is installed successfully, if you want to perform some operations directly, you must use initialization events which is called initEvents. Then bind the name of the command to be executed, the name supports String and Array. If you want to execute multiple commands, you need to put the commands in the array one by one, goby will actively execute the specified command after installation.

Example

First, register the commands to be executed automatically

        
          function activate (content) {
            goby.registerCommand('hello', function (content) {
              goby.showInformationMessage("helloWorld");
            });
          }
          
          exports.activate = activate;
        
      

Second, use initEvents to bind the command.

        
          {
            "name": "initEvents",
            "publisher": "Goby Team",
            "description": "initEvents by Goby Team",
            "initEvents": "hello"
          }
        
      

The final effect is as follows: when you download and install the extension, the hello command will be executed automatically and push notification.

Extension translation

The default language of the plug-in needs to be English. If you need to adapt to other languages in Goby, you need to set a translation file; if no translation is set, Goby uses the default language.

Example

Configure the translation file path in package.json

	    
	      {
	        "language":{
	          "CN":"src/assets/translate/CN/translate.json",
	          "DE":"src/assets/translate/DE/translate.json",
	          "JA":"src/assets/translate/JA/translate.json",
	          "KO":"src/assets/translate/KO/translate.json",
	          "FR":"src/assets/translate/FR/translate.json"
	        }
	      } 
	    
	  

Translation file:translate.json

• It must be in JSON format and the content is the same as package.json.

• content include:description、contributes、readme and changelog.

• The value of readme and changelog is the relative path between the corresponding file and the current language translate.json.

• It is recommended to use i18n for the translation of the content in the custom pop-up window, please refer to the FOFA plugin.

For example: Chinese translation

	    
	      {
	        "description":"将通过FOFA查询的IP和端口,快速导入goby进行扫描。",
	        "contributes":{
	            "configuration":{
	               "Email": {
	                    "description": "FOFA Email"
	                },
	                "Key": {
	                    "description": "FOFA Key"
	                },
	                "Size": {
	                    "description": "查询返回到每页的数量,默认100条,最大可设置为10000条。"
	                } 
	            },
	            "views":{
	                "scanDia": [
	                    {
	                        "title": "FOFA",
	                        "tips":"FOFA"
	                    }
	                ]
	            }
	        },
	        "readme":"./README.md",
	        "changelog":"./CHANGELOG.md"
	      }
	    
	  

Extension list

Every goby extension needs an extension list (package.json), which must be placed in the extension's root directory.

Field description

Field Required Type Detail
name Yes String Name of extension
publisher Yes String Name of publisher
engines Yes String The lowest goby version the extension depends on, such as 1.6.170
version Yes String The version number of the extension, each time the extension is updated, the version must be newer than before
main Yes String The main entrance of extension
description Yes String The description of extension
initEvents No String/Array Initialization events, commands that are automatically executed after the extension is installed
icon No String The icon of extension,32*32 is recommended
contributes Yes Object Entry and configuration of extension custom components, etc
scripts No Object Equivalent to npm's scripts
devDependencies Object Equivalent to npm's devDependencies

Complete example

        
          {
            "name": "FOFA",
            "publisher": "Goby Team",
            "description": "将通过fofa查询的IP和端口,快速导入goby进行扫描。",
            "version": "0.1.0",
            "icon": "src/assets/img/fofa.png",
            "engines": "1.6.170",
            "initEvents": "fofa",
            "main": "./src/extension.js",
            "contributes": {
              "configuration": {
                "email": {
                  "type": "string",
                  "default": "",
                  "description": "fofa email"
                },
                "key": {
                  "type": "string",
                  "default": "",
                  "description": "fofa key"
                }
              },
              "views": {
                "scanDia": [
                  {
                    "command": "fofa",
                    "title": "FOFA",
                    "icon": "src/assets/img/fofa.png"
                  }
                ]
              }
            },
            "scripts": {},
            "devDependencies": {},
            "dependencies": {}
          }