Skip to content

4. Build From Source

Jump to bottom
pikachu edited this page May 30, 2022 · 1 revision

The best way to make an operational agent is with Docker and main.py. This process is covered in the Quickstart guide. But if you would rather build the agent from source, you can do that, too.

If you're building from source, we recommend using a Linux host to build the agent to simplify the process.

⚠️ Important: Default Parameters

If you build the agent from source without modifying the source code, you cannot execute the agent without command-line arguments or a config file dropped to disk. Consider the OPSEC implications of this. To execute the agent in this case, you must use one of the agent command line arguments. See that page for details.

Install Rust

🟠 Note:

We strongly recommend building the agent on Linux. It is technically possible to install Rust on Windows and build it there. But we've found this to be a miserable experience. Just use Ubuntu. It works, we promise.

You need 🦀 Rust 🦀 to build the agent from scratch.

On Linux/macOS, you can run:

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Head to rustup for full instructions.

Build the Agent

Download the OffensiveNotion repository and change to the agent/ directory.

Cargo uses what are known as "target triples" to indicate what platform to compile to. To see which ones you have installed, run rustup target list.

The native target (Linux on Linux, Windows on Windows, macOS on macOS) will work without additional configuration. We'll discuss cross-compilation in a later section.

In addition to target triples, you can build either a debug or release target. debug is appropriate for testing, but release should be the only build deployed during engagements.

Linux

From the agent/ directory, run:

$ cargo build [--release]

... to build the Linux debug or release agent.

The agent is built in the target/ subdirectory.

Windows (from Linux)

We recommend compiling to Windows from Linux because honestly, it works better. Plus, you have more control over the samples getting submitted to Defender.

Install the Windows toolchain:

# MingW tools to build Windows apps on Linux
apt install -y mingw-w64
rustup toolchain install stable-x86_64-pc-windows-gnu

...and build the agent:

$ cargo build --target x86_64-pc-windows-gnu [--release]

The agent is built in the target/x86_64-pc-windows-gnu/ subdirectory.

macOS

Building natively on macOS is fairly straightforward. As above, follow these steps:

  1. Install Rust by following the instructions at rustup.rs
  2. Clone the the OffensiveNotion GitHub repository.
  3. cd to the agent directory.

Now, before running cargo build, you'll need to make sure the XCode command line tools are installed. If you've already set up XCode before, you're set. Otherwise, run the following in a Terminal:

xcode-select --install

The necessary tools (clang, etc.) are now ready to use. You can now run cargo build --release. The result will be in the target/release/ directory inside of agent.

🟠Important

There are a few special considerations when using the macOS agent that we've detailed in macOS Notes. Go see that section after you've read this one.

Cross-compiling to macOS from Linux.

It is in fact possible to cross-compile from Linux to macOS. This blog post contains the additional instructions necessary to do so. A few gotchas:

  • Make sure the additional config for linker and ar options are in agent/.cargo/config. Currently, the .cargo folder doesn't exist.
  • If you don't want to add that folder/file, you can run cargo with the following options:
    • CARGO_TARGET_x86_64_APPLE_DARWIN_LINKER=x86_64-apple-dawrin14-clang CARGO_TARGET_x86_64_APPLE_DARWIN_AR=x86_64_apple-darwin14-ar cargo build --release --target x86_64-apple-darwin
  • Make sure after cloning/building OSXCross, that you add its bin folder to the front of your $PATH.
Clone this wiki locally