diff --git a/pages/docs/fuzzing.md b/pages/docs/fuzzing.md deleted file mode 100644 index c2790638e52ce3198c6631c68a7ff5667c3edc53..0000000000000000000000000000000000000000 --- a/pages/docs/fuzzing.md +++ /dev/null @@ -1 +0,0 @@ -fuzzing \ No newline at end of file diff --git a/pages/docs/img/openapi.png b/pages/docs/img/openapi.png new file mode 100644 index 0000000000000000000000000000000000000000..09b4c8b663c4cdfbfa69f44a925c00440bea5a6c Binary files /dev/null and b/pages/docs/img/openapi.png differ diff --git a/pages/docs/img/parser.png b/pages/docs/img/parser.png new file mode 100644 index 0000000000000000000000000000000000000000..cff5320e87916874d091d910eba70c103b53c642 Binary files /dev/null and b/pages/docs/img/parser.png differ diff --git a/pages/docs/index.md b/pages/docs/index.md index d88920142b367f075a67cd3751718ef8fae29746..4730a1d92d1b00d262cb356f39b93e03d47fe7f5 100644 --- a/pages/docs/index.md +++ b/pages/docs/index.md @@ -1,3 +1,75 @@ -Index +# RAGO - RAG OpenAPI Framework - +## Introduction + +`RAGO` is the first REST API fuzzing tool modeled in [JastAdd](https://jastadd.cs.lth.se/). + + +First of all, This tool parses [an OpenAPI specification (OAS)](https://swagger.io/specification/) in Java classes and transfers it into `AST-Node`. These Nodes are able to be re-transformed and saved in JSON which describes its API Specification, if needed. + + + + +After the parsing phase, `RAGO` is prepared to generate tests automatically in two different ways based on Fuzzing, [Random Testing](#ragoRandTest) and [Parameter Inference](#ragoParamInf). + +## OpenAPI Specification in JastAdd + +[OpenAPI specification (OAS)](https://swagger.io/specification/) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers and is represented in JSON or YAML. It consists of 30 objects and is structured in a tree-shape. + + +To understand better how OpenAPI documentations could be transformed in JastAdd, compare the following Object in the JastAdd-grammar and [OpenAPI Object description](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oasObject) +``` +OpenAPIObject ::= <OpenAPI> <JsonSchemaDialect> I:InfoObject Serv:ServerObject* + P:PathsObject* W:Webhook* C:ComponentsObject Sr:SecurityRequirementObject* + T:TagObject* [E:ExternalDocObject] Ex:Extension*; +``` + + + +There are some implementation details developers must consider: + +- JastAdd doesn't support `Map`. So, it must be constructed in a tuple (AST-Node). e.g. + - `ServerVariablesTuple ::= <Name> S:ServerVariableObject;` + - `variables` in [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#serverObject) + +- In OAS, several objects can be replaced by [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject). In `RAGO`, we implemented this structure in an abstract node to every concerned object. e.g. + - [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject) + - following abstract node in JastAdd + + +Example of [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject) implementation +``` + abstract ParameterOb; + ParameterReference : ParameterOb ::= <Ref> ...; + ParameterObject : ParameterOb ::= <Name> <In> ...; +``` + + +- Most objects can be extended with `Extension` containing unfixed name and values. In JastAdd, this is also implemented in a tuple (AST-Node) `Extension ::= <Key> <Value:Object>;` + +## Fuzzing in RAGO + +To generate API tests automatically, `RAGO` supports two following techniques based on Fuzzing which involves providing invalid, unexpected, or random data as inputs to an API. + +In this first version, this tool considers only two request types, `GET` and `POST`, and parameters. It means that `RAGO` currently generates only URLs. + +### <a name="ragoRandTest"></a>Random Testing + +Random testing is based on the simple randomizer, `RandomRequestGenerator`. This generator reads an `OpenAPIObject` mapped by an OpenAPI documentation and checks all parameter types of operations existing in the `OpenAPIObject`. + + +Afterwards, `RandomRequestGenerator` knows which request needs which parameter type and generates random parameters for all requests and URLs appending these parameters. + + +### <a name="ragoParamInf"></a>Parameter Inference + +Most tests based on the simple randomizing techniques are not effective because of low coverages and unusual validations. To observe more concrete test results, `InferParameter` generates tests automatically using random test results of `RandomRequestGenerator`. + + +Test results (responses) generated by `RandomRequestGenerator` are saved in a dictionary and utilized to infer parameters that might be usable in other requests. + + +If there is a same schema set in a request and a response, parameters of them are inferred by following strategies: + +- Case-insensitive +- Id completion in a field name (e.g. if a property has a name "id", it gets an additional field name available in the specification) \ No newline at end of file diff --git a/pages/docs/uml.md b/pages/docs/uml.md new file mode 100644 index 0000000000000000000000000000000000000000..6067b97c507d46ea628dd347f35331a6df983cc7 --- /dev/null +++ b/pages/docs/uml.md @@ -0,0 +1,3 @@ +# UML Class Diagram for RAGO + + \ No newline at end of file diff --git a/pages/mkdocs.yml b/pages/mkdocs.yml index 572435caa3b703e9253452c86f6af7c286d8987a..3d476a51ff58a8d20f50075e36237189ff78e821 100644 --- a/pages/mkdocs.yml +++ b/pages/mkdocs.yml @@ -4,7 +4,7 @@ site_dir: ../public nav: - "Overview": index.md - - "Fuzzing Example": fuzzing.md + - "UML Class Diagram for RAGO": uml.md - "API documentation": ragdoc/index.html theme: