diff --git a/cli/Readme.md b/cli/Readme.md index a0fc562..2cf98bf 100644 --- a/cli/Readme.md +++ b/cli/Readme.md @@ -1,18 +1,6 @@ # RAFT CLI -`raft.py` is Rest API Fuzz Testing service CLI that is used for deployment of the service to Azure, job creation, deletion, etc. See full documentation [RAFT CLI reference](../docs/cli-reference.md) +`raft.py` is Rest API Fuzz Testing service CLI that is used for deployment of the +service to Azure, job creation, deletion, etc. See full documentation [RAFT CLI reference](../docs/cli-reference.md) -`raft_local.py` is a script that does not require Azure to run RAFT job configurations. This script requires installation of Python and Docker to run RAFT job configurations. - -This script only support **job create** command. See `raft_local.py --help` for details. -`raft_local.py` expects the following folder structure (You can run `raft_local.py local init` to auto-create required directories) - -```Text -CLI //root folder where you downloaded the CLI -|- raft_local.py // raft_local.py script -|- local // folder named local located at the same level as raft_local.py - |- secrets // folder named secrets located inside of local folder - |- storage // folder names storage located inside of local folder -``` - -`storage` folder will contain all of the data produced by RAFT job runs. -`secrets` folder is a user maintained folder. It uses files without an extension to store data needed for authentication with services under test. For example if my RAFT job configuration requires a text token. I can store the token in file `MyToken` under `CLI/local/secrets/MyToken` and use `MyToken` string name in RAFT job configuration as `TxtToken` authentication method. +`raft_local.py` is a script that does not require Azure to run RAFT job configurations. +See documentation on how to use [RAFT on your development machine](../docs/how-to-use-raft-local.md) \ No newline at end of file diff --git a/cli/raft_local.py b/cli/raft_local.py index fba4aa1..9b481c6 100644 --- a/cli/raft_local.py +++ b/cli/raft_local.py @@ -75,6 +75,9 @@ def init_tools(tools_path): return tools, tool_paths def init_local(work_directory): + if not os.path.exists(work_directory): + os.mkdir(work_directory) + secrets_path = os.path.join(work_directory, 'secrets') if not os.path.exists(secrets_path): os.mkdir(secrets_path) @@ -574,9 +577,10 @@ def run(args): work_dir = os.path.join(script_dir, 'local') if local_action == 'init': - storage, secrets = init_local(work_dir) + storage, secrets, event_sink = init_local(work_dir) print(f'Created results storage folder: {storage}') print(f'Created secrets folder: {secrets}') + print(f'Created events_sink folder: {event_sink}') if job_action == 'create': cli = RaftLocalCLI(work_dir) diff --git a/docs/how-to-use-raft-local.md b/docs/how-to-use-raft-local.md new file mode 100644 index 0000000..82e1b5b --- /dev/null +++ b/docs/how-to-use-raft-local.md @@ -0,0 +1,95 @@ +# How to run RAFT on your local machine + +There are times where you might want to test your service on your development machine before +committing the changes to run in a CI/CD pipeline with your Azure deployment of RAFT. The +`raft_local.py` script is your way to do that. + +Because RAFT uses containers for the testing tools, this script will pull down the tools needed +and run them using docker on your local machine. + +### Requirements + +This script has been tested with these versions of these tools. +* Python (3.8) +* Docker (20.10) + +### Limitations + +This script only supports the **job create** command. See `raft_local.py --help` for details. + +### Getting Started + +Run `raft_local.py local init` to auto-create required directories. + +These are the directories that will be created and are expected by the script. +```Text +CLI //root folder where you downloaded the CLI +|- raft_local.py // raft_local.py script +|- local // folder named local located at the same level as raft_local.py + |- secrets // folder named secrets located inside of local folder + |- storage // folder names storage located inside of local folder + |- events_sink // folder used to synchronize test tool events +``` + + +* The `storage` folder will contain all of the data produced by RAFT job runs. +* The `secrets` folder is a user maintained folder.
+ The files in this folder are the names of the secret used in the job definition file. + These files should not have an extension. + + For example if my RAFT job configuration requires a text token. + I can store the token in file `MyToken` under `CLI/local/secrets/MyToken` and use `MyToken` + as the secret name in RAFT job configuration. + + ``` + "authenticationMethod": { + "TxtToken": "MyToken" + } + ``` + +### Running raft_local.py + +Once you have completed the getting started portion you can use `raft_local.py` to +run a job on your local machine. + +Here is an example job definition that runs RESTler and ZAP on a +deployed instance of [PetStore](https://petstore3.swagger.io) that can be launched with +`raft_local.py` + + +```text +{ + "testTasks": { + "targetConfiguration": { + "apiSpecifications": [ "https://petstore3.swagger.io/api/v3/openapi.json" ], + "endpoint": "https://petstore3.swagger.io" + }, + "tasks": [ + { + "toolName": "RESTler", + "outputFolder": "restler-logs", + "toolConfiguration": { + "tasks": [ + { + "task": "compile" + }, + { + "task": "Fuzz", + "runConfiguration": { + "Duration": "00:10:00" + } + } + ] + } + }, + { + "toolName": "ZAP", + "outputFolder": "zap-logs" + } + ] + } +} +``` + +Example command line to create a local job:
+`python raft_local.py job create --file ` \ No newline at end of file diff --git a/docs/samples.md b/docs/samples.md index fbf7589..470ce46 100644 --- a/docs/samples.md +++ b/docs/samples.md @@ -10,4 +10,13 @@ you might want to [onboard](how-to-onboard-a-tool.md). The samples are located in the **cli/samples** folder under the root of the RAFT repo, and are organized into three folders: **Zap**, **RESTler**, **Dredd**, and **multiple-tools**, the latter of which shows how to execute more than -one tool in a single job. Each sample folder includes it's own `readme.md` file explaining what the sample is about and how to run it. \ No newline at end of file +one tool in a single job. Each sample folder includes it's own `readme.md` file explaining what the sample is about and how to run it. + +**IMPORTANT NOTE:**
+The sample python scripts have been written to take advantage of your Azure deployment of RAFT. +In most sample directories there is a python script that runs the sample and is an example of how to use +our python SDK to run jobs. In many of the sample job definition files there are substitutions that are +made via the python script. + +Because of this, the files typically will not run without modification with the `raft_local.py` script. +See [here](how-to-use-raft-local.md) for more information about running RAFT on your desktop with `raft_local.py`. \ No newline at end of file diff --git a/docs/index.md b/docs/start-here.md similarity index 100% rename from docs/index.md rename to docs/start-here.md