Skip to content
Snippets Groups Projects
Commit 6300d575 authored by Jiří Rája's avatar Jiří Rája :fire:
Browse files

Merge branch '3-add-documentation-for-the-cryton-deploy-project' into 'master'

Added instructions for the Ansible deployment

Closes #3

See merge request cryton/cryton-documentation!4
parents 864e384f ff97bcf3
No related branches found
No related tags found
No related merge requests found
## Description It is possible to install Cryton using ansible. We will only cover basics and installation on a single machine.
This project is used for deploying the Cryton toolset using Ansible.
Cryton toolset is tested and targeted primarily on **Debian** and **Kali Linux**. Please keep in mind that All roles with more information can be found [here](https://gitlab.ics.muni.cz/cryton/ansible){target="_blank"}.
**only the latest version is supported** and issues regarding different OS or distributions may **not** be resolved.
- Make sure you run Ansible using Python3 (`ansible_python_interpreter: /usr/bin/python3`). ## Quick-start
- Supposedly there is no need for `gather_facts`. First, we have to create inventory.yml file:
- Run roles using sudo (become).
- For the best experience specify `cryton_COMPONENT_version` where *COMPONENT* is depending on the role (core, cli, worker, modules)
and select the latest version (**the master branch is not stable**).
- To update the default variables stored in .env files use `cryton_COMPONENT_environment` where *COMPONENT* is depending on the role (core, cli, worker).
- Values for each role can be found in `cryton-deploy/roles/ROLE/defaults/main.yml`.
- Once you update cryton_COMPONENT_environment, **make sure you've updated all the variables**.
## Roles ??? abstract "Show the inventory.yml file"
### deploy-core ```yaml
Install prerequisites, dependencies (RabbitMQ, Postgres, and PgBouncer), and Core using Docker Compose. {! include "inventory.yml" !}
Core's REST API is by default served on port 8000. ```
Override environment variables as specified in the [settings](https://cryton.gitlab-pages.ics.muni.cz/cryton-documentation/2022.2/starting-point/core/#settings){target="_blank"}. Then, we can create a playbook:
In the Ansible playbook use the following:
```yaml
- role: deploy-core
cryton_core_environment:
VARIABLE_TO_OVERRIDE: new_value
...
```
For all available role variables, check `cryton-deploy/roles/deploy-core/defaults/main.yml`. ??? abstract "Show the playbook.yml file (preferred installation is using pip)"
To create, update, and load the Docker configuration saved in /etc/docker/daemon.json, set `update_docker_daemon_configuration: yes`, ```yaml
and use `docker_daemon_configuration` dictionary to create the configuration. {! include "playbook-pip.yml" !}
Example and default: ```
```
docker_daemon_configuration:
mtu: 1442
```
### deploy-worker (with modules) ??? abstract "Show the playbook.yml file (preferred installation is using Docker)"
Install prerequisites and Worker with modules using pipx.
Start the Worker afterward in the background (you have to check for errors manually in the `{{ cryton_worker_output_file }}`).
To start msfrpcd in the background use `start_msfrpcd: yes`. ```yaml
Set `cryton_cli_runas_user` to the correct user for whom will the Worker be installed. {! include "playbook-docker.yml" !}
```
Optionally, Worker can be installed in a mode fitting for development purposes. To enable this mode, set ``development: True`` variable for Ansible. Once we have created `playbook.yml` and `inventory.yml`, we can install the [requirements](https://galaxy.ansible.com/docs/using/installing.html){target="_blank"} and run the playbook.
This will install and run the Worker using poetry.
Override environment variables as specified in the [settings](https://cryton.gitlab-pages.ics.muni.cz/cryton-documentation/2022.2/starting-point/worker/#settings){target="_blank"}.
In the Ansible playbook use the following:
```yaml
- role: deploy-worker
cryton_worker_environment:
VARIABLE_TO_OVERRIDE: new_value
...
```
For all available role variables, check `cryton-deploy/roles/deploy-worker/defaults/main.yml`.
For running the Ansible playbook, community.general module is needed. Install it by ``ansible-galaxy collection install community.general``.
### deploy-cli
Install prerequisites, dependencies, and CLI in `~/.local/bin/cryton-cli` using pipx, register it to PATH, and export .env vars into `~/.local/cryton-cli/.env`.
Set `cryton_cli_runas_user` to the correct user for whom will the Worker be installed.
Override environment variables as specified in the [settings](https://cryton.gitlab-pages.ics.muni.cz/cryton-documentation/2022.2/starting-point/cli/#settings){target="_blank"}.
In the Ansible playbook use the following:
```yaml
- role: deploy-cli
cryton_cli_environment:
VARIABLE_TO_OVERRIDE: new_value
...
```
For all available role variables, check `cryton-deploy/roles/deploy-cli/defaults/main.yml`.
### register-worker
Register Worker in Core using CLI.
Specify `cryton_worker_name`, `cryton_worker_description`, and `cryton_cli_runas_user` to the correct user with access to the CLI.
Override environment variables as specified in the [settings](https://cryton.gitlab-pages.ics.muni.cz/cryton-documentation/2022.2/starting-point/cli/#settings){target="_blank"}.
In the Ansible playbook use the following:
```yaml
- role: register-worker
cryton_cli_environment:
VARIABLE_TO_OVERRIDE: new_value
...
```
For all available role variables, check `cryton-deploy/roles/register-worker/defaults/main.yml`.
### deploy-frontend
Install prerequisites and frontend for Cryton Core API using Docker Compose. The frontend is by default served on port 8080.
**!This role requires the host to have at least 2048 MB RAM and 2 CPU cores (tested with AMD Ryzen 5 5600x) otherwise the Frontend installation might fail.!**
Override environment variables as specified in the [settings](https://cryton.gitlab-pages.ics.muni.cz/cryton-documentation/2022.2/starting-point/frontend/#settings){target="_blank"}.
In the Ansible playbook use the following:
```yaml
- role: deploy-frontend
cryton_frontend_environment:
VARIABLE_TO_OVERRIDE: new_value
...
```
For all available role variables, check `cryton-deploy/roles/deploy-frontend/defaults/main.yml`.
To create, update, and load the Docker configuration saved in /etc/docker/daemon.json, set `update_docker_daemon_configuration: yes`,
and use `docker_daemon_configuration` dictionary to create the configuration.
Example and default:
```
docker_daemon_configuration:
mtu: 1442
```
## Examples
### Deploy Core
```yaml
- name: Deploy Core
hosts: c2-server
become: yes
roles:
- role: deploy-core
```
### Deploy Worker (with modules)
```yaml
- name: Deploy Worker with modules
hosts: attacker
become: yes
roles:
- role: deploy-worker
cryton_worker_runas_user: my-user
cryton_worker_environment:
CRYTON_WORKER_MODULES_DIR: "{{ cryton_modules_directory }}/modules"
CRYTON_WORKER_RABBIT_HOST: 127.0.0.1
CRYTON_WORKER_NAME: unique-name
```
### Deploy CLI
```yaml
- name: Deploy CLI
hosts: client
become: yes
roles:
- role: deploy-cli
cryton_cli_runas_user: my-user
cryton_cli_environment:
CRYTON_CLI_API_HOST: 127.0.0.1
```
### Register Worker
```yaml
- name: Register Worker
hosts: client
roles:
- role: register-worker
cryton_cli_runas_user: my-user
cryton_worker_name: unique-name
cryton_worker_description: custom Worker description
cryton_cli_environment:
CRYTON_CLI_API_HOST: 127.0.0.1
```
### Deploy CLI and register new Worker
```yaml
- name: Deploy CLI and register Worker
hosts: client
become: yes
vars:
cryton_cli_runas_user: my-user
cryton_cli_environment:
CRYTON_CLI_API_HOST: 127.0.0.1
roles:
- role: deploy-cli
- role: register-worker
cryton_worker_name: unique-name
cryton_worker_description: custom Worker description
```
### Deploy frontend
```yaml
- name: Deploy frontend
hosts: client
become: yes
roles:
- role: deploy-frontend
cryton_frontend_environment:
crytonRESTApiHost: 127.0.0.1
```
- name: deploy-cli
src: https://gitlab.ics.muni.cz/cryton/ansible/deploy-cli.git
version: "{{{ release_version }}}.0"
scm: git
- name: deploy-core
src: https://gitlab.ics.muni.cz/cryton/ansible/deploy-core.git
version: "{{{ release_version }}}.0"
scm: git
- name: deploy-worker
src: https://gitlab.ics.muni.cz/cryton/ansible/deploy-worker.git
version: "{{{ release_version }}}.0"
scm: git
- name: deploy-frontend
src: https://gitlab.ics.muni.cz/cryton/ansible/deploy-frontend.git
version: "{{{ release_version }}}.0"
scm: git
- name: register-worker
src: https://gitlab.ics.muni.cz/cryton/ansible/register-worker.git
version: "{{{ release_version }}}.0"
scm: git
- name: Deploy all components using Docker (Compose)
hosts: default
become: yes
run_as_user: root
roles:
- role: deploy-cli
cryton_cli_installation: docker
- role: deploy-core
cryton_core_installation: docker
cryton_core_environment:
CRYTON_CORE_RABBIT_HOST: cryton-rabbit
CRYTON_CORE_DB_HOST: cryton-pgbouncer
CRYTON_CORE_API_USE_STATIC_FILES: true
- role: deploy-frontend
- role: deploy-worker
cryton_worker_installation: docker
- role: register-worker
cryton_cli_executable: docker exec cryton-cli cryton-cli
cryton_worker_name: Worker
cryton_worker_description: base description
- name: Deploy all components using pip
hosts: default
become: yes
roles:
- role: deploy-cli
- role: deploy-core
- role: deploy-frontend
- role: deploy-worker
- role: register-worker
cryton_worker_name: Worker
cryton_worker_description: base description
...@@ -39,17 +39,24 @@ git clone https://gitlab.ics.muni.cz/cryton/cryton-modules.git --branch {{{ git_ ...@@ -39,17 +39,24 @@ git clone https://gitlab.ics.muni.cz/cryton/cryton-modules.git --branch {{{ git_
Download the .env file (settings): Download the .env file (settings):
=== "curl" [//]: # (=== "curl")
```shell [//]: # ()
curl -o .env {{{ config.site_url }}}/getting-started/env [//]: # ( ```shell)
```
=== "wget" [//]: # ( curl -o .env {{{ config.site_url }}}/getting-started/env)
```shell [//]: # ( ```)
wget -O .env {{{ config.site_url }}}/getting-started/env
``` [//]: # ()
[//]: # (=== "wget")
[//]: # ()
[//]: # ( ```shell)
[//]: # ( wget -O .env {{{ config.site_url }}}/getting-started/env)
[//]: # ( ```)
??? abstract "Show the .env file" ??? abstract "Show the .env file"
...@@ -59,17 +66,24 @@ Download the .env file (settings): ...@@ -59,17 +66,24 @@ Download the .env file (settings):
Download the Compose configuration: Download the Compose configuration:
=== "curl" [//]: # (=== "curl")
```shell [//]: # ()
curl -O {{{ config.site_url }}}/getting-started/docker-compose.yml [//]: # ( ```shell)
```
=== "wget" [//]: # ( curl -O {{{ config.site_url }}}/getting-started/docker-compose.yml)
```shell [//]: # ( ```)
wget {{{ config.site_url }}}/getting-started/docker-compose.yml
``` [//]: # ()
[//]: # (=== "wget")
[//]: # ()
[//]: # ( ```shell)
[//]: # ( wget {{{ config.site_url }}}/getting-started/docker-compose.yml)
[//]: # ( ```)
??? abstract "Show the Compose config" ??? abstract "Show the Compose config"
......
...@@ -68,7 +68,7 @@ nav: ...@@ -68,7 +68,7 @@ nav:
- Quick-start: getting-started/quick-start.md - Quick-start: getting-started/quick-start.md
- Workflow: getting-started/workflow.md - Workflow: getting-started/workflow.md
- Execution example: getting-started/execution-example.md - Execution example: getting-started/execution-example.md
# - Deployment with Ansible: getting-started/ansible.md - Deployment with Ansible: getting-started/ansible.md
# - Testing environment: getting-started/playground.md # - Testing environment: getting-started/playground.md
- Components: - Components:
- Core: components/core.md - Core: components/core.md
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment