========================================================================
       COMbust 0.9 BETA - 03/20/2003
========================================================================

Why?
====

COMbust is a tool for testing ActiveX/COM/DCOM components on the Windows platform.  It enumerates the interfaces provided by the components and uses intelligent fuzzing to inject data into the components for testing.  It can quickly find security vulnerabilities due to improper input validation. 


What COM objects can be assessed?
=================================

COM objects COMbust can fuzz need to have a Dispatch interface. Scripts can be used to get around non creatable objects or objects presenting a dynamic interface. On the other hand, objects expecting call back interfaces can currently not be assessed.

What does COMbust do?
=====================

At a high level:
- Enumerates all methods published by an object
- Calls each method with boundary cases arguments

The COMbust.xml file lists argument values for each type of variable. For example if an object implements foo(BSTR,INT), COMbust will call foo with all combinations possible created with a VT_BSTR and a VT_INT.

So What?
========

Now the fun part! Sometimes COMbust or the object hosting process will crash... this means that you found at least a DOS if not a buffer overflow (look out for the infamous exception at 0x41414141).
If you monitor the file system and registry, you might find ways to remotely access them.

COMbust.xml
===========
This xml file is divided into multiple sections:
- "<Config>" for configuration elements
- "<Fuzz>" for fuzzing values
- "<Ignore>" for methods you want to avoid

<Config>
Currently, the only configuration available is "<MaxCombinations>". This integer represents the maximum number of calls that can be made to a single function.
To build on the foo(BSTR,INT) example, if you have 8 strings and 4 integers, this represents 32 combinations. If <MaxCombinations> was set to 10, COMbust would move on to the next method after testing the first 10 combinations. 
For the record, a few methods I have seen had 14 variant arguments (total: 35^14)!

<Fuzz>
This node  represents the test values for each variant type. You will notice it has a subnode for each variant type containing an unlimited number of <value>.

<Fuzz:value>
Each value has the following syntax:
<value Label="_label_" [count="_count_"] [dt:dt="_type_"]>val</value>
where:
_label_ is a textual description of this test case. Currently not used by the application
_count_ is an optional repeat count in string values. 
_type_ is an xml typecast so that the value is converted automatically to a variant type.

Examples:
<value Label="Long string" count="4000" dt:dt="string">A</value>
Will create a 4k string of As.

<Value Label="true" dt:dt="Boolean">1</Value>
Will create a boolean of value "true".

<Ignore>
This node lists all methods to be ignored. This includes COM framework related functionality such as AddRef and Release, but can also include methods you want COMbust to ignore. The syntax is as follows:
<value>[ProgId::]FunctionName</value>
Where:
- ProgId is the optional Object name
- FunctionName is the method name to ignore. This is a case insensitive comparison.

Keep in mind that is an Object publishes a "Get" and "Set" method with the same name, they will both be ignored if they have the same name.

Examples:
<value>AddRef</value>
Ignores "AddRef" in any object fuzzed

<value>Edit.Ctl::CanPaste</value>
Ignores the method(s) called "CanPaste" for an object called "Edit.Ctl".

Basic Call:
===========

COMbust can be executed in two ways:
- with a CLSID:  COMbust -c {EF99BD32-C1FB-11D2-892F-0090271D4F88}
- with a ProgId: COMbust -p msxml2.domdocument.3.0

Both are synonyms. Use the most convenient format depending on your source for the object to fuzz.

Advanced Call:
==============
To the above calls, you can add:
- "-f FunctionName"  to only fuzz a single function
- "-o" to produce a batch file for fuzzing each function independently. This can be useful to automate testing of an object.
- "-e" option to safely enumerate content of the object. In this case, COMbust does not fuzz the object but only enumerates the methods.

Output:
=======
The output is divided into 3 sections:
- Header Info
- Method Enumeration
- Fuzzing

Output is verbose... Bear with me as sometimes processes die without notice and the output trace is all that's left even though it can be infrequently misleading.

Header Info
CLSID and ProgId in addition to published information associated to the object. Also contains number of published methods.

Method Enumeration
For each method, full signature including return type, argument names and types. The following line contains textual description of the method if provided by the object.
At the end of the enumeration, COMbust will display the number of combinations to be tested.

Fuzzing
For each method, COMbust will output the actual function call with arguments. If the argument is longer than 15 characters, the output will truncate it and append "(...)" to it. 
Following the function call, whatever response or handled exception is also displayed.

If COMbust detects an unhandled exception, it will output the crucial key word "CRASH!!!!" when the exception is caught by COMbust.

Scripting
=========
Not all COM objects are directly accessible by COMbust. Some objects are not insatiable and require a call to a helper function to get an instance; other objects require initialization before being functional.
To solve these issues, COMbust has 3 scriptable entry points:
- Creation of an object
- Initialization of an object
- Cleanup

Calling COMbust with "-s filepath" will enable the functionality. The file extension will trigger the scripting language:
- ".vbs" will assume vbscript
- ".js" will assume javascript

A script file can have any or all of the following implemented:
- function NewObject() to create a new object
- function Finalize(obj) to cleanup an object.
- function Initialize(obj) to initialize an object COMbust created

NewObject()
This function can do anything, but must return a COM object. For example:

'Will fuzz an instance of ChildObject.
function NewObject()
	set a = CreateObject("My.ProgId.1")
	MsgBox("hello")
	set NewObject = a.GetChildObject()
end function


Finalize()
If this function is implemented, it will be called once COMbust fuzzed the object.

'save xml file.
Function Finalize(obj)
	obj.Save()
end function


Initialize()
If this function is implemented, it will be called before COMbust fuzzes the object.

'Load xml file.
Function Initialize(obj)
	obj.Load("test.xml")
end function



Sample Output
=============
 Note that edits will be represented by "[...]"

C:\COMbust -p msxml2.domdocument.3.0

***************************************************************************
msxml2.domdocument.3.0 - 0
***************************************************************************
COM Interface for:msxml2.domdocument.3.0
        Name:IXMLDOMDocument2
        Description:(null)
        Help File:(null)

        Functions:82
        Variables:0
        Implementations:1
Dispatch Function VOID QueryInterface(PTR  riid ,PTR  ppvObj )
[...]
Dispatch Function PTR createProcessingInstruction(BSTR  target ,BSTR  data )
        create a processing instruction node
[...]
Combinations to be tested: 1984
IGNORING: Dispatch Function VOID QueryInterface(PTR  riid ,PTR  ppvObj )
[...]
Dispatch Put VOID nodeValue("" )
Dispatch Put VOID nodeValue(".\fuzz.file" )
Dispatch Put VOID nodeValue("\\?\c:\fuzz.log" )
Dispatch Put VOID nodeValue("AAAAAAAAAAAAAAA(...)" )
Dispatch Put VOID nodeValue("BBBBBBBBBBBBBBB(...)" )
[...]
Dispatch Put VOID nodeValue(-1 )
Dispatch Put VOID nodeValue(-99999999.9999 )
Dispatch Put VOID nodeValue(99999999.9999 )
[...]		

Feedback:
=========
Send comments/praise/flame to fbret@stake.com
If you publish any findings, please mention COMbust!


Version History:
================

03/20/2003 - 0.9b Second internal release
12/02/2002 - First internal release
10/15/2003 - 0.1 Working proof of concept
