Skip to main content

Common uses

Integrate with your Marketplace via APIs

This section helps Partners or Distributors to integrate in their Marketplace.

Create a company

To get started, you need to use the createCompany method from Companies API to create a company,

To create a company include the following parameters in your request:

Parameter

Type

Description

Notes

type

Number

The company type

Set the value to:

  • 0 to create a Partner account.

  • 1 to create a Customer account.

licenseSubscription

Object

An object containing the license details

Set the value of the type attribute to one of these values:

  • 3 (monthly subscription).

  • 4 (monthly license trial).

  • 5 (monthly subscription trial).

name

String

The company name.

Must be unique.

parentId

String

Your company ID.

Must not be confused with the company hash.

assignedProductType

Integer

The type of the product that the company will use.

Possible values:

  • 0 for Endpoint Security.

  • 3 for Bitdefender EDR. The default value is 0.

Important

You can use this parameter only with the following types of licensing:

  • 3 for monthly subscription.

  • 5 for monthly subscription trial.

additionalProductTypes

Array of integers

The type of products the company can resell to their clients.

Possible values of the array elements:

  • 0 for Endpoint Security.

  • 3 for Bitdefender EDR.

Default value: the same value assigned to assignedProductType.

Note

If set, it must contain, at least the value of the assignedProductType.

Important

You can use this parameter only with the following types of licensing: 3 for monthly subscription, 5 for monthly subscription trial.

assignedProtectionModel

String

The type of the protection model that the company will use.

Possible values:

  • aLaCarte

  • mspSecure

  • mspSecurePlus

  • mspSecureExtra

Default value: depends on the protection models made available by the partner company.

Important

You can only use this parameter if all the following conditions are met:

  • type = 3 (monthly subscription)

  • assignedProductType = 0 (Endpoint Security)

Note

The value assigned to this parameter will automatically assign one or more values to the additionalProtectionModels array.

assignedProtectionModel

Default value for additionalProtectionModels

aLaCarte

aLaCarte

mspSecure

mspSecure

mspSecurePlus

mspSecure,mspSecurePlus

mspSecureExtra

mspSecure,mspSecurePlus, mspSecureExtra

additionalProtectionModels

Array of strings

This parameter allows the Partner company being created to assign additional protection models to their clients apart from the ones provided by the assignedProtectionModel object.

Possible values:

  • aLaCarte

  • mspSecure

  • mspSecurePlus

  • mspSecureExtra

Default value: depends on the value assigned to the assignedProtectionModel field.

Important

You can only use this parameter if one the following conditions are met:

  • assignedProductType = 3 (Bitdefender EDR), additionalProductType must include 0 (Endpoint Security), and type = 3 (monthly subscription).

  • assignedProductType = 0 (Endpoint Security), type = 3 (monthly security), and assignedProtectionModel is included in the request.

accountEmail

String

The email for the new user account to be linked to the new company.

If the parameter canBeManagedByAbove is set to false, the accountEmail parameter must be included.

accountFullName

String

The full name of the new user account to be linked to the new company.

This parameter is required when canBeManagedByAbove is set to false.

contactPerson

Object

Contains information regarding the company's designated contact person.

The object contains the following fields:

  • fullName - the person's first and last name.

  • email - their business email address.

    Important

    This field is mandatory when the contactPerson parameter is included in the request.

  • phoneNumber, their business phone number.

  • companyRole, their position in the company.

You can further customize your request by using the optional parameters described in the createCompany article.

Return value: This method returns a string with the ID of the newly created company. You can use this string for other workflows.

For more information about this method, refer to createCompany.

Return example:

{
    "id":"e249c22c-0ada-4772-a9f1-ee1cbb322588",
    "jsonrpc":"2.0",
    "result": "5493dcd2b1a43df00b7b23c6"
}

Assign a monthly subscription to a company

You can use the setMonthlySubscription method this method to:

  • Switch a company from a trial license to a monthly subscription.

  • Enable or disable add-ons for a company you manage that has a monthly subscription.

  • Change the protection model a company is using or is allowed to distribute.

  • Change a company's licensing model from yearly to monthly subscription.

Set the following parameters in any sequence:

Parameter

Type

Optional

Description

manageExchange

Boolean

Yes

True for allowing the company to use the Security for Exchange service, False otherwise. Default value is False.

manageEncryption

Boolean

Yes

True for allowing the company to use the Full Disk Encryption service, False otherwise. Default value is False.

manageRemoteEnginesScanning

Boolean

Yes

True for allowing the company to use the Security for Virtualized Environments service, False otherwise. Default value is False.

Note

This parameter can not be used if any of the manageRemoteEnginesScanning and manageRemoteEnginesScanningResell settings under the ownUse and resell object parameters exist.

manageHyperDetect

Boolean

Yes

True for allowing the company to use the HyperDetect service, False otherwise. Default value is False.

manageSandboxAnalyzer

Boolean

Yes

True for allowing the company to use the Sandbox Analyzer service, False otherwise. Default value is False.

managePatchManagement

Boolean

Yes

True for allowing the company to use the Patch Management service, False otherwise. Default value is False.

manageEventCorrelator

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.

manageEmailSecurity

Boolean

Yes

True for allowing the company to use the Email Security service, False otherwise. Default value is False.

manageMobileSecurity

Boolean

Yes

True for allowing the company to use the Mobile Security service, False otherwise. Default value is False.

manageContainerProtection

Boolean

Yes

True for allowing the company to use the Container Protection service, False otherwise. Default value is False.

Important

This setting can only be set to true if assignedProtectionModel has the aLaCarte value assigned.

Note

This parameter can not be used if any of the manageContainerProtection and manageContainerProtectionResell settings under the ownUse and resell object parameters exist.

licensedServices

Object

Yes

An object containing service settings for the company.

This parameter makes sense only when creating a company with license of type 3. If omitted, the service will be unavailable.

  • mdrServiceOwnUse, an integer representing which MDR Service type is enabled for the company's own use. Possible values: 0 for Disabled, 1 for Foundations, 2 for Response (deprecated). Enabling this also enables MDR service reselling if the company type is Partner. Enabling this option will also enable EDR. If omitted, the service will be unavailable.

  • mdrServiceResell, a boolean specifying whether the company is allowed to resell MDR services (Foundations and Response) to the companies it creates. If omitted, reselling will be unavailable. This makes sense only for partner companies.

assignedProductType

Number

Yes

The product type assigned to the target company. Possible values:

  • 0, for Endpoint Security

  • 3, for Bitdefender EDR

The default value is 0.

additionalProductTypes

Array

Yes

This parameter applies only to Partner companies. It is an array of integers representing the product types that the Partner can assign to its clients. Possible integer values:

  • 0, for Endpoint Security

  • 3, for Bitdefender EDR

If you set this parameter, the array must contain at least the value of assignedProductType and you must also set the assignedProductType. If not set, the default value is the value of assignedProductType.

assignedProtectionModel

String

Yes

assignedProtectionModel, a string representing the type of the protection model that the company will use.

Possible values:

  • aLaCarte

  • mspSecure

  • mspSecurePlus

  • mspSecureExtra

Default value: depends on the protection models made available by the partner company.

You can only use this parameter if all the following conditions are met:

  • type = 3 (monthly subscription)

  • assignedProductType = 0 (Endpoint Security)

Note

The value assigned to this parameter will automatically assign one or more values to the additionalProtectionModels array.

assignedProtectionModel

Default value for additionalProtectionModels

aLaCarte

aLaCarte

mspSecure

mspSecure

mspSecurePlus

mspSecure,mspSecurePlus

mspSecureExtra

mspSecure,mspSecurePlus, mspSecureExtra

additionalProtectionModels

String

Yes

An array of strings representing types of protection models. This parameter allows a Partner company to assign additional protection models to their clients apart from the ones provided by the assignedProtectionModel object.

Possible values:

  • aLaCarte

  • mspSecure

  • mspSecurePlus

  • mspSecureExtra

Default value: depends on the value assigned to the assignedProtectionModel field.

You can only use this parameter if one the following conditions are met:

  • assignedProductType = 3 (Bitdefender EDR), additionalProductType must include 0 (Endpoint Security), and type = 3 (monthly subscription).

  • assignedProductType = 0 (Endpoint Security), type = 3 (monthly security), and assignedProtectionModel is included in the request.

