diff --git a/Dockerfile b/Dockerfile index 3ce15dc478..e429c7c12d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -25,10 +25,11 @@ ENTRYPOINT [ \ # Example local BB # docker run -v "/$(pwd)/generated_tests":/generated_tests webfuzzing/evomaster --blackBox true --bbSwaggerUrl http://host.docker.internal:8080/v3/api-docs --maxTime 5s # -# Example WB +# Example WB (NOT IMPLEMENTED YET) # docker run -v "/$(pwd)/generated_tests":/generated_tests webfuzzing/evomaster --dockerLocalhost true # -# TODO and em.yaml +# Setting for existing em.yaml +# -v "/$(pwd)/em.yaml":/em.yaml # # Debugging # docker run -it --entrypoint sh webfuzzing/evomaster diff --git a/core/src/main/kotlin/org/evomaster/core/EMConfig.kt b/core/src/main/kotlin/org/evomaster/core/EMConfig.kt index ef69fbe0c0..8c44e867e9 100644 --- a/core/src/main/kotlin/org/evomaster/core/EMConfig.kt +++ b/core/src/main/kotlin/org/evomaster/core/EMConfig.kt @@ -1073,10 +1073,6 @@ class EMConfig { @Max(maxTcpPort) var sutControllerPort = ControllerConstants.DEFAULT_CONTROLLER_PORT - @Important(6.2) - @Cfg("Replace references to 'localhost' to point to the actual host machine." + - " Only needed when running EvoMaster inside Docker.") - var dockerLocalhost = false @Important(7.0) @Url @@ -1090,6 +1086,17 @@ class EMConfig { " Users should not modify this parameter, as it is set automatically in the Docker image of EvoMaster.") var runningInDocker = false + /** + * TODO this is currently not implemented. + * Even if did, there would still be major issues with handling WireMock. + * Until we can think of a good solution there, no point in implementing this. + */ + @Experimental + @Cfg("Replace references to 'localhost' to point to the actual host machine." + + " Only needed when running EvoMaster inside Docker.") + var dockerLocalhost = false + + @FilePath @Cfg("When generating tests in JavaScript, there is the need to know where the driver is located in respect to" + " the generated tests") diff --git a/core/src/main/kotlin/org/evomaster/core/Main.kt b/core/src/main/kotlin/org/evomaster/core/Main.kt index dc46f847eb..d3ee8cdb54 100644 --- a/core/src/main/kotlin/org/evomaster/core/Main.kt +++ b/core/src/main/kotlin/org/evomaster/core/Main.kt @@ -87,14 +87,25 @@ class Main { val config = EMConfig().apply { updateProperties(options) } if(config.runningInDocker){ - LoggingUtil.getInfoLogger().info("You are running EvoMaster inside Docker." + - " To access the generated test suite under '/generated_tests', you will need to mount a folder" + - " or volume." + - " Also references to host machine on 'localhost' would need to be replaced with" + - " 'host.docker.internal'." + - " If this is the first time you run EvoMaster in Docker, you are strongly recommended to first" + - " check the documentation at:" + - " ${inBlue("https://github.com/WebFuzzing/EvoMaster/blob/master/docs/docker.md")}") + if(config.blackBox) { + LoggingUtil.getInfoLogger().info( + inGreen("You are running EvoMaster inside Docker." + + " To access the generated test suite under '/generated_tests', you will need to mount a folder" + + " or volume." + + " Also references to host machine on 'localhost' would need to be replaced with" + + " 'host.docker.internal'." + + " If this is the first time you run EvoMaster in Docker, you are strongly recommended to first" + + " check the documentation at:") + + " ${inBlue("https://github.com/WebFuzzing/EvoMaster/blob/master/docs/docker.md")}" + ) + } else { + LoggingUtil.getInfoLogger().warn( + inYellow( + "White-box testing (default in EvoMaster) is currently not supported / not recommended in Docker." + + " To run EvoMaster in black-box mode, you can use --blackBox true." + ) + ) + } } initAndRun(args) diff --git a/docs/config_file.md b/docs/config_file.md new file mode 100644 index 0000000000..3c6caa82c5 --- /dev/null +++ b/docs/config_file.md @@ -0,0 +1,3 @@ +## Config + +Documentation under construction \ No newline at end of file diff --git a/docs/docker.md b/docs/docker.md index b7ac66f75d..db31256883 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -6,7 +6,13 @@ It can be run with: > docker run webfuzzing/evomaster \ -Where `` would be the [command-line options](options.md). +Where `` would be the [command-line options](options.md), +like for example `--blackBox true` + +> __IMPORTANT__ +> +> For __white-box__ testing, running from Docker is currently not supported. As such, it is discouraged. +> You can try it, but likely you will get major issues with hostname and ephemeral port resolutions, as well as issues with external dependency mocks. ## Accessing the generated test files @@ -19,6 +25,10 @@ An example is mounting the local `./generated_tests`, using for example: There can be other ways to access the `/generated_tests` folder inside the Docker image (e.g., using volumes), but, for that, you will need to check the Docker documentation. +WARNING: note the `/` before `$(pwd)`. This is needed only if running in a MSYS shell on Windows like _Git Bash_, as it automatically converts paths on the command line. +Unfortunately, this will also mess up any input parameter to EvoMaster that is recognized as a path (e.g., if starting with a `/`). +You can [read more here](https://stackoverflow.com/questions/52944738/how-to-force-git-for-windows-bash-shell-to-not-convert-path-string-to-windows-p). + ## Issues with "localhost" An important fact to keep in mind is that references to `localhost` will point to the Docker virtual network, and not your host machine. @@ -35,6 +45,7 @@ would need to be replaced with Note that here the port `8080` and the the path `/v3/api-docs` are just examples. + + + + + + ## Handling "em.yaml" configuration file -TODO +If you want to use a configuration file (e.g., `em.yaml`) to specify command-line options, this needs to be mounted into Docker. +For example by using: + +> -v "$(pwd)/em.yaml":/em.yaml + +By default, _EvoMaster_ in Docker searches for a configuration file under `/em.yaml`. +You can mount your configuration file (based on its absolute path) into that. + +> WARNING: in _Git Bash_, you will need a `/` before `$(pwd)`, i.e., Linux-like paths should start with a `//` and not a `/` (as otherwise get converted, and you might end up seeing weird things like prepended paths such as `C:/Program Files/Git`). Also, options like +`--configPath` will not work there. + + +By default, if there is no `em.yaml` file, _EvoMaster_ will create one in the current working directory, with comments on how it should be configured. +However, if you run through Docker, you will not be able to directly access such file, unless you mount the whole `/` root folder (which is not recommended). +But you can still create it manually. +[See documentation](config_file.md). \ No newline at end of file diff --git a/docs/options.md b/docs/options.md index be672f5bdc..e9f777daf6 100644 --- a/docs/options.md +++ b/docs/options.md @@ -53,7 +53,6 @@ There are 3 types of options: |`endpointTagFilter`| __String__. Comma-separated list of OpenAPI/Swagger 'tags' definitions. Only the REST endpoints having at least one of such tags will be fuzzed. If no tag is specified here, then such filter is not applied. *Default value*: `null`.| |`sutControllerHost`| __String__. Host name or IP address of where the SUT EvoMaster Controller Driver is listening on. This option is only needed for white-box testing. *Default value*: `localhost`.| |`sutControllerPort`| __Int__. TCP port of where the SUT EvoMaster Controller Driver is listening on. This option is only needed for white-box testing. *Constraints*: `min=0.0, max=65535.0`. *Default value*: `40100`.| -|`dockerLocalhost`| __Boolean__. Replace references to 'localhost' to point to the actual host machine. Only needed when running EvoMaster inside Docker. *Default value*: `false`.| |`overrideOpenAPIUrl`| __String__. If specified, override the OpenAPI URL location given by the EvoMaster Driver. This option is only needed for white-box testing. *Constraints*: `URL`. *Default value*: `""`.| ## Internal Command-Line Options @@ -228,6 +227,7 @@ There are 3 types of options: |`appendToTargetHeuristicsFile`| __Boolean__. Whether should add to an existing target heuristics file, instead of replacing it. It is only used when processFormat is TARGET_HEURISTIC. *Default value*: `false`.| |`bbProbabilityUseDataPool`| __Double__. Specify the probability of using the data pool when sampling test cases. This is for black-box (bb) mode. *Constraints*: `probability 0.0-1.0`. *Default value*: `0.8`.| |`discoveredInfoRewardedInFitness`| __Boolean__. If there is new discovered information from a test execution, reward it in the fitness function. *Default value*: `false`.| +|`dockerLocalhost`| __Boolean__. Replace references to 'localhost' to point to the actual host machine. Only needed when running EvoMaster inside Docker. *Default value*: `false`.| |`dpcTargetTestSize`| __Int__. Specify a max size of a test to be targeted when either DPC_INCREASING or DPC_DECREASING is enabled. *Default value*: `1`.| |`employResourceSizeHandlingStrategy`| __Enum__. Specify a strategy to determinate a number of resources to be manipulated throughout the search. *Valid values*: `NONE, RANDOM, DPC`. *Default value*: `NONE`.| |`enableAdaptiveResourceStructureMutation`| __Boolean__. Specify whether to decide the resource-based structure mutator and resource to be mutated adaptively based on impacts during focused search.Note that it only works when resource-based solution is enabled for solving REST problem. *Default value*: `false`.|