Introducing rescope - A Scope Parser for Burp Suite & OWASP ZAP

5 minute read Modified:

Introducing rescope. A tool that parses your scope definitions to Burp/ZAP compatible formats for import. Useful for bug hunters and those working with large scopes.

rescope is a tool I wrote (in Go) that lets you quickly define scopes in Burp/ZAP. It’s mainly intended for “bug hunters”, and pentesters who deal with larger scopes. However, I often find myself using it for smaller scopes as well.

Simply give it a file (scope) containing target identifiers and rescope parses this to regex & spits out a file that can be imported to either Burp or ZAP directly.

I won’t detail the functionality of rescope here, but rather share my thoughts on how scopes are defined at the moment and raise some questions as far as efficiency goes, especially in consideration to scopes that are large or otherwise specific. Keep in mind that whatever follows are merely my point of view based on personal experience in working with both programs.

For everything else, be sure to check out the project on Github (link above).

Defining scopes

Scopes are defined in mainly two ways, which goes for both Burp & ZAP:

  1. Add them manually - involves having to write regular expressions except when adding simple prefixes to Burp.

  2. Add from history - means you’ll first have to proxy some traffic to index the target and then add it from the history/sitemap context menu. This is according to Portswigger “by far the easiest” way to define scopes.

Either way is excellent (IMO) and is completely fine in most cases, that is; when you have a scope that is rather small-ish in size. However, I found that the larger (or more specific) the scope, the more annoying it becomes to define. Again, I can only speak for myself here, and you may never have experienced this yourself but to give you some perspective; imagine having to define a scope containing ~30 identifiers, many of which are considered out-of-scope. You take the simplest route and begin proxying traffic, so they become selectable from the history/sitemap. Not so fast.. Targets out-of-scope are out of scope for a reason, so it’s probably not a good idea to proxy any traffic from these to begin with - meaning you’ll have to add those separately (the manual way). In case you forgot, excluded targets can not be set to either Burp or ZAP directly. The target (or its parent) must first be included to scope, then removed from includes in order for it become excluded.

Moving on, for each target, you will have to filter through the entire sitemap and add each from the context menu individually, which (in the case of Burp) becomes especially painful when you don’t have a paid licence. Fair enough, but what if your added domain doesn’t match the identifier from your scope exactly? I.e., your identifier contains wildcards (e.g., *.google.com). Well, since those cannot be added directly either, you will have to first add something close to it (like www.google.com), then modify its regular to expression to reflect the wildcard later on. Of course, this is not a big problem in itself but if you ever had to repeat these steps 30 times over then I think you already know the process is questionable at best.

Not to mention, the bigger the scope, the greater the risk of you messing something up along the way; which is actually a big deal when you think about it. Imagine wrapping up a project, only to find you had failed to include one of the key targets at the very end. Or worse, you made a typo upon modifying one of the regexes (e.g. you forgot to escape ‘.’) Which lead you out-of-bounds without knowing. Going out-of-bounds can be very bad (even career limiting), so you better be careful as all it takes is one simple mistake.

Could’ve been easy?

A very simple scope could look something like this.

scope.txt
// include this
*.example.com  
ftp:example.com  
sub.example.com:8080

// exclude this 
pita.example.com  
example.com/admin/*

Which is just a list of identifiers that tell you what to include or exclude from the scope. Not all scopes are set the same, but for the most part, this is what you get. So if that’s the “golden standard” (if you will), then one may wonder why Burp/ZAP doesn’t provide any ways of parsing this directly. Just copy the identifiers from your scope to an ‘Include/Exclude’ field inside the application and that’s it, right? Having said that, there may be restrictions of sorts that I’m not aware of which could prevent this from being implemented, but as it stands, I can’t think of any good reason why it’s not already there.

Using rescope

Considering the issues described I came up with rescope, which turned out to be a great starting project for learning Go.

Simply provide a scope (file containing scope identifiers) and rescope will parse this to a format that can be imported from Burp/ZAP directly.

$ rescope burp -i scope.txt -o burp.json
$ rescope zap --name CoolScope -i scope1.txt -i scope2.txt -o zap.context

I wanted to make the process of parsing scopes as simple as possible. As you probably know, scopes come in various forms (websites, emails, spreadsheets, etc). Whatever the case, they usually contain more than just target identifiers, such as descriptions, tags, comments and so on.

Take this scope on HackerOne for instance. If you copy/paste its scope table to a file directly, then you’ll bring with you other information such as comments, asset type, environmental score, etc.. all scrambled together on separate lines. To save yourself from having to manually filter this out in advance, rescope identifies the targets for you. It doesn’t matter what comes before and after the identifiers, as long as they’re there.

rescope may (without my knowledge) identify or parse scope-identifiers inaccurately. Therefore you should probably go over the results yourself and make sure it got what you wanted. If not then please submit an issue. Alternatively you can always find me on Twitter.

IP ranges/CIDR should be parsable, and you can easily separate excludes from includes, in addition to parsing multiple scopes at once to the same result.

I hope you found this tool useful, and if you did then feel free to drop a like or follow me on Twitter for more stuff like this.