thinkst / canarytokens

# Canarytokens
by Thinkst Applied Research
## Overview
Canarytokens help track activity and actions on your network.
If you have any issues please check out our FAQ over here, or create an issue and we'll try to get back to you as soon as possible.
## Table of Contents
 - Code of Conduct
 - Deprecations
 - Installation
 - Configuration
 - AWS ID infrastructure
 - Configuration of Outgoing SMTP
 - Alert throttling
 - Webhook failure limiting
 - FAQ
 - Contributing
## Code of Conduct
This project and everyone participating in it is governed by the
Code of Conduct.
By participating, you are expected to uphold this code. Please report unacceptable behavior
to github@thinkst.com.
## Deprecations
* The Slack API Token is deprecated and it's no longer possible to create new ones. Old tokens will still work.
## Installation
We recommend the Docker image installation process.
## Configuration
The Canarytokens server can use many different settings configurations. You can find them in `settings.py`. There are two
main settings files: `frontend.env` and `switchboard.env`.
The `frontend.env` contains the frontend process settings such as:
- CANARY_DOMAINS=mytesttokensdomain.com
- CANARY_NXDOMAINS=pdf.demo.canarytokens.net
- CANARY_AWSID_URL= 
- CANARY_AWSID_AUTH= 
- CANARY_AWSID_GUID= 
- CANARY_AWSID_CONTROL_ACCOUNT_ID= 
- CANARY_WEB_IMAGE_UPLOAD_PATH=/uploads
- CANARY_GOOGLE_API_KEY= 
- LOG_FILE=frontend.log
The `switchboard.env` contains the switchboard process settings such as:
| Variable Name | Value |
|---------------------------------|--------------------------------------------------|
| CANARY_MAILGUN_DOMAIN_NAME | |
| CANARY_MAILGUN_API_KEY | |
| CANARY_MANDRILL_API_KEY | |
| CANARY_SENDGRID_API_KEY | |
| CANARY_PUBLIC_IP | |
| CANARY_PUBLIC_DOMAIN | |
| CANARY_ALERT_EMAIL_FROM_ADDRESS | noreply@yourdomain.com |
| CANARY_ALERT_EMAIL_FROM_DISPLAY | "Canarytoken Mailer" |
| CANARY_ALERT_EMAIL_SUBJECT | "Alert" |
| CANARY_MAX_ALERTS_PER_MINUTE | 1000 |
| CANARY_SMTP_USERNAME | |
| CANARY_SMTP_PASSWORD | |
| CANARY_SMTP_SERVER | smtp.gmail.com |
| CANARY_IPINFO_API_KEY | |
| CANARY_SMTP_PORT | 587 |
| CANARY_WEB_IMAGE_UPLOAD_PATH | /uploads |
| LOG_FILE | switchboard.log |
| ERROR_LOG_WEBHOOK | |
| CANARY_FORCE_HTTPS | force `https` protocol scheme for Canarytokens |
| CANARY_LAMBDA_AWS_CRED_REPORT_AUTH | |
Please note that when choosing which email provider you would like to use, you **MUST** only provide
information related to that provider. E.g. if you have `CANARY_MAILGUN_API_KEY` then you must remove the others such as
`CANARY_SENDGRID_API_KEY` and `CANARY_MANDRILL_API_KEY`.
If you are using Mailgun's European infrastructure for your Canarytokens Server, you will need to add `CANARY_MAILGUN_BASE_URL=https://api.eu.mailgun.net` to your `switchboard.env`. If you do not specify that,
we will use the regular URL as 'https://api.mailgun.net' as the default.
### AWS ID infrastructure
AWS API key Canarytokens use AWS-side infrastructure to allocate IAM use