{"id":21388679,"url":"https://github.com/cybersecsi/docker-vuln-runner","last_synced_at":"2025-07-21T16:05:03.332Z","repository":{"id":133912247,"uuid":"557718924","full_name":"cybersecsi/docker-vuln-runner","owner":"cybersecsi","description":"A Docker runner for vulnhub environment. ","archived":false,"fork":false,"pushed_at":"2024-01-15T10:00:09.000Z","size":186,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-03-15T10:51:59.032Z","etag":null,"topics":["automation","docker","vulhub","vuln","vulnenv","vulnerability"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cybersecsi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-10-26T07:10:47.000Z","updated_at":"2024-01-15T09:59:58.000Z","dependencies_parsed_at":"2024-01-15T10:09:39.290Z","dependency_job_id":"8b5b5f51-53d9-4752-9c2f-d87082de77fa","html_url":"https://github.com/cybersecsi/docker-vuln-runner","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cybersecsi%2Fdocker-vuln-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cybersecsi%2Fdocker-vuln-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cybersecsi%2Fdocker-vuln-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cybersecsi%2Fdocker-vuln-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cybersecsi","download_url":"https://codeload.github.com/cybersecsi/docker-vuln-runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225894259,"owners_count":17541027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","docker","vulhub","vuln","vulnenv","vulnerability"],"created_at":"2024-11-22T12:19:06.252Z","updated_at":"2024-11-22T12:19:07.232Z","avatar_url":"https://github.com/cybersecsi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/cybersecsi/docker-vuln-runner/main/logo.png\" alt= \"Docker Vuln Runner\" width=\"300px\"\u003e\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003cb\u003eDocker Vuln Runner\u003c/b\u003e \u003cbr /\u003e\n    A Docker runner for docker-based vulnerable environments. \n\u003cp\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/cybersecsi/docker-vuln-runner/blob/main/README.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/Documentation-complete-green.svg?style=flat\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cybersecsi/docker-vuln-runner/blob/main/LICENSE.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-GNU%20GPL-blue\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Table of Contents\n- [Overview](#overview)\n- [Install](#install)\n- [Local Usage](#local-usage)\n- [Distributed Usage](#distributed-usage)\n- [Demo](#demo)\n- [Development](#development)\n- [Credits](#credits)\n- [License](#license)\n\n## Overview\n``vuln-runner``  is a tool that allows you to quickly run the docker vulnerable stacks. \n\nThe vulnerable stack actually supported are: \n* [vulhub repo](https://github.com/vulhub/vulhub)\n\nAt [SecSI](https://secsi.io) we found it useful to reproduce vulnerable environments for training purposes. To reproduce vulnerable environment easily, take a look at [DSP](https://secsi.io/docker-security-playground/).\n\n## Install\nYou can easily install it by running:\n```\npip install vuln-runner\n```   \nThis will install three basic command:   \n* **vuln-runner**: the basic module to run vuln-runner in local-mode;\n* **vuln-controller**: the controller module that manages a set of **vuln-nodes** ;\n* **vuln-node** : a vulnerable node that can receive commands from a vuln-controller.  \n\n## Local Usage  \nIt is possible to use vuln-env in local-mode. The docker environment is installed locally and it all the vulnerable stacks runs locally.  \n\n```\nvuln-runner --help\n```\n\nThis will display help for the tool. Here are all the switches it supports.\n\n```\nUsage: vuln-runner [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  down              Down a list of vulnerable projects\n  down-env          Down an environment\n  generate-vulnenv  Generate \u003cno_env\u003e vulnerable environments composed of...\n  init\n  list              List the vulnerable names\n  run               Run a list of vulnerable projects\n  run-env           Run an environment taken from a JSON configuration file\n  update            Update the vulnerable git repositories\n\n```\n\n* **Initialized the vulnerable environment:**  \n```\nvuln-runner init\n```\n\n[![asciicast](https://asciinema.org/a/nYJEd62OzL3WLUuigyjeChLIE.svg)](https://asciinema.org/a/nYJEd62OzL3WLUuigyjeChLIE)\n\n\n* **List the vulnerable stacks:**\n```\nvuln-runner list\n```  \n\n\n[![asciicast](https://asciinema.org/a/raziKJLlR6vWSbiIwY1w8kqaq.svg)](https://asciinema.org/a/raziKJLlR6vWSbiIwY1w8kqaq)  \n\n* **Run a list of vulnerable stacks:**\n\n```\nvuln-runner run vulhub.CVE-2014-3120,vulhub.CVE-2018-1270\n```\n\n[![asciicast](https://asciinema.org/a/wIOCYSrD9o5ZE6NmuCWLTTD8A.svg)](https://asciinema.org/a/wIOCYSrD9o5ZE6NmuCWLTTD8A)  \n\n\n* **Down the list of vulnerable stacks:**\n```\nvuln-runner down vulhub.CVE-2014-3120,vulhub.CVE-2018-1270\n```\n\n[![asciicast](https://asciinema.org/a/fAuTCMJHdxa5sRK0VlbfAKqcV.svg)](https://asciinema.org/a/fAuTCMJHdxa5sRK0VlbfAKqcV)  \n\n### Advanced usage: vulnerable environment  \nWith the previous commands you can already manage your vulnerable stacks and manually run and stop them. \nAnyway, you can also create *vulnerable environments*. \nA vulnerable environment is a set of vulnerable docker-compose stacks that has not ports' conflicts.   \nYou can generate a vulnerable environment descriptor in JSON format with the `generate-vulnenv` command:   \n``` \nvuln-runner generate-vulnenv NO_VULNS [--no-env=\u003cdefault=1\u003e]\n```  \n\n* `NO_VULNS` defines the number of vulnerable stacks for each environment. \n* `--no-env` defines the number of environments. It is useful if you want to run vuln-runner in different hosts, where each host runs a single environment.   \n\nFor example, to create a JSON vulnerable descriptor with two vulnerable stack and two environments: \n```\nvuln-runner generate-vulnenv 2 --no-env=2  \n```\n\n[![asciicast](https://asciinema.org/a/KxRWBVOMLymUQiWgjDDm4f6JS.svg)](https://asciinema.org/a/KxRWBVOMLymUQiWgjDDm4f6JS)   \n\nYou can output into the JSON descriptor into a file an reuse with two commands: \n* **run-env**: run the set of stacks belonging to a vulnerable environment.   \n```\nvuln-runner run-env output.json 1\n```\n[![asciicast](https://asciinema.org/a/vuL2l5vL8bqRefx9EAqYlqxFC.svg)](https://asciinema.org/a/vuL2l5vL8bqRefx9EAqYlqxFC)\n\n* **down-env**: down the vulnerable environment.  \n\n```\nvuln-runner down-env output.json 1\n```\n[![asciicast](https://asciinema.org/a/fAuTCMJHdxa5sRK0VlbfAKqcV.svg)](https://asciinema.org/a/fAuTCMJHdxa5sRK0VlbfAKqcV)  \n\n\n## Distributed Usage  \nIt is possible to use `vuln-runner` in distributed-mode: \n1. *vuln-nodes* initialize a token and run a tcp server that listens for commands  \n2. A *vuln-controller* initializes the same token and can manage the vulnerable environments     \nThe example architecture is shown in the following Figure:   \n![image](https://user-images.githubusercontent.com/18548727/199806289-5fba4fec-7e8f-4c97-bb81-c325a7dfa681.png)\n\n### node configuration   \n1. Initializes the node: \n \n```  \nvuln-runner init \nvuln-node init \n```\nYou have to define a token that will be used to validate the requests that comes from a controller. \n\n2. Start the vulnerable node: \n```  \nvuln-node start  \n```   \nFrom this moment the `vuln-node` listens for connections on port **4545** .  \nWhen a vuln-node is listening for a connection the controlle is able to find it through the **discovery** step. \n\n\n### controller configuration  \n1. Initialize the controller  \n```  \nvuln-runner init \nvuln-controller init \n```   \n\n2. Discover the remote nodes  \n```   \nvuln-controller discovery \u003csubnet_vulnerable_nodes\u003e -u  \n```    \nThrough this command the controller finds all the hosts presents in the network. \nWhen the `-u` option is used, the `hosts.json` configuration file present in the ~/.vulnenv folder is updated with the list of the vuln-nodes. \n\n3. Generate the vulnerable environments   \nAfter the configuration the `hosts.json` it is possible to generate a vulnerable environment configuration composed of `\u003cno_env\u003e` vulnerable scenarios. For example, the following command: \n```  \nvuln-controller generate-vulnenv 2  \n```\n\ngenerates two vulnerable environment for each `vuln-node` discovered previosly.       \n\n4. Manage the enviornments   \nTo run a single vulnerable environment:  \n```  \nvuln-controller run-env \u003cip\u003e  \n```   \nIt is also possible to run all the vulnerable environments:   \n```   \nvuln-controller run-envs   \n```    \n\nTo shutdown the environments:   \n```   \nvuln-controller down-envs  \n```  \n\n\n### Design considerations for the distributed architecture  \nThe token is used to authenticate the requests that comes from the controller. It is not used as secure mechanism. \nAll the protocol is unencrypted, as we suppose that the environment is \"unsecure-by-default\". It is used to setup vulnerable machines. An attacker could potentially intercepts the requests and put them down. \n\nYou could setup firewall rules to allow the connections to the **4545** only from the controller IP host. \n\nThis is useful as the students should not be able to see that port. \n\n\n\n## Development  \nThe [poetry](https://python-poetry.org/) packaging and management tool was used to build the project.  \nTo initialize the project: \n```\npoetry install \n```  \n\nTo run the several commands, you can use poetry as follows:  \n\n``` \npoetry run vuln-runner \u003ccommand\u003e  \n```\n\n\n\n\n## Credits\nDeveloped by gx1 [@SecSI](https://secsi.io)\n\n## License\n*Docker Vuln Runner* is released under the [GPL LICENSE](https://github.com/cybersecsi/docker-vuln-runner/blob/main/LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcybersecsi%2Fdocker-vuln-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcybersecsi%2Fdocker-vuln-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcybersecsi%2Fdocker-vuln-runner/lists"}