Merge branch 'english_corrections'

README.md

@@ -1,18 +1,20 @@
 [![Build Status](https://travis-ci.com/ysoftdevs/wapifuzz.svg?branch=master)](https://travis-ci.com/ysoftdevs/wapifuzz)
 
 # WapiFuzz - fully autonomous web APIs fuzzer
-Fuzzing is popular testing technique for various error types detection. There are many fuzzing engines and fuzzers, which can help you with fuzzing itself. But there is currently no tool which can fully automate fuzzing just by providing API specification.
+Fuzzing is a popular testing technique for various error types detection. There are many fuzzing engines and fuzzers which can help people with fuzzing itself. However, there is not currently a tool that can fully automate fuzzing just by providing API specification.
 
-And that is why WapiFuzz was created. We believe that web API documentation is all that fuzzer needs to do his job. WapiFuzz can be easily deployed to almost any continuous integration (CI) service. It is based on popular [Boofuzz](https://github.com/jtpereyda/boofuzz) fuzzer and provides rich test reports to JUnit XML format.
+And that is a reason why WapiFuzz was created. We believe that web API documentation is all that fuzzer needs to do his job. WapiFuzz can be easily deployed to almost any continuous integration (CI) service. It is based on popular [Boofuzz](https://github.com/jtpereyda/boofuzz) fuzzer and provides test reports to JUnit XML format.
 
 ## What does the WapiFuzz test?
-Current version of WapiFuzz tests following parts of HTTP request to your API:
+WapiFuzz can find vulnerabilities in following parts of the HTTP request:
 - HTTP header
-- URI attributes of all documented requests
-- JSON body primitive types of all documented HTTP body examples
+- Path and query attributes
+- JSON body primitive types
 
-## What types of vulnerabilities does WapiFuzz testing?
-- Numeric strings (overflows, reserved words, ...)
+All requests are automatically generated from provided OpenAPI documentation.
+
+## What types of vulnerabilities does WapiFuzz test?
+- Numeric strings (overflows, reserved words, etc.)
 - Command injection
 - SQL injection
 - Path traversal
@@ -21,14 +23,14 @@ Current version of WapiFuzz tests following parts of HTTP request to your API:
 - XML / XPath attacks
 
 ## Requirements for your web API
-You can automatically test your web API if it meets following criteria:
+You can automatically test your web API if it meets the following criteria:
 - Documented in OpenAPI 2 or OpenAPI 3
 - Consumes and produces only `application/json` or `text/plain` content
 
-If you have your API documented in other documentation formats, you can try use some convertor.
-There are plenty convertors online. Some of theme are listed here: https://openapi.tools/.
+If you have your API documented in other documentation formats, you can try to use some converters. There are plenty of converters online and the most common ones are listed here: https://openapi.tools/.
 
-Consuming JSON data is not mandatory requirement. If your API does not consumes JSON, WapiFuzz will still tests HTTP header and URI attributes processing of your server.
+Consuming JSON data is not mandatory a requirement. If your API does not consume JSON, WapiFuzz will still test HTTP header and URI attributes processing of your server.
+The fuzzing of the HTTP body part will be limited due to unsupported content format.
 
 ## Dependencies
 - Python 3
@@ -37,25 +39,25 @@ Consuming JSON data is not mandatory requirement. If your API does not consumes
 - PowerShell or Bash
 
 ## Usage
-The only thing you need to do is create config file. You can find template in root of repository in `config_example.json` file. You can just modify this file and then pass it's path to runner script.
+The only thing you need to do is to create a WapiFuzz config file. You can find a template in the root of the repository in `config_example.json` file. You can just modify this file and then pass its path to the runner script.
 
-In config file you are able to specify following options:
-- **fixed_url_attributes** -> if you want to set some attributes to static values
-- **headers** -> headers which are sent by each request (useful for AUTH token insertion)
-- **receive_timeout** -> maximum amount of time waiting for response (in seconds)
+You are able to specify the following options in the config file:
+- **fixed_url_attributes** -> if you want to set some URL attributes to the static values
+- **headers** -> the headers which are sent by each request (useful for an AUTH token insertion)
+- **receive_timeout** -> the maximum amount of time waiting for a response (in seconds)
 - **reporting_interval** -> progress reporting interval (in seconds)
-- **http_fuzzing** -> boolean value for enabling / disabling fuzzing of HTTP protocol
-- **skipping_endpoints_keywords** [list of string keywords] -> endpoints containing any keyword in it from this list will be skipped (can be used for skipping auth/logout endpoints)
-- **startup_command** -> startup command for your tested process / service, see more details in `procmon/README.md`
-- **are_non_required_attributes_in_requests** -> boolean value, set to true, if you want attributes, that are specified as non-required, be part of URI part of request
-- **payloads_to_json_primitives_mapping** -> mapping of payloads folders to JSON primitives (see `config_example.json` for an example)
-  - **boolean** -> array of folder names with payloads which will be used for JSON boolean primitive fuzzing
-  - **number** -> array of folder names with payloads which will be used for JSON number primitive fuzzing
-  - **string** -> array of folder names with payloads which will be used for JSON string primitive fuzzing
-- **target** -> dictionary with following fields:
+- **http_fuzzing** -> enabling/disabling fuzzing of a pure HTTP protocol
+- **skipping_endpoints_keywords** [list of keywords] -> if a keyword is in some endpoint, this endpoint will be skipped (can be used for skipping auth/logout endpoints)
+- **startup_command** (only needed if you want to use process monitor) -> startup command for your tested process / service, see more details in `procmon/README.md`
+- **are_non_required_attributes_in_requests** -> set to true, if you want non-required attributes to be part of URL
+- **payloads_to_json_primitives_mapping** -> mapping of payload folders to JSON primitives
+  - **boolean** -> an array of folder names with payloads which will be used for JSON boolean fuzzing
+  - **number** -> an array of folder names with payloads which will be used for JSON number fuzzing
+  - **string** -> an array of folder names with payloads which will be used for JSON string fuzzing
+- **target** -> information about the tested application
   - **hostname** -> victim hostname or IP address
   - **port** -> victim port
-  - **ssl** -> boolean value, set to `true` if you want use SSL tcp connection, otherwise `false`
+  - **ssl** -> set to `true` for SSL TCP connections, otherwise `false`
 
 Great, WapiFuzz is now ready for fuzzing! Run it by following commands.
 ### Windows
@@ -65,32 +67,30 @@ Execute `run.ps1 -c config_file_path -openapi openapi_doc_file_path [-payloads c
 Execute `run.sh config_file_path openapi_doc_file_path [custom_payloads_file_path]` command from Bash.
 
 ### Docker
-You just need to run the container with following arguments:
+You just need to run the container with the following arguments:
 
 `docker run -p {host_port}:{container_port} -v $(pwd):/usr/local/fuzzer/mnt/ starek4/wapifuzz:latest config.json sqta.yaml [custom_payloads.txt]`
 
-where files `config.json`, `sqta.yaml` and `custom_payloads` needs to be stored in the working directory.
-With parameter `-p` you also need to bind port number, which is used for communication with your web API, to the container.
-So for example, if your API listen on the port 80, you can simply do `-p 80:80`.
+where files `config.json`, `sqta.yaml` and `custom_payloads.txt` need to be stored in the working directory.
+You also need to bind port number with the parameter `-p`, which is used for communication with your web API, to the container.
+So for example, if your API listens on the port 80, you can simply do `-p 80:80`.
 
 #### Custom payloads file
-As you can see in run script parameters, you may even specify your own payloads! Just create text file with your own testing strings (one on each line) and pass path to this file via run script parameters!
+As you can see in the run script parameters, you can specify your payloads! Just create a text file with your strings (every string should have a separate line) and pass the path to this file via the run script parameters. They will be automatically added to every fuzzed part of the request.
 
 
-## Where I can find test reports?
-After WapiFuzz finish, three main report files are generated. If you are using docker image just the way that is described above, you simply find these three files in your working directory.
-If you are running WapiFuzz by run scripts, you can find these files in the following paths:
+## Where can I find test reports?
+When WapiFuzz completes its run, three main report files are generated. If you are using a docker image equally as it is described above, you simply find these three files in your working directory. If you are running WapiFuzz by run scripts, you can find these files in the following paths:
 
 - JUnit File: `./reporter/results.junit.xml`
 - HTML report: `./reporter/reports.html`
 - Full text log: `./fuzzing.log`
 
 ### JUnit report
-The first is the JUnit file (`./reporter/results.junit.xml`), which contains full test report and contains logs for failed tests. Almost every CI system provides a way how to present JUnit test reports in some human friendly way.
+The first report file is the JUnit file (`./reporter/results.junit.xml`), which contains full test report and logs for failed tests. Almost every CI system provides a way how to present JUnit test reports in a human friendly way.
 
 ### HTML report
-WapiFuzz also generates nicely formatted HTML test report, stored at `./reporter/reports.html`.
+WapiFuzz also generates nicely formatted HTML test report stored at `./reporter/reports.html`.
 
-### Additional text logs
-WapiFuzz informs you about overall progress at standard output. If you want complete tests logs even
-for successfully finished test cases you can find it in log file (`./fuzzing.log`).
+### Full text log
+Detailed text log with all the information help you to understand what happened during the fuzzing.

procmon/README.md

@@ -1,30 +1,30 @@
 # Process monitor
-Process monitor is Python 2 script, which can monitor tested process.
-This means, it should be running on testing target.
-You can find process monitor script in this folder both for Windows and Unix systems.
+The process monitor is an optional component of the Boofuzz library.
+It is a Python 2 script, which can monitor the tested process.
+This means the script is run on the testing target system.
+You can find process monitor script in this folder for both Windows and Unix systems.
 
-Process monitor works by communication via port 26002, so all nodes between tested and testing device needs to have open this port.
+Process monitor works by communication via port 26002, therefore all nodes between tested and testing systems need to have opened this port.
 
 ## What is it good for?
-Well, process monitor is used for the following benefits:
-- Restarting tested application after failure
-- Checks before and after each test if process is still running
-- Starting tested application when it dies cause of testing payload
-- Generating dump file for each application crash
+- Restarting tested application after the vulnerability was triggered
+- Additional checks happening before and after each test to confirm the appropriate tested process is still running
+- Starting tested application when it dies
 
 ## Installation
-Windows process monitor needs some prerequisites. See installation instructions here:
+For the Windows platform, two prerequisites need to be installed before running process monitor.
+See official installation instructions here:
 https://boofuzz.readthedocs.io/en/latest/user/install.html#extras
 
-## Running of script
-Process monitor contains help with arguments description, so just enter `--help` argument and it will print a help for you.
+## Running of a script
+Process monitor contains help with arguments description, thus just type `--help` as an argument and it will print help for you.
 
 Example command:
 `python process_monitor_windows.py -p TestedApplication.exe`
 
 
-## How to tell WapiFuzz that we want to monitor process?
-If you want to use process monitor, just add starting command for your tested service / process into WapiFuzz configuration file. Example configuration key should look like this:
+## How to connect WapiFuzz with process monitor?
+If you want to connect WapiFuzz with process monitor and process monitor has been already running on a tested system, just add starting command for your tested service/process into the WapiFuzz configuration file. Example configuration key can look like this:
 `"startup_command": ["python", "C:\\server\\httpd.py"]`
 
-WapiFuzz then automatically connect with running process monitor script on tested system and will use its features.
+WapiFuzz then automatically connects with the running process monitor script on the tested system and it will use its features.