DocsRelease Notes

Installation

Suggest Edits

The ./HAVOC platform runs as a collection of AWS resources within your own AWS account. It does not have any dependencies upon Havoc Inc. services other than the public repositories used to make the software and images available for use. The installation process is fully automated through Terraform templates. It is not necessary to download any of the images or Lambda functions directly since Terraform takes care of all of that for you but for the sake of transparency, the repositories used to make the software and images available are as follows:

Prerequisites

  • Access (with appropriate privileges) to the AWS account where the ./HAVOC platform will be installed
  • Linux or Mac OS (the ./HAVOC CLI is not supported on Windows)
  • The Git CLI utility (installation instructions)
  • AWS CLI version 2 with a user profile configured (installation instructions)
  • Zip package
    • sudo apt update && sudo apt install zip on Ubuntu
  • Python version 3.7 or higher with python3-dev, python3-venv and python3-pip
    • sudo apt update && sudo apt install python3-dev python3-venv python3-pip on Ubuntu

Note that having more than a passing familiarity with AWS is highly recommended.

Installation Options

  • aws_region - (Required) the AWS region to install ./HAVOC resources, i.e. "us-east-1."
  • aws_profile - (Required) the local AWS profile that Terraform will use to deploy resources.
  • campaign_name - (Required) the name to assign to the AWS resources that Terraform creates.
  • results_queue_expiration - (Required) the length in days to retain container task results entries in the Queue table in DynamoDB. 30 days is recommended.
  • enable_domain_name - (Required) set to true to deploy with a custom domain name, false to deploy without a custom domain name. See additional details about deploying with a custom domain.
    • hosted_zone - (Required) the Hosted Zone ID for the domain that will be used for the Campaign API.
    • domain_name - (Required) the name of the custom domain to use with the Campaign API.
  • campaign_admin_email - (Required) the email address for the Campaign API admin.

See the variables.tf file from the havoc-deploy repository for more configurable options, including the campaign_prefix, which is set to "havoc" by default.

Custom Domain Additional Details
The ./HAVOC platform can be installed with or without a custom domain. If you have a domain name that you would like to use for the Campaign API, you'll need to make sure that the AWS account that the ./HAVOC platform will be installed in has a Route53 Hosted Zone associated with the domain.

If you do not enable a custom domain for your ./HAVOC deployment, the URL for your Campaign API will be the default URL provided by the Amazon API Gateway.

If you do enable a custom domain for your ./HAVOC deployment, the Campaign API's DNS name will be "<campaign_name>-api" as the hostname portion of the FQDN plus your custom domain name. So as an example, if your campaign_name is "my-campaign" and your domain name is "example.com," the FQDN for your Campaign API will be "my-campaign-api.example.com." Also note that the custom domain name can be used to assign resolvable host names to container tasks. See the Administration pages and the Usage pages for more information.

If you have a domain name but it is not currently associated with the AWS account that the ./HAVOC platform will be installed in, you can add a Route53 Hosted Zone for a subdomain of the primary domain. Sticking with the "example.com" domain name scenario from above, if that domain is hosted by a third-party provider or is in a different AWS account, you can create a Hosted Zone entry in Route53 for a subdomain of "example.com" such as "sec-test.example.com" and add a Name Server (NS) entry for the subdomain to the zone file of the primary domain. With this example, using a campaign_name of "my-campaign" the Campaign API FQDN would be "my-campaign-api.sec-test.example.com."

See Amazon's Route53 Hosted Zone documentation for more details about using custom domains in AWS.

If you are deploying with a custom domain, the AWS Route53 console has a tendency to hide part of the hosted-zone-id on monitors with certain screen resolutions so take care to copy the entire Zone ID.

Install

Download and execute the ./HAVOC CLI with the -d option to deploy a new campaign to your AWS account:

git clone https://github.com/havocsh/havoc.git
cd havoc
./havoc --deployment create

Follow the prompts and provide the requested information to proceed with the deployment. The required resources will be deployed to AWS and the local ./HAVOC CLI environment will be created, including a ~/.havoc/config file that contains your ./HAVOC API configuration and credentials and a ~/.havoc/playbooks file that lists the ./HAVOC playbooks that have been configured. This file will be blank upon initial deployment. See the Playbooks page for more information about configuring ./HAVOC playbooks.

Note that managing (updating, removing, etc.) the ./HAVOC installation in your AWS account is dependent upon various state files in the havoc/havoc-deploy directory so it's imperative that the directory is preserved. See the Updates page for more information about updating your ./HAVOC installation.

When Terraform completes the installation, it will output details that you will need later for accessing and interacting with the ./HAVOC deployment's API. The output will look similar to this:

Outputs:

API_DOMAIN_NAME = "<campaign_name>-api.<campaign_domain_name>"
API_KEY = "<random_string>"
API_REGION = "<your_aws_region>"
CAMPAIGN_ADMIN_EMAIL = "<your_admin_email>"
CAMPAIGN_ID = "<campaign_prefix>-<campaign_name>"
SECRET = "<random_string>"

Updated 5 months ago