IntegrationServices Policy v3 API Migration

The integrationServices/v3/Policy API will be deactivated on July 31, 2024.

Overview

This is to assist in migrating integrations from integrationServices/v3/Policy API to policyservice/v1 API.

In this document, you will find

A mapping of deprecated v3 Policy API endpoints to new v1 API endpoints
A mapping of deprecated v3 Policy schema to new v1 API schema
Sample payloads for the legacy v3 Policy APIs and the new v1 APIs

Guides and Resources

Carbon Black Cloud Python SDK
After migrating, learn how to increase security by removing unused API keys

Authorization Changes

The new PolicyService v1 APIs use role based access control (RBAC) to enable enforcement of least privilege, enabling API keys to be only granted the permissions necessary.

Grant the API key some of the following permissions based on the API operations to be performed.

org.policies.READ
org.policies.CREATE
org.policies.UPDATE
org.policies.DELETE

API Endpoints

All the new policyservice v1 APIs require org key to be passed as a path variable. The legacy v3 APIs used to derive the org key from the API key.

API Endpoint Equivalencies

Operation	Legacy v3 Policy Endpoint	New v1 PolicyService Endpoint
Get Policies	GET /integrationServices/v3/policy	N/A
Get Policy Summary	N/A	GET /policyservice/v1/orgs/{org_key}/policies/summary
Get Policy	GET /integrationServices/v3/policy/{id}	GET /policyservice/v1/orgs/{org_key}/policies/{id}
Create Policy	POST /integrationServices/v3/policy	POST /policyservice/v1/orgs/{org_key}/policies
Update Policy	PUT /integrationServices/v3/policy/{id}	PUT /policyservice/v1/orgs/{org_key}/policies/{id}
Delete Policy	DELETE /integrationServices/v3/policy/{id}	DELETE /policyservice/v1/orgs/{org_key}/policies/{id}
Add rule to policy	POST /integrationServices/v3/policy/{id}/rule	POST /policyservice/v1/orgs/{org_key}/policies/{id}/rules
Remove rule from policy	DELETE /integrationServices/v3/policy/{id}/rule/{rule_id}	DELETE /policyservice/v1/orgs/{org_key}/policies/{id}/rules/{rule_id}
Update existing rule	PUT /integrationServices/v3/policy/{id}/rule/{rule_id}	PUT /policyservice/v1/orgs/{org_key}/policies/{id}/rules/{rule_id}

Create/Update/Get Policy APIs

The following table contains the fields to be substituted when migrating from Policy Integration v3 APIs for Create/Update/Get Policy APIs. The fields or sub-fields not captured here remain the same for their respective API endpoints.

The policyService/v1 APIs return the entire policy object as a response.

Field Substitutions

Policy Integration v3 APIs	New PolicyService v1 APIs	Comments
success	N/A	success is now indicated with HTTP code
policyInfo.id	id
policyInfo.name	name
policyInfo.description	description
policyInfo.priorityLevel	priority_level
policyInfo.systemPolicy	is_system
N/A	org_key
policyInfo.latestRevision	N/A	Unused field
policyInfo.version	version
policyInfo.vdiAutoDeregInactiveIntervalMs	auto_deregister_inactive_vdi_interval_ms
policyInfo.policy.knownBadHashAutoDeleteDelayMs	auto_delete_known_bad_hashes_delay
policyInfo.policy.id	N/A	Unused field
policyInfo.policy.updateVersion	N/A	Unused field
policyInfo.policy.maxRuleID	N/A	Unused field
policyInfo.policy.sensorAutoUpdateEnabled	N/A	Unused field
policyInfo.policy.pscReportingRules	N/A	Unused field
policyInfo.policy.mobileSensorSettings	N/A	Unused field
policyInfo.policy.phishingSetting	N/A	Unused field
policyInfo.policy.sensorSettings	sensor_settings
policyInfo.policy.directoryActionRules	directory_action_rules
policyInfo.policy.directoryActionRules.actions.FILE_UPLOAD	directory_action_rules.file_upload	The elements in the action array are now moved at the direction_action_rules level.
policyInfo.policy.directoryActionRules.actions.PROTECTION	directory_action_rules.protection
policyInfo.policy.rules	rules
policyInfo.policy.avSettings	av_settings
policyInfo.policy.avSettings.apc	av_settings.avira_protection_cloud
policyInfo.policy.avSettings.apc.maxFileSize	av_settings.avira_protection_cloud.max_file_size
policyInfo.policy.avSettings.apc.riskLevel	av_settings.avira_protection_cloud.risk_level
policyInfo.policy.avSettings.apc.maxExeDelay	av_settings.avira_protection_cloud.max_exe_delay
policyInfo.policy.avSettings.onAccessScan	av_settings.on_access_scan	The ONACCESS_SCAN feature flag that was part of avSettings.features array is now moved under av_settings.on_access_scan
policyInfo.policy.avSettings.onAccessScan.profile	av_settings.on_access_scan.mode
policyInfo.policy.avSettings.features[].enabled	av_settings.on_access_scan.enabled
policyInfo.policy.avSettings.onDemandScan	av_settings.on_demand_scan	The ONDEMAND_SCAN feature flag that was part of avSettings.features array is now moved under av_settings.on_demand_scan
policyInfo.policy.avSettings.onDemandScan.scanUsb	av_settings.on_demand_scan.scan_usb
policyInfo.policy.avSettings.onDemandScan.scanCdDvd	av_settings.on_demand_scan.scan_cd_dvd
policyInfo.policy.avSettings.onDemandScan.schedule.recoveryScanIfMissed	av_settings.on_demand_scan.schedule.recovery_scan_if_missed
policyInfo.policy.avSettings.onDemandScan.schedule.rangeHours	av_settings.on_demand_scan.schedule.range_hours
policyInfo.policy.avSettings.onDemandScan.schedule.startHour	av_settings.on_demand_scan.schedule.start_hour
policyInfo.policy.avSettings.features[].enabled	av_settings.on_access_scan.enabled
policyInfo.policy.avSettings.signatureUpdate	av_settings.signature_update	The SIGNATURE_UPDATE feature flag that was part of avSettings.features array is now moved under av_settings.signature_update
policyInfo.policy.avSettings.signatureUpdate.schedule.fullIntervalHours	av_settings.signature_update.schedule.full_interval_hours
policyInfo.policy.avSettings.signatureUpdate.schedule.initialRandomDelayHours	av_settings.signature_update.schedule.initial_random_delay_hours
policyInfo.policy.avSettings.signatureUpdate.schedule.intervalHours	av_settings.signature_update.schedule.interval_hours
policyInfo.policy.avSettings.features[].enabled	av_settings.signature_update.enabled
policyInfo.policy.avSettings.updateServers	av_settings.update_servers
policyInfo.policy.avSettings.updateServers.serversOverride	av_settings.update_servers.servers_override
policyInfo.policy.avSettings.updateServers.serversForOffSiteDevices	av_settings.update_servers.servers_for_offsite_devices
policyInfo.policy.avSettings.updateServers.servers	av_settings.update_servers.servers_for_onsite_devices
policyInfo.policy.avSettings.updateServers.servers.regId	N/A	Unused field
policyInfo.policy.avSettings.updateServers.servers.flags	av_settings.update_servers.servers_for_onsite_devices.preferred	This flags field is renamed to preferred and its type is now boolean and not integer
policyInfo.policy.avSettings.updateServers.servers.server	av_settings.update_servers.servers_for_onsite_devices.server	The server field was an array of strings, now it is just a string
policyInfo.threatSightMdrConfiguration	managed_detection_response_permissions
policyInfo.threatSightMdrConfiguration.policyModificationPermission	managed_detection_response_permissions.policy_modification
policyInfo.threatSightMdrConfiguration.quarantinePermission	managed_detection_response_permissions.quarantine

Sample Payloads

Sample Legacy integrationServices v3 API Payload

{
    "policyInfo": {
        "id": 7049,
        "priorityLevel": "LOW",
        "systemPolicy": false,
        "latestRevision": 1505155560455,
        "policy": {
            "sensorSettings": [{
                "name": "SHOW_UI",
                "value": "true"
            }, {
                "name": "BACKGROUND_SCAN",
                "value": "true"
            }],
            "avSettings": {
                "updateServers": {
                    "servers": [{
                        "flags": 0,
                        "regId": null,
                        "server": ["http://updates.cdc.carbonblack.io/update"]
                    }],
                    "serversForOffSiteDevices": ["http://updates.cdc.carbonblack.io/update"]
                },
                "apc": {
                    "maxFileSize": 4,
                    "maxExeDelay": 45,
                    "riskLevel": 4,
                    "enabled": false
                },
                "onAccessScan": {
                    "profile": "NORMAL"
                },
                "features": [{
                    "enabled": false,
                    "name": "SIGNATURE_UPDATE"
                }, {
                    "enabled": true,
                    "name": "ONACCESS_SCAN"
                }, {
                    "enabled": true,
                    "name": "ONDEMAND_SCAN"
                }],
                "onDemandScan": {
                    "profile": "NORMAL",
                    "scanCdDvd": "AUTOSCAN",
                    "scanUsb": "AUTOSCAN",
                    "schedule": {
                        "days": null,
                        "rangeHours": 0,
                        "startHour": 0,
                        "recoveryScanIfMissed": true
                    }
                },
                "signatureUpdate": {
                    "schedule": {
                        "intervalHours": 2,
                        "fullIntervalHours": 0,
                        "initialRandomDelayHours": 4
                    }
                }
            },
            "directoryActionRules": [{
                "actions": {
                    "FILE_UPLOAD": false,
                    "PROTECTION": false
                },
                "path": "C:\\FXCM\\**"
            }],
            "rules": [{
                "id": 1,
                "required": true,
                "operation": "RUN",
                "application": {
                    "value": "KNOWN_MALWARE",
                    "type": "REPUTATION"
                },
                "action": "DENY"
            }, {
                "id": 2,
                "required": true,
                "operation": "RUN",
                "application": {
                    "value": "COMPANY_BLACK_LIST",
                    "type": "REPUTATION"
                },
                "action": "DENY"
            }],
            "id": -1
        },
        "version": 2,
        "name": "documentation test 2",
        "description": "test policy for documentation"
    },
    "success": true,
    "message": "Success"
}

