Vault7: CIA Hacking Tools Revealed

Navigation: » Directory » Marble Framework

Marble Framework Home

SECRET//NOFORN

Marble Framework

Description: The Marble Framework is designed to allow for flexible and easy-to-use obfuscation when developing tools. When signaturing tools, string obfuscation algorithms (especially those that are unique) are often used to link malware to a specific developer or development shop. This framework is intended to help us (AEDApplied Engineering Devision) to improve upon our current process for string/data obfuscation in our tools. The framework utilizes pre and post-build execution steps to apply obfuscation to the tool. If the tool breaks the build, the post build will always be able to repair it. The pre-build execuion step will store clean copies of the code before making modifications. The post build execution step restores the files to a clean-copy state. The framework allows for obfuscation to be chosen randomly from a pool of techniques. These techniques can be filtered based upon the project needs. If desired, a user may also, select a specific technique to use for obfuscation. A receipt file is generated on run (and replaces any previous receipts). The receipt file identifes the algorithm used as well as all of the strings/data that was obfuscated. The post-build step will also double check to make sure none of the obfuscated data appears in the binary.

The framework's integration into the EDGEngineering Development Branch Project Wizard will set up the appropriate project and solution properties needed to run. Currently, the obfuscation framework will only be set for release builds. If it is so desired to debug the obfuscated strings you may manually set the pre and post build events.

Core Library Repository

Framework Terminology

Marble: A Marble is a specific algorithm that scrambles and unscrambles data.

Mibster: The Mibster is the utility that does the scrambling and altering of source files. The Mibster starts by choosing a Marble (an algorithm) from the filtered list of available algroithms. The Mibster then scans the directories containing source, looking for an strings and data to scramble. The Mibster keeps a clean copy of the original source and replaces it with the scrambled versions of strings/data as well as supplies the unscramble function. The source should compile after Mibster modifies source.

Mender: The Mender restores the source files to their original state. If, for any reason, the Mibster fails or breaks the code, the Meder can always restore the state to its original.

Warble: A Warble is a wide-character string (wchar_t *) that needs to be scrambled by the Mibster.

Carble: A Carble is a multi-byte string (char *) that needs to be scrambled by the Mibster.

Validator: The Validator is a utility that takes (as an input) the receipt file generated by the Mibster. The Validator uses the receipt file to verify that all the strings intended to be scrambled are not contained in the final binary.

Framework Diagram

Choosing Your Algorithms

When you first include the Marble Framework in your Project/Solution you will be given the default Marble.h header file. The default header file tells the Mibster to choose any Marble in the framework. Depending upon your style and/or project requirements you may want to alter this file (Marble.h). The options you have currently are as follows:

Use a specific algorithm:

//Class random key forward through array, constructor only, private variable, zero clear
//#include "MBL_CLASS_XOR1D.h"
 
//Class random key backwards through array, constructor only, private variable, zero clear
#include "MBL_CLASS_XOR2D.h"
 
//Class random key forward through array, constructor only, private variable, random clear
//#include "MBL_CLASS_XOR3D.h"
 
//Class random key backwards through array, constructor only, private variable, random clear
//#include "MBL_CLASS_XOR4D.h"

*By uncommenting the include for an algorithm, you tell the Mibster to use this specific algorithm. The Mibster parses this header from top to bottom. This means that if more than one define statement is uncommented, the algorithm listed first in the file will be chosen.

Use only C algorithms (No C++):

/*
	Define NOCPP if you wish to only choose from the pool of obfuscation techniques that do not/not pull in the C++ runtime. 
*/
#define NOCPP //Always use forward slashes to comment out this define

*By uncommenting the define for NOCPP, you indicate to the Mibster that only "C" algorithms should be included in the pool. C++ algorithms usually involve cleaning up (clearing) strings/data when destructed..

Exclude specific algorithms from the pool:

//Class random key forward through array, constructor only, private variable, zero clear
//#include "MBL_CLASS_XOR1D.h"
 
//Class random key backwards through array, constructor only, private variable, zero clear
//--#include "MBL_CLASS_XOR2D.h"
 
//Class random key forward through array, constructor only, private variable, random clear
//#include "MBL_CLASS_XOR3D.h"
 
//Class random key backwards through array, constructor only, private variable, random clear
//#include "MBL_CLASS_XOR4D.h"

*To exclude specific algorithms from the pool you must prepend two hyphens (–) to the include statement (see MBL_CLASS_XOR2 above).

Currently, all C++ algorithms contain cleanup routines.All algorithms generate random keys with which the data is obfuscated.

Coding With The Marble Framework

Now comes the fun stuff. Marble.h supplies you with two new types to use: CARBLE (char) and WARBLEObfuscation Function (see 14588467) (wchar_t). Using these types allow you to flag a string for obfuscation. The following are requirements for the Marble Framework to work successfully:

CARBLE and WARBLEObfuscation Function (see 14588467) strings/data must be declared inside of a function. If you are looking to do a Melomy look at using the MungePayload utility.
Use square braces ([ ]) not pointers (*).
All source file must be ANSI, UTF8, or Unicode.
There is no support for \U \u or \ooo (octals).
Special characters are supported \r, \n, etc. However, when using \x in strings you must supply 4 characters in a WARBLEObfuscation Function (see 14588467) string and 2 characters in a CARBLE string (Examples: CARBLE cTest[] = "\xAA\xBB"; WARBLEObfuscation Function (see 14588467) wcTest[] = L"\xAABB\xCCDD":)
You can use string literals or arrays to define your string/data. When using curly braces you must have the appropriate number of characters following 0x (2 characters for CARBLE, 4 characters for WARBLEObfuscation Function (see 14588467)).
String literals may not be on multiple lines. Currently multi-line string literals are not supported.
When using gotos in functions be aware that when using C++ obfuscation algorithms, you may get build errors for declaring objects after goto statements.

Now let's talk about what is supported. Here are some examples:

#include <Windows.h>
#include "Marble.h"

int wmain(int argc, wchar_t* argv[])
{
	//Normal Text
	CARBLE cOne[] = "This is a test of a string obfuscation technique";

	//Text with braces, semi colons escaped characters (including \x)
	CARBLE cTwo[] = " Text with weird {spaces} in; the text\n\n\t\tabc\x22\x33 124";
 
	//You can also use curly braces to define your string/data (must be two characters following 0x)
	CARBLE cThree[] = {
		0x32, 0xD7, 0x08, 0x57, 0x34, 0x34, 0xC8, 0x4B, 0xC5, 0xA8, 0x53, 0x45, 0xF2, 0x0D, 0xB7, 0xF0,
		0x5F, 0xD2, 0xED, 0xEA, 0xE1, 0x73, 0x2B, 0xCA, 0xFE
	};
	return 0;
}

#include <Windows.h>
#include "Marble.h"

int wmain(int argc, wchar_t* argv[])
{
	//Normal strngs including escaped characters as well as \x
	WARBLE wcOne[] = L" Text with \"weird spaces; in the text\n\n\t\tabc\x2233\x3344 124";
 
	//Normal Wide-Char string - can't be multi-line
	WARBLE wcTwo[] = L"Creates or opens a file or I/O device. The most commonly used I/O devices are as follows: file, file stream, directory, physical disk, volume, console buffer, tape drive, communications resource, mailslot, and pipe. The function returns a handle that can be used to access the file or device for various types of I/O depending on the file or device and the flags and attributes specified. To perform this operation as a transacted operation, which results in a handle that can be used for transacted I / O, use the CreateFileTransacted function.";
 
	//WCHAR array is supported
	WARBLE wcThree[] = {
		0x0000, 0x1122, 0x3344, 0x5566, 0x7799, 0x0000, 0x1122, 0x3344, 0x5566, 0x7799, 0x0000, 0x1122, 0x3344, 0x5566, 0x7799,
		0x0000, 0x1122, 0x3344, 0x5566, 0x7799, 0x0000, 0x1122, 0x3344, 0x5566, 0x7799, 0x0000, 0x1122, 0x3344, 0x5566, 0x7799
	};
 
	//Add foreign languages
	//Arabic
	WARBLE wcArabic[] = L"بعد أملاً شواطيء في, ٣٠ دول زهاء ماشاء. كل الشتاء، المجتمع واعتلاء حيث, غضون الشمال الشّعبين الى بل. قد قام الشتاء انتصارهم الإنذار،, بوابة قبضتهم اتفاقية بعض عل. شدّت وفرنسا ابتدعها ثم كما.";
	
	//Chinese
	WARBLE wcChinese[] = L"汫汭沎 煘煓瑐 廘榙榾 誙 钃麷, 鶭黮齥 逯郹崸嵀惉 滭滹漇 緳 踶輵 浶洯浽 螭蟅謕 嵉愊惵 橀 趏跮, 嵥 垼娕 蟷蠉蟼 鏀顝饇, 壾 鞈頨 跣鉌鳭 郺鋋錋 綒 嗛嗕塨 灊灅甗 礌簨繖 轒醭 醆鋍鞎 糲蘥蠩 炾笀耔 嵷 螭蟅, 駍駔鳿 簻臗藱 棳棔欿 嵷 揳揓";
	
	//Russian
	WARBLE wcRussian[] = L"Зыд нэ нонюмэш контынтёонэж. Видэ бландит ан квуй, дуо декам эпикюре эа. Йн дйкит мольлиз дэлььякатезшимя жят. Нэ мэль рыбюм мэльиорэ фэюгаят, зальы тхэопхражтуз ан мэя. Ут вэл хабымуч фиэрэнт инзтруктеор, ку шапэрэт пхаэдрум кончюлату ыам, ыюм но оптёон льаорыыт янтэрэсщэт.";
	
	//Korean
	WARBLE wcKorean[] = L"사용할 수있는 구절 많은 변화가 있지만, 대부분의, 주입 유머로, 어떤 형태의 변경을 입었거나 조금이라도 믿을 보이지 않는 단어를 무작위. 당신은 Lorem Ipsum의 통로를 사용하려는 경우, 당신은 텍스트의 가운데에 숨겨진 뭔가 당황 없다는 확신해야합니다";
	
	//Farsi
	WARBLE wcFarsi[] = L"لورم ایپسوم یا طرح‌نما (به انگلیسی: Lorem ipsum) به متنی آزمایشی و بی‌معنی در صنعت چاپ، صفحه‌آرایی و طراحی گرافیک گفته می‌شود. طراح گرافیک از این متن به عنوان عنصری از ترکیب بندی برای پر کردن صفحه و ارایه اولیه شکل ظاهری و کلی طرح سفارش گرفته شده استفاده می نماید، تا از نظر گرافیکی نشانگر چگونگی نوع و اندازه فونت و ظاهر متن باشد. معمولا طراحان گرافیک برای صفحه‌آرایی، نخست از متن‌های آزمایشی و بی‌معنی استفاده می‌کنند تا صرفا به مشتری یا صاحب کار خود نشان دهند که صفحه طراحی یا صفحه بندی شده بعد از اینکه متن در آن قرار گیرد چگونه به نظر می‌رسد و قلم‌ها و اندازه‌بندی‌ها چگونه در نظر گرفته شده‌است. از آنجایی که طراحان عموما نویسنده متن نیستند و وظیفه رعایت حق تکثیر متون را ندارند و در همان حال کار آنها به نوعی وابسته به متن می‌باشد آنها با استفاده از محتویات ساختگی، صفحه گرافیکی خود را صفحه‌آرایی می‌کنند تا مرحله طراحی و صفحه‌بندی را به پایان برند.";
	
	return 0;
}

Adding To The Framework

To add to the framework, here are the steps that need to be taken:

Write up an obfuscation algorithm breaking it into the following parts:
1. A scramble/unscramble class that inherits the IScramble interface (see the Marble Repository)
2. Any supportorting unscramble function that will reside in the deobfuscator header file
Creating a branch off of the Marble Repository, create a pull request to merge your code
Create a branch in the Marble Test Harness (repo here) and pull down the new code from Marble
Once the Test Harness is passed, create a pull request to merge the new code into Corelib
Do a pull to update any current projects utilizing the framework to get the lastest version of the framework

Reporting Issues With Marbles

If an issue occurs when building with any Marble algorithm, please report it by creating a JIRA issue under the Core Library Project. Alternatively you can email User #72806. To help with debugging the issue please copy the contents of the project (to include the receipt file from the build) to the folder \\FS-01\share\Marble-Issues\(Your Project Name). Also, include in the folder screenshots of the errors or a breif description. If you are trying to build in a tight timeline, make a copy of the issue in the share folder, modify Marble.h to exclude the Marble with the issue, and rebuild.

Marble Framework Breifing Slides:

Marble Framework.pptx

SECRET//NOFORN

Recent space activity

('recently-updated' missing)

Space contributors

('contributors' missing)

Attachments:

Sub-Pages:

Marble Descriptions SECRET
Setting Up Marble Manually SECRET
Setting Up Marble With The EDG Project Wizard SECRET
Component Diagram and Description SECRET

Previous versions:

Contact

Tor

Tails

Tips

1. Contact us if you have specific problems

2. What computer to use

3. Do not talk about your submission to others

After

1. Do not talk about your submission to others

2. Act normal

3. Remove traces of your submission

4. If you face legal action

Submit documents to WikiLeaks