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

Return to the regular view of this page.

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

SEE ALSO

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

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 25-Mar-2025

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

SEE ALSO

  • carbon - Carbon - Infrastructure automation for offensive operations.
Auto generated by spf13/cobra on 25-Mar-2025

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 25-Mar-2025

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

SEE ALSO

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

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

SEE ALSO

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

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 25-Mar-2025

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 25-Mar-2025

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 25-Mar-2025

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.

SEE ALSO

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

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 25-Mar-2025

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 25-Mar-2025

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.

SEE ALSO

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

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

SEE ALSO

  • carbon - Carbon - Infrastructure automation for offensive operations.
Auto generated by spf13/cobra on 25-Mar-2025

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

SEE ALSO

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

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

SEE ALSO

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

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

SEE ALSO

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

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

SEE ALSO

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

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

SEE ALSO

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

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

SEE ALSO

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

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

SEE ALSO

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

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

SEE ALSO

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

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

SEE ALSO

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

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

SEE ALSO

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