Awesome
Manual JavaScript Linting is a Bug <!-- omit in toc -->
ESLinter
is a Burp extension that extracts JavaScript from responses and lints
them with ESLint while you do your manual testing.
Features
- Use your own artisanal hand-crafted ESLint rules.
- Extend Burp's JavaScript analysis engine.
- Pain-free setup.
- Get up and running with three commands.
- Results Are stored in two different places.
- SQLite is forever.
- It doesn't interrupt your work flow.
- Let the extension lint while you do your magic.
- It's hella configurable.
- Running Burp on a slow machine? Reduce the number of threads.
- Don't want to lint now? Click that shiny
Process
button to pause it. - Want to close Burp? No problem. Unfinished tasks will be read from the database and executed when the extension is loaded again.
- Want to only process requests from certain hosts? Add it to the scope and
set the associated key in the config file to
true
. - Don't like large JavaScript files? Set the max size in the config.
- Want to process requests from another extension? See Process Requests Made by Other Extensions.
- Filter results by host.
- Start typing in the text field in the extension tab.
Quickstart
- Install
git
,npm
andJDK 11
.- AdoptOpenJDK 11 is recommended. Make sure
JAVA_HOME
is set.
- AdoptOpenJDK 11 is recommended. Make sure
- Clone the repository.
gradlew -q clean
. Not needed for a fresh installation.gradlew -q install
- Clones the
eslint-security
git submodule. - Runs
npm install
ineslint-security
.
- Clones the
gradlew -q config -Ptarget=/relative/or/absolute/path/to/your/desired/project/location
- E.g.,
gradlew -q config -Ptarget=testproject
creates a directory namedtestproject
inside theeslinter
directory. - Creates
config.json
in therelease
directory with a sane configuration.
- E.g.,
- Add the extension jar at
release/eslint-all.jar
to Burp.- The first time a new config is loaded, you might get an error not being able to connect to the database, this is OK.
- Navigate to the
ESLinter
tab and click on theProcess
button. - Browse the target website normally with Burp as proxy.
- Observe the extracted JavaScript being linted.
- Look in the project directory to view all extracted and linted files.
- Double-click on any result to open a dialog box. Choose a path to save both the beautified JavaScript and lint results.
- For build troubleshooting please see Building the Extension below.
Double click in action
Table of Content <!-- omit in toc -->
- Features
- Quickstart
- Extension Configuration
- Triage The Results
- Technical Details
- Common Bugs
- FAQ
- Development
- Credits
- Future Work and Feedback
- License
Extension Configuration
It's recommended to use the config
Gradle task. You can also create your own
extension configs. Open the config file in any text editor and change the
values. For in-depth configuration, please see
docs/configuration.md.
Change the ESLint Rules
Option 1: If you used the config Gradle task.
- Edit the
eslint-security/eslintrc-parsia.js
file and add/remove rules.- Make a copy first if you want to use it as a guideline.
- Reload the extension.
Option 2: If you want to keep your ESLint rules in a different path.
- Create your own rules and store them at any path.
- Edit the
release/config.json
file. - Change the
eslint-config-path
to the ESLint rule path from step 1. - Reload the extension.
Change the ESLint Rule File
Edit the eslint-config-path
key in the release/config.json
file and point it
to your custom ESLint rule file.
Change the Number of Linting Threads
The number of linting threads can be configured. For slower machines, it might need to be reduced.
- Edit the extension config file.
- Change the value of
number-of-linting-threads
.
Process Requests Made by Other Extensions
- Add
extender
to theprocess-tool-list
in the config file. - Move ESLinter to the bottom of your extension list in the Extender tab.
- Reload the extension.
- ESLinter should be able to see requests created by other extensions.
Process Requests Made by Other Burp Tools
- Add the tool name to the
process-tool-list
in the config file. E.g.,Scanner
. - Move ESLinter to the bottom of your extension list in the Extender tab.
- Reload the extension.
- ESLinter should be able to see requests created by other Burp tools.
Customize ESLint Rules
Start by modifying one of the ESLint rule files in the eslint-security repository.
To disable a rule either comment it out or change the numeric value of its key
to 0
.
If you are adding a rule that needs a new plugin you have to add it manually
(usually via npm) to the location of your eslint
and js-beautify
commands.
If you want to contribute your custom ESLint rules please feel free to create pull requests in eslint-security.
For more information on configuring ESLint and writing custom rules please see:
- https://eslint.org/docs/user-guide/configuring
- https://eslint.org/docs/developer-guide/working-with-rules
Triage The Results
- Open the project directory in your editor (set in the config command).
- Open any file in the
linted
sub-directory. These files contain the results. - Alternatively, double-click any row in the extension's tab to select a directory to save both the original JavaScript and lint results for an individual request.
- The extension uses the ESLint codeframe output format. This format includes a few lines of code before and after what was flagged by ESLint. You can use these results to understand the context. This is usually not enough.
- To view the corresponding JavaScript file, open the file with the same name
(minus
-linted
) in thebeautified
sub-directory. - The json object at the top of every file contains the URL and the referer of the request that contained the JavaScript. Use this information to figure out where this JavaScript was located.
Technical Details
The innerworkings of the extension are discussed in docs/technical-details.md.
Common Bugs
Make a Github issue if you encounter a bug. Please use the Bug issue template and fill it as much as you can. Be sure to remove any identifying information from the config file.
Supported Platforms
ESLinter was developed and tested on Windows and Burp 2.1. It should work on most platforms. If it does not please make a Github issue.
The Connection to the Database Is Not Closed
You cannot delete the database if you unload the extension.
Workaround:
- Close Burp and delete the file.
My Selected Row is Gone
The table in the extension tab is updated every few seconds (controlled via the
update-table-delay
key in the config file). This means your selected row will
be unselected when the table updates. This is not an issue.
This might look odd when double-clicking a row. The FileChooser dialog pops up to select a path. When the table is updated, the selection is visually gone. This is not an issue. The data in the row is retrieved when you double-click and is not interrupted when the row is deselected after the table update.
FAQ
Why Doesn't the Extension Create Burp Issues?
- This is not a Burp pro extension. Burp Issues are supported in the pro version.
- Depending on the ESLint rules, this will create a lot of noise.
SHA-1 Is Broken
Yes, but the extension uses SHA-1 to create a hash of JavaScript text. This hash is an identifier to detect duplicates. Adversarial collisions are not important here.
Development
Building the Extension
- Install AdoptOpenJDK 11
- Run
gradlew bigjar
. - The jar file will be stored inside the
release
directory.
Development
- Fork the repository.
- Create a new branch.
- Modify the extension.
- Run
gradlew bigjar
to build it. Then test it in Burp. - Create a pull request. Please mention what has been modified.
Diagnostics
Set "diagnostics": true
in the config file to see debug messages. These
messages are useful when you are testing a single file in Burp Repeater. For
more information, please see the The Diagnostics Flag
section in
docs/configuration.md.
Debugging
See the following blog post to see how you can debug Java Burp extensions in Visual Studio Code. The instructions can be adapted to use in other IDEs/editors.
Credits
Lewis Ardern
For being a Solid 5/7 JavaScript guy.
See his presentation Manual JavaScript Analysis is a Bug.
Jacob Wilkin
The original idea for the ESLinting JavaScript received in Burp was from the following blog post by Jacob Wilkin:
Summary:
- Browse the target and perform manual testing as usual.
- Extract JavaScript from Burp.
- Clean them up a bit and remove minified standard libraries.
- Run ESLint with some security rules on the remaining JavaScript.
- Triage the results.
- ???
- Profit.
Tom Limoncelli
My main drive for automation comes from reading the amazing article named Manual Work is a Bug by Thomas Limoncelli. READ IT.
The article defines four levels of automation:
- Document the steps.
- Jacob's post above.
- Create automation equivalents.
- I created a prototype that linted JavaScript files after I extracted them from Burp manually.
- Create automation.
- This extension.
- Self-service and autonomous systems.
- Almost there in future work.
Similar Unreleased Extension by David Rook
Searching for "eslint burp" on Twitter returns a series of tweets from 2015 by David Rook. It appears that he was working on a Burp extension that used ESLint to create issues. The extension was never released.
Source Code Credit
This extension uses a few open source libraries. You can see them in the
dependencies
section of the build.gradle file.
In addition, it uses code copied from Apache Commons libraries. I copied individual files instead of the complete Apache Commons-Lang library.
- src/utils/StringUtils.java uses code from the Apache commons-lang.StringUtils.
- src/utils/SystemUtils is an almost exact copy of Apache commons-lang.SystemUtils.
Future Work and Feedback
Please see the Github issues. If you have an idea, please make a Github issue
and use the Feature request
template.
License
Opensourced under the "GNU General Public License v3.0" and later. Please see LICENSE for details.