Sample Policy Service v1 API Payload

{
    "id": 4920125,
    "name": "Standard",
    "org_key": "ABCD1234",
    "priority_level": "MEDIUM",
    "position": -1,
    "is_system": true,
    "description": "Prevents known malware and reduces false positives. Used as the default policy for all new sensors, unless sensor group criteria is met.",
    "auto_deregister_inactive_vdi_interval_ms": 0,
    "auto_delete_known_bad_hashes_delay": null,
    "av_settings": {
        "avira_protection_cloud": {
            "enabled": false,
            "max_exe_delay": 45,
            "max_file_size": 4,
            "risk_level": 4
        },
        "on_access_scan": {
            "enabled": true,
            "mode": "NORMAL"
        },
        "on_demand_scan": {
            "enabled": true,
            "profile": "NORMAL",
            "schedule": {
                "days": null,
                "start_hour": 0,
                "range_hours": 0,
                "recovery_scan_if_missed": true
            },
            "scan_usb": "AUTOSCAN",
            "scan_cd_dvd": "AUTOSCAN"
        },
        "signature_update": {
            "enabled": true,
            "schedule": {
                "full_interval_hours": 0,
                "initial_random_delay_hours": 4,
                "interval_hours": 4
            }
        },
        "update_servers": {
            "servers_override": [],
            "servers_for_onsite_devices": [{
                "server": "http://updates2.cdc.carbonblack.io/update2",
                "preferred": false
            }],
            "servers_for_offsite_devices": ["http://updates2.cdc.carbonblack.io/update2"]
        }
    },
    "rules": [{
            "id": 1,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "KNOWN_MALWARE"
            },
            "operation": "RUN"
        },
        {
            "id": 2,
            "required": false,
            "action": "TERMINATE",
            "application": {
                "type": "REPUTATION",
                "value": "COMPANY_BLACK_LIST"
            },
            "operation": "RUN"
        }
    ],
    "directory_action_rules": [{
        "file_upload": false,
        "protection": false,
        "path": "C:\\FXCM\\**"
    }],
    "sensor_settings": [{
        "name": "ALLOW_UNINSTALL",
        "value": "true"
    }],
    "managed_detection_response_permissions": {
        "policy_modification": true,
        "quarantine": true
    },
    "version": null,
    "message": null
}
\

Delete Policy API

The new Delete Policy API returns a 204 no content response on success.

Add/Update Policy Rule APIs

The payload for these APIs had a top-level ruleInfo field. In the new APIs, the ruleInfo field is removed and all its members are now direct members of the new payload. Please see the samples below.

Sample payloads

Sample Legacy integrationServices v3 API Payload

{
    "ruleInfo": {
        "action": "DENY",
        "application": {
            "type": "REPUTATION",
            "value": "COMPANY_BLACK_LIST"
        },
        "operation": "RANSOM",
        "required": true,
        "id": 1
    }
}

Sample Policy Service v1 API Payload

{
    "id": 3,
    "required": false,
    "action": "TERMINATE",
    "application": {
        "type": "REPUTATION",
        "value": "SUSPECT_MALWARE"
    },
    "operation": "RUN"
}

Delete Policy Rule API

The new Delete Policy Rule API returns a 204 no content response on success.

Carbon Black Cloud Python SDK Migration

Version 1.4.0 of the Carbon Black Cloud Python SDK supports the new policyService/v1 APIs.

This was a breaking change to users of the API; users must change the credentials to a Custom API key with necessary permissions.

All legacy methods remain to provide backwards compatibility.

Customers should update to the new cbc_sdk.platform Policies module to take advantage of new features at their convenience so new features can be used in the future.

See details in the 1.4.0 release notes for the Carbon Black Cloud Python SDK.

Give Feedback

New survey coming soon!

Last modified on August 17, 2022

Carbon Black Cloud

Page Contents