Skip to content

Commit ba649fd

Browse files
marina-pmarina-p
committed
Restler v6.1 - initial commit
1 parent c621c43 commit ba649fd

File tree

273 files changed

+74476
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

273 files changed

+74476
-0
lines changed

‎.gitignore

+10
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,13 @@
1+
## Ignore Python development temporary files
2+
3+
venv/
4+
env/
5+
*.pyc
6+
mprofile_*
7+
8+
## Ignore VS Code settings
9+
.vscode/settings.json
10+
111
## Ignore Visual Studio temporary files, build results, and
212
## files generated by popular Visual Studio add-ons.
313
##

‎.vscode/launch.json

+204
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
{
2+
// Use IntelliSense to learn about possible attributes.
3+
// Hover to view descriptions of existing attributes.
4+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"name": "Python: Current File",
9+
"type": "python",
10+
"request": "launch",
11+
"program": "${file}"
12+
},
13+
{
14+
"name": "Python: Payload body checker",
15+
"type": "python",
16+
"request": "launch",
17+
"program": "${workspaceFolder}\\restler\\restler.py",
18+
"args" :[
19+
"--fuzzing_mode",
20+
"directed-smoke-test",
21+
"--restler_grammar",
22+
"c:\\restler\\restlerpayloadbody\\compile\\grammar.py",
23+
"--custom_mutations",
24+
"c:\\restler\\restlerpayloadbody\\compile\\dict.json",
25+
"--settings",
26+
"c:\\restler\\restlerpayloadbody\\settings_custom.json",
27+
"--enable_checkers",
28+
"payloadbody",
29+
"--garbage_collection_interval",
30+
"30"
31+
]
32+
},
33+
{
34+
"name": "Python: examples checker",
35+
"type": "python",
36+
"request": "launch",
37+
"program": "${workspaceFolder}\\restler\\restler.py",
38+
"args" :[
39+
"--fuzzing_mode",
40+
"directed-smoke-test",
41+
"--restler_grammar",
42+
"c:\\restler\\restlerexampleschecker\\compile\\grammar.py",
43+
"--custom_mutations",
44+
"c:\\restler\\restlerexampleschecker\\compile\\dict.json",
45+
"--settings",
46+
"c:\\restler\\restlerexampleschecker\\settings.json",
47+
"--enable_checkers",
48+
"examples",
49+
"--no_tokens_in_logs",
50+
"t",
51+
"--garbage_collection_interval",
52+
"30"
53+
]
54+
},
55+
{
56+
"name": "Python: unit test",
57+
"type": "python",
58+
"request": "launch",
59+
"program": "${workspaceFolder}\\restler\\restler.py",
60+
"args" :[
61+
"--fuzzing_mode",
62+
"directed-smoke-test",
63+
"--restler_grammar",
64+
"restler\\unit_tests\\log_baseline_test_files\\test_grammar.py",
65+
"--custom_mutations",
66+
"restler\\unit_tests\\log_baseline_test_files\\test_dict.json",
67+
"--settings",
68+
"c:\\restler\\restlertest\\test_settings.json",
69+
"--use_test_socket",
70+
"--garbage_collection_interval", "30",
71+
"--target_ip", "1", "--target_port", "1"
72+
]
73+
},
74+
{
75+
"name": "Python: restler.py -h",
76+
"type": "python",
77+
"request": "launch",
78+
"program": "${workspaceFolder}\\restler\\restler.py",
79+
"args" :[
80+
"-h"
81+
],
82+
"stopOnEntry": true,
83+
"console": "externalTerminal",
84+
"cwd": "c:\\temp\\restler"
85+
},
86+
{
87+
"name": "Python: restler.py",
88+
"type": "python",
89+
"request": "launch",
90+
"program": "${workspaceFolder}\\restler\\restler.py",
91+
"args" :[
92+
"--swagger_specification",
93+
"c:\\temp\\restler\\demo_server.json",
94+
"--inspect_grammar",
95+
"sdf"
96+
],
97+
"stopOnEntry": true,
98+
"console": "externalTerminal",
99+
"cwd": "c:\\temp\\restler"
100+
},
101+
{
102+
"name": "Python: Attach",
103+
"type": "python",
104+
"request": "attach",
105+
"localRoot": "${workspaceFolder}",
106+
"remoteRoot": "${workspaceFolder}",
107+
"port": 3000,
108+
"secret": "my_secret",
109+
"host": "localhost"
110+
},
111+
{
112+
"name": "Python: Terminal (integrated)",
113+
"type": "python",
114+
"request": "launch",
115+
"program": "${file}",
116+
"console": "integratedTerminal"
117+
},
118+
{
119+
"name": "Python: Terminal (external)",
120+
"type": "python",
121+
"request": "launch",
122+
"program": "${file}",
123+
"console": "externalTerminal"
124+
},
125+
{
126+
"name": "Python: Django",
127+
"type": "python",
128+
"request": "launch",
129+
"program": "${workspaceFolder}/manage.py",
130+
"args": [
131+
"runserver",
132+
"--noreload",
133+
"--nothreading"
134+
],
135+
"debugOptions": [
136+
"RedirectOutput",
137+
"Django"
138+
]
139+
},
140+
{
141+
"name": "Python: Flask (0.11.x or later)",
142+
"type": "python",
143+
"request": "launch",
144+
"module": "flask",
145+
"env": {
146+
"FLASK_APP": "${workspaceFolder}/app.py"
147+
},
148+
"args": [
149+
"run",
150+
"--no-debugger",
151+
"--no-reload"
152+
]
153+
},
154+
{
155+
"name": "Python: Module",
156+
"type": "python",
157+
"request": "launch",
158+
"module": "module.name"
159+
},
160+
{
161+
"name": "Python: Pyramid",
162+
"type": "python",
163+
"request": "launch",
164+
"args": [
165+
"${workspaceFolder}/development.ini"
166+
],
167+
"debugOptions": [
168+
"RedirectOutput",
169+
"Pyramid"
170+
]
171+
},
172+
{
173+
"name": "Python: Watson",
174+
"type": "python",
175+
"request": "launch",
176+
"program": "${workspaceFolder}/console.py",
177+
"args": [
178+
"dev",
179+
"runserver",
180+
"--noreload=True"
181+
]
182+
},
183+
{
184+
"name": "Python: All debug Options",
185+
"type": "python",
186+
"request": "launch",
187+
"pythonPath": "${command:python.interpreterPath}",
188+
"program": "${file}",
189+
"module": "module.name",
190+
"env": {
191+
"VAR1": "1",
192+
"VAR2": "2"
193+
},
194+
"envFile": "${workspaceFolder}/.env",
195+
"args": [
196+
"arg1",
197+
"arg2"
198+
],
199+
"debugOptions": [
200+
"RedirectOutput"
201+
]
202+
}
203+
]
204+
}

‎CODE_OF_CONDUCT.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Microsoft Open Source Code of Conduct
2+
3+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
4+
5+
Resources:
6+
7+
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
8+
- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
9+
- Contact [[email protected]](mailto:[email protected]) with questions or concerns

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) Microsoft Corporation.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE

‎README.md

+126
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# RESTler
2+
3+
## What is RESTler?
4+
5+
RESTler is the *first stateful REST API fuzzing tool* for automatically testing cloud services through their REST APIs and finding security and reliability bugs in these services. For a given cloud service with an OpenAPI/Swagger specification, RESTler analyzes its entire specification, and then generates and executes tests that exercise the service through its REST API.
6+
7+
RESTler intelligently infers producer-consumer dependencies among request types from the Swagger specification; and during testing, it checks for specific bugs and dynamically learns from prior service responses how the service behaves. This intelligence allows RESTler to explore deeper service states reachable only through specific request sequences and to find more bugs.
8+
9+
RESTler is described in these peer-reviewed research papers:
10+
11+
1. [RESTler: Stateful REST API Fuzzing](https://patricegodefroid.github.io/public_psfiles/icse2019.pdf) (ICSE'2019)
12+
2. [Checking Security Properties of Cloud Service REST APIs](https://patricegodefroid.github.io/public_psfiles/icst2020.pdf) (ICST'2020)
13+
3. [Differential Regression Testing for REST APIs​](https://patricegodefroid.github.io/public_psfiles/issta2020.pdf) (ISSTA'2020)
14+
4. [Intelligent REST API Data Fuzzing​​](https://patricegodefroid.github.io/public_psfiles/fse2020.pdf) (FSE'2020)
15+
16+
RESTler was created at Microsoft Research and is still under active development.
17+
18+
![RESTler architecture](./docs/user-guide/RESTler-arch.png)
19+
20+
21+
## Setting up RESTler
22+
23+
RESTler was designed to run on 64-bit machines.
24+
25+
### **Build instructions**
26+
27+
#### Prerequisites
28+
29+
- Windows: [.NET core SDK 3.1](https://dotnet.microsoft.com/download/dotnet-core?utm_source=getdotnetcorecli&utm_medium=referral) or higher, Powershell 5.1 or higher
30+
- Linux: [.NET core SDK 3.1](https://dotnet.microsoft.com/download/dotnet-core?utm_source=getdotnetcorecli&utm_medium=referral) or higher, [PowerShell 7 Core](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-linux?view=powershell-7)
31+
32+
Create a directory where you'd like to place the RESTler binaries:
33+
34+
```mkdir restler_bin```
35+
36+
Switch to the repo root directory and run the following PowerShell script:
37+
38+
```./build_restler.ps1 -destDir <full path to RESTler bin above>```
39+
40+
### **Binary-drop instructions**
41+
42+
RESTler binary drops are coming soon.
43+
44+
#### Prerequisites
45+
46+
* Windows: [.NET core SDK 3.1](https://dotnet.microsoft.com/download/dotnet-core?utm_source=getdotnetcorecli&utm_medium=referral) or higher, [Python 3.8.2](https://www.python.org/downloads/windows/) or higher.
47+
* Linux: [.NET core SDK 3.1](https://dotnet.microsoft.com/download/dotnet-core?utm_source=getdotnetcorecli&utm_medium=referral) or higher, Python 3.8.2 or higher.
48+
49+
50+
## Using RESTler
51+
52+
RESTler runs in 4 main modes (in order):
53+
54+
1. **Compile:** from a Swagger JSON specification (and optionally examples), generate a RESTler grammar. See [Compiling](./docs/user-guide/Compiling.md).
55+
2. **Test:** execute quickly all of the endpoints+methods in a compiled RESTler grammar for debugging the test setup and compute what parts of the Swagger spec are covered. This mode is also called a *smoketest*.
56+
See [Testing](./docs/user-guide/Testing.md). To use custom test engine settings, see [Test Engine Settings](./docs/user-guide/SettingsFile.md).
57+
3. **Fuzz-lean:** execute once every endpoint+method in a compiled RESTler grammar with a default set of checkers to see if bugs can be found quickly. See [Fuzzing](./docs/user-guide/Fuzzing.md).
58+
4. **Fuzz:** bug hunting - explore a RESTler fuzzing grammar in smart breadth-first-search mode (deeper search mode) for finding more bugs.
59+
**Warning:** This type of fuzzing is more aggressive and may create outages in the service under test if the service is poorly implemented (e.g., fuzzing might create resource leaks, perf degradation, backend corruptions, etc.).
60+
See [Fuzzing](./docs/user-guide/Fuzzing.md).
61+
62+
## Quick Start
63+
64+
For a quick intro with simple examples, see this [Tutorial](./docs/user-guide/TutorialDemoServer.md).
65+
66+
To quickly try RESTler on your API, see [Quick Start](./docs/user-guide/QuickStart.md).
67+
68+
## Bugs found by RESTler
69+
There are currently two categories of bugs found by RESTler.
70+
71+
- **Error code**: currently, any time a response with status code ```500``` ("Internal Server Error") is received, a bug is reported.
72+
- **Checkers**: each checker tries to trigger specific bugs by executing targeted additional requests or sequences of requests at certain points during fuzzing, determined by context. Some checkers try to find additional 500s, while other checkers try to find specific logic bugs such as resource leaks or hierarchy violations. For a full description of checkers, see [Checkers](./docs/user-guide/Checkers.md).
73+
74+
When a bug is found, RESTler reports bugs triaged in bug buckets, and provides a replay log that can be used to reproduce the bug (see [Replay](./docs/user-guide/Replay.md)).
75+
76+
77+
## Best Practices​ (Advanced Topics)
78+
79+
For tips on using RESTler effectively, please see [Best Practices](./docs/user-guide/BestPractices.md) and [Improving Swagger Coverage](./docs/user-guide/ImprovingCoverage.md).
80+
81+
See also these [Frequently Asked Questions](./docs/user-guide/FAQ.md).
82+
83+
84+
## Contributing
85+
86+
This project welcomes contributions and suggestions. Most contributions require you to
87+
agree to a Contributor License Agreement (CLA) declaring that you have the right to,
88+
and actually do, grant us the rights to use your contribution. For details, visit
89+
https://cla.microsoft.com.
90+
91+
When you submit a pull request, a CLA-bot will automatically determine whether you need
92+
to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
93+
instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
94+
95+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
96+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
97+
or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
98+
99+
For more information, see [Contributing.md](./docs/contributor-guide/Contributing.md).
100+
101+
## Trademarks
102+
103+
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
104+
105+
## Data collection
106+
107+
The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.
108+
109+
For more information, see [Telemetry.md](./docs/user-guide/Telemetry.md).
110+
111+
## Reporting Security Issues
112+
113+
Security issues and bugs should be reported privately, via email, to the
114+
Microsoft Security Response Center (MSRC) at
115+
[[email protected]](mailto:[email protected]). You should receive a
116+
response within 24 hours. If for some reason you do not, please follow up via
117+
email to ensure we received your original message. Further information,
118+
including the [MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155)
119+
key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/default).
120+
121+
For additional details, see [Security.md](Security.md).
122+
123+
124+
# Privacy & Cookies
125+
126+
https://go.microsoft.com/fwlink/?LinkId=521839

0 commit comments

Comments
 (0)