dockersecurityplayground / dsp

A Microservices-based framework for the study of Network Security and Penetration Test techniques

DockerSecurityPlayground

Docker Security Playground is an application that allows you to:

• Create network and network security scenarios, in order to understand network protocols,
  rules, and security issues by installing DSP in your PC.
• Learn penetration testing techniques by simulating vulnerability labs scenarios
• Manage a set of docker-compose project . Main goal of DSP is to learn in penetration testing and network security, but its flexibility allows you the creation, graphic editing and managment run / stop of all your docker-compose labs.

How To Use

Follow DSP channel to learn how to use DSP. You can also use wiki documentation to understand how you can use DSP.
Follow Installation and Start steps to run DSP.

The package:

• Install docker and docker-compose
• Install latest stable nodejs
• Install dsp
• Creates a dsp user on the target machine

When the installation is complete, you can run dsp by using the systemd command:

systemctl start dsp   

DSP will run on "http://localhost:18181"

Developer Installation

1. Install DSP Requirements:

• Nodejs (v 7 or later)
• git
• docker
• docker-compose
• compiler tools (g++, c, c++)

2. Install node dependencies and run:

git clone https://github.com/giper45/DockerSecurityPlayground.git
cd DockerSecurityPlayground
npm install

3. Run:

npm start  

To start the application. This will launch a server listening on 18181 (or another if you set have set PORT environment variable) port of your localhost.

With your favourite browser go to http://localhost:18181. You'll be redirected on installation page, set parameters and click install.
I suggest you to run dsp on a Ubuntu virtual machine and expose on 0.0.0.0 interface.
If you want to expose on another interface, change DSP_IFACE environment variable:

export DSP_IFACE="0.0.0.0"

Now you can use dsp on Remote interface.

Update the application:

When you update the application it is important to update the npm packages (The application uses mydockerjs, a npm docker API that I am developing during DSP development: https://www.npmjs.com/package/mydockerjs)

npm run update

Clean DSP

If something goes wrong, you can reset DSP to factory by using the following command:

npm run uninstall  

This will delete everything, and you can start DSP from the installation step.

Official Repository

DSP_Projects contains official DSP labs. Contribute to DSP by creating new DSP Labs

How can I share my labs with the world ?

During the installation you can create a local environment that has not link with git, or you can associate a personal repository the the application. This is very useful if you want to share your work with other people.
DSP Repository must have several requirements, so I have created a base DSP Repo Template that you can use to create your personal repository.
So, the easiest way to share labs is the following:

1. Fork the NS-Unina project: https://github.com/NS-unina/DSP_Repo.git
2. During the installation set github directory param to your forked repository.
3. Now create your labs and share it!

It is important that all images that you use should be available to other users, so:

• You can publish on docker hub so other users can pull your images in order to use your labs.
• You can prov[ide dockerfiles inside the .docker-images directory, so users can use build.sh to build your images and use your repo.

If you need a "private way" to share labs you should share the repository in other ways, at current time there is no support to share private repositories.

In DSP you can manage multiple user repositories (Repositories tab)

DSP Features

• Graphic Editor of docker-compose
• Docker Image and Dockerfile Management
• GIT Integration
• DSP Repository with a set of network security scenarios

Any question ?

If you have a problem you can use Issue section.

Docker Wrapper Image

DSP implements a label convention called DockerWrapperImage that allows you to create images that expose action to execute when a lab is running. Look at the doc

Tests

To run a test:

mocha test/<test-nodejs-file.js>   

tests use helper.start() method to initialize the test environment:

• A test config is created
• homedir directory is mocked, in this way it is possible to use internal dsp directory for tests.

Troubleshooting

During dependencies installation

If you have error regarding node-pty module, try to:

• Install build-essentials : (In Ubuntu: apt install -y build-essentials)
• Use nodejs LTS (note-pty has some isseus, as shown here

If you have the following error:

ERR! typeerror Error: Missing required argument #1  

You need to update nodejs:

sudo apt-get install -y python-software-properties
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash
sudo apt-get install nodejs

During DSP installation

If you have the following error during the installation:

[2020-12-14T10:18:21.854Z]  INFO: DockerSecurityPlayground/1536 on vagrant: [DOCKER ACTIONS - DOWNLOAD IMAGE]
events.js:174
      throw er; // Unhandled 'error' event
      ^

Error: connect EACCES /var/run/docker.sock
    at PipeConnectWrap.afterConnect [as oncomplete] (net.js:1107:14)
Emitted 'error' event at:
    at Socket.socketErrorListener (_http_client.js:401:9)
    at Socket.emit (events.js:198:13)
    at emitErrorNT (internal/streams/destroy.js:91:8)
    at emitErrorAndCloseNT (internal/streams/destroy.js:59:3)
    at process._tickCallback (internal/process/next_tick.js:63:19)

Verify 2 things:

1. docker is installed
2. current user is in docker group

To test it:

docker ps   

DO NOT USE SUDO if you are running DSP with normal user.
If you have the following error:

vagrant@vagrant:~/git/DockerSecurityPlayground$ docker ps
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/json: dial unix /var/run/docker.sock: connect: permission denied

You need to add your user to group docker:
https://docs.docker.com/engine/install/linux-postinstall/

$ sudo groupadd docker
$ sudo usermod -aG docker $USER

Log-out and log-in
Now you need to clean DSP:

npm run uninstall  

And now everything should work.

MacOS error

MacOS ECONNRESET error:

events.js:183
      throw er; // Unhandled 'error' event
      ^

Error: read ECONNRESET
    at _errnoException (util.js:992:11)
    at TCP.onread (net.js:618:25)

On Mac it seems that there is some problem with some node package, so in order to solve this run:

MacBook-Pro:DockerSecurityPlayground gaetanoperrone$ npm install [email protected] --save-dev --save-exact

Other info here: http://gitlab.comics.unina.it/NS-Thesis/DockerSecurityPlayground_1/wikis/docker-operation-errors

node-pty issues

The application is based on node-pty pseudoterminal, that is subjected to several compilation errors. In order to compile you need to install the compilation toolchain for Ubuntu:

apt-get install -y build-essential

And the XCode for macOS users.

Please, follow the library documentation guide to fix the compilation errors that could occurr when you run npm install command. Here some potential issues:

• error: no template named 'remove_cv_t' in namespace 'std'; did you mean 'remove_cv'? : try to use the C++ v17 : env CXXFLAGS="-std=c++17" npm i

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request, we'll check

Any Questions?

Use the Issues in order to ask everything you want!.

Links

• Landing Page
• 
• DSP Vagrant Box used in Blackhat Session
• Blackhat scenario in Gitlab

Relevant DSP Repositories

• https://github.com/giper45/DSP_Projects.git : Official DSP Repository
• https://github.com/giper45/DSP_Repo.git : DSP Template to create another repository: fork it to start creating your personal remote environment
• https://github.com/NS-unina/DSP_Repo.git : Repository created for Network Security Course of Simon Pietro Romano in University of the Study in Naples, Federico II

Contributors

gx1 🐛 💻 🖋 🎨 📖 🚧 📆	Simon Pietro Romano 🎨 📖 📆	catuhub 🐛 💻 🎨 📖 🚧 📆	Giuseppe Di Terlizzi 💻	Alessandro 📖 📹 🖋	Roberto 💻 🖋 🚇	the-licato 🚇
Gabriele Previtera 💻 📢

Thanks to Giuseppe Criscuolo and Alessandro Placido Luise for the logo design

Changelog

Got to CHANGELOG.md to see al the version changes.

Cite this work

If you use Docker Security Playground for your research activity, cite the following paper published by the IEEE (Institute of Electrical and Electronics Engineers) https://ieeexplore.ieee.org/document/8169747

License

This project is under the MIT license

dsp's Issues

Add color legend in images page

In images page we should show the color meaning:

• Red : an image that is used in labs but that is not present locally
• Orange: an image not used in labs and not present locally
• Green: an image present locally and used in labs

Can't download image in lab L_10_BufferOverflow_Fuzzing

Describe the bug
DSP can't download the image "alessandro123456/wfuzz:latest" needed for the lab L_10_BufferOverflow_Fuzzing,

To Reproduce
Steps to reproduce the behavior:

1. Go to L_10_BufferOverflow_Fuzzing in the NetworkSecurity_Unina 1.1 labs
2. Click on download all images
3. Note that the image is not downloaded with error :
   {"message":"manifest for alessandro123456/wfuzz:latest not found: manifest unknown: manifest unknown"}

Expected behavior
DSP should pull the image from docker hub

Screenshots

Additional context
In the other lab L10_FuzzingTraining there is a image "alessandro123456/wfuzz:tagname" that is correctly downloaded. This is probably the image needed for the lab L_10_BufferOverflow_Fuzzing.

ADD DSP_Repo to official repos

Bug expose ports in edit container

Describe the bug
Sometimes, during the edit of a container, the options are not updated.

To Reproduce
TBD

Error when the user repo does not contains the labels.json file

The application crashes if labels.json is not present on user repo.

"Netcat the Almighty" non si avvia se sono presenti più versione di una stessa immagine

Il laboratorio "Netcat the Almighty" non si avvia se è presente sia l'immagine
nsunina/alpine_netcat:v1.1 sia la v1.0
dando l'errore:
ERROR: The following images are not installed: nsunina/alpine_netcat:v1.1,nsunina/alpine_netcat:v1.1

eliminando manualmente la v1.0 riprende a funzionare normalmente

"Back" button in the graphic panel

When entering in editing mode into a specific node/network, allow for a "Back" button (to return to the main panel without applying any modification) rather than just the currently available "Save" button.

Docker image managment

Each lab has a list of images

• Green image: installed images
• Orange images: image not used, you can delete them
• Red images: required images: you should install

A button to install red docker-images , a button to delete docker-images
A progress bar during the downloading of images

Clone empty repository and repository creation

Application should create a repository with docker syntax when the user set an empty repository.
If the user set a repository with a dsp structure this will be used.

Network graph information is not correct if you create two different networks.

To Reproduce

1. Create two networks

Start Capture for labs containing spaces

Describe the bug
If a lab contains spaces, start capture actions gives errors
To Reproduce
Steps to reproduce the behavior:

1. Go to lab containing spaces
2. Click on Start Lab
3. Click on Start Capture
4. DSP gives the following error:
   Unable to find image 'pluto:latest' locally

Expected behavior
Container name that contains spaces should be quoted.

Change container name should change depends on option in containers

Describe the bug
If containers have depends_on option enabled and user changes the name of a container, depends_on option is not changed

To Reproduce

1. Go to Edit Network
2. Create two containers (c1 and c2)
3. On first container, set depends_on -> c3
4. Change the name of second contrainer (c2 -> c3)

Docker image tagging

DSP should uses tagging images, now all labs uses a latest syntax notation.

Saving docker-conpose upon editing of nodes/networks

After modifying a node/network in the graphic panel, the docker-compose file should be automatically updated.

Multiple Repo support

DSP Should support multiple external repositories.

Navigate to Dockerfile page from Edit Network Section

If dockerfile images are used, it would be useful during edit network to go in Dockerfile page.

No images and docker graph editor gui

If the user has not downloaded docker images, it should not be able to reach docker_graph_editor GUI.

Block the change of edit container when the user has not updated the container

checksum when import a file

If the file already exists and is equal, do not throw an error.
In order to do this, it could be possible to compare checksums

Labels not updated during lab creation after label creation

Describe the bug
When the user creates a new label, dsp does not udpate labels in edit info.
To Reproduce
Steps to reproduce the behavior:

1. Create a new lab
2. Create a new label
3. Click on edit info
4. New label is not shown

Expected behavior
DSP should see new label

A good bug to implement publish subscribe mechanism :-)

Crash when a broken link is present on home directory

JSLint refactoring code

Make all the code compliant to jslint rules.

Labs can't start if the docker image used is too big

Describe the bug
Labs can't start if the docker image used is too big.

To Reproduce
Steps to reproduce the behavior:
1 - Create a new lab.
2 - Drag a host in the GUI.
3 - Select an image of size greater than 1GB

Log
On running lab :

ERROR: DockerSecurityPlayground/2413 on kali: Trying to redefine maintainer which is a string
Error: Trying to redefine maintainer which is a string
at DotObject.fill (/root/DockerSecurityPlayground/node_modules/dot-object/index.js:92:17)
at /root/DockerSecurityPlayground/node_modules/dot-object/index.js:147:12
at Array.forEach ()
at DotObject.object (/root/DockerSecurityPlayground/node_modules/dot-object/index.js:141:20)
at Function.object (/root/DockerSecurityPlayground/node_modules/dot-object/index.js:76:31)
at JDCgetCapabilities (/root/DockerSecurityPlayground/app/data/docker-converter.js:76:33)
at JDCGetServices..each (/root/DockerSecurityPlayground/app/data/docker-converter.js:133:18)
at Function.each (/root/DockerSecurityPlayground/node_modules/underscore/underscore.js:1230:9)
at Object.JDCGetServices (/root/DockerSecurityPlayground/app/data/docker-converter.js:99:5)
at Object.JSONDockerComposeConvert (/root/DockerSecurityPlayground/app/data/docker-converter.js:161:25)

Notes
"maintainer" is a label in this tested docker image used to reproduce the bug. If I remove maintainer it gives the same problem with "CMD".

.dsp empty directory problem

Unable to access DSP on a remote server because of "host" parameter in function server.listen

Describe the bug

In order to access the service opened on port 8080 (Tested with a Ubuntu 20.04.1 LTS server and a Kali Linux server. ) the parameter "host" must be removed from the function server.listen in index.js.

So this function :

server.listen(port, host, () => {
  if (localConfig.config.test) { log.warn('Testing mode enabled'); }
  log.info(`Server listening on ${host}:${port}`);
});

Should become

server.listen(port, () => {
  if (localConfig.config.test) { log.warn('Testing mode enabled'); }
  log.info(`Server listening on ${host}:${port}`);
});

To Reproduce
Steps to reproduce the behavior:
1.Install DSP on a remote server
2. Try Access DSP service through http:/"publicipofserver":8080

Additional notes
The application works fine on the local machine ( http://localhost:8080/ ) without the parameter host if I modify the index.js file and
run the app with "sudo npm start". This is tested with Linux 5.9.0-kali1-amd64 on Kali Linux 2020

Add template guide in editInfo

When a user writes the application does not know which tags can use:

The code that parses at the moment is the following:

this.parse = function parse(text) {
    text = text.replace(/\{\{hostname\}\}/g, $location.host())
    text = text.replace(/\{\{url\}\}/g, $location.protocol() + "://" + $location.host())
    return text
  }

it would be useful to have a guide in GUI in order to understand the special keyword that the user can use.

DSP Crashes for docker_socket module bug in listing bash commands

Describe the bug
DSP Crashes for docker_socket module bug in listing bash commands
To Reproduce
Steps to reproduce the behavior:

1. Start a lab
2. Connect on a terminal
3. Stop lab. The application crashes

Expected behavior
DSP should check if output variable is undefined before listing binCommands:

p/util/docker_socket.js:22
      const binCommands = output.split("\n");
TypeError: Cannot read property 'split' of undefined


  ```                              ^

Invalid argument exception thrown during first configuration on Node 14.x

Issue Description
Since Node.js 14.5 has been promoted to LTS, now it's the default version downloaded from 'stable' channel. Within this version, the method writeFileSync has a data mandatory argument. https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options
In initUserRepo function declared at app/util/project_init.js, this function (line 21) was called without this mandatory argument, causing ERR_INVALID_ARG_TYPE exception and application crash.

To Reproduce
Steps to reproduce the behavior:

1. Remove config/config_user.json file (to initialize the application to the first usage)
2. Start the application, compile initial configuration form and click on 'Install'
3. The exception is shown on the terminal, as the application crashes.

Expected behavior
Docker Security Playground configuration proceeds correctly and automatically redirects to http://localhost:8080/labs

Screenshots

Desktop:

• OS: Debian based Linux distro, macOS 10.15
• Browser: Chrome, Safari, Firefox
• Node.js 14.5

Add images during lab description

Is your feature request related to a problem? Please describe.
It could be useful to add images durng the description of a lab. In this way
Describe the solution you'd like
Add upload support to lab.html view.
Images should be uploaded in a user dir (i.e. <name_user>/upload) and should be provided a templating system to add images.

Interface should give warning if all the images are not installed

With version 3 this behaviour is not more available. It is possible to start a lab even if the user has not all the images installed

Exit from a running container should come back to edit network lab

Acutally it returns to old interface

Labels issue in labs section

Describe the bug
DSP only shows current user labels filter in the main labs page.
It should show a complete list of labels.
To Reproduce
Steps to reproduce the behavior:

1. Go to labs with a new user that has not created labels
2. Click on labels filter: user cannot filter by label for all the labs.

Expected behavior
DSP should show a complete list of labels.

Error in docker image if a lab has not a network.json

Steps to reproduce

• Create a new lab but does not create the graph network
• Navigate inside the image section: the error will occur

Check if there is no connectivity

Verify when connection is used if there is connection before to download packages

Support to markdown syntax for lab description

Is your feature request related to a problem? Please describe.
DSP Should be able to read README.md in a lab. In this way, it is possible to use git to document the scenarios.

Describe the solution you'd like
Add README section, and a preview

The wireshark monitoring service should be executed with network_mode: host

When running the wireshark monitoring service you basically dont see any meaningful traffic.

A complete an solution can be to run the container with the flag "network_mode: host" in order to sniff all the traffic flowing through the host.

Code snippets for images customization

Well-known Docker images customizations should be collected and made available to users.
Example: privilege escalation configurations in form of Dockerfile code snippets available from GUI.

Check Docker Daemon execution on npm start

Is your feature request related to a problem? Please describe.
DSP should check that Docker is running after execution.

Describe the solution you'd like
Add checks about docker daemon execution

Graph enhancements

Network graph should have a legend on the left.
network should show the subnet ip addresses.
Containers should show the image name
Containers should show the ip in the link

gitignore support to shared folders

Is your feature request related to a problem? Please describe.
User should be able to "freeze" Folders that are shared inside labs to reuse in code review processes should.
This could be performed by creating a flag "freeze dir" when the user has configured the laboratory. The checkbox will add a .gitignore inside the lab.

war files uploaded via edit dockerfile wrong mode

Go to manage images -> dockerfiles -> create-> make a dockerfile such as
FROM tomcat:7 ADD test.war /usr/local/tomcat/webapps/ EXPOSE 8080 CMD ["catalina.sh", "run"]

upload test.war ->> save image and build. Build completes. war file not active.
entered container file exists in /usr/local/tomcat/webapps/, however error below in catalina log. attempt to unzip manually also fails. wget same war file from container, deploys perfect.
Thoughts: the uploader doesn't transfer the war file properly.

`Jul 13, 2020 8:12:02 PM org.apache.catalina.startup.HostConfig deployWAR
SEVERE: Error deploying web application archive [/usr/local/tomcat/webapps/test.war]
java.lang.IllegalStateException: ContainerBase.addChild: start: org.apache.catalina.LifecycleException: Error in resourceStart()
at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:1011)
at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:983)
at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:639)
at org.apache.catalina.startup.HostConfig.deployWAR(HostConfig.java:1127)
at org.apache.catalina.startup.HostConfig$DeployWar.run(HostConfig.java:2019)
at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
at java.util.concurrent.FutureTask.run(FutureTask.java:266)
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
at java.lang.Thread.run(Thread.java:748)