manageIntegrityMonitoring

Integer

Yes

True for allowing the company to use the Integrity Monitoring service, False otherwise. Default value is False.

imDataRetention

Integer

No

The number of days the events will be stored for. It is only returned if manageIntegrityMonitoring is true. Possible values: 0 (7 days retention), 1 (90 days retention), 2 (180 days retention), 3 (365 days retention). The default value is 0 (7 days retention).

ownUse

Object

Yes

An object containing activation settings for the company's services and add-ons. This parameter makes sense only when creating a company with license of type 3 or 5 (monthly inherited subscription).

  • manageXDRIdentityProviders, gives access to Sensors Management integration for Azure AD and Active Directory. Possible values: true or false.

  • manageXDRProductivityApps, gives access to Sensors Management integration for Office 365, Google Workspace and Microsoft Intune. Possible values: true or false.

  • manageXDRNetwork, gives access to Sensors Management integration for Network Sensor. Possible values: true or false.

  • manageXDRCloudWorkloads, gives access to Sensors Management integration for AWS and Azure Cloud. Possible values: true or false.

    Important

    To assign the true value to any of the parameters above, the manageEventCorrelator parameter or the manageEventCorrelator setting under the ownuse parameter needs to be set to true.

    Note

    Assigning true to any of the manageXDRIdentityProviders, manageXDRProductivityApps, manageXDRNetwork or manageXDRCloudWorkloads settings will activate XDR. To deactivate XDR, set all of them to false.

  • manageRemoteEnginesScanning, optional, activates the Security for Virtualized Environments service for your company. Possible values: true or false. Default value: false.

    Note

    This setting can not be used if the manageRemoteEnginesScanning parameter outside of the ownUse object is present.

  • manageContainerProtection, optional. activates the Container Protection service for your company. Possible values: true or false. Default value: false.

    Important

    This setting can only be set to true if assignedProtectionModel has the aLaCarte value assigned.

    Note

    This setting can not be used if the manageContainerProtection parameter outside of the ownUse object is present.

  • manageEventCorrelator, a boolean specifying whether the company can use Endpoint Detection and Response (EDR) or not. The default value is false. Setting this parameter to true will automatically set the manageSandboxAnalyzer and manageHyperDetect settings under the ownuse parameter to true.

    Note

    This setting can not be used if the manageEventCorrelator parameter outside of the ownUse object is present.

  • manageSandboxAnalyzer, a boolean specifying whether the company can use Sandbox Analyzer or not. The default value is false.

    Note

    This setting can not be used if the manageSandboxAnalyzer parameter outside of the ownUse object is present.

  • manageHyperDetect, a boolean specifying whether the company can use HyperDetect or not. The default value is false.

    Note

    This setting can not be used if the manageHyperDetect parameter outside of the ownUse object is present.

resell

Object

Yes

An object containing your company's reselling settings for services and add-ons. This parameter makes sense only when creating a company with license of type 3 or 5 (monthly inherited subscription).

  • manageXDRResell - allows selling the eXtended Detection and Response service to your customers. Possible values: true or false.

    Note

    If true, the manageXDRIdentityProviders, manageXDRProductivityApps, manageXDRNetwork and manageXDRCloudWorkloads will automatically be set as true for your managed companies.

  • manageRemoteEnginesScanningResell, optional, allows selling the Security for Virtualized Environments service to your customers. Possible values: true or false. Default value: false.

    Note

    This setting can not be used if the manageRemoteEnginesScanning parameter outside of the resell object is present.

  • manageContainerProtectionResell, optional, allows selling the Container Protection service to your customers. Possible values: true or false. Default value: false.

    Important

    This setting can only be set to true if the additionalProtectionModels parameter has the aLaCarte value assigned.

    Note

    This setting can not be used if the manageContainerProtection parameter outside of the ownUse object is present.

  • manageEventCorrelatorResell, optional, allows selling Endpoint Detection and Response (EDR) to your customers. Possible values: true or false. Default value: false. Setting this setting to true will automatically set the manageSandboxAnalyzerResell and manageHyperDetectResell settings under the resell parameter to true.

    Note

    This setting can not be used if the manageEventCorrelator parameter outside of the ownUse object is present.

  • manageSandboxAnalyzerResell, optional, allows selling Sandbox Analyzer to your customers. Possible values: true or false. Default value: false.

    Note

    This setting can not be used if the manageSandboxAnalyzer parameter outside of the ownUse object is present.

  • manageHyperDetectResell, optional, allows selling HyperDetect to your customers. The default value is false.

    Note

    This setting can not be used if the manageHyperDetect parameter outside of the ownUse object is present.

Request example:

{
    "params": {
        "companyId": "64be4c5cb904ea72f3001049",
        "reservedSlots": 120,
        "removeReservedSlots": false,
        "endSubscription": "2029-04-14",
        "autoRenewPeriod": 12,
        "manageExchange": false,
        "manageEncryption": false,
        "managePatchManagement": false,
        "ownUse": {
            "manageXDRIdentityProviders": false,
            "manageXDRProductivityApps": false,
            "manageXDRNetwork": false,
            "manageXDRCloudWorkloads": false,
            "manageRemoteEnginesScanning": false,
            "manageContainerProtection": false,
            "manageHyperDetect": true,
            "manageSandboxAnalyzer": true,
            "manageEventCorrelator": true
        },
        "resell": {
            "manageXDRResell": true,
            "manageRemoteEnginesScanningResell": true,
            "manageContainerProtectionResell": true,
            "manageHyperDetectResell": true,
            "manageSandboxAnalyzerResell": true,
            "manageEventCorrelatorResell": true
        },
        "manageEmailSecurity": false,
        "manageIntegrityMonitoring": true,
        "imDataRetention": 2,
        "licensedServices": {
            "mdrServiceOwnUse": 1,
            "mdrServiceResell": true
        },
        "minimumUsage": {
            "endpointMonthlyUsage": 120
        },
        "assignedProductType": 0,
        "additionalProductTypes": [
            0
        ],
        "assignedProtectionModel": "mspSecure",
        "additionalProtectionModels": [
            "aLaCarte",
            "mspSecure",
            "mspSecurePlus"
        ],
        "setNewProtectionModelForClients": "aLaCarte"
    },
    "jsonrpc": "2.0",
    "method": "setMonthlySubscription",
    "id": "d4d50719-3215-455a-a329-086fe77f6d72"
}

Return value: This method does not return any value.

For more information about this method, refer to createCompany.

Return example:

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 and companyID parameters.

To check the usage at the end of the month, set the following parameters in any sequence:

Parameter

Type

Description

companyID

String

The ID of the company. The default value is the ID of the company linked to the user who generated the API key.

targetMonth

String

The month for which the usage is returned. It should have the following format: mm/yyyy. The default value is the current month.

Request example:

  {
       "params": {
           "targetMonth": "03/2015",
           "companyId": "55115935b1a43dcc4a7b23c6"
       },       "jsonrpc": "2.0",
       "method": "getMonthlyUsage", 
       "id": "5087eab8-b74f-4a3e-85b3-4271e85890d4"
  }

Return value:

This method returns an Object containing the number of license seats used during the specified month, for each acquired service, or 0 if the queried company does not have a monthly license:

  • endpointMonthlyUsage - the monthly usage for all endpoints scanned with local engines.

  • aLaCarteMonhtlyUsage - the monthly usage for endpoints scanned with local engines that belong to companies that use the A-la-carte protection model.

  • mspSecureMonthlyUsage - the monthly usage for endpoints scanned with local engines that belong to companies that use the Secure protection model.

  • mspSecurePlusMonthlyUsage - the monthly usage for endpoints scanned with local engines that belong to companies that use the Secure Plus protection model.

  • mspSecureExtraMonthlyUsage - the monthly usage for endpoints scanned with local engines that belong to companies that use the Secure Extra protection model.

  • emailSecurityMonthlyUsage - the monthly usage for Email Security mailboxes.

  • mobileSecurityMonthlyUsage - the monthly usage for Mobile Security devices.

  • exchangeMonthlyUsage - the monthly usage for Exchange mailboxes.

  • encryptionMonthlyUsage - the monthly usage for the encryption module.

  • atsMonthlyUsage - the monthly usage for the sandboxAnalyzer and hyperDetect modules.

  • edrMonthlyUsage - the monthly usage for the EDR module.

  • mdrFoundationsMonthlyUsage - the monthly usage for MDR Foundationsservice.

  • mdrResponseMonthlyUsage - the monthly usage for MDR Response service.

  • patchManagementMonthlyUsage - the monthly usage for the patch management module.

  • containerProtectionMonthlyUsage - the monthly usage for container protection module.

  • integrityMonitoringUsage - the total number of endpoints that make use of Integrity Monitoring.

  • integrityMonitoring90DaysUsage - the number of endpoints that make use of Integrity Monitoring with 90 days event retention.

  • integrityMonitoring180DaysUsage - the number of endpoints that make use of Integrity Monitoring with 180 days event retention.

  • integrityMonitoring1YearUsage - the number of endpoints that make use of Integrity Monitoring with 1 year event retention.

  • xdrIdentitySensorsMonthlyUsage, the monthly usage of Azure AD and Active Directory integration in Sensors Management.

  • xdrProductivitySensorsMonthlyUsage, the monthly usage of Office 365 integration in Sensors Management.

  • xdrNetworkSensorsMonthlyUsage, the monthly usage of Network Sensor integration in Sensors Management.

  • xdrCloudSensorsMonthlyUsage, the monthly usage of AWS integration in Sensors Management.

  • sveVsMonthlyUsage - the monthly usage for virtual servers scanned with Security Server.

  • sveVdiMonthlyUsage - the monthly service usage (in hours) for virtual desktops scanned with Security Server.

  • minimumUsage - An Object containing types of licenses and the minimum number of slots which the company commits through legal agreement to use on a monthly basis:

    • endpointMonthlyUsage, the minimum number of endpoints that the client agreed to use from the main license.

Return example:

  {
  "result": {
    "endpointMonthlyUsage": 4,
    "encryptionMonthlyUsage": 0,
    "emailSecurityMonthlyUsage": 0,
    "mobileSecurityMonthlyUsage": 0,
    "exchangeMonthlyUsage": 0,
    "atsMonthlyUsage": 0,
    "edrMonthlyUsage": 0,
    "mdrFoundationsMonthlyUsage": 0,
    "mdrResponseMonthlyUsage": 0,
    "patchManagementMonthlyUsage": 0,
    "integrityMonitoringUsage": 0,
    "integrityMonitoring90DaysUsage": 0,
    "integrityMonitoring180DaysUsage": 0,
    "integrityMonitoring1YearUsage": 0,
    "sveVsMonthlyUsage": 0,
    "sveVdiMonthlyUsage": 0,
    "containerProtectionMonthlyUsage": 0,
    "xdrIdentitySensorsMonthlyUsage": 0,
    "xdrProductivitySensorsMonthlyUsage": 0,
    "xdrNetworkSensorsMonthlyUsage": 0,
    "xdrCloudSensorsMonthlyUsage": 0,
    "aLaCarteMonthlyUsage": 1,
    "mspSecureMonthlyUsage": 1,
    "mspSecurePlusMonthlyUsage": 0,
    "mspSecureExtraMonthlyUsage": 2
  },
  "jsonrpc": "2.0",
  "id": "5986",
  "error": null
}

For more information about this method, refer to getMonthlyUsage.

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.

Retrieve a company's licensing information

Use the getLicenseInfo method from Licensing API to retrieve license information for a company. For more information about this method, refer to getLicenseInfo.

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.

Bitdefender GravityZone – 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:

  1. Check the prerequisites.

  2. 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.

  3. Add the repository to the APT sources list.

  4. 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 -

  5. Configure via bash script.

  6. Enable system service.

  7. Test the connector.

  8. 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

  1. Connect to the Ubuntu 20.04 server.

  2. 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

  3. Install the DEB package.

    sudo apt update  
sudo apt install gz-evpsc

  4. 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.

  5. (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

  6. Enable the system service

    systemctl enable gz-evpsc

  7. 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 obtain an SSL/TLS certificate for this service in a few other ways:

  1. 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.

  2. 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.

  3. 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
In this section: