This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Carbon

Infrastructure automation for offensive operations. https://analog-substance.github.io/carbon/

Purpose

Carbon’s primary purpose is to provide a consistent execution environment to facilitate offensive security assessments.

It uses:

  • Packer to build images.
  • Terraform to provision infrastructure.
  • Golang project structure.

Features

It is aimed at supporting various services to ensure it can scale with you as your operations become more complex.

FeatureAWS ✅QEMU ✅VirtualBox ✅vSphere ❌Multipass ✅Azure ❌GCP ❌
Image build templates✅✅✅✅❌ N/A❌❌
Build images✅✅✅✅❌ N/A❌❌
Launch one off VM from images❌✅❌❌❌❌❌
Destroy VMs✅✅✅✅❌ N/A❌❌
VM Start/Stop/SSH/VNC✅✅✅❌✅❌❌
Infrastructure Creation❌❌❌❌❌ N/A❌❌

❌ = Not Right Now, but planned
✅ = Supported

Install

You can download a prebuilt release from our GitHub Releases page. Or use go install.

go install github.com/analog-substance/carbon@latest

Requirements

Carbon expects the following to be installed and accessible in your $PATH.

  • Packer
  • Terraform
  • SSH Client
  • vncviewer (TigerVNC)

Usage

Manage and use infrastructure with a consistent interface, regardless of where it lives.

Usage:
  carbon [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Display config information
  dev         Unstable sub-commands for testing random ideas
  help        Help about any command
  image       manage images and image builds
  vm          Manage and interact with VMs

Flags:
      --config string         config file (default is $HOME/.carbon.yaml)
  -e, --environment strings   Environment to use. Some providers/profiles support many environments.
  -h, --help                  help for carbon
  -j, --json                  Output in JSON
  -p, --profile strings       Profile to use. Like an instance of a provider. Used to specify aws profiles
  -P, --provider strings      Provider to use vbox, aws
  -v, --version               version for carbon

Use "carbon [command] --help" for more information about a command.

Images

Bootstrap Image Build Configuration

carbon image bootstrap -n my-image -t ubuntu-24.04 -s aws

Build Images

carbon image build -n my-image

Manage Images and Image Builds

List image build configs.

carbon image list -b

Infrastructure

Create New Infrastructure

Modify Infrastructure

Teardown Infrastructure

Operating

Starting

carbon vm start -i i-afde123ae43

Stopping

carbon vm stop -i i-afde123ae43

Connecting to VMs

carbon vm ssh -i i-afde123ae43

Things to do

  • docs
    • vhs example gifs
  • create/destroy one off VMs
  • provision aws env (create files, call terraform)
  • Self Test to ensure dependencies are met
  • Cloud init from templates (Base, Operator, Operator Desktop, Implant VM)
  • vSphere provider
  • DNS management
    • point a domain
    • list domains
  • Jobs / Distributed execution
  • Simple deploy/config of services (Pwndoc, Gophish, modlishka, Guacamole, Sliver, Mythic)
  • GCP Provider
  • Azure Provider
  • LXD Provider
  • Different OS (CentOS, Arch)
  • Chat Bots
    • Slack Bot
    • Discord Bot
  • Web GUI
  • tests (lol, this should not be last)

1 - Carbon CLI

Carbon CLI Reference

Synopsis

Infrastructure automation for offensive operations.

Purpose

Carbon’s primary purpose is to provide a consistent execution environment to facilitate offensive security assessments.

Dependencies

  • Packer to build images.
  • Terraform to provision infrastructure.
  • Golang project structure.

Supported Providers

  • AWS
  • QEMU (Local)
  • VirtualBox (Local)
  • vSphere (in progress)
  • Multipass (Local)

There are plans to bring support to the following:

  • GCP
  • Azure
  • VMware (Local)
  • QEMU (Remote)

Options

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -h, --help            help for carbon
  -j, --json            Output in JSON

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.1 - Completion

Generate completion script

Synopsis

To load completions:

Bash:

source <(carbon completion bash)

# To load completions for each session, execute once:
# Linux:
carbon completion bash > /etc/bash_completion.d/carbon
# macOS:
carbon completion bash > /usr/local/etc/bash_completion.d/carbon

Zsh:

# If shell completion is not already enabled in your environment,
# you will need to enable it.  You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrc

# To load completions for each session, execute once:
carbon completion zsh > "${fpath[1]}/carbon"

# You will need to start a new shell for this setup to take effect.

fish:

carbon completion fish | source

# To load completions for each session, execute once:
carbon completion fish > ~/.config/fish/completions/carbon.fish

PowerShell:

carbon completion powershell | Out-String | Invoke-Expression

# To load completions for every new session, run:
carbon completion powershell > carbon.ps1
# and source this file from your PowerShell profile.

carbon completion [bash|zsh|fish|powershell]

Options

  -h, --help   help for completion

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

  • carbon - Carbon - Infrastructure automation for offensive operations.
Auto generated by spf13/cobra on 10-Oct-2024

1.2 - Config

View and manage configuration values.

Synopsis

View and manage configuration values.

Carbon loads configuration files from your home directory, then merges it with a configuration file in the current directory (if it exists). This should allow you the flexibility you need.

Configuration keys

  • carbon.default.dir
  • carbon.deployments.dir
  • carbon.images.dir
  • carbon.packer.dir
  • carbon.projects.dir
  • carbon.providers.aws.enabled
  • carbon.providers.aws.profiles.default.enabled
  • carbon.providers.multipass.enabled
  • carbon.providers.multipass.profiles.default.enabled
  • carbon.providers.qemu.enabled
  • carbon.providers.qemu.profiles.default.enabled
  • carbon.providers.virtualbox.enabled
  • carbon.providers.virtualbox.profiles.default.enabled
  • carbon.terraform.dir
carbon config [flags]

Examples

# Configure vSphere credentials
carbon config carbon.credentials.vsphere_server.provider vsphere
carbon config carbon.credentials.vsphere_server.username vsphere_user@vsphere.example
carbon config carbon.credentials.vsphere_server.password_command 'op read op://Private/vSphere Creds/password'

# Set a default project directory
carbon config carbon.default.dir ~/my/path/haxors

Options

  -h, --help           help for config
  -r, --remove-reset   remove key from the config or reset to default
  -s, --save           save the current configuration
  -k, --sub-keys       display only the sub-keys

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

  • carbon - Carbon - Infrastructure automation for offensive operations.
Auto generated by spf13/cobra on 10-Oct-2024

1.3 - Image

View or manage images and image builds.

Synopsis

View or manage images and image builds.

Options

  -h, --help   help for image

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.4 - Image Bootstrap

Create packer files and other image build configs.

Synopsis

Create packer files and other image build configs.

carbon image bootstrap [flags]

Examples

carbon image bootstrap -n operator-desktop-aws -s aws -t ubuntu-desktop

Options

  -h, --help              help for bootstrap
  -n, --name string       Name of image build
  -s, --service string    Service provider (aws, virtualbox, qemu, multipass)
  -t, --template string   Template to use (default "ubuntu-24.04")

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.5 - Image Build

Build an image.

Synopsis

build an image.

carbon image build [flags]

Examples

carbon image build -t aws -n operator-desktop-aws

Options

  -h, --help                   help for build
  -n, --name string            Name of image build
  -t, --provider-type string   Name of provider to use
  -a, --provisioner string     Name of provisioner to use (default "cloud-init")

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.6 - Image Destroy

Delete images.

Synopsis

Delete images.

carbon image destroy [flags]

Examples

carbon image destroy -i qemu/some-image-123123123

Options

  -h, --help              help for destroy
  -i, --image-id string   ID of image to delete

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.7 - Image List

list images

Synopsis

list images and image builds.

carbon image list [flags]

Examples

# List all images
carbon image list

#list image builds
carbon image list -b

Options

  -b, --builds   List build configs
  -h, --help     help for list

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.8 - Project

Manage and interact with projects

Synopsis

Manage projects. Projects are directories with terraform code to manage resources for the project.

Options

  -h, --help             help for project
  -p, --project string   Name of the project.

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.9 - Project Add-Machine

Add a new machine to a project

Synopsis

Add a new machine to the project.

carbon project add-machine [flags]

Examples

carbon project add-machine -p example-qemu-carbon -n modlishka -P qemu -i carbon-ubuntu-desktop-20241008201758

Options

  -h, --help                   help for add-machine
  -i, --image string           Name of the VM to add.
  -n, --name string            Name of the VM to add.
  -P, --provider-type string   Provider for the new machine

Options inherited from parent commands

      --config string    config file (default is $HOME/.carbon.yaml)
      --debug            Debug mode
  -j, --json             Output in JSON
  -p, --project string   Name of the project.

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.10 - Project Apply

Run terraform apply

Synopsis

Apply terraform. No need to change dirs.

carbon project apply [flags]

Examples

carbon project apply -p project-name

Options

  -h, --help   help for apply

Options inherited from parent commands

      --config string    config file (default is $HOME/.carbon.yaml)
      --debug            Debug mode
  -j, --json             Output in JSON
  -p, --project string   Name of the project.

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.11 - Project List

Manage and interact with projects

Synopsis

List projects.

carbon project list [flags]

Examples

carbon project list

Options

  -h, --help   help for list

Options inherited from parent commands

      --config string    config file (default is $HOME/.carbon.yaml)
      --debug            Debug mode
  -j, --json             Output in JSON
  -p, --project string   Name of the project.

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.12 - Update

Update {{.Use}} to latest version

Synopsis

Update or check for updates. The default update method is to download the latest release from GitHub.

carbon update [flags]

Examples

# Update to latest version
carbon update

# Use go install to update
carbon update -g

# Download from a specific URL
# Not sure why anyone else would need this. I use it for quickly testing builds on different machines.
carbon update -u http://10.0.0.2:8000/dist/carbon_darwin_arm64/carbon

# This is typically used after I run the following:
#	goreleaser release --clean --snapshot
#	python -m http.server

Options

  -C, --check        Check for update
  -f, --force        Force update, even if release is not newer
  -g, --go-install   Use go install instead of downloading release from GitHub
  -h, --help         help for update
  -u, --url string   URL to download from (force implies)

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

  • carbon - Carbon - Infrastructure automation for offensive operations.
Auto generated by spf13/cobra on 10-Oct-2024

1.13 - Vm

Manage and interact with VMs.

Synopsis

Manage and interact with VMs.

Options

  -h, --help           help for vm
      --host strings   Hostname or IP Address.
  -i, --id string      ID of machine to start.
  -n, --name string    Name of the VM.
  -u, --user string    SSH Username. (default "ubuntu")

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
  -j, --json            Output in JSON

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.14 - Vm Destroy

destroy VM

Synopsis

Destroy a VM.

carbon vm destroy [flags]

Examples

carbon vm destroy -n vm-name

Options

  -h, --help   help for destroy

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
      --host strings    Hostname or IP Address.
  -i, --id string       ID of machine to start.
  -j, --json            Output in JSON
  -n, --name string     Name of the VM.
  -u, --user string     SSH Username. (default "ubuntu")

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.15 - Vm Launch

launch a new vm from an image

Synopsis

launch a new vm from an image.

carbon vm launch [flags]

Examples

carbon vm launch -I qemu/carbon-ubuntu-desktop-20241007212910 -n vm-name

Options

  -h, --help              help for launch
  -I, --image-id string   ID of image
  -n, --name string       Name of new VM

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
      --host strings    Hostname or IP Address.
  -i, --id string       ID of machine to start.
  -j, --json            Output in JSON
  -u, --user string     SSH Username. (default "ubuntu")

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.16 - Vm List

List VMs across all available providers, profiles, and environments.

Synopsis

List VMs across all available providers, profiles, and environments.

carbon vm list [flags]

Examples

# list all virtual machines
carbon vm list

# You can also supply a name search, this wil return VMs with names containing 'vm-'
carbon vm list -n vm-

Options

  -h, --help   help for list

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
      --host strings    Hostname or IP Address.
  -i, --id string       ID of machine to start.
  -j, --json            Output in JSON
  -n, --name string     Name of the VM.
  -u, --user string     SSH Username. (default "ubuntu")

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.17 - Vm Restart

Restart VM(s)

Synopsis

Restart VM(s).

carbon vm restart [flags]

Examples

carbon vm restart -n vm-name

Options

  -h, --help   help for restart

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
      --host strings    Hostname or IP Address.
  -i, --id string       ID of machine to start.
  -j, --json            Output in JSON
  -n, --name string     Name of the VM.
  -u, --user string     SSH Username. (default "ubuntu")

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.18 - Vm Ssh

SSH to a VM

Synopsis

SSH to a VM. Carbon will call exec on the ssh binary. This means the SSH process takes over the carbon process. So SSH agents should just work.

carbon vm ssh [flags]

Examples

# SSH to a VM
carbon vm ssh -n vm-name

# execute one off command on a VM
carbon vm ssh -n vm-name -- cat /etc/passwd

# proxy through a bastion
carbon vm ssh -n vm-name -- -oProxyCommand="carbon vm ssh -n bastion -- -W %h:%p"

# forward ssh agent
carbon vm ssh -n vm-name -- -A

# open socks proxy
carbon vm ssh -n vm-name -- -D 1080

Options

  -h, --help   help for ssh

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
      --host strings    Hostname or IP Address.
  -i, --id string       ID of machine to start.
  -j, --json            Output in JSON
  -n, --name string     Name of the VM.
  -u, --user string     SSH Username. (default "ubuntu")

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.19 - Vm Start

Start VMs

Synopsis

start VMs.

carbon vm start [flags]

Examples

carbon vm start -n vm-name

Options

  -h, --help   help for start

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
      --host strings    Hostname or IP Address.
  -i, --id string       ID of machine to start.
  -j, --json            Output in JSON
  -n, --name string     Name of the VM.
  -u, --user string     SSH Username. (default "ubuntu")

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.20 - Vm Stop

Stop VM(s)

Synopsis

Stop VM(s).

By default, carbon will attempt to hibernate the machine rather than power it off.

carbon vm stop [flags]

Examples

carbon vm start -n vm-name

Options

  -h, --help   help for stop

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
      --host strings    Hostname or IP Address.
  -i, --id string       ID of machine to start.
  -j, --json            Output in JSON
  -n, --name string     Name of the VM.
  -u, --user string     SSH Username. (default "ubuntu")

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

1.21 - Vm Vnc

VNC to a VM

Synopsis

VNC to a VM. This will:

  • SSH to the target VM.
  • Check to see if vncserver is running.
  • If not, start vncserver on the remote machine
  • If a vnc passwd file does not exist one will be created
  • Copy the password file to the local machine
  • Setup a tunnel to access vnc
  • start vncviewer
carbon vm vnc [flags]

Examples

carbon vnc start -n vm-name

Options

  -h, --help       help for vnc
  -k, --kill-vnc   Kill VNC before starting

Options inherited from parent commands

      --config string   config file (default is $HOME/.carbon.yaml)
      --debug           Debug mode
      --host strings    Hostname or IP Address.
  -i, --id string       ID of machine to start.
  -j, --json            Output in JSON
  -n, --name string     Name of the VM.
  -u, --user string     SSH Username. (default "ubuntu")

SEE ALSO

Auto generated by spf13/cobra on 10-Oct-2024

2 - Types

Carbon has several types defined for providers to use

Carbon organizes your machines in a tree like:

  • Providers
    • Profiles
      • Environments

An example could look like this:

  • Provider: AWS
    • Profile: default aws profile
      • Environment: VPC 001
      • Environment: VPC 002
    • Profile: red team aws profile
      • Environment: VPC 001
      • Environment: VPC 002
  • Provider: VirtualBox
    • Profile: local
      • Environment: local
  • Provider: Multipass
    • Profile: local
      • Environment: local
  • Provider: vSphere
    • Profile: whatever.vsphere.local
      • Environment: Datacenter 01
      • Environment: Datacenter 02

2.1 - Provider

Provider interface

A provider can be thought of as the service provider or application used to virtualize your environments. Think of AWS, GCP, Azure, VirtualBox, or vSphere. They provide the ability to spin up VMs.

2.2 - Profile

Profile interface

If providers are AWS, GCP, and VirtualBox. Profile can be thought of as the AWS/GCP account or in the case of VirtualBox the machine it is running on.

2.3 - Environment

Environment interface

Environments provide the magic. They provide the functionality to:

  • List virtual machines
  • Start, stop, and restart virtual machines
  • Mapping provider specific values to the values Carbon expects

Most of the code for providers will happen here.

2.4 - Image

Image interface

Images are the results of a packer build. They are snapshots of a VM. Ideally they are configured and ready to use. VMs can be created from an Image.

2.5 - Image Build

Image build interface

An image build is simply packer configs to build specific images.

2.6 - Project

Project interface

Deployments are where your Terraform code lives for your projects. Typically, this would be deployments/projects .

2.7 - VM

VM interface

The VM interface defines methods for interacting with a VM. Unlike the rest of the types, there probably won’t be multiple implementations. Since the Carbon provided Machine struct should be sufficient.

3 - Providers

Providers help carbon work with various services.

Providers allow Carbon to interact with external applications to retrieve information about your operating environment.

By default, providers will automatically discover configuration profiles to use. You can disable the auto discovery and force enabled specific profiles.

carbon:
  providers:
    aws:
      auto_discover: false
      profiles:
        default:
          enabled: true

3.1 - AWS

AWS Provider for Carbon

The AWS provider uses AWS profiles as Platforms, VPCs as Environments, and EC2 instances as VMs. It will read your AWS config and return all of your profiles as platforms. Carbon does not use the AWS CLI directly, it is recommended to have it setup and configured especially if using SSO. Carbon will treat VPCs as environments.

3.2 - Multipass

Multpass provider

The Multipass provider is a simple wrapper around the Multipass executable. If Multipass is installed this provider will allow Carbon to interact with them. Since Multipass is on the local machine there is only one Profile returned (local) and one Environment returned (local).

3.3 - QEMU

QEMU via LibVirt

This provider uses the libvirt sdk by digital ocean. Currently, it is hardcoded to use qemu:///system, this should change in the future.

3.4 - VirtualBox

VirtualBox Provider

VirtualBox is an easy-to-use virtualization solution. It is also free. It is typically installed on your computer and allows you to create virtual machines for testing. Because of this, certain Carbon features will be static.

This provider is a simple wrapper around vbox-manage. If that is installed, it will allow you to interact with your VMs using Carbon.

4 - Models

Individual “objects” to make things easier

4.1 - Machine

Machine

The machine struct provides a lot of functionality and relies on the providers to do their job correctly.

5 - Infrastructure as Code

Packer, Cloud Init, Terraform and Ansible.

There are various configurations and applications required to build, deploy, and manage infrastructure. Carbon leverages reliable and trusted leaders in this space. We didn’t want to re-invent the wheel or force you to learn something only applicable to the offensive security domain. This makes customizing Carbon as simple as reading the documentation of the application being used.

5.1 - Projects

Where project infrastructure begins

projects go here.

5.2 - Ansible

Playbooks and roles.

Ansible is not used by default. There are plans to leverage this in the future.

5.3 - Carbon

Simple scripts to glue things together

While other applications are doing the heavy lifting. These scripts make the installation process a little simpler.

5.4 - Cloud Init

Automate image configurations

WIP

5.5 - Packer Image Building

Using packer to generate images

Packer is used to build images for use in Terraform.

Installation

MacOS

We can install packer using Hashicorp’s Brew Tap.

brew tap hashicorp/tap
brew install hashicorp/tap/packer

5.5.1 - Ubuntu 24.04 Packer Config

Default build image

Ubuntu 24.04 is the default build for Carbon. It is based on a minimal server installation. This means you only install what you need to operate. Image customization will be facilitated through Cloud Init. This should make building and testing new configurations easy.

5.5.1.1 -

Usage

VirtualBox

Building with VirtualBox

packer build  .

Testing with VirtualBox

A simple script has been provided to create a new VirtualBox machine with the newly created disk image.

scripts/test-carbon-ubuntu.sh

5.6 - Terraform

Using Terraform

Terraform is used to deploy our infrastructure

Prerequisites

In order to properly use Terraform, you’ll need access to our AWS account.

Installation

MacOS

We can install terraform using Hashicorp’s Brew Tap.

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

5.6.1 - Modules

Using Terraform

Terraform modules are used to make easily reusable infrastructure

5.6.1.1 - Remote State Module

A simple module to provision an s3 bucket for remote state.

This module should be used to bootstrap an AWS environment. It contains minimal configurations to enable the rest of Terraform to use an S3 bucket as its backend.