← Home
Unfortunately, there is no "quick start". Please read and follow each step carefully. I promise it'll be worth it or your money back.1
Clone this repository to your local machine.
$ git clone https://github.com/spacesiren/spacesiren.git
Make sure you have Terraform >= 0.13 installed somewhere in your PATH.
$ terraform -v
It is highly recommended that you use a dedicated AWS account for this application, as you will be disseminating credentials tied to the account. The credentials should not grant any privileges, but a separate account is still a good idea.
It is also recommended that you authenticate to the SpaceSiren account using an IAM Role, as opposed to an IAM User or the root credentials. This can be easily done using AWS Organizations, or you may make a new standalone account and create a cross-account IAM Role to connect into it. While you may still use an IAM User or the root credentials, IAM Users should be reserved only for honey tokens, and best practice dictates that the root account be used as little as possible.
Once your new AWS account is set up, configure your local AWS CLI config using profile name "spacesiren". It may look something like this:
# ~/.aws/config
[profile default]
[profile spacesiren]
source_profile = default
role_arn = arn:aws:iam::111222333444:role/OrganizationAccountAccessRole
region = us-east-1
# ~/.aws/credentials
[default]
aws_access_key_id = AKIAXXXXXXXXXXXXXXXX
aws_secret_access_key = YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
Once it's set up, ensure that you can authenticate to the new account.
$ aws sts get-caller-identity --profile spacesiren
The 12-digit account ID of your new SpaceSiren account should be in the response.
You will need to have your own domain. If you do not have one, you will need to register a new one. If you are using an existing domain, you will need the ability to manage DNS for it or contact someone who can.
- In your SpaceSiren AWS account, go to Route 53 and create a new public hosted
zone for this application. For example, if you own
example.com
, create a new subdomain zone forspacesiren.example.com
. You may name the subdomain anything you wish. If you are registering a new domain, make a new hosted zone matching the name of your new domain. - If you are using a subdomain, create a new NS record in its parent zone for your subdomain and values assigned to you from the new Route 53 hosted zone.
- If you registered a new domain, configure your domain's custom nameservers to match those given to you by the new Route 53 zone.
SpaceSiren requires at least 2 S3 buckets to work: one for CloudTrail records and the other for Lambda functions. A 3rd bucket is also recommended for storing your Terraform states, which this guide will cover.
Create 3 new S3 buckets in the US East (N. Virginia) region. You may name them anything you like. Enable object versioning, AES-256 (SSE-S3) encryption, and all blocking of public access on each bucket. Take note of the names of your new buckets. For example, your bucket names may look like this:
mycompany-spacesiren-cloudtrail
mycompany-spacesiren-functions
mycompany-spacesiren-terraform-states
This step is optional, but recommended.
In your SpaceSiren account and region us-east-1, create a new DynamoDB table with name "spacesiren-terraform-lock" and primary key "LockID" (string). The rest of the options can be adjusted to your liking; you shouldn't need more than 1 provisioned capacity for each read and write. On-demand will also work and should not incur any measurable cost.
Switch to the terraform/
directory for the Configuration and Run steps.
Copy the terraform-local.tf.example
file to terraform-local.tf
and replace
the value for bucket
with the name of your Terraform states bucket.
Copy the terraform.tfvars.example
file to terraform.tfvars
, and review and fill
each option.
Required variables include:
cloudtrail_bucket
: The name of your new CloudTrail bucket from the setup steps.functions_bucket
: The name of your Lambda functions bucket.dns_zone_name
: The name of your Route 53 hosted zone.
Optional variables you may also wish to configure are:
alert_cooldown
: How long (in seconds) after the first alert for a honey token you would like to suppress future notifications. 0 for no cooldown, and -1 for infinite cooldown (i.e., only one alert per honey token).default_tags
: A map of tags to apply to all provisioned AWS resources.
Alert variables are covered below.
Alerts are optional, but a big part of what make SpaceSiren useful. This Getting Started guide will only cover email alerts. Visit the Alerts page for information on all supported alert types.
In your terraform.tfvars
file, set the following options:
alert_email_from_user
to your preferred FROM address username. The domain will match what you set indns_zone_name
.alert_email_to_address
to your preferred TO full email address. You will need to verify this address before receiving any alerts to it. You should automatically receive a verification email after SpaceSiren setup is complete. For now, continue on.
For example, with the following config...
dns_zone_name = "spacesiren.example.com"
alert_email_from_user = "alerts"
alert_email_to_address = "[email protected]"
Alert email messages would come from [email protected]
and be sent
to [email protected]
.
Finally, apply the Terraform configuration.
$ terraform init
$ terraform apply
The apply shouldn't take long, but it may take up to a few minutes.
If the apply went well, setup of SpaceSiren is complete! At the end of the run output, you will see your new API endpoint for creating tokens.
You can use your SpaceSiren API to create and manage tokens, but first you must set up an authentication key.
If you are starting fresh, there will be no authentication keys present. To
create your first key pair, you will need your Provision Key. In your SpaceSiren
AWS account, go to the
SSM Parameter Store
and find the parameter named /spacesiren/api/provision_key
. Show the value
and take note of it.
Using your preferred API client (such as Postman, Insomnia, or curl), create a
new POST request to your API endpoint as the destination and /key
as the
path, like so:
https://api.spacesiren.example.com/key
Include the following request headers, replacing the value for X-Provision-Key
with your own from Parameter Store.
Content-Type: application/json
X-Provision-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Set the request body type to JSON and include these options:
{
"admin": true,
"description": "My first API key"
}
You may replace the description with anything you like, or omit it entirely.
Submit the request, and you should receive a response with the following attributes:
{
"key": {
"key_id": "59ee279b-941b-4312-89c4-35030caba89a",
"secret_id": "LiNasGp5g8hgNo0GvebYnNyqLJ50bMqSLYe97jdjsWw=",
"_etc": "etc."
}
}
The values for key_id
and secret_id
comprise your authentication key pair.
Take note of them and keep at least the Secret ID secret. You will use them for
the next API call.
Once you have your authentication key pair, it's time to create your first token.
Create a new HTTP POST request to your API endpoint with /token
as the path,
like so:
https://api.spacesiren.example.com/token
Set the request headers again, but instead of using the Provision Key like last time, use your authentication key pair.
Content-Type: application/json
X-Key-ID: 59ee279b-941b-4312-89c4-35030caba89a
X-Secret-ID: LiNasGp5g8hgNo0GvebYnNyqLJ50bMqSLYe97jdjsWw=
Make a JSON body with the following options:
{
"description": "My first honey token",
"location": "Where no one should find it"
}
You may replace description
and location
with anything you like or omit them.
Submit the request, and you should receive a response with the following attributes:
{
"access_key_id": "AKIARVLMFKK3C2D32XXS",
"secret_access_key": "FkxwoYhRBccM3AXzX5G7T88ikKlZyooRhYefs4Dl",
"_etc": "etc."
}
If you did, congratulations on creating your first honey token! SpaceSiren will track these IAM User credentials and you will receive a notification to the alert output(s) you've set up if they are ever used.
- Get it? Because it's free. I won't be able to reimburse your AWS costs, so contact AWS billing support for a refund.