elk-tls-docker
This docker-compose project will assist with setting up and creating a ELK stack using either self-signed TLS certificates or using LetsEncrypt certificates for communications. In general you get HTTPS for all services.
Please checkout our WiKi for detailed explanation of the project structure, configuration settings, and more.
Environment Details
This project was built so that you can test and use built-in features under Elastic Security, like detections, signals, cases, and other features.
This docker-compose project will create the following Elastic containers based on version 7.12.0:
- Elasticsearch
- Logstash
- Kibana
- Packetbeat
- Filebeat
- Elastic Agent (Ubuntu 20.04)
- Metricbeat
Setup
In order to use this project, you must first include the following in a file named .env. I have provided an example environment variable file here .env-example.
Copy or create your own
.envfrom the provided example or from the code block below
ELK_VERSION=7.15.0
ELASTIC_USERNAME=elastic
ELASTIC_PASSWORD=some_password
# Configuration Variables
ELASTICSEARCH_HEAP=2g
LOGSTASH_HEAP=1g
PACKETBEAT_HEAP=256m
FILEBEAT_HEAP=256m
METRICBEAT_HEAP=256m
XPACK_ENCRYPTION_KEY=somesuperlongstringlikethisoneMQBbtsynu4bV2uxLy
# Self signed TLS certificates
CA_PASSWORD=some_password
CA_DAYS=3650
ELASTIC_DIR=/usr/share/elasticsearch
LOGSTASH_DIR=/usr/share/logstash
KIBANA_DIR=/usr/share/kibana
PACKETBEAT_DIR=/usr/share/packetbeat
FILEBEAT_DIR=/usr/share/filebeat
METRICBEAT_DIR=/usr/share/metricbeat
# Letsencrypt certificates
## Setting STAGING to true means it will generate self-signed certificates
## Setting STAGING to false means it will generate letsencrypt certificates
# STAGING=false
STAGING=true
# swag Configuration
#DOMAIN=mydomain.com
#SUBDOMAIN=kibana
#SUBFOLDER=kibana
#[email protected]
#TIMEZONE=America/Chicago
Note: You may need to change the size of the HEAP variables in the above configuration file based on your system requirements. The settings present are for a machine with 8GB of memory
Additionally, you must either clone this repository or download the entire repository in order to build and run these containers.
You can find more documentation about these settings in our WiKi
Keystore
Before we build or create our containers we first need to create our keystore and certificates. You can do this using the docker-compose.setup.yml yaml file. If you run into issues you can see the associated documentation in our WiKi Page about Certificates or create an issue in this repository.
Creating Keystore for self-signed certificates
By default creation of self-signed certificates is used and makes the most sense when testing out this project. To do so you simply run the following command first:
docker-compose -f docker-compose.setup.yml run --rm certsPlease see our documentation about Setup using self-signed certificates.
Creating Keystore & Certificates for production
If you are wanting to deploy this project in a production like environment, please see our documentation Setup using Letsencrypt.
Running a development environment
Now, that you have your keys/certs and passwords set we can then just restart the containers by running:
docker-compose up -d
You should be able to login into the ELK stack and be on your way.
You can find additioanl information about the environments that are created on your Environment Details WiKi page.
Running a production environment
Here is a walkthrough on setting up a production-like environment using LetsEncrypt.
You should be able to login into the ELK stack and be on your way.
You can find additioanl information about the environments that are created on your Environment Details WiKi page.
Common Issues
Please see our WiKi documentation for the most Common Issues I have seen through testing and usage of this project.
To remove all images from your system run: docker rmi $(docker images -a -q)
To remove all volumes from your system run: docker volume prune
Enabling features
This project provides a few (continually adding as needed & requested) helper scripts that assist with enabling specific features within Elastic Kibana SIEM featureset as well as adding test data to your Elasticsearch instance.
Please see our Enabling Features page in our Wiki
Road Map
Below are a list of features that are being planned for future releases:
- Adding additional services from Elastic
- Adding certificate authentication for external usage
Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
Versioning
We use SemVer for versioning.
Change Log
Please read CHANGELOG.md for details on features for a specific version of elk-tls-docker
Authors
- Josh Rickard - Initial work - MSAdministrator
See also the list of contributors who participated in this project.
License
This project is licensed under the MIT License - see the LICENSE file for details