Common uses
Integrate with your Marketplace via APIs
This section helps Partners or Distributors to integrate in their Marketplace.
Create an MSP trial account
To get started, you need to use the createCompany
method from Companies API to create a partner company account with a monthly license trial.
To create a partner company account with a monthly license trial, set the following parameters specifically:
Parameter | Type | Description | Notes |
---|---|---|---|
| Number | The company type. | Set value to |
| Object | An object containing the license details. | Set |
Return value: This method returns a string with the ID of the newly created partner company. You can use this string for other workflows. For more information about this method, refer to createCompany.
Create a customer monthly subscription trial account
To create a customer (end-user) account under an MSP with a monthly subscription trial set the following parameters specifically:
Parameter | Type | Description | Notes |
---|---|---|---|
| Number | The company type. | Set value to |
| Object | An object containing the license details. | Set |
Return value: This method returns a string with the ID of the newly created customer company. For more information about this method, refer to createCompany.
Set a monthly subscription
Use the setMonthlySubscription
method and set the following parameters in any sequence:
Parameter | Type | Optional | Description |
---|---|---|---|
| String | No | The ID of the company that will inherit license seats from the parent company. |
| Number | Yes | The number of seats ensured for the target company from the parent's company total amount of seats. The default value is 0, meaning that no seats will be reserved. If no value is passed, the parameter preserves its previous value. |
| Boolean | Yes | True for allowing the company to use the Security for Exchange service, False otherwise. Default value is False. |
| Boolean | Yes | True for allowing the company to use the Full Disk Encryption service, False otherwise. Default value is False. |
| Boolean | Yes | True for allowing the company to use the Security for Virtualized Environments service, False otherwise. Default value is False. |
| Boolean | Yes | True for allowing the company to use the HyperDetect service, False otherwise. Default value is False. |
| Boolean | Yes | True for allowing the company to use the Sandbox Analyzer service, False otherwise. Default value is False. |
| Boolean | Yes | True for allowing the company to use the Patch Management service, False otherwise. Default value is False. |
| Boolean | Yes | True for allowing the company to use the Endpoint Detection and Response (EDR) service, False otherwise. Default value is False. EDR requires Sandbox Analyzer and HyperDetect to be enabled. Any change of this parameter's value will automatically set the parameters manageSandboxAnalyzer and manageHyperDetect with the same value. Omitting passing a value will not affect the values set for these two parameters.. |
Return value: This method returns a string with the ID of the newly created partner company. You can use this string for other workflows. For more information about this method, refer to createCompany.
The MSP receives a welcoming email from with a link to the and its provisioned credentials. We recommend MSPs to change the password upon the first login.
Note
To invoice based on usage without setting a hard limit count for MSP license consumption, do not specify the reservedSlots
parameter.
Check the usage at the end of the month
If you do not have any add-ons enabled, you can pull the monthly usage directly from through the getMonthlyUsage
method, by specifying the targetMonth
(last month) and companyID
parameters of your MSP account.
To check the usage at the end of the month, set the following parameters in any sequence:
Parameter | Type | Description |
---|---|---|
| String | The ID of the company. The default value is the ID of the company linked to the user who generated the API key. |
| String | The month for which the usage is returned. It should have the following format: |
For usage calculators and reports about add-ons enabled for your MSP, refer to this Calculate the endpoint usage with the Monthly License Usage report
Obtain a company’s ID
Use the findCompaniesByName
method from Companies API to obtain a company ID, its usage or the company details. For more information about this method, refer to findCompaniesByName.
Check for enabled add-ons in an MSP account
Use the getLicenseInfo
method from Licensing API to retrieve license information for a company. For more information about this method, refer to getLicenseInfo.
Enable or disable add-ons in an MSP account
Use the setMonthlySubscription
method from Companies API to enable or disable additional Cloud Security for MSP add-ons, by setting the parameters to True
or False
.
To enable or disable additional protection layers, set the following parameters in any sequence:
Parameter | Type | Description | Notes |
---|---|---|---|
| Boolean |
| Security for add-on. |
| Boolean |
| Full Disk Encryption add-on. |
| Boolean |
| Security for Virtualized Environments add-on. |
| Boolean |
| Hyper Detect, as part of Advanced Threat Security add-on. |
| Boolean |
| , as part of Advanced Threat Security add-on. |
| Boolean |
| Patch Management add-on. |
| Boolean |
requires and Hyper Detect to be enabled. Any change of this parameter's value will automatically set the parameters | add-on. |
Return value: This method does not return any value. For more information about this method, refer to setMonthlySubscription
To add a second add-on on top of any existing service, you need to include all previous parameters associated with add-ons that are already enabled.
Setting these parameters results in enabling or disabling the ability to deploy and license add-ons.
If you enable an add-on, the MSP can deploy the associated module on existing and newly added endpoints. An add-on used at least once during the month is counted for usage.
If you disable an add-on, the associated module is deactivated and its usage is not generated for the upcoming month. As a result, the MSP is unable to manage any module associated with a disabled add-on.
Suspend MSP account in case of contract breach
You are always in control and able to act when a contractual agreement breach occurs.
The suspendCompany
method from the Companies API allows you to suspend active companies with unpaid bills or other contract infringements.
Under these circumstances, you can suspend a company’s access to and deactivate associated endpoints. You can choose to apply this recursively to all managed companies by the MSP, to prevent the usage from accumulating in a given month. For more information about this method, refer to suspendCompany
To activate suspended companies, refer to activateCompany.
Sending events from GravityZone cloud platform to SIEMs lacking HTTPS listeners
This article aims to help you install a connector between GravityZone and SIEM solutions that do not have HTTPS listeners for events.
BitdefenderGravityZone – the cloud platform, provides alerts about security events in CEF and JSON message standards. These alerts are sent through the Event Push Service.
The GravityZone APIs are exposed using JSON-RPC 2.0 protocol specified here. For details on GravityZone API, refer to the available documentation.
If your SIEM does not have any HTTP/HTTPS listeners, but supports a Syslog service, you need to install the GravityZone Event Push Service Connector.
The connector uses the POST method to receive authenticated and secured messages from the GravityZone Event Push Service. It parses the message and then forwards it to a local or a remote Syslog server. You can use the Syslog server to feed these messages to the SIEM.
To install the connector, follow these steps:
Check the prerequisites.
If you have a version of the GravityZone Event Event Push Service that has been set up manually before March 29th, 2022, remove its files from your system.
Add the repository to the APT sources list.
Install the DEB package.
Note
If you receive a
signatures couldn't be verified because the public key is not available
error message during the DEB package installation, download and install a digital signature for the package files:curl -sS https://download.bitdefender.com/repos/gzrepos.key.asc | apt-key add -
Configure via bash script.
Enable system service.
Test the connector.
Configure GravityZone to send messages to the SIEM.
Check the prerequisites
Before proceeding any further, you need to meet the following prerequisites:
Linux basic knowledge
GravityZone cloud solution
A GravityZone API key that covers Event Push Service API
Ubuntu 20.04 LTS server with the following configuration:
Hardware:
1 CPU
2 GB RAM
1 Gbit virtual NIC
80 GB HDD
Note
This configuration can sustain an environment up to 15000 endpoints. The CPU and network usage will increase proportionally with the number of endpoints.
Important
The SIEM receiving events from the event push requires a Public IP assigned for the GravityZone Event Push server to forward events to.
Install the connector
Connect to the Ubuntu 20.04 server.
Add the Bitdefender Connector repository to APT.
sudo echo "deb http://download.bitdefender.com/repos/deb-hydra20-evpsc/ bitdefender non-free" >> /etc/apt/sources.list
Install the DEB package.
sudo apt update sudo apt install gz-evpsc
Run the configuration script.
cd /opt/bitdefender/gz-evpsc # Usage: # ./config.sh <PORT> <SYSLOGPORT> <TRANSPORT> <TARGET> <AUTH> <CONFIG_FILENAME> # Example: # ./config.sh 3200 514 Tcp 127.0.0.1 'Basic dGVzdDp0ZXN0' config.json sudo ./config.sh <PORT> <SYSLOGPORT> <TRANSPORT> <AUTH> <CONFIG_FILENAME>
Note
The connector needs to have a public IP address assigned for the GravityZone Event Push server to forward events to.
(optional) Add certificates paths to the
config
file.By default, the
config.sh
script creates self signed certificates for the HTTPS connector server. For better security, certificates obtained from a certificate authority can be placed in the following files:/opt/bitdefender/gz-evpsc/api/config/server.key /opt/bitdefender/gz-evpsc/api/config/server.crt
Enable the system service
systemctl enable gz-evpsc
Start the system service
systemctl start gz-evpsc
Obtain the security certificate for authentication
The GravityZone cloud platform only sends Push Event messages to HTTPS capable collectors. For the collector service to function over HTTPS, and provide a secure communication with Bitdefender Cloud, you need to set it up to function with an SSL/TLS certificate.
By default, the config.sh
script creates self signed certificates for the HTTPS connector server. You can also obtain an SSL/TLS certificate for this service in a few other ways:
From a trusted public Certificate Authority (CA)
Note
We strongly recommend this method, since it will allow our Cloud servers to properly validate the identity the URL of the collector and avoid any man-in-the-middle attacks.
From your company’s internal PKI
Note
We do not recommend this method, since the Bitdefender public cloud service is not be able to validate a certificate signed by a private CA.
Create a self-signed certificate
Note
We strongly advise against this option. It does not provide any certificate validation methods and exposes the communication to man-in-the-middle attacks. This method should only be used for testing purposes and never in production environments.
Further on, you will need the sslkey.pem
and ssl.cer
/ssl.crt
files, signed by your CA of choice.
Test the connector
Use this HTTPS message example to test the connector you have just configured:
Event Push Service request header
Authorization: Basic xxxxxxxxxxxxxx
Event Push Service payload
{ "cef": "0", "events": [ "CEF:0|Bitdefender|GravityZone|6.4.08|70000|Registration|3|BitdefenderGZModule=registrationdvchost=TEST_ENDPOINTasdadBitdefenderGZComputerFQDN=test.example.com dvc=192.168.1.2", "CEF:0|Bitdefender|GravityZone|6.4.0-8|35|Product ModulesStatus|5|BitdefenderGZModule=modules dvchost=TEST_ENDPOINTasdadBitdefenderGZComputerFQDN=test.example.com dvc=192.168.1.2", "CEF:0|Bitdefender|GravityZone|6.4.0-8|35|Product ModulesStatus|5|BitdefenderGZModule=modules dvchost=TEST_ENDPOINTasdadBitdefenderGZComputerFQDN=test.example.com dvc=192.168.1.2" ] }
Use the following
cURL
command to send the payload to the collector service:curl -k -H 'Authorization: Basic xxxxxxxxxxxxxxxxxx' \ -H "Content-Type: application/json" \ -d '{"cef": "0","events": ["CEF:0|Bitdefender|GravityZone|6.4.08|70000|Registration|3|BitdefenderGZModule=registrationdvchost=TEST_ENDPOINTasdadBitdefenderGZComputerFQDN=test.example.com dvc=192.168.1.2","CEF:0|Bitdefender|GravityZone|6.4.0-8|35|Product ModulesStatus|5|BitdefenderGZModule=modules dvchost=TEST_ENDPOINTasdadBitdefenderGZComputerFQDN=test.example.com dvc=192.168.1.2","CEF:0|Bitdefender|GravityZone|6.4.0-8|35|Product ModulesStatus|5|BitdefenderGZModule=modules dvchost=TEST_ENDPOINTasdadBitdefenderGZComputerFQDN=test.example.com dvc=192.168.1.2"]}' \ https://your_web_server_hostname_or_public_IP:port/api
Important
Replace the authorization header and URL with the one configured above in the
config.json
file.The event should appear in your defined syslog server and as output of the running
server.js
.
Configure GravityZone to send messages to the SIEM
Now that the HTTPS collector service is running and listening for messages, you can configure Control Center to send events to the above-defined URL: https://your_web_server_hostname_or_public_IP:port/api
.
All settings for Event Push Service API are configured via the setPushEventSettings
method. For detailed information about these settings, refer to Push.
Using your API key of choice, configure the API push events and the service URL where you want the messages delivered:
$ curl --tlsv1.2 -sS -k -X POST \ https://CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/push \ -H 'authorization: Basic API_KEY_BASE64_ENCODED_WITH_COLON_APPENDED' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{"id":"1","jsonrpc":"2.0","method":"setPushEventSettings","params":{"serviceSettings":{"requireValidSslCertificate":false,"authorization":"Basic xxxxxxxxxx","url":" https://your_web_server_hostname_or_public_IP:port/api"},"serviceType":"cef","status":1,"subscribeToEventTypes":{"adcloudgz":true,"antiexploit":true,"aph":true,"av":true,"avc":true,"dp":true,"endpoint-moved-in":true,"endpoint-moved-out":true,"exchange-malware":true,"exchange-user-credentials":true,"fw":true,"hd":true,"hwid-change":true,"install":true,"modules":true,"network-monitor":true,"network-sandboxing":true,"new-incident":true,"ransomware-mitigation":true,"registration":true,"supa-update-status":true,"sva":true,"sva-load":true,"task-status":true,"troubleshooting-activity":true,"uc":true,"uninstall":true}}}'
Important
When using a valid service certificate signed by a public CA, we recommend setting "requireValidSslCertificate":true
, to force certificate validation. If you are using a self-signed certificate or a certificate signed by your internal CA, set "requireValidSslCertificate":false
.
Important
Make sure to replace "authorization":"Basic xxxxxxxxxx"
and "url":" https://your_web_server_hostname_or_public_IP:port/api"
with the correct values for your server, as defined in the config.json
file, and CONTROL_CENTER_APIs_ACCESS_URL
and API_KEY_BASE64_ENCODED_WITH_COLON_APPENDED
with the correct values for your GravityZone instance.
Once configured, wait about 10 minutes for the settings to take effect, and then make a request using getPushEventSettings
.
$ curl --tlsv1.2 -sS -k -X POST \ https://CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/push \ -H 'authorization: Basic API_KEY_BASE64_ENCODED' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{"id":"3","jsonrpc":"2.0","method":"getPushEventSettings","params":{}}'
The result should look like this:
{ "id": "2", "jsonrpc": "2.0", "result": { "serviceSettings": { "authorization": "********", "requireValidSslCertificate": false, "url": "https://your_web_server_hostname_or_public_IP:port/api" }, "serviceType": "cef", "status": 1, "subscribeToCompanies": null, "subscribeToEventTypes": { "adcloud": false, "antiexploit": true, "aph": true, "av": true, ………. "uninstall": true } } }
To send a test event, you can call the sendTestPushEvent
API method.
$ curl --tlsv1.2 -sS -k -X POST \ https://CONTROL_CENTER_APIs_ACCESS_URL/v1.0/jsonrpc/push \ -H 'authorization: Basic API_KEY_BASE64_ENCODED' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{"id":"4","jsonrpc":"2.0","method":"sendTestPushEvent","params":{"eventType": "av"}}'
The result should look like this:
{
"id": "4",
"jsonrpc": "2.0",
"result": {
"computer_name": "FC-WIN7-X64-01",
"computer_fqdn": "fc-win7-x64-01",
"computer_ip": "10.17.46.196",
"computer_id": "59a1604e60369e06733f8abb",
"product_installed": "BEST",
"malware_type": "file",
"malware_name": "EICAR-Test-File (not a virus)",
"file_path": "C:\\eicar0000001.txt",
"hash": "8b3f191819931d1f2cef7289239b5f77c00b079847b9c2636e56854d1e5eff71",
"final_status": "deleted",
"timestamp": "2017-09-08T12:01:36.000Z",
"companyId": "5ac8460f8a799399a78b456c",
"module": "av",
"_testEvent_": true
}
}
The event should shortly show up in the Syslog server and in the server.js
output.
Check the log files
You can find the log file here:
/opt/bitdefender/var/log/gz-evpsc/log.txt