ToolEmbed¶

ToolEmbed is used to add resources (binaries, configuration files) to a DFIR ORC binary. It takes an XML configuration file as input. To understand why this is needed and what happens when DFIR-Orc.exe is executed, please refer to Architecture. A tutorial presents how to configure and reconfigure binaries.

In daily life, when using a repository as DFIR ORC configuration GitHub, one can directly edit configuration files and run the script Configure.cmd, which essentially sets a few environment variables and runs ToolEmbed.

ToolEmbed is also able to extract all the resources from a configured binary, thanks to the /dump option. This can be useful to quickly edit a configuration and obtain a new configured binary.The tutorial illustrates this scenario.

Important

ToolEmbed is run from the packaged DFIR-Orc.exe, built with OrcCapsule.exe capsule add: it configures a copy of the binary it runs from. The input element is no longer used, and is ignored with a warning.

Run from a binary that is not packaged, such as DFIR-Orc_x64.exe, ToolEmbed does nothing but print:

[DEPRECATED] DFIR-ORC does not use Mothership anymore, call ToolEmbed from Capsule wrapper

The layout of the XML configuration file is as follows:

<input > value </input> (ignored)
<output > value </output>
<run attributes=”…”></run>
<run32 attributes=”…”></run32>
<run64 attributes=”…”></run64>
<file attributes=”…” />
<pair attributes=”…” />
<archive attributes=”…” >
<file attributes=”…” />
</archive>

</toolembed>

Here is a typical ToolEmbed configuration file.

<toolembed>
    <output>.\output\DFIR-Orc.exe</output>

    <run32 args="WolfLauncher">self:#</run32>
    <run64 args="WolfLauncher">7z:#Tools|DFIR-Orc_x64.exe</run64>

    <file name="WOLFLAUNCHER_CONFIG" path=".\config\DFIR-ORC_config.xml"/>

    <file name="GetHives_config.xml" path=".\config\GetHives_config.xml"/>
    <file name="GetUserHives_config.xml" path=".\config\GetUserHives_config.xml"/>
    <file name="GetSamHive_config.xml" path=".\config\GetSamHive_config.xml"/>
    <file name="GetEvents_config.xml" path=".\config\GetEvents_config.xml"/>
    <file name="NTFSInfo_config.xml" path=".\config\NTFSInfo_config.xml"/>
    <file name="NTFSInfoHashPE_config.xml" path=".\config\NTFSInfoHashPE_config.xml"/>
    <file name="FatInfo_config.xml" path=".\config\FatInfo_config.xml"/>
    <file name="FatInfoHashPE_config.xml" path=".\config\FatInfoHashPE_config.xml"/>
    <file name="GetArtefacts_config.xml" path=".\config\GetArtefacts_config.xml"/>
    <file name="GetYaraSamples_config.xml" path=".\config\GetYaraSamples_config.xml"/>
    <file name="ruleset.yara" path=".\config\ruleset.yara"/>

    <archive name="Tools" format="7z" compression="Ultra">
        <file name="DFIR-Orc_x64.exe" path=".\tools\DFIR-Orc_x64.exe"/>
        <file name="autorunsc.exe" path=".\tools\autorunsc.exe"/>
    </archive>
</toolembed>

Usage¶

There are two most classical ways to use ToolEmbed:

The following command allows to obtain a configured binary, using an XML configuration file specifying all necessary elements.

DFIR-Orc.exe ToolEmbed /config=DFIR-Orc_embed.xml

Alternatively, the /embed option can be used as a more flexible replacement:

DFIR-Orc.exe ToolEmbed /embed=c:\path\to\your\config\DFIR-Orc_embed.xml /out=DFIR-Orc.exe
; Or
DFIR-Orc.exe ToolEmbed /embed=c:\path\to\your\config\ /out=DFIR-Orc.exe

The line below allows to extract resources from a configured binary in a directory of choice.

DFIR-Orc.exe ToolEmbed /dump=Configured-binary.exe /out=dump-dir\

Warnings¶

ToolEmbed tries to detect a risky configuration and warns about it, but still builds the binary: the decision is the user’s, so an insecure configuration remains possible.

It warns when:

collected data is uploaded unencrypted: an archive no recipient covers, or a log, console, outline or outcome without encryption;
the upload entries do not have the same include/exclude;
retry is used with mode="async", where it has no effect.

`toolembed` Element¶

optional=no, default=N/A

Root element.

Back to Root

`input` Element, `/input=<Path>` Option¶

Deprecated since version 10.3: The input element (and its /input command-line equivalent) named the binary ToolEmbed used as a Mothership. DFIR ORC does not use a Mothership any more: ToolEmbed configures the packaged binary it runs from.

An input element left in a configuration file is ignored, and reported as such.

optional=yes (ignored), default=N/A

The element is kept only so that configuration files written for earlier versions still parse. It has no effect: the resources are added to a copy of the running binary, written to output.

Back to Root

`output` Element, `/out=<Path>` Option¶

optional=no, default=N/A

This element contains the path to the output file created by ToolEmbed. It is first created as a copy of the input file and, then, the specified resources are added. Environment variables will be substituted.

For details on the output element syntax, please refer to the output documentation.

Example¶

<output>.\output\DFIR-Orc.exe</output>

Back to Root

`run` Element, `/run=<Ressource>` Option¶

optional=yes, default=N/A

This element specifies the unconfigured binary which should run. See Architecture for details. This element can be overridden by run32 or run64 elements (or options).

Attributes¶

args (optional=yes, default=N/A)
The optional args attribute allows the addition of arguments. This yields a command line starting with the specified binary, followed by the optional args, then potentially followed by arguments passed on by the capsule.

Example¶

...
<run args="WolfLauncher">self:#</run>

This example results in the capsule relaunching itself with the added argument “WolfLauncher” (which results in the execution of the code of WolfLauncher, the scheduler for DFIR ORC). Notation self:# and resources are documented in Referencing Resources in Configurations.

Back to Root

`run32` Element, `/run32=<Ressource>` Option¶

Deprecated since version 10.3: The run32 element (and its /run32 command-line equivalent) is deprecated for specifying DFIR-ORC binaries. Use the new /embed option instead.

optional=yes, default=N/A

This element specifies the unconfigured binary which should run on 32-bit platforms. See Architecture for details. When specified this element overrides a run element (or option).

Attributes¶

args (optional=yes, default=N/A)
The optional args attribute allows the addition of arguments. This yields a command line starting with the specified binary, followed by the optional args, then potentially followed by arguments passed on by the capsule.

Example¶

...
<run32 args="WolfLauncher">self:#</run32>

This example results in the capsule relaunching itself with the added argument “WolfLauncher” (the scheduler for DFIR ORC). Notation self:# and resources are documented in Referencing Resources in Configurations.

Back to Root

`run64` Element, `/run64=<Ressource>` Option¶

Deprecated since version 10.3: The run64 element (and its /run64 command-line equivalent) is deprecated for specifying DFIR-ORC binaries. Use the new /embed option instead.

optional=yes, default=N/A

This element specifies the unconfigured binary which should run on 64-bit platforms. See Architecture for details. When specified this element overrides a run element (or option).

Attributes¶

args (optional=yes, default=N/A)
The optional args attribute allows the addition of an argument (before all transmitted arguments)

Example¶

<run64 args="WolfLauncher">7z:#Tools|Orc_x64.exe</run64>

This example results in the launch of Orc_x64.exe contained in the 7z archive Tools, with the added argument “WolfLauncher” (the scheduler for DFIR ORC). Notation 7z:#Tools and resources are documented in Referencing Resources in Configurations.

Back to Root

`file` Element, `/AddFile=<Path>,<Name>` Option¶

optional=yes, default=N/A

The file element provides a simple way to embed a file as a resource in the destination binary.

Attributes¶

name (optional=no, default=N/A)
The name of the resource to be created in the target binary
path (optional=no, default=N/A)
The path to the file to be added to the resource

Example¶

<file name="WOLFLAUNCHER_CONFIG" path=".\config\DFIR-ORC_config.xml"/>

This creates a resource named WOLFLAUNCHER_CONFIG which contains the .\config\DFIR-ORC_config.xml file. On a command line, the equivalent resource is created by using /AddFile=.\config\DFIR-ORC_config.xml,WOLFLAUNCHER_CONFIG.

Back to Root

`pair` Element, `/name=<Value>` Option¶

optional=yes, default=N/A

This element is used internally to allow a level of indirection between a tool binary code and the configured resources. This should not be necessary in a user-created configuration.

Attributes¶

name (optional=no, default=N/A)
The name of the resource
value (optional=no, default=N/A)
The string value of the resource.

Example¶

<pair name="XMLLITE_X86DLL" value="7z:#Tools|xmllite.dll" />

This line creates a resource named XMLLITE_X86DLL which contains the string “7z:#Tools|xmllite.dll”.

Back to Root

`archive` Element¶

optional=yes, default=N/A

The archive element provides the ability to embed files in a resource but in a compressed archive (to minimize the size of the resulting binary). This element is a container for file sub-elements used to define the archive (see below).

This mechanism is deemed too complex to be described on a command line, there is no equivalent option. To use it, an XML configuration file must be passed as an argument through the /config option.

Attributes¶

name (optional=no, default=N/A)
The name attribute is the name of the resource to be created in the target binary
format (optional=no, default=”cab”)
The archive format to use to archive the files. Allowed values are:
- cab
- zip
- 7z
compression (optional=yes, default=”fast”)
The level of compression in the archive (for zip and 7zip format). Supported values are:
- None
- Fastest
- Fast
- Normal
- Maximum
- Ultra

Example¶

<archive name="Tools" format="7z" compression="Ultra">
        ...
</archive>

This creates a resource in the output file named “Tools” in the 7zip archive file format.

Back to Root

`file` Element (in `archive`)¶

The file element provides a simple way to embed a file in an archive in the configured binary.

Attributes¶

name (optional=no, default=N/A)
The name attribute is the name of the resource to be created in the target binary
path (optional=no, default=N/A)
The file system path to the file to be added to the resource relative to the current directory.

Example¶

<archive name="Tools" format="7z" compression="Ultra">
    <file name="DFIR-Orc_x64.exe" path=".\tools\DFIR-Orc_x64.exe"/>
    <file name="autorunsc.exe" path=".\tools\autorunsc.exe"/>
</archive>

This creates a resource named “Tools” in the 7zip file format. This archive will contain two files:

DFIR-Orc_x64.exe copied from .\tools\DFIR-Orc_x64.exe
autorunsc.exe copied from .\tools\autorunsc.exe

These paths are relative to the directory where DFIR-Orc.exe toolembed is launched.

Back to Root

`/dump[=<Path>]` Option¶

optional=yes, default=N/A

This option allows to extract the resources from a configured binary (stored at the given path), in a directory specified using /out. This option has no equivalent XML element, it just exists as a switch to revert the behavior of ToolEmbed, and when extracting resources no configuration file is needed.

DFIR-Orc.exe toolembed /dump=DFIR-Orc-1.exe /out=dumpdir\

This command writes the unconfigured binaries and configurations embedded in dumpdir\.

If this option is used without specifying a <Path>, the resources of the executed DFIR ORC binary itself are dumped.

DFIR-Orc.exe toolembed /dump /out=dumpdir\

`/embed=<Path>` Option¶

optional=yes, default=N/A

This option is a more flexible replacement for the combination of /fromdump and /config. It accepts a path that can point to either:

an XML configuration file describing the embedding operation.
an XML configuration directory with every XML inside.

This option supersedes both /fromdump and /config and is the recommended way to configure a DFIR-ORC binary going forward. This option can be executed from any directory.

DFIR-Orc.exe ToolEmbed /embed=DFIR-Orc_embed.xml /out=DFIR-Orc.exe

`/force` Option¶

optional=yes, default=N/A

Allow ToolEmbed to overwrite an existing output binary.

DFIR-Orc.exe ToolEmbed /config=DFIR-Orc_embed.xml /out=DFIR-Orc.exe /force

Version

Table of Contents

ToolEmbed¶

Usage¶

Warnings¶

`toolembed` Element¶

`input` Element, `/input=<Path>` Option¶

`output` Element, `/out=<Path>` Option¶

Example¶

`run` Element, `/run=<Ressource>` Option¶

Attributes¶

Example¶

`run32` Element, `/run32=<Ressource>` Option¶

Attributes¶

Example¶

`run64` Element, `/run64=<Ressource>` Option¶

Attributes¶

Example¶

`file` Element, `/AddFile=<Path>,<Name>` Option¶

Attributes¶

Example¶

`pair` Element, `/name=<Value>` Option¶

Attributes¶

Example¶

`archive` Element¶

Attributes¶

Example¶

`file` Element (in `archive`)¶

Attributes¶

Example¶

`/dump[=<Path>]` Option¶

`/embed=<Path>` Option¶

`/force` Option¶

ToolEmbed¶

Usage¶

Warnings¶

toolembed Element¶

input Element, /input=<Path> Option¶

output Element, /out=<Path> Option¶

Example¶

run Element, /run=<Ressource> Option¶

Attributes¶

Example¶

run32 Element, /run32=<Ressource> Option¶

Attributes¶

Example¶

run64 Element, /run64=<Ressource> Option¶

Attributes¶

Example¶

file Element, /AddFile=<Path>,<Name> Option¶

Attributes¶

Example¶

pair Element, /name=<Value> Option¶

Attributes¶

Example¶

archive Element¶

Attributes¶

Example¶

file Element (in archive)¶

Attributes¶

Example¶

/dump[=<Path>] Option¶

/embed=<Path> Option¶

/force Option¶

`toolembed` Element¶

`input` Element, `/input=<Path>` Option¶

`output` Element, `/out=<Path>` Option¶

`run` Element, `/run=<Ressource>` Option¶

`run32` Element, `/run32=<Ressource>` Option¶

`run64` Element, `/run64=<Ressource>` Option¶

`file` Element, `/AddFile=<Path>,<Name>` Option¶

`pair` Element, `/name=<Value>` Option¶

`archive` Element¶

`file` Element (in `archive`)¶

`/dump[=<Path>]` Option¶

`/embed=<Path>` Option¶

`/force` Option¶