Script Deobfuscation API

Overview

Allows users to deobfuscate obfuscated PowerShell scripts. Deobfuscation increases an analyst’s efficiency when analyzing malicious scripts.

Use Cases

  • Automatically deobfuscating PowerShell is not something that is generally and automatically available in industry.
  • Deobfuscation of PowerShell opens the doors to understanding attackers better and faster than manually deobfuscating
  • This API allows customers to automatically extract previously difficult information from a PowerShell script, and also deobfuscating and returning a more human readable version.


Note: This was initially released under the internal name Reveal and updated shortly after to Script Deobfuscation API.

Requirements

  • Any Carbon Black Cloud product

Resources


Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/tau/v2/orgs/{org_key}/reveal

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Deobfuscation > Script Deobfuscation (previously Reveal) API > script.deobfuscation, allow permission to EXECUTE

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/tau/v2/orgs/{org_key}/reveal

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Deobfuscation:script.deobfuscation, allow permission to EXECUTE

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.

API Calls

Deobfuscate script

Allows users to deobfuscate obfuscated scripts

API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud script.deobfuscation EXECUTE Majority of environments
VMware Cloud Services Platform _API.Deobfuscation:script.deobfuscation.execute N/A - included in permission name Prod UK and AWS GovCloud (US)
Note:


Request 
POST {cbc-hostname}/tau/v2/orgs/{org_key}/reveal

Request Body - application/json

{
  "input": "<string>"
}


Body Schema

Field Definition Data Type Values
input REQUIRED Obfuscated script content String

Response Codes

Code Description Content-Type Content
200 Script deobfuscated application/json Example Response Below
400 Bad request application/json 
{
    "error_code": "Bad Request",
    "message": "Malformed json payload: json payload has only one known property Input"
}
404 Not found application/json 
{
  "error_code": "Not Found",
  "message": "Not Found"
}

Examples

Request 
POST https://defense.conferdeploy.net/tau/v2/orgs/ABCD1234/reveal
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
        "input": "\"powershell.exe\" -noninteractive -encodedcommand WwBDAG8AbgBzAG8AbABlAF0AOgA6AEkAbgBwAHUAdABFAG4AYwBvAGQAaQBuAGcAIAA9ACAATgBlAHcALQBPAGIAagBlAGMAdAAgAFQAZQB4AHQALgBVAFQARgA4AEUAbgBjAG8AZABpAG4AZwAgACQAZgBhAGwAcwBlADsAIABJAG4AdgBvAGsAZQAtAEEAdABvAG0AaQBjAFQAZQBzAHQAIABUADEAMQA5ADcAIAAtAFQAZQBzAHQATgBhAG0AZQAgACIAQgBpAHQAcwBhAGQAbQBpAG4AIABEAG8AdwBuAGwAbwBhAGQAIAAoAGMAbQBkACkAIgAgAC0AUABhAHQAaABUAG8AQQB0AG8AbQBpAGMAcwBGAG8AbABkAGUAcgAgAEMAOgBcAEEAdABvAG0AaQBjAFIAZQBkAFQAZQBhAG0AXABDAHkAYgBvAHIAZwBcAGEAdABvAG0AaQBjAHMAIAAgAC0ASQBuAHAAdQB0AEEAcgBnAHMAIABAAHsAIgByAGUAbQBvAHQAZQBfAGYAaQBsAGUAIgAgAD0AIAAiAFMAdQBzAHAAaQBjAGkAbwB1AHMAVABMAEQAIgB9AA=="
}
Response Body 
{
    "original_code": "[Console]::InputEncoding = New-Object Text.UTF8Encoding $false\n\n\nInvoke-AtomicTest T1197 -TestName \"Bitsadmin Download (cmd)\" -PathToAtomicsFolder C:\\AtomicRedTeam\\Cyborg\\atomics -InputArgs @{remote_file = \"SuspiciousTLD\",\n}\n",
    "deobfuscated_code": "[Console]::InputEncoding = New-Object Text.UTF8Encoding $false\n\n\nInvoke-AtomicTest T1197 -TestName \"Bitsadmin Download (cmd)\" -PathToAtomicsFolder C:\\AtomicRedTeam\\Cyborg\\atomics -InputArgs @{remote_file = \"SuspiciousTLD\",\n}\n",
    "identities": [
        "InputEncoding",
        "Invoke-AtomicTest",
        "New-Object",
        "T1197",
        "Text.UTF8Encoding"
    ],
    "strings": [],
    "obfuscation_level": 0.029678002879441317
}
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

Script Deobfuscation Response

Field Definition Data Type Values
deobfuscated_code Deobfuscated script String
identities Keywords identified in the deobfuscated script.Keys are the high level descriptions of the contained strings, and are dynamic over time. Array
obfuscation_level Level of obfuscation identified, Score from ML model, a floating point number in range of 0.0 to 1.0, where 1 being definitely obfuscated according to the model. Float
original_code Obfuscated input provided in request String
strings List of strings identified in the script and consist of function names, method names, and string values. Array

Last modified on October 30, 2023