Local development environment

A development environment is available to create and test custom plugins before deploying directly to an OnSight vCollector. This may be run within any environment supporting Python and does not need to be installed to an OnSight.

onsight-dev.sh provides the local development environment for both custom plugins and countermeasure plugins. you can build and test your custom plugins and countermeasure plugins locally.

Install

1. Setup a recent Linux (Ubuntu or RHEL) machine and install Docker and jq

2. Download onsight-dev.sh.

Environment setup

1. Set environment variables based on the build you are running:

   • CM_DEV_BASE (optional, default = current directory)

2. plugins

   • copy custom plugins to {CM_DEV_BASE}/onsight/custom-metrics

   • copy countermeasures plugins to {CM_DEV_BASE}/onsight/countermeasures

3. packages

   • install the python packages required to run a plugin in {CM_DEV_BASE}/onsight/dependencies directory

     pip install -t onsight/dependencies pyyaml

4. ssh-keys

   • copy (or generate) ssh private key in {CM_DEV_BASE}/onsight/ssh-keys directory

5. secrets

   • create secret repo configuration in {CM_DEV_BASE}/onsight/secrets directory

Usage

$ ./onsight-dev.sh --help

Usage: onsight-dev [OPTIONS] COMMAND [ARGS]...

Options:

--help  Show this message and exit.

Commands:

countermeasure  run countermeasure

custom-metric   run custom metric plugin

dump            print metadata via API

list-secret     List secrets for countermeasure and custom plugins

set-secret      Set secret for countermeasure and custom plugins

Run Test

Download the metadata of target instance from FortiMonitor API

You can get the api-key from https://fortimonitor.forticloud.com/report/ApiKeyManagement.

(Specify --api-host if you run the API locally)

$ ./onsight-dev.sh dump \

--api-key=6336a1b3-b89d-442e-ae13-3fdf3e8ce2bc \

--instance-id=2486 > 2486.metadata

Sample metadata:

$ cat 2486.metadata

{

"instance_id": 2486,

"hostname": "144.202.55.142",

"device_type": "server",

"device_sub_type": null,

"tags": [],

"attributes": {

"server.origin": "manual",

"server.os": "Linux"

}

}

Execute custom plugin with metadata:

1. specify --textkey and --metric-textkey to run

2. specify metadata that will be passed to get_data() function

   $ ./onsight-dev.sh custom-metric \

   	--textkey com.fortinet.cisco \

   	--metric-textkey power_supply_status \

   	--metadata 2486.metadata

3. You can omit --textkey and --metric-textkey by adding textkey and metric_textkey into the metadata file.

   $ cat 2486.metadata

   {

   	"textkey": "com.fortinet.cisco",

   	"metric_textkey": "power_supply_status",

   	"instance_id": 2486,

   	"hostname": "144.202.55.142",

   	"device_type": "server",

   	"device_sub_type": null,

   	"tags": [],

   	"attributes": {

   	"server.origin": "manual",

   	"server.os": "Linux"

   	}

   }

   $ ./onsight-dev.sh custom-metric --metadata 2486.metadata

4. You can execute custom plugin directly with metadata retrieved from the API.

   (Specify --api-host if you run API locally)

   ./onsight-dev.sh custom-metric \

   	--textkey com.fortinet.cisco \

   	--metric-textkey power_supply_status \

   	--api-key=6336a1b3-b89d-442e-ae13-3fdf3e8ce2bc \

   	--instance-id=2486

5. logs are stored under {CM_DEV_BASE}/onsight/logs/ directory.