Extending Native Winapi Functionality

Winapi Access

Vbscript in and of itself can not directly call every native function that makes up the windows api. It lacks a foreign function interface that would make direct calls possible. With that said, Vbscript is able to call com methods that are exposed via the IDispatch interface. Com modules can be written in a wide variety of languages. By using one of these other languages that does have full win32 api access we are able to expand the functionality of what we can accomplish.

The code containing our example com api is available in the top level "api" folder. It is written using c++ because that is a language I'm more comfortable with. C++ usage is by no means required, a number of other languages could be used and the associated UUID's would just need to be updated in the install scripts if using manual placement. I'm going to outline what extending the com api via the existing c++ could work look like below

Project setup

The COM api is built from a project under the top level "api" folder. It is developed as a visual studio 2022 project. As it currently stands the project will output new builds to a "bin" folder. Copy the dll's into the Specula servers "data/payloads/api" folder to update what will be pushed and installed with your new product.

adding new functions

There are 3 files the need to be updated in the COM project to add a new function to the exposed api.

1. SpeculaAPI.idl
2. Specula.h
3. Specula.cpp

idl

To add a new function you start by defining it within the IDL. All of the available options for syntax is beyond the scope of what I want to cover, but simply put, you'll use the next id to declare a function returning an HRESULT. Next you'll define input and output parameters. its very likely you want your output parameter to be a retval that is returned when the function is called from a scripting language.

header

You'll match the name and arguments as defined in the idl file. the function definition needs to be wrapped using the STDMETHOD macro. This is declaring the method as a part of your COM object similar to adding a method to any old c++ class.

CPP

Here you'll implement your functionality. Remember that you must return an HRESULT with S_OK representing a successful operation. Use the passed in pointer to populate the retval that is returned to the script.

Adding server code

After you have updated the API and placed it on the Specula server you need to create a module to support the usage of the newly exposed COM api function. Most information related to development of a new module can be found here

You can follow the existing examples under functions/api/* to see how to access the com object and use it.

We recommend adding this overload to the module's preprocess function.

 def preprocess(self, agent):
        if agent.api_verified != True:
            raise RuntimeError("API has not been verified, please run api_verify first to check that the API is working\nIf it works it will mark the attribute api_verified to True\nTo override you would need to use dbedit to change the value to true")