Jul 13, 2020 8:12:02 PM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deployment of web application archive [/usr/local/tomcat/webapps/test.war] has finished in [50] ms
Jul 13, 2020 8:12:02 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-apr-8080"]
Jul 13, 2020 8:12:02 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 109 ms
root@ec8baf0f83ed:/usr/local/tomcat# ls webapps
test.war
root@ec8baf0f83ed:/usr/local/tomcat# unzip webapps/test.war
Archive: webapps/test.war
▒
error [webapps/test.war]: missing 1729769170 bytes in zipfile
(attempting to process anyway)
error [webapps/test.war]: attempt to seek before beginning of zipfile
(please check that you have transferred or created the zipfile in the
appropriate BINARY mode and that you have compiled UnZip properly)
`

Editing environment variables

It would be nice to have the possibility of editing environment variables in order to modify their values. As of now, you have to delete them and then re-create with the new value.

Web socket error stdout maxBuffer length exceeded

Describe the bug
Web socket error: RangeError [ERR_CHILD_PROCESS_STDIO_MAXBUFFER]: stdout maxBuffer length exceeded

To Reproduce
Steps to reproduce the behavior:

1. Go to olindo image
2. Click on Save Image and Build
   3 The error occurs during build of the image

Expected behavior
DSP should manage large buffer size

Download all button in images page should not be present if no images have been yet created.

In images page a lab that does not contain docker images allows to click on Download All buttons. This button should be disabled.

Lab checking

Application should checks if each docker image has been downloaded before that he can enter into a lab

Lab already run if the lab is stopped and try to edit network

Describe the bug
If you try to edit network when the lab is stopped, it returns lab already run

To Reproduce
Steps to reproduce the behavior:

1. Go to a lab
2. Start Lab
3. Stop Lab
4. Try to edit network. It gives warning "Lab still runs"

Expected behavior
It should update the lab state and allows the user to update the lab.

Unit Test update

Old test cases, must update, refactoring, improve.

DSP should return an error if an image does not contain bash binary

When download images is completed, Edit Network should appear for User Labs

Describe the bug
If a lab does not have images, these could be downloaded. If the lab does not contain all images, network cannot be edited, so the button "Edit Network" does not appear.
If the user download the images, Edit Network button should appear.

To Reproduce
Steps to reproduce the behavior:

1. Go to a user lab (editable lab) that does not contain all images
2. Click on "Download Images"
3. Download Images
4. "Edit Network" should appear if the user wants to edit

Files in dockerfile don't have executable

Describe the bug
When the file are saved in dockerfile panel, set chmod +x if the user set the executable flag
This is a problem because when the container is built, you could require to have executable files.

To Reproduce
Steps to reproduce the behavior:

1. Go to dockerfiles directory
2. Drag a file
3. Select the file
4. Save and build
5. Run the container
   The script cannot be used for permission denied issues .

Expected behavior
It should be possible to set permission in front-end.