Feature	AWS	QEMU	VirtualBox	DigitalOcean	vSphere	Multipass	GCP	Azure
VM: List	✅	✅	✅	✅	✅	✅	✅	❌
VM: Start / Stop / Reboot	✅	✅	✅	✅	✅	✅	✅	❌
VM: SSH / RDP / VNC	✅	✅	✅	✅	✅	✅	✅	❌
VM: Create / Destroy	✅	✅	✅	✅	✅	✅	❌	❌
Image Builds	✅	✅	✅	❌	✅	❌ N/A	❌	❌
Images (Build, Destroy)	✅	✅	✅	❌	✅	❌ N/A	❌	❌
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

Be sure to check out the providers section for additional information on configuring your provider.

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 completion script
  config      View and manage configuration values.
  help        Help about any command
  image       View or manage images and image builds.
  project     Manage and interact with projects
  update      Update carbon to latest version
  vm          Manage and interact with VMs.
                                                                                                                                                                                                                                                                       
## Flags
                                                                                                                                                                                                                                                                                                          
      --config string   config file (default is $HOME/carbon.yaml)
      --debug           Debug mode
  -h, --help            help for carbon
  -j, --json            Output in JSON
  -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)
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.

ℹ️ Checkout the latest docs here
😢 Have a problem? Create an Issue
❤️ Enjoying Carbon? Star the Repo

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
DigitalOcean
Multipass (Local)
QEMU (Local)
VirtualBox (Local)
vSphere (in progress)

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

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

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.dir.projects
carbon.dir.instance
carbon.dir.deployments
carbon.dir.packer
carbon.dir.images
carbon.dir.terraform
carbon.providers.vsphere.enabled
carbon.providers.vsphere.auto_discover
carbon.providers.vsphere.profiles.default.enabled
carbon.providers.vsphere.profiles.default.username
carbon.providers.vsphere.profiles.default.password
carbon.providers.vsphere.profiles.default.password_command
carbon.providers.vsphere.profiles.default.use_1pass_cli
carbon.providers.vsphere.profiles.default.url
carbon.providers.vsphere.profiles.default.environments
carbon.providers.vsphere
carbon.providers.aws.enabled
carbon.providers.aws.auto_discover
carbon.providers.aws.profiles.default.enabled
carbon.providers.aws.profiles.default.username
carbon.providers.aws.profiles.default.password
carbon.providers.aws.profiles.default.password_command
carbon.providers.aws.profiles.default.use_1pass_cli
carbon.providers.aws.profiles.default.url
carbon.providers.aws.profiles.default.environments
carbon.providers.aws
carbon.providers.qemu.enabled
carbon.providers.qemu.auto_discover
carbon.providers.qemu.profiles.default.enabled
carbon.providers.qemu.profiles.default.username
carbon.providers.qemu.profiles.default.password
carbon.providers.qemu.profiles.default.password_command
carbon.providers.qemu.profiles.default.use_1pass_cli
carbon.providers.qemu.profiles.default.url
carbon.providers.qemu.profiles.default.environments
carbon.providers.qemu
carbon.providers.virtualbox.enabled
carbon.providers.virtualbox.auto_discover
carbon.providers.virtualbox.profiles.default.enabled
carbon.providers.virtualbox.profiles.default.username
carbon.providers.virtualbox.profiles.default.password
carbon.providers.virtualbox.profiles.default.password_command
carbon.providers.virtualbox.profiles.default.use_1pass_cli
carbon.providers.virtualbox.profiles.default.url
carbon.providers.virtualbox.profiles.default.environments
carbon.providers.virtualbox
carbon.providers.multipass.enabled
carbon.providers.multipass.auto_discover
carbon.providers.multipass.profiles.default.enabled
carbon.providers.multipass.profiles.default.username
carbon.providers.multipass.profiles.default.password
carbon.providers.multipass.profiles.default.password_command
carbon.providers.multipass.profiles.default.use_1pass_cli
carbon.providers.multipass.profiles.default.url
carbon.providers.multipass.profiles.default.environments
carbon.providers.multipass
carbon.providers.digitalocean.enabled
carbon.providers.digitalocean.auto_discover
carbon.providers.digitalocean.profiles.default.enabled
carbon.providers.digitalocean.profiles.default.username
carbon.providers.digitalocean.profiles.default.password
carbon.providers.digitalocean.profiles.default.password_command
carbon.providers.digitalocean.profiles.default.use_1pass_cli
carbon.providers.digitalocean.profiles.default.url
carbon.providers.digitalocean.profiles.default.environments
carbon.providers.digitalocean

carbon config [flags]

Examples

# Configure digitalocean credentials
carbon config carbon.providers.digitalocean.profiles.default.use_1pass_cli true
carbon config carbon.providers.digitalocean.profiles.default.password "op://Private/some path/api_key"

# Set a default project directory
carbon config carbon.dir.instance ~/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

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

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-base")

Options inherited from parent commands

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

1.5 - Image Build

Build an image.

Synopsis

build an image.

carbon image build [flags]

Examples

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

Options

  -h, --help                 help for build
  -n, --name string          Name of image build
  -a, --provisioner string   Name of provisioner to use (default "cloud-init")
  -S, --service string       Service provider (aws, virtualbox, qemu, multipass)

Options inherited from parent commands

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

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

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

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

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 image to use.
  -n, --name string      Name of the VM to add.
  -N, --no-apply         Do not run terraform apply.
  -S, --service string   Service provider (aws, virtualbox, qemu, multipass)

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.

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.

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.

1.12 - Project New

Create a new project.

Synopsis

Create a new project.

carbon project new [flags]

Examples

carbon project new -n project-name

Options

  -f, --force            Force over writing files.
  -h, --help             help for new
  -n, --name string      Name of the new project.
  -S, --service string   Service provider (aws, virtualbox, qemu, multipass)

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.

1.13 - Update

Update carbon 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

1.14 - 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

1.15 - 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")

1.16 - 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")

1.17 - 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
  -p, --private-ip   Print private IP address

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")

1.18 - Vm Rdp

RDP to a VM

Synopsis

RDP to a VM. This will:

RDP to the VM :D

carbon vm rdp [flags]

Examples

carbon vnc rdp -n vm-name

Options

  -h, --help         help for rdp
  -p, --private-ip   Use private IP address

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")

1.19 - 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")

1.20 - 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
  -p, --private-ip   Use private IP address

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")

1.21 - 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")

1.22 - 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 stop -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")

1.23 - 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 vm vnc -n vm-name

Options

  -h, --help         help for vnc
  -k, --kill-vnc     Kill VNC before starting
  -p, --private-ip   Use private IP address

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")

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.

Getting Started

Set up AWS CLI - aws config - aws sso con

RDP on mac requires windows app

3.2 - DigitalOcean WIP

DigitalOcean Provider for Carbon

This is a WIP, Missing Images and Image Builds

Map

DigitalOcean	Carbon	Description
Account	Profile	Default token is pulled from the `DIGITALOCEAN_TOKEN` environment variable, or from the `doctl` config file
Project	Environment

3.3 - Example Provider

Provider Boiler Plate

3.4 - GCloud Provider WIP

GCP Compute provider

This is a WIP

Map

GCP	Carbon	Description
Account	Profile
Project & Zone	Environment

Configuration

use project/zone for the environment name.

carbon:
    providers:
        gcloud:
            profiles:
                default:
                    environments:
                      gcp-project/us-east3-c

3.5 - 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.6 - 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.7 - 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.

3.8 - vSphere Provider WIP

VMWare vSphere

This is a WIP

Map

VSphere	Carbon	Description
Account	Profile	Vsphere account
Host System	Environment

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.

VNC

Requires TigerVNC to be installed.

RDP

RDP on Mac requires the Windows App.

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.1.1 - Example Project

Example Project

Project directories hold the Terraform files any given project. You could also throw in some docs or markdown with other information.

The terraform file main.tf will read the carbon-config.yaml file and pass it to the carbon terraform module.

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 Base

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.2 - 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.2.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 - Carbon Module

The kitchen sinks of terraform modules

This module will include all required providers. You are welcome to remove ones you do not need. Carbon will do it’s best to minimize what it copies based what providers you are using.

5.6.1.2 - 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.

6 - Package

Carbon main package

import "github.com/analog-substance/carbon"

Carbon main package

Index

6.1 - carbon

Package carbon provides core application functionality and constants

import "github.com/analog-substance/carbon/pkg/carbon"

Package carbon provides core application functionality and constants

Index

Constants

const CloudInitDir = "cloud-init"

const ISOVarUsage = "var.iso_url"

const PackerFileIsoVars = "iso-variables.pkr.hcl"

const PackerFileLocalVars = "local-variables.pkr.hcl"

const PackerFilePacker = "packer.pkr.hcl"

const PackerFilePrivateVarsExample = "private.auto.pkrvars.hcl.example"

const PackerFileSuffixAnsible = "-ansible.pkr.hcl"

const PackerFileSuffixCloudInit = "-cloud-init.pkr.hcl"

const PackerFileSuffixVariables = "-variables.pkr.hcl"

Variables

var AllProviders = []types.Provider{
    aws.New(),
    qemu.New(),
    virtualbox.New(),
    multipass.New(),
    digitalocean.New(),
    vsphere.New(),
}

func AvailableProviders

func AvailableProviders() []types.Provider

type Carbon

type Carbon struct {
    // contains filtered or unexported fields
}

func New

func New(config common.CarbonConfig) *Carbon

func (*Carbon) FindVMByID

func (c *Carbon) FindVMByID(id string) []types.VM

func (*Carbon) FindVMByName

func (c *Carbon) FindVMByName(name string) []types.VM

func (*Carbon) GetConfig

func (c *Carbon) GetConfig() common.CarbonConfig

func (*Carbon) GetImage

func (c *Carbon) GetImage(imageID string) (types.Image, error)

func (*Carbon) GetImageBuild

func (c *Carbon) GetImageBuild(name, provider, provisioner string) (types.ImageBuild, error)

func (*Carbon) GetImageBuildTemplates

func (c *Carbon) GetImageBuildTemplates() []string

func (*Carbon) GetImageBuilds

func (c *Carbon) GetImageBuilds() ([]types.ImageBuild, error)

func (*Carbon) GetImages

func (c *Carbon) GetImages() ([]types.Image, error)

func (*Carbon) GetProject

func (c *Carbon) GetProject(name string) (types.Project, error)

func (*Carbon) GetProjects

func (c *Carbon) GetProjects() ([]types.Project, error)

func (*Carbon) GetProvider

func (c *Carbon) GetProvider(providerType string) (types.Provider, error)

func (*Carbon) GetVMs

func (c *Carbon) GetVMs() []types.VM

func (*Carbon) Profiles

func (c *Carbon) Profiles() []types.Profile

func (*Carbon) Providers

func (c *Carbon) Providers() []types.Provider

func (*Carbon) VMsFromHosts

func (c *Carbon) VMsFromHosts(hostnames []string) []types.VM

type Options

type Options struct {
    Providers    []string
    Profiles     []string
    Environments []string
}

6.2 - cloud_init

import "github.com/analog-substance/carbon/pkg/cloud_init"

Index

type AptSource

type AptSource struct {
    Source string `yaml:"source"`
    Keyid  string `yaml:"keyid"`
}

type CloudConfig

type CloudConfig struct {
    Timezone          string   `yaml:"timezone"`
    SSHDeletekeys     bool     `yaml:"ssh_deletekeys"`
    SSHAuthorizedKeys []string `yaml:"ssh_authorized_keys"`
    Apt               struct {
        Sources map[string]AptSource `yaml:"sources"`
    }   `yaml:"apt"`
    WriteFiles     []WriteFile `yaml:"write_files"`
    PackageUpgrade bool        `yaml:"package_upgrade"`
    Packages       []string    `yaml:"packages"`
    Runcmd         [][]string  `yaml:"runcmd"`
}

func (*CloudConfig) MergeWith

func (c *CloudConfig) MergeWith(otherConfig *CloudConfig)

type WriteFile

type WriteFile struct {
    Path        string `yaml:"path"`
    Content     string `yaml:"content"`
    Owner       string `yaml:"owner"`
    Permissions string `yaml:"permissions"`
    Encoding    string `yaml:"encoding,omitempty"`
}

6.3 - cmd

import "github.com/analog-substance/carbon/pkg/cmd"

Index

Variables

CarbonCmd represents the base command when called without any subcommands

var CarbonCmd = &cobra.Command{
    Use:   "carbon",
    Short: "Carbon - Infrastructure automation for offensive operations.",
    Long: `Infrastructure automation for offensive operations.
- ℹ️ Checkout the latest docs [here](https://analog-substance.github.io/carbon/)
- 😢 Have a problem? [Create an Issue](https://github.com/analog-substance/carbon/issues/new?title=Something%20is%20broken)
- ❤️ Enjoying Carbon? [Star the Repo](https://github.com/analog-substance/carbon)

## 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)
`,
    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {

        if debug {
            common.LogLevel(slog.LevelDebug)
        }
        log.Debug("debug mode", "debug", debug)

        carbonConfigFile := common.GetConfig()
        home, err := homedir.Dir()
        if err != nil {
            log.Debug("error getting home directory", "error", err)
        } else {
            err := carbonConfigFile.MergeInConfigFile(filepath.Join(home, cfgFileName))

            if err != nil {
                log.Debug("error loading carbon config from home", "error", err)
            }
        }

        err = carbonConfigFile.MergeInConfigFile(cfgFileName)
        if err != nil {
            log.Debug("error loading carbon config from home", "error", err)
        }

        carbonObj = carbon.New(carbonConfigFile.Carbon)
        updateConfigHelp()

        return nil
    },
}

func AskIfSure

func AskIfSure(msg string) bool

func Execute

func Execute()

Execute adds all child commands to the root command and sets flags appropriately. This is called by main.main(). It only needs to happen once to the rootCmd.

func ListingDir

func ListingDir(dir string)

6.4 - common

import "github.com/analog-substance/carbon/pkg/common"

Index

Constants

const DefaultDeploymentsDirName = "deployments"

const DefaultImagesDirName = "images"

const DefaultInstanceConfigKey = "instance"

const DefaultInstanceDir = "."

const DefaultPackerDirName = "packer"

const DefaultProjectsDirName = "projects"

const DefaultTerraformDirName = "terraform"

const DeploymentsConfigKey = "deployments"

const ImagesConfigKey = "images"

const PackerConfigKey = "packer"

const TerraformConfigKey = "terraform"

const TerraformProjectConfigKey = "projects"

func Get

func Get(s string) any

func ImagesDir

func ImagesDir() string

func Keys

func Keys() []string

func LogLevel

func LogLevel(level slog.Level)

func Logger

func Logger() *slog.Logger

func PackerDir

func PackerDir() string

func ProjectsDir

func ProjectsDir() string

func Set

func Set(s string, v any) any

func SetProvidersTypes

func SetProvidersTypes(p []string)

func Time

func Time(what string) func()

func WithGroup

func WithGroup(groupName string) *slog.Logger

type CarbonConfig

type CarbonConfig struct {
    Dir       map[string]string         `yaml:"dir"`
    Providers map[string]ProviderConfig `yaml:"providers"`
}

func (*CarbonConfig) Get

func (cc *CarbonConfig) Get(search []string) any

func (*CarbonConfig) Keys

func (cc *CarbonConfig) Keys(prefix string) []string

func (*CarbonConfig) Set

func (cc *CarbonConfig) Set(search []string, val any) *CarbonConfig

type CarbonConfigFile

type CarbonConfigFile struct {
    Carbon CarbonConfig `yaml:"carbon"`
}

func GetConfig

func GetConfig() *CarbonConfigFile

func (*CarbonConfigFile) Get

func (cf *CarbonConfigFile) Get(search []string) any

func (*CarbonConfigFile) Keys

func (cf *CarbonConfigFile) Keys() []string

func (*CarbonConfigFile) MergeInConfigFile

func (cf *CarbonConfigFile) MergeInConfigFile(cfgFile string) error

func (*CarbonConfigFile) Set

func (cf *CarbonConfigFile) Set(search []string, val any) *CarbonConfigFile

type ProfileConfig

type ProfileConfig struct {
    Enabled         bool            `yaml:"enabled"`
    Username        string          `yaml:"username" `
    Password        string          `yaml:"password" `
    PasswordCommand string          `yaml:"password_command"`
    Use1PassCLI     bool            `yaml:"use_1pass_cli" `
    URL             string          `yaml:"url"`
    Environments    map[string]bool `yaml:"environments"`
}

func DefaultProfileConfig

func DefaultProfileConfig() ProfileConfig

func (*ProfileConfig) Get

func (pc *ProfileConfig) Get(search []string) any

func (*ProfileConfig) GetPassword

func (pc *ProfileConfig) GetPassword() string

func (*ProfileConfig) Keys

func (pc *ProfileConfig) Keys(prefix string) []string

func (*ProfileConfig) Set

func (pc *ProfileConfig) Set(search []string, val any) *ProfileConfig

func (*ProfileConfig) UnmarshalYAML

func (pc *ProfileConfig) UnmarshalYAML(unmarshal func(interface{}) error) error

type ProviderConfig

type ProviderConfig struct {
    Enabled      bool                     `yaml:"enabled"`
    AutoDiscover bool                     `yaml:"auto_discover"`
    Profiles     map[string]ProfileConfig `yaml:"profiles"`
}

func DefaultProviderConfig

func DefaultProviderConfig() ProviderConfig

func (*ProviderConfig) Get

func (pc *ProviderConfig) Get(search []string) any

func (*ProviderConfig) Keys

func (pc *ProviderConfig) Keys(prefix string) []string

func (*ProviderConfig) Set

func (pc *ProviderConfig) Set(search []string, val any) *ProviderConfig

func (*ProviderConfig) UnmarshalYAML

func (pc *ProviderConfig) UnmarshalYAML(unmarshal func(interface{}) error) error

6.5 - models

import "github.com/analog-substance/carbon/pkg/models"

Index

func GetImageBuildsForProvider

func GetImageBuildsForProvider(provider string) ([]types.ImageBuild, error)

func NewImage

func NewImage(imageID string, imageName string, createdAt time.Time, env types.Environment) types.Image

type BuildBlock

type BuildBlock struct {
    Name        string   `hcl:"name,optional"`
    Description string   `hcl:"description,optional"`
    FromSources []string `hcl:"sources,optional"`
    Config      hcl.Body `hcl:",remain"`
}

type Image

type Image struct {
    // contains filtered or unexported fields
}

func (*Image) CreatedAt

func (i *Image) CreatedAt() string

func (*Image) Destroy

func (i *Image) Destroy() error

func (*Image) Environment

func (i *Image) Environment() types.Environment

func (*Image) ID

func (i *Image) ID() string

func (*Image) Launch

func (i *Image) Launch(imageLaunchOptions types.ImageLaunchOptions) error

func (*Image) MarshalJSON

func (i *Image) MarshalJSON() ([]byte, error)

func (*Image) Name

func (i *Image) Name() string

func (*Image) Profile

func (i *Image) Profile() types.Profile

func (*Image) Provider

func (i *Image) Provider() types.Provider

type ImageBuild

type ImageBuild struct {
    // contains filtered or unexported fields
}

func NewImageBuild

func NewImageBuild(buildPath, provider, provisioner string) *ImageBuild

func (*ImageBuild) Build

func (b *ImageBuild) Build() error

func (*ImageBuild) MarshalJSON

func (b *ImageBuild) MarshalJSON() ([]byte, error)

func (*ImageBuild) Name

func (b *ImageBuild) Name() string

func (*ImageBuild) ProviderType

func (b *ImageBuild) ProviderType() string

func (*ImageBuild) Provisioner

func (b *ImageBuild) Provisioner() string

type Machine

type Machine struct {
    InstanceName       string             `json:"name"`
    InstanceID         string             `json:"id"`
    CurrentUpTime      time.Duration      `json:"up_time"`
    InstanceType       string             `json:"type"`
    PublicIPAddresses  []string           `json:"public_ip_addresses"`
    PrivateIPAddresses []string           `json:"private_ip_addresses"`
    CurrentState       types.MachineState `json:"current_state"`
    Env                types.Environment  `json:"-"`
}

func (*Machine) Cmd

func (m *Machine) Cmd(user string, privateIP bool, cmdArgs ...string) (string, error)

func (*Machine) Destroy

func (m *Machine) Destroy() error

func (*Machine) Environment

func (m *Machine) Environment() types.Environment

func (*Machine) ExecSSH

func (m *Machine) ExecSSH(user string, privateIP bool, cmdArgs ...string) error

func (*Machine) ID

func (m *Machine) ID() string

func (*Machine) IPAddress

func (m *Machine) IPAddress() string

func (*Machine) Name

func (m *Machine) Name() string

func (*Machine) NewSSHSession

func (m *Machine) NewSSHSession(user string, privateIP bool) (*ssh_util.Session, error)

func (*Machine) PrivateIPAddress

func (m *Machine) PrivateIPAddress() string

func (*Machine) Profile

func (m *Machine) Profile() types.Profile

func (*Machine) Provider

func (m *Machine) Provider() types.Provider

func (*Machine) Restart

func (m *Machine) Restart() error

func (*Machine) Start

func (m *Machine) Start() error

func (*Machine) StartRDPClient

func (m *Machine) StartRDPClient(user string, privateIP bool) error

func (*Machine) StartVNC

func (m *Machine) StartVNC(user string, privateIP bool, killVNC bool) error

StartVNC will create a VNC session on the virtual machine It accomplishes this by:

SSH to the VM.
Start VNC if it is not already running.
Forward a port through the SSH session.
VNC to the forwarded port.

Requires TigerVNC to be installed.

func (*Machine) State

func (m *Machine) State() string

func (*Machine) Stop

func (m *Machine) Stop() error

func (*Machine) Type

func (m *Machine) Type() string

func (*Machine) UpTime

func (m *Machine) UpTime() time.Duration

type PackerConfig

type PackerConfig struct {
    Source SourceBlock `hcl:"source,block"`
    Build  BuildBlock  `hcl:"build,block"`
}

type Project

type Project struct {
    // contains filtered or unexported fields
}

func NewProject

func NewProject(buildPath string) *Project

func (*Project) AddMachine

func (d *Project) AddMachine(machine *types.ProjectMachine, noApply bool) error

func (*Project) GetConfig

func (d *Project) GetConfig() (*types.ProjectConfig, error)

func (*Project) MarshalJSON

func (d *Project) MarshalJSON() ([]byte, error)

func (*Project) Name

func (d *Project) Name() string

func (*Project) SaveConfig

func (d *Project) SaveConfig() error

func (*Project) TerraformApply

func (d *Project) TerraformApply() error

type SourceBlock

type SourceBlock struct {
    Type   string   `hcl:"type,label"`
    Name   string   `hcl:"name,label"`
    Config hcl.Body `hcl:",remain"`
}

6.6 - Providers

6.6.1 - aws

Package aws handles communications with AWS APIs

import "github.com/analog-substance/carbon/pkg/providers/aws"

Package aws handles communications with AWS APIs

Index

func New

func New() types.Provider

New creates new instance of an AWS Provider and returns it. Defaults to no awsProfileNames, this forces a query of the AWS config at runtime.

type Environment

type Environment struct {
    // contains filtered or unexported fields
}

func (*Environment) CreateVM

func (e *Environment) CreateVM(options types.MachineLaunchOptions) error

func (*Environment) DestroyImage

func (e *Environment) DestroyImage(imageID string) error

func (*Environment) DestroyVM

func (e *Environment) DestroyVM(id string) error

func (*Environment) ImageBuilds

func (e *Environment) ImageBuilds() ([]types.ImageBuild, error)

func (*Environment) Images

func (e *Environment) Images() ([]types.Image, error)

func (*Environment) Name

func (e *Environment) Name() string

func (*Environment) Profile

func (e *Environment) Profile() types.Profile

func (*Environment) RestartVM

func (e *Environment) RestartVM(id string) error

func (*Environment) StartVM

func (e *Environment) StartVM(id string) error

func (*Environment) StopVM

func (e *Environment) StopVM(id string) error

func (*Environment) VMs

func (e *Environment) VMs() []types.VM

type Profile

type Profile struct {
    types.Profile
}

func NewProfile

func NewProfile(name string, providerInstance *Provider, config common.ProfileConfig) *Profile

func (*Profile) Environments

func (p *Profile) Environments() []types.Environment

type Provider

type Provider struct {
    types.Provider
    // contains filtered or unexported fields
}

func (*Provider) AWSProfiles

func (p *Provider) AWSProfiles() []string

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

func (*Provider) Profiles

func (p *Provider) Profiles() []types.Profile

6.6.2 - base

import "github.com/analog-substance/carbon/pkg/providers/base"

Index

Constants

const CloudInitDir = "cloud-init"

const ISOVarUsage = "var.iso_url"

const PackerFileIsoVars = "iso-variables.pkr.hcl"

const PackerFileLocalVars = "local-variables.pkr.hcl"

const PackerFilePacker = "packer.pkr.hcl"

const PackerFilePrivateVarsExample = "private.auto.pkrvars.hcl.example"

const PackerFileSuffixAnsible = "-ansible.pkr.hcl"

const PackerFileSuffixCloudInit = "-cloud-init.pkr.hcl"

const PackerFileSuffixVariables = "-variables.pkr.hcl"

func DestroyImageForFileBasedProvider

func DestroyImageForFileBasedProvider(imageID string) error

func GetImagesForFileBasedProvider

func GetImagesForFileBasedProvider(providerType string, e types.Environment) ([]types.Image, error)

func New

func New() types.Provider

func NewProfile

func NewProfile(name string, providerInstance types.Provider, config common.ProfileConfig) types.Profile

func NewWithName

func NewWithName(name string) types.Provider

type Environment

type Environment struct {
    // contains filtered or unexported fields
}

func (*Environment) CreateVM

func (e *Environment) CreateVM(options types.MachineLaunchOptions) error

func (*Environment) DestroyImage

func (e *Environment) DestroyImage(imageID string) error

func (*Environment) DestroyVM

func (e *Environment) DestroyVM(id string) error

func (*Environment) ImageBuilds

func (e *Environment) ImageBuilds() ([]types.ImageBuild, error)

func (*Environment) Images

func (e *Environment) Images() ([]types.Image, error)

func (*Environment) Name

func (e *Environment) Name() string

func (*Environment) Profile

func (e *Environment) Profile() types.Profile

func (*Environment) RestartVM

func (e *Environment) RestartVM(id string) error

func (*Environment) StartVM

func (e *Environment) StartVM(id string) error

func (*Environment) StopVM

func (e *Environment) StopVM(id string) error

func (*Environment) VMs

func (e *Environment) VMs() []types.VM

type ImageBuildDate

type ImageBuildDate struct {
    Name string
}

type Profile

type Profile struct {
    // contains filtered or unexported fields
}

func (*Profile) Environments

func (p *Profile) Environments() []types.Environment

func (*Profile) GetConfig

func (p *Profile) GetConfig() common.ProfileConfig

func (*Profile) Name

func (p *Profile) Name() string

func (*Profile) Provider

func (p *Profile) Provider() types.Provider

func (*Profile) SetConfig

func (p *Profile) SetConfig(config common.ProfileConfig)

func (*Profile) ShouldIncludeEnvironment

func (p *Profile) ShouldIncludeEnvironment(envName string) bool

type Provider

type Provider struct {
    // contains filtered or unexported fields
}

func (*Provider) GetConfig

func (p *Provider) GetConfig() common.ProviderConfig

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

func (*Provider) Name

func (p *Provider) Name() string

func (*Provider) NewImageBuild

func (p *Provider) NewImageBuild(name, tplDir string) (types.ImageBuild, error)

func (*Provider) NewProject

func (p *Provider) NewProject(name string, force bool) (types.Project, error)

func (*Provider) Profiles

func (p *Provider) Profiles() []types.Profile

func (*Provider) SetConfig

func (p *Provider) SetConfig(config common.ProviderConfig)

func (*Provider) Type

func (p *Provider) Type() string

6.6.3 - digitalocean

import "github.com/analog-substance/carbon/pkg/providers/digitalocean"

Index

func New

func New() types.Provider

type Environment

type Environment struct {
    // contains filtered or unexported fields
}

func (*Environment) CreateVM

func (e *Environment) CreateVM(options types.MachineLaunchOptions) error

func (*Environment) DestroyImage

func (e *Environment) DestroyImage(imageID string) error

func (*Environment) DestroyVM

func (e *Environment) DestroyVM(id string) error

func (*Environment) ImageBuilds

func (e *Environment) ImageBuilds() ([]types.ImageBuild, error)

func (*Environment) Images

func (e *Environment) Images() ([]types.Image, error)

func (*Environment) Name

func (e *Environment) Name() string

func (*Environment) Profile

func (e *Environment) Profile() types.Profile

func (*Environment) RestartVM

func (e *Environment) RestartVM(id string) error

func (*Environment) StartVM

func (e *Environment) StartVM(id string) error

func (*Environment) StopVM

func (e *Environment) StopVM(id string) error

func (*Environment) VMs

func (e *Environment) VMs() []types.VM

type Profile

type Profile struct {
    types.Profile
    // contains filtered or unexported fields
}

func NewProfile

func NewProfile(name string, providerInstance *Provider, config common.ProfileConfig) *Profile

func (*Profile) Environments

func (p *Profile) Environments() []types.Environment

type Provider

type Provider struct {
    types.Provider
    // contains filtered or unexported fields
}

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

func (*Provider) Profiles

func (p *Provider) Profiles() []types.Profile

6.6.4 - example

import "github.com/analog-substance/carbon/pkg/providers/example"

Index

func New

func New() types.Provider

type Environment

type Environment struct {
    // contains filtered or unexported fields
}

func (*Environment) CreateVM

func (e *Environment) CreateVM(options types.MachineLaunchOptions) error

func (*Environment) DestroyImage

func (e *Environment) DestroyImage(imageID string) error

func (*Environment) DestroyVM

func (e *Environment) DestroyVM(id string) error

func (*Environment) ImageBuilds

func (e *Environment) ImageBuilds() ([]types.ImageBuild, error)

func (*Environment) Images

func (e *Environment) Images() ([]types.Image, error)

func (*Environment) Name

func (e *Environment) Name() string

func (*Environment) Profile

func (e *Environment) Profile() types.Profile

func (*Environment) RestartVM

func (e *Environment) RestartVM(id string) error

func (*Environment) StartVM

func (e *Environment) StartVM(id string) error

func (*Environment) StopVM

func (e *Environment) StopVM(id string) error

func (*Environment) VMs

func (e *Environment) VMs() []types.VM

type Profile

type Profile struct {
    types.Profile
}

func NewProfile

func NewProfile(name string, providerInstance *Provider, config common.ProfileConfig) *Profile

func (*Profile) Environments

func (p *Profile) Environments() []types.Environment

type Provider

type Provider struct {
    types.Provider
    // contains filtered or unexported fields
}

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

func (*Provider) Profiles

func (p *Provider) Profiles() []types.Profile

6.6.5 - multipass

import "github.com/analog-substance/carbon/pkg/providers/multipass"

Index

func New

func New() types.Provider

type Environment

type Environment struct {
    // contains filtered or unexported fields
}

func (*Environment) CreateVM

func (e *Environment) CreateVM(options types.MachineLaunchOptions) error

func (*Environment) DestroyImage

func (e *Environment) DestroyImage(imageID string) error

func (*Environment) DestroyVM

func (e *Environment) DestroyVM(id string) error

func (*Environment) ImageBuilds

func (e *Environment) ImageBuilds() ([]types.ImageBuild, error)

func (*Environment) Images

func (e *Environment) Images() ([]types.Image, error)

func (*Environment) Name

func (e *Environment) Name() string

func (*Environment) Profile

func (e *Environment) Profile() types.Profile

func (*Environment) RestartVM

func (e *Environment) RestartVM(id string) error

func (*Environment) StartVM

func (e *Environment) StartVM(id string) error

func (*Environment) StopVM

func (e *Environment) StopVM(id string) error

func (*Environment) VMs

func (e *Environment) VMs() []types.VM

type Profile

type Profile struct {
    types.Profile
}

func NewProfile

func NewProfile(name string, providerInstance *Provider, config common.ProfileConfig) *Profile

func (*Profile) Environments

func (p *Profile) Environments() []types.Environment

type Provider

type Provider struct {
    types.Provider
    // contains filtered or unexported fields
}

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

func (*Provider) Profiles

func (p *Provider) Profiles() []types.Profile

6.6.5.1 - api

import "github.com/analog-substance/carbon/pkg/providers/multipass/api"

Index

func AppPath

func AppPath() string

func RestartVM

func RestartVM(id string) error

func SleepVM

func SleepVM(id string) error

func StartVM

func StartVM(id string) error

type MultipassListOutput

type MultipassListOutput struct {
    List []MultipassVM `json:"list"`
}

type MultipassVM

type MultipassVM struct {
    Ipv4    []string `json:"ipv4"`
    Name    string   `json:"name"`
    Release string   `json:"release"`
    State   string   `json:"state"`
}

func ListVMs

func ListVMs() []MultipassVM

6.6.6 - qemu

import "github.com/analog-substance/carbon/pkg/providers/qemu"

Index

func New

func New() types.Provider

type Environment

type Environment struct {
    // contains filtered or unexported fields
}

func (*Environment) CreateVM

func (e *Environment) CreateVM(options types.MachineLaunchOptions) error

func (*Environment) DestroyImage

func (e *Environment) DestroyImage(imageID string) error

func (*Environment) DestroyVM

func (e *Environment) DestroyVM(id string) error

func (*Environment) ImageBuilds

func (e *Environment) ImageBuilds() ([]types.ImageBuild, error)

func (*Environment) Images

func (e *Environment) Images() ([]types.Image, error)

func (*Environment) Name

func (e *Environment) Name() string

func (*Environment) Profile

func (e *Environment) Profile() types.Profile

func (*Environment) RestartVM

func (e *Environment) RestartVM(id string) error

func (*Environment) StartVM

func (e *Environment) StartVM(id string) error

func (*Environment) StopVM

func (e *Environment) StopVM(id string) error

func (*Environment) VMs

func (e *Environment) VMs() []types.VM

type Profile

type Profile struct {
    types.Profile
}

func NewProfile

func NewProfile(name string, providerInstance *Provider, config common.ProfileConfig) *Profile

func (*Profile) Environments

func (p *Profile) Environments() []types.Environment

type Provider

type Provider struct {
    types.Provider
    // contains filtered or unexported fields
}

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

func (*Provider) Profiles

func (p *Provider) Profiles() []types.Profile

6.6.6.1 - api

import "github.com/analog-substance/carbon/pkg/providers/qemu/api"

Index

type Domain

type Domain struct {
    LVDomain *libvirt.Domain

    LVDomainState *libvirt.DomainState
    ID            string
    Name          string

    PublicIPAddresses  []string
    PrivateIPAddresses []string
    CurrentUpTime      time.Duration
    // contains filtered or unexported fields
}

func (*Domain) Destroy

func (d *Domain) Destroy() error

func (*Domain) Reboot

func (d *Domain) Reboot() error

func (*Domain) Start

func (d *Domain) Start() error

func (*Domain) Suspend

func (d *Domain) Suspend() error

type QEMU

type QEMU struct {
    // contains filtered or unexported fields
}

func Connect

func Connect(libVirtURL string) (*QEMU, error)

func (*QEMU) AllNetworks

func (q *QEMU) AllNetworks() ([]libvirt.Network, error)

func (*QEMU) Close

func (q *QEMU) Close() error

func (*QEMU) CreateDomain

func (q *QEMU) CreateDomain(name string, storageVol *StorageVolume) (*Domain, error)

func (*QEMU) GetDomain

func (q *QEMU) GetDomain(id string) (*Domain, error)

func (*QEMU) GetDomains

func (q *QEMU) GetDomains() ([]*Domain, error)

func (*QEMU) GetStoragePool

func (q *QEMU) GetStoragePool(name string) (*StoragePool, error)

func (*QEMU) GetStoragePools

func (q *QEMU) GetStoragePools() ([]*StoragePool, error)

type StoragePool

type StoragePool struct {
    LVStoragePool *libvirt.StoragePool
    Volumes       []*StorageVolume
    // contains filtered or unexported fields
}

func (*StoragePool) GetVolumes

func (s *StoragePool) GetVolumes() ([]*StorageVolume, error)

func (*StoragePool) ImportImage

func (s *StoragePool) ImportImage(name string, imageFile string) (*StorageVolume, error)

type StorageVolume

type StorageVolume struct {
    LVStorageVolume *libvirt.StorageVol
    // contains filtered or unexported fields
}

6.6.7 - virtualbox

import "github.com/analog-substance/carbon/pkg/providers/virtualbox"

Index

func New

func New() types.Provider

type Environment

type Environment struct {
    // contains filtered or unexported fields
}

func (*Environment) CreateVM

func (e *Environment) CreateVM(options types.MachineLaunchOptions) error

func (*Environment) DestroyImage

func (e *Environment) DestroyImage(imageID string) error

func (*Environment) DestroyVM

func (e *Environment) DestroyVM(id string) error

func (*Environment) ImageBuilds

func (e *Environment) ImageBuilds() ([]types.ImageBuild, error)

func (*Environment) Images

func (e *Environment) Images() ([]types.Image, error)

func (*Environment) Name

func (e *Environment) Name() string

func (*Environment) Profile

func (e *Environment) Profile() types.Profile

func (*Environment) RestartVM

func (e *Environment) RestartVM(id string) error

func (*Environment) StartVM

func (e *Environment) StartVM(id string) error

func (*Environment) StopVM

func (e *Environment) StopVM(id string) error

func (*Environment) VMs

func (e *Environment) VMs() []types.VM

type Profile

type Profile struct {
    types.Profile
}

func NewProfile

func NewProfile(name string, providerInstance *Provider, config common.ProfileConfig) *Profile

func (*Profile) Environments

func (p *Profile) Environments() []types.Environment

type Provider

type Provider struct {
    types.Provider
    // contains filtered or unexported fields
}

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

func (*Provider) Profiles

func (p *Provider) Profiles() []types.Profile

6.6.7.1 - api

import "github.com/analog-substance/carbon/pkg/providers/virtualbox/api"

Index

func AppPath

func AppPath() string

func RestartVM

func RestartVM(id string) error

func SleepVM

func SleepVM(id string) error

func StartVM

func StartVM(id string) error

type VBoxVM

type VBoxVM struct {
    Name               string
    ID                 string
    State              string
    GuestOS            string
    UpTime             time.Duration
    PrivateIPAddresses []string
    // contains filtered or unexported fields
}

func ListVMs

func ListVMs() []VBoxVM

6.6.8 - vsphere

import "github.com/analog-substance/carbon/pkg/providers/vsphere"

Index

func New

func New() types.Provider

type Environment

type Environment struct {
    // contains filtered or unexported fields
}

func (*Environment) CreateVM

func (e *Environment) CreateVM(options types.MachineLaunchOptions) error

func (*Environment) DestroyImage

func (e *Environment) DestroyImage(imageID string) error

func (*Environment) DestroyVM

func (e *Environment) DestroyVM(id string) error

func (*Environment) ImageBuilds

func (e *Environment) ImageBuilds() ([]types.ImageBuild, error)

func (*Environment) Images

func (e *Environment) Images() ([]types.Image, error)

func (*Environment) Name

func (e *Environment) Name() string

func (*Environment) Profile

func (e *Environment) Profile() types.Profile

func (*Environment) RestartVM

func (e *Environment) RestartVM(id string) error

func (*Environment) StartVM

func (e *Environment) StartVM(id string) error

func (*Environment) StopVM

func (e *Environment) StopVM(id string) error

func (*Environment) VMs

func (e *Environment) VMs() []types.VM

type Profile

type Profile struct {
    types.Profile
    // contains filtered or unexported fields
}

func NewProfile

func NewProfile(name string, providerInstance *Provider, config common.ProfileConfig) *Profile

func (*Profile) Environments

func (p *Profile) Environments() []types.Environment

type Provider

type Provider struct {
    types.Provider
    // contains filtered or unexported fields
}

func (*Provider) IsAvailable

func (p *Provider) IsAvailable() bool

func (*Provider) Profiles

func (p *Provider) Profiles() []types.Profile

6.7 - rdp_client

import "github.com/analog-substance/carbon/pkg/rdp_client"

Index

func Start

func Start(options Options) error

func StartRDPClient

func StartRDPClient(options Options) error

type Options

type Options struct {
    Delay int
    User  string
    Host  string
}

6.8 - ssh_util

import "github.com/analog-substance/carbon/pkg/ssh_util"

Index

type Session

type Session

type Session struct {
    Session *ssh.Session
    Client  *ssh.Client
    // contains filtered or unexported fields
}

func NewSession

func NewSession() (*Session, error)

func (*Session) ClientConfig

func (session *Session) ClientConfig(user string) *ssh.ClientConfig

func (*Session) Close

func (session *Session) Close()

func (*Session) Connect

func (session *Session) Connect(serverAddr, user string) error

func (*Session) ForwardAgent

func (session *Session) ForwardAgent() error

func (*Session) ForwardLocalPort

func (session *Session) ForwardLocalPort(localPort, remotePort int) error

func (*Session) Output

func (session *Session) Output(cmd string) (string, error)

Output uses ssh_util.Session to run cmd on the remote host and returns its standard output.

6.9 - types

import "github.com/analog-substance/carbon/pkg/types"

Index

Variables

var StateRunning = MachineState{"Running"}

var StateSleeping = MachineState{"Sleeping"}

var StateStarting = MachineState{"Starting"}

var StateStopped = MachineState{"Stopped"}

var StateStopping = MachineState{"Stopping"}

var StateTerminated = MachineState{"Terminated"}

var StateTerminating = MachineState{"Terminating"}

var StateUnknown = MachineState{"Unknown"}

type Environment

type Environment interface {
    Name() string
    VMs() []VM
    Profile() Profile
    StartVM(string) error
    StopVM(string) error
    RestartVM(string) error
    ImageBuilds() ([]ImageBuild, error)
    Images() ([]Image, error)
    CreateVM(MachineLaunchOptions) error
    DestroyVM(string) error
    DestroyImage(string) error
}

type Image

type Image interface {
    ID() string
    Name() string
    CreatedAt() string
    Environment() Environment
    Profile() Profile
    Provider() Provider
    Launch(imageLaunchOptions ImageLaunchOptions) error
    Destroy() error
}

type ImageBuild

type ImageBuild interface {
    Name() string
    ProviderType() string
    Provisioner() string
    Build() error
}

type ImageLaunchOptions

type ImageLaunchOptions struct {
    Name string
}

type MachineLaunchOptions

type MachineLaunchOptions struct {
    CloudInitTpl string `json:"cloud-init"`
    Image        Image  `json:"image"`
    Name         string `json:"name"`
}

type MachineState

type MachineState struct {
    Name string `json:"name"`
}

type Profile

type Profile interface {
    Environments() []Environment
    Name() string
    Provider() Provider
    SetConfig(config common.ProfileConfig)
    GetConfig() common.ProfileConfig
    ShouldIncludeEnvironment(envName string) bool
}

type Project

type Project interface {
    Name() string
    TerraformApply() error
    AddMachine(machine *ProjectMachine, noApply bool) error
}

type ProjectConfig

type ProjectConfig struct {
    Machines []*ProjectMachine `yaml:"machines"`
}

type ProjectMachine

type ProjectMachine struct {
    Name       string `yaml:"name"`
    Image      string `yaml:"image,omitempty"`
    Type       string `yaml:"type,omitempty"`
    Profile    string `yaml:"profile,omitempty"`
    Purpose    string `yaml:"purpose,omitempty"`
    VolumeSize int    `yaml:"volume_size,omitempty"`
    Provider   string `yaml:"provider,omitempty"`
}

type Provider

type Provider interface {
    Profiles() []Profile
    Name() string
    Type() string
    IsAvailable() bool
    SetConfig(config common.ProviderConfig)
    GetConfig() common.ProviderConfig
    NewImageBuild(name string, tplDir string) (ImageBuild, error)
    NewProject(name string, force bool) (Project, error)
}

type VM

VM interface provides access to useful information and actions related to Virtual Machines

type VM interface {
    // Name returns the name of a virtual machine
    Name() string

    // ID returns the ID of the virtual machine
    ID() string

    // IPAddress returns the public IP address of the virtual machine
    IPAddress() string

    // PrivateIPAddress of the virtual machine
    PrivateIPAddress() string
    UpTime() time.Duration
    State() string
    Type() string

    Environment() Environment
    Profile() Profile
    Provider() Provider

    Destroy() error
    Start() error
    Stop() error
    Restart() error

    ExecSSH(string, bool, ...string) error
    StartVNC(user string, privateIP bool, killVNC bool) error
    StartRDPClient(user string, privateIP bool) error
    Cmd(string, bool, ...string) (string, error)
    NewSSHSession(string, bool) (*ssh_util.Session, error)
}

6.10 - vnc_viewer

import "github.com/analog-substance/carbon/pkg/vnc_viewer"

Index

func Start

func Start(options Options) error

func StartViewer

func StartViewer(options Options) error

type Options

type Options struct {
    Delay        int
    PasswordFile string
    Host         string
}

Carbon

Purpose

Features

Install

Requirements

Usage

Images

Bootstrap Image Build Configuration

Build Images

Manage Images and Image Builds

Infrastructure

Create New Infrastructure

Modify Infrastructure

Teardown Infrastructure

Operating

Starting

Stopping

Connecting to VMs

Things to do

1 - Carbon CLI

Synopsis

Purpose

Dependencies

Supported Providers

Options

SEE ALSO

Auto generated by spf13/cobra on 25-Mar-2025

1.1 - Completion

Synopsis

Options

Options inherited from parent commands

SEE ALSO

Auto generated by spf13/cobra on 25-Mar-2025

1.2 - Config

Synopsis

Configuration keys

Examples

Options

Options inherited from parent commands

SEE ALSO

Auto generated by spf13/cobra on 25-Mar-2025

1.3 - Image

Synopsis

Options

Options inherited from parent commands

SEE ALSO

Auto generated by spf13/cobra on 25-Mar-2025

1.4 - Image Bootstrap

Synopsis

Examples

Options

Options inherited from parent commands

SEE ALSO

Auto generated by spf13/cobra on 25-Mar-2025

1.5 - Image Build

Synopsis

Examples

Options

Options inherited from parent commands

SEE ALSO

Auto generated by spf13/cobra on 25-Mar-2025

1.6 - Image Destroy

Synopsis

Examples

Options

Options inherited from parent commands

SEE ALSO

Auto generated by spf13/cobra on 25-Mar-2025

1.7 - Image List

Synopsis

Examples

Options

Options inherited from parent commands

SEE ALSO

Auto generated by spf13/cobra on 25-Mar-2025

1.8 - Project

Synopsis

Options

Options inherited from parent commands

SEE ALSO