diff --git a/documentation/architecture.md b/documentation/architecture.md new file mode 100644 index 00000000..86d8760b --- /dev/null +++ b/documentation/architecture.md @@ -0,0 +1,24 @@ +# Architecture + +SMERSH uses many docker containers in its architecture, it means you have to allow few services, here is the complete list of ports to open. In addition, you will find on this page the schema composing the database. + +![test](img/steup.png) + +## Ports mapping + +| Container | Default DNS | +| --------- | -------------------- | +| Api | `api.{DOMAIN}` | +| Bitwarden | `bitwarden.{DOMAIN}` | +| Client | `{DOMAIN}` | +| Db | NOT EXPOSED | +| php | NOT EXPOSED | +| CodiMD | `codimd.{DOMAIN}` | +| db-codiMD | NOT EXPOSED | + + +## Database + +Here is the organisation of the tables within the API + +![test](img/database.png){ align=left } diff --git a/documentation/img/UML-smersh.png b/documentation/img/UML-smersh.png new file mode 100644 index 00000000..bcb1eaaa Binary files /dev/null and b/documentation/img/UML-smersh.png differ diff --git a/documentation/img/database.png b/documentation/img/database.png new file mode 100644 index 00000000..899dc91f Binary files /dev/null and b/documentation/img/database.png differ diff --git a/documentation/img/favicon.ico b/documentation/img/favicon.ico new file mode 100644 index 00000000..dca13d12 Binary files /dev/null and b/documentation/img/favicon.ico differ diff --git a/documentation/img/logo-white.png b/documentation/img/logo-white.png new file mode 100644 index 00000000..1d1e2aa2 Binary files /dev/null and b/documentation/img/logo-white.png differ diff --git a/documentation/img/mission-step.png b/documentation/img/mission-step.png new file mode 100644 index 00000000..9dc736b8 Binary files /dev/null and b/documentation/img/mission-step.png differ diff --git a/documentation/img/preview-api.png b/documentation/img/preview-api.png new file mode 100644 index 00000000..1592f75d Binary files /dev/null and b/documentation/img/preview-api.png differ diff --git a/documentation/img/preview-cli.png b/documentation/img/preview-cli.png new file mode 100644 index 00000000..558e89f7 Binary files /dev/null and b/documentation/img/preview-cli.png differ diff --git a/documentation/img/preview-dashboard.png b/documentation/img/preview-dashboard.png new file mode 100644 index 00000000..3b7aeabe Binary files /dev/null and b/documentation/img/preview-dashboard.png differ diff --git a/documentation/img/preview-fake-mission.png b/documentation/img/preview-fake-mission.png new file mode 100644 index 00000000..b5e4b293 Binary files /dev/null and b/documentation/img/preview-fake-mission.png differ diff --git a/documentation/img/preview-mission.png b/documentation/img/preview-mission.png new file mode 100644 index 00000000..8b95323b Binary files /dev/null and b/documentation/img/preview-mission.png differ diff --git a/documentation/img/preview-report.png b/documentation/img/preview-report.png new file mode 100644 index 00000000..ccffe8a8 Binary files /dev/null and b/documentation/img/preview-report.png differ diff --git a/documentation/img/preview.gif b/documentation/img/preview.gif new file mode 100644 index 00000000..9e2ddb5e Binary files /dev/null and b/documentation/img/preview.gif differ diff --git a/documentation/img/search.png b/documentation/img/search.png new file mode 100644 index 00000000..6f283710 Binary files /dev/null and b/documentation/img/search.png differ diff --git a/documentation/img/steup.png b/documentation/img/steup.png new file mode 100644 index 00000000..285acb2a Binary files /dev/null and b/documentation/img/steup.png differ diff --git a/documentation/img/upload-cli.png b/documentation/img/upload-cli.png new file mode 100644 index 00000000..33e198f9 Binary files /dev/null and b/documentation/img/upload-cli.png differ diff --git a/documentation/index.md b/documentation/index.md new file mode 100644 index 00000000..d478e0c5 --- /dev/null +++ b/documentation/index.md @@ -0,0 +1,20 @@ +--- +title: Pentest oriented collaborative tool +summary: used to track the progress of your company's engagements and generate reports +authors: + - Houziaux Mike + - Taba Franck +date: 31/07/2021 +--- + +# One look to know everything about your pentest + + + +# Table of Contents +1. [Installation](installation.md) +2. [Application lifecycle](lifecycle.md) +3. [Preview](preview.md) +4. [Report](report.md) +5. [Architecture](architecture.md) +6. [Smersh-cli](smersh-cli.md) diff --git a/documentation/installation.md b/documentation/installation.md new file mode 100644 index 00000000..41764b41 --- /dev/null +++ b/documentation/installation.md @@ -0,0 +1,64 @@ +# Installation + +First of all, you need to download the Projet `git clone git@github.com:CMEPW/Smersh.git` then move to `api` folder and copy .env-dist to .env. + +## With docker + +We are using the environment variable called DOMAIN declared in the .env at the root folder of the project. +You can override this variable as your own. Be sure to register the domain in your `/etc/hosts` that point to your local host. + +As we use træfik as reverse-proxy, you can refer to their documentation to learn how to customize this instance. + +Run `make initialize` then go to [http://smersh.lan](http://smersh.lan) and use `jenaye:jenaye` to log in. + + +## Manually + +### How to run API ? + + +``` +docker-compose up # when build is done do the next command +docker-compose exec php bin/console do:da:cr # create database +docker-compose exec php bin/console do:sc:up --force # generation of tables +docker-compose exec php bin/console make:entity --overwrite # +docker-compose exec php bin/console doctrine:fixtures:load # load fake data + +``` + +### How to Generate JWT ? + +``` +docker-compose exec php sh -c ' + set -e + apk add openssl + mkdir -p config/jwt + jwt_passphrase=${JWT_PASSPHRASE:-$(grep ''^JWT_PASSPHRASE='' .env | cut -f 2 -d ''='')} + echo "$jwt_passphrase" | openssl genpkey -out config/jwt/private.pem -pass stdin -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096 + echo "$jwt_passphrase" | openssl pkey -in config/jwt/private.pem -passin stdin -out config/jwt/public.pem -pubout + setfacl -R -m u:www-data:rX -m u:"$(whoami)":rwX config/jwt + setfacl -dR -m u:www-data:rX -m u:"$(whoami)":rwX config/jwt +' +``` + +### How to run client ? + + + +## How to access SMERSH from VPS ? + +You have to create a file named `config` into the `.ssh/` folder of you current user (your host). + +``` +Host smersh + Hostname + Port + User + LocalForward 127.0.0.1:8000 127.0.0.1:8000 + LocalForward 127.0.0.1:4200 127.0.0.1:4200 + LocalForward 127.0.0.1:3000 127.0.0.1:3000 + LocalForward 127.0.0.1:8888 127.0.0.1:8888 +``` + +Then you can run `ssh smersh` and go to [http://localhost:4200](http://localhost:4200). + diff --git a/documentation/lifecycle.md b/documentation/lifecycle.md new file mode 100644 index 00000000..eaaaf34a --- /dev/null +++ b/documentation/lifecycle.md @@ -0,0 +1,5 @@ +# Application lifecycle + +![UML](img/UML-smersh.png){ width=80%, align=right } + +SMERSH is designed in such a way that the manager prepares the mission, and the only task left is for the pentester to fill in the vulnerabilities found during the audit with. \ No newline at end of file diff --git a/documentation/preview.md b/documentation/preview.md new file mode 100644 index 00000000..a2462dd2 --- /dev/null +++ b/documentation/preview.md @@ -0,0 +1,22 @@ +## Dashboard + + +![Dashboard](img/preview-dashboard.png) + +## Mission preview +![Mission](img/preview-fake-mission.png) + +## Hacktivity preview + +![Hacktivity](img/mission-step.png) + + +## API preview + +![API](img/preview-api.png) + + +## Searchbar + +![search](img/search.png) + diff --git a/documentation/report.md b/documentation/report.md new file mode 100644 index 00000000..f677eb97 --- /dev/null +++ b/documentation/report.md @@ -0,0 +1,47 @@ +# Report + +The report is generated on the client side through the [*docxtemplater*](https://www.npmjs.com/package/docxtemplater) library, the principle is simple, we pass him an object in the form of key/value. + +All data is returned through the API so you can make a request on the url `http://localhost:8000/api/missions/` using your token. Everything happens at the level of [this code block](https://github.com/CMEPW/Smersh/blob/d5c6a4397a35d786c72395073ea8186659cd5188/client/src/app/components/mission-single/mission-single.component.ts#L428) + + +>For information this token can be retrieved through a get request on the entry point `authentication_token` and uses the settings username and password : + + +```c +curl --request POST \ + --url http://localhost:8000/authentication_token \ + --header 'Content-Type: application/json' \ + --data '{ + "username": "jenaye", + "password": "jenaye" + +}' +``` + +![report-preview](img/preview-report.png){ width=40%, height=20%, align=right } + +## Where can I put my docx template ? + + +You can move your template to the `clients/src/assets/` folder and rename it `Smersh.docx`. + +>It is also possible to give it another name, however you will have to change the [following line](https://github.com/CMEPW/Smersh/blob/d5c6a4397a35d786c72395073ea8186659cd5188/client/src/app/components/mission-single/mission-single.component.ts#L422), then rebuild the container by typing `docker-compose up --build --force-recreate --remove-orphans client` + +## Which variables are used ? + +Here is the list of all the variables that will be used to generate the report + +| startDate | Start date of the mission | +|----------------|----------------------------------------------------------------------------------------------------------------| +| CLIENT_NAME | Name of the customer | +| creds | Bitwarden credentials identifiers | +| classification | Type of report | +| phone | Phone number number | +| version | Report version number | +| authors | List of pentesters assigned on the mission missioL | +| state | The status of the report | +| scope | All the domain names and associated vulnerability as well as their criticality. | + + +For example, if you want to use the key `to` inside the report, change its value in the `data` object and then add this to the desired location `{to}`. \ No newline at end of file diff --git a/documentation/smersh-cli.md b/documentation/smersh-cli.md new file mode 100644 index 00000000..3d24372b --- /dev/null +++ b/documentation/smersh-cli.md @@ -0,0 +1,105 @@ +# Smersh-cli + +`smersh-cli` made by respecting the CRUD standards, the command line is interactive and easy to use + +![preview-cli](/img/preview-cli.png) + +## Installation + +### Via Docker + +This project includes a Dockerfile that you can build using the following command: + +```bash +cd +docker image build -t smershcli:v1.0 . +``` + +Once the image is built, you can simply run smersh-cli using the following command: + +```bash +docker run -it +``` + +### Via Pip + +You can also install the latest release directly from PyPI using the following command: + +```bash +pip install smersh_cli +``` + +### Manually + +`smersh-cli` requires at least Python 3.5 because of the usage of typing (see [PEP 484](https://www.python.org/dev/peps/pep-0484/) +for more information). However, we recommend Python 3.8 to avoid using a hack to get the project working (see [issue #12](https://github.com/CMEPW/smersh-cli/issues/12)). +If you have an older Python version, you will need to upgrade as we won't support any version below 3.5. + +`smersh-cli` also depends on the following libraries: + +* rich +* cmd2 +* requests +* dataclasses_json +* pydantic +* importlib_metadata + +If you have `setuptools` installed you can use the following command to install all dependencies and the package at once: + +```bash +python setup.py install +``` + +You can then use `smersh-cli` simply by using the command `smersh-cli`. + + +## Usage + +To run `smersh-cli`, you simply have to invoke the `main.py` script with your SMERSH API url as one single argument: + +```bash +python main.py +``` + +You will then be asked to enter your credentials before having an interactive command line interface (see below for an +example). + + +### Commands + +smersh-cli implements every single builtin `cmd2` command (see the [cmd2 documentation](https://cmd2.readthedocs.io/en/latest/features/builtin_commands.html) +for more information about these commands). However, please think twice before using commands like `py` or `ipy` because +you can easily break something. + +In addition to these commands, `smersh-cli` implements the following ones: + +* show +* use +* assign +* save +* upload +* delete +* exit + +Please note that every command is documented. The documentation can be shown with the `help` command. + + +### Upload +It is also possible to upload a file to add your entire scope. However, the file must be formatted like this: + +``` +https://jenaye.fr +10.10.10.2 +devcv.fr +192.168.1.0/24 +``` + +![smersh-cli](/img/upload-cli.png) + +### Commands and contexts + +Some commands require a 'context' to be used. This is the case for the `assign`, `save` and `delete` commands. A context +is used to tell the program about which object the operation you want to perform refers to. To change the context you +need to use the `use` command. You can see at any time which context is active thanks to the prompt of the interactive +command line. In order to exit the active context, use the `exit` command (**warning**: every unsaved modification will +be lost). \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..f78b7d03 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,24 @@ +site_name: Smersh documentation +site_url: https://docs.smersh.app +repo_url: https://github.com/CMEPW/Smersh +repo_name: Smersh +edit_uri: documentation +theme: + palette: + primary: red + accent: deep orange + logo: img/logo-white.png + favicon: img/favicon.ico + name: material + features: + - toc.integrate +markdown_extensions: + - attr_list + - pymdownx.highlight + - pymdownx.superfences +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/CMEPW/Smersh + - icon: fontawesome/brands/twitter + link: https://twitter.com/smersh_sec \ No newline at end of file