swurg
[!UPDATE] This extension has been updated to use the latest Burp Montoya Java API. The extension has undergone a complete overhaul to improve both its
UI
/UX
and performance. These changes ensure that the extension is modern and optimised for use.
Burp Suite
extension designed for OpenAPI
-based API
testing
Swurg is a The
OpenAPI
Specification (OAS
) defines a standard, programming language-agnostic interface description forREST
APIs
, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined viaOpenAPI
, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, theOpenAPI
Specification removes guesswork in calling a service.Use cases for machine-readable
API
definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases.OpenAPI
documents describe anAPI
's services and are represented in eitherYAML
orJSON
formats. These documents may either be produced and served statically or be generated dynamically from an application.
Performing security assessment of OpenAPI
-based APIs
can be a tedious task due to Burp Suite
(industry standard) lacking native OpenAPI
parsing capabilities. A solution to this situation, is to use third-party tools (e.g. SOAP-UI
) or to implement custom scripts (often on a per engagement basis) to handle the parsing of OpenAPI
documents and integrate/chain the results to Burp Suite
to use its first class scanning capabilities.
Swurg is an OpenAPI
parser that aims to streamline this entire process by allowing security professionals to use Burp Suite
as a standalone tool for security assessment of OpenAPI
-based APIs
.
Features
OpenAPI
documents can be parsed either from a supplied file or URL. The extension can fetchOpenAPI
documents directly from a URL using theSend to Swagger Parser
feature under theTarget -> Site map
context menu.- Parse
OpenAPI
documents, formerly known as theSwagger specification
, fully compliant withOpenAPI
2.0/3.0 Specifications (OAS
). - Requests can be directly viewed/edited within the extension prior to sending them to other Burp tools.
- Requests can be sent to the
Comparer, Intruder, Repeater, Scanner, Site map and Scope
Burp tools. - Requests matching specific criterias (detailed in the 'Parameters' tab) can be intercepted to automatically match and replace the parsed parameters default values defined in the 'Parameters' tab. This feature allows for fine-tuning of the requests prior to sending them to other Burp tools (e.g., scanner). Edited requests can be viewed within the 'Modified Request (
OpenAPI
Parser)' tab of Burp's message editor. - Row highlighting allowing pentesters to highlight "interesting"
API
calls and/or colour code them for reporting purposes. - Includes an export to
CSV
feature, allowing users to easily export selectedAPI
requests inCSV
format for further analysis or reporting. - Supports both
JSON
andYAML
formats.
Requirements
- System requirements:
-
Operating System: Compatible with
Linux
,macOS
, andWindows
operating systems. -
Java Development Kit (JDK):
Version 11
or later. -
Burp Suite Professional or Community Edition:
Version 2023.3.2
or later.[!IMPORTANT] Please note that using any version lower than
2023.3.2
may result in a java.lang.NoSuchMethodError. It is crucial to use the specified version or a more recent one to avoid this issue.
- Build tool:
- Gradle:
Version 6.9
or later (recommended). The build.gradle file is provided in the project repository.
- Environment variables:
- Set up the
JAVA_HOME
environment variable to point to the JDK installation directory.
Please ensure that all system requirements, including a compatible version of Burp Suite
, are met before building and running the project. Note that the project's external dependencies will be automatically managed and installed by Gradle
during the build process. Adhering to the requirements will help avoid potential issues and reduce the need for opening new issues in the project repository.
Installation
1. Compilation
-
Ensure you have Gradle installed and configured.
-
Download the
swurg
repository:git clone https://github.com/aress31/swurg cd .\swurg\
-
Build the standalone
jar
:./gradlew fatJar
Burp Suite
2. Loading the Extension Into To install swurg
in Burp Suite
, first go to the Extensions
tab and click on the Add
button. Then, select the swurg-all
jar file located in the .\build\libs
folder to load the extension.
Alternatively, you can skip the Compilation step entirely and download the extension directly from the BApp Store.
Note: The version distributed on the BApp Store might be lagging behind the version available on this repository.
Roadmap
- Beautify the graphical user interface.
- Deep parsing of
OpenAPI
schemas to collect all nested parameters along with their example/type. - Code simplification/refactoring.
- Use
MyHttpRequest
instead ofRequestWithMetadata
.
- Use
- Enable cells editing to change
API
calls directly from theGUI
. - Fix the custom request editor tab to work properly with intercepted requests based on the match and replace rulesets.
- Further optimise the source code.
- Implement support for authenticated testing (via user-supplied
API
-keys). - Improve the
Param
column by adding parameters type (e.g.inquery
,inbody
). - Improve the tables and context menus.
- Increase the extension verbosity (via the bottom panel).
Project Information
In July 2016, after posting a request for improvement on the PortSwigger support forum, I decided to take the initiative and to implement a solution myself.
The extension is still in development, feedback, comments and contributions are therefore much appreciated.
π
Sponsor If this extension has saved you time and hassle during a security assessment, consider showing some love by sponsoring a cup of coffee Sponsor
button at the top of the page or click here to contribute and keep the caffeine flowing.
Reporting Issues
Did you find a bug? Well, don't just let it crawl around! Let's squash it together like a couple of bug whisperers!
Please report any issues on the GitHub issues tracker. Together, we'll make this extension as reliable as a cockroach surviving a nuclear apocalypse!
Contributing
Looking to make a splash with your mad coding skills?
Awesome! Contributions are welcome and greatly appreciated. Please submit all PRs on the GitHub pull requests tracker. Together we can make this extension even more amazing!
License
See LICENSE.