IntegrationServices Policy v3 API Migration

The integrationServices/v3/Policy API will be deactivated on September 5, 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

If you did not update prior to July 31st 2024

  • Review the log files of integrations that had not been updated to identify failures.
  • Update the integrations to use the PolicyService v1 APIs per this guide.
  • If the integration does not allow reprocessing of failed actions, or if the policy changes are urgent, use the Carbon Black Cloud console to make necessary changes.

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.

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

{
    "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"
}

{
    "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

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

{
    "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.


Last modified on June 3, 2024