GBounty Usage Manual

Overview

GBounty is a multi-step website vulnerability scanner designed for penetration testers and bug bounty hunters. It leverages customizable profiles contributed by security researchers to identify potential vulnerabilities in web applications. This guide provides an in-depth look into its features, configuration, and usage best practices.

Important Notices:

Active Development: GBounty is actively maintained. Breaking changes may occur with new releases. Always review the release changelog before updating.
Standalone Usage: GBounty is primarily intended as a standalone CLI tool. Running it as a service may pose security risks. Ensure additional security measures are in place.

Installation

Using Go

GBounty requires Go v1.21 or later for installation. Run the following command to install the latest development version:

go install -v github.com/bountysecurity/gbounty/cmd/gbounty@main

Using Pre-Compiled Binaries

Navigate to the GitHub Releases page and download the latest binary for your operating system (Linux, macOS, or Windows) and architecture (e.g., amd64, arm64). Extract and make the binary executable:

chmod +x gbounty
./gbounty --help

Other Installation Methods

Currently, GBounty does not support package managers like Homebrew, Snap, Choco, or Docker. Contributions to add these are welcome.

Command Syntax

Usage:
  gbounty [flags]

Flags:
  -h, --help
    	Show help
  --update
    	Update the binary and profiles to the latest version
  --update-app
    	Update the binary to the latest version
  --update-profiles
    	Update profiles to the latest version
  --force-update-profiles
    	Re-download the latest version of profiles
  --check-updates
    	Check for available updates forcefully
	By default, available updates are checked only once a day

TARGET INPUT:
  -u, --url value
    	If specified, it will be used as a target url
	Can be used more than once: -u url1 -u url2
  -uf, --urls-file string
    	If specified, each line present on the file will be used as a target urls
  -rf, --requests-file string
    	If specified, each file present on the compressed file will be used as a target url and request template
	Only zipped (.zip) requests files are supported
  -rr, --raw-request value
    	If specified, contents on given path will be used as a target url and request template
	Can be used more than once: --raw-request path/requests/req1.txt --raw-request path/requests/req2.txt
	The host address must be in the first line before the raw request. Otherwise, the 'Host' header will be used
  -pf, --params-file string
    	If specified, each line present on the file will be used as a request parameter
	Used in combination with --params-split
  -ps, --params-split int
    	Determines the amount of parameters (-pf/--params-file) included into each group (default: 10)
	Use one (1) to scan every param individually
  -pm, --params-method string
    	Determines the HTTP method the params (-pf/--params-file) will be included into (default: "GET")
	Supported methods are: "GET" (url) and "POST" (www/url-encoded, body)
  -pe, --params-encoding string
    	Determines the encoding the params (-pf/--params-file) will be included into (default: "url")
	Supported encodings are: "url" (application/x-www-form-urlencoded) and "json" (application/json)
	Only used when --params-method/-pm is set to "POST"
  -h2, --http2
    	Forces HTTP/2. If enabled, the proto from the request template, if present, will be ignored

Options for --url (-u) and --urls-file:
  -X, --method string
    	If specified, it will be used as the HTTP method for request templates
  -H, --header value
    	If specified, it will be used as the HTTP header(s) for request templates
	Can be used more than once: -H "Accept: application/json" -H "Content-Type: application/json"
  -d, --data value
    	If specified, it will be used as the HTTP body data for request templates

PROFILE OPTIONS:
  -p, --profiles value
    	Determines the path where profile file(s) will be read from (default: "./profiles/")
	It can also be used with the path to a specific profile file
	Can be used more than once: -p profiles/XSS.bb2 -p profiles/SQLi.bb2
  -t, --tag value
    	If specified, only profiles tagged with provided tags will be used
	Can be used more than once: -t tag1 -t tag2
  -active, --only-active
    	If specified, only active profiles will be analyzed during the scan
  -passive, --only-passive
    	If specified, only passive profiles will be analyzed during the scan
  -psreq, --only-passive-req
    	If specified, only passive request profiles will be analyzed during the scan
  -psres, --only-passive-res
    	If specified, only passive response profiles will be analyzed during the scan
  -tags, --print-tags
    	Print available profile tags
	Used in combination with --tag
  -poc, --only-poc
    	If specified, only matched requests will be printed, nothing else.

RUNTIME OPTIONS:
  -c, --concurrency int
    	Determines how many target URL(s) will be scanned concurrently (default: 10)
  -r, --rps int
    	Determines the limit of requests per second (per URL) (default: 10)
  -safm, --stop-at-first-match
    	If specified, the scan will stop at the first match found for each combination of
	(a) profile, (b) step and (c) entrypoint
	Enabled by default, can be disabled with --stop-at-first-match=false or -safm=false
  -s, --silent
    	If specified, no results will be printed to stdout
  -bh, --blind-host string
    	If specified, the blind host will be injected into {BH} labels
  -email, --email-address string
    	If specified, the email address will be injected into {EMAIL} labels
  --proxy-address string
    	If specified, requests are proxied to the given address
	To specify host and port use 'host:port'
  --proxy-auth string
    	If specified, proxied requests will include authentication details
  -m, --in-memory
    	Use memory (only) as storage for intermediate scan results.
	Otherwise, it will use the filesystem (default)
  -sos, --save-on-stop
    	Save the scan's status, when manually interrupted
	The scan's identifier will be printed, to be used in combination with --from
  -f, --from string
    	Scan's identifier to be used to continue from

OUTPUT OPTIONS:
  -o, --output string
    	Determine the path where the output file will be stored to
	By default, the output file is formatted as plain text
  -j, --json
    	If specified, the output file will be JSON-formatted
	By default, the output file is formatted as plain text
  -md, --markdown
    	If specified, the output file will be Markdown-formatted
	By default, the output file is formatted as plain text
  -a, --all
    	If specified, results will include all requests and responses
	By default, only those requests that caused a match are included in results
	As it causes a noisy output, must be used in combination with -o/--output flag
  -areq, --all-requests
    	If specified, results will include all requests
	By default, only those requests that caused a match are included in results
	As it causes a noisy output, must be used in combination with -o/--output flag
  -ares, --all-responses
    	If specified, results will include all responses
	By default, only those requests that caused a match, and no response, are included in results
	As it causes a noisy output, must be used in combination with -o/--output flag
  -se, --show-errors
    	If specified, failed requests are included in results
  -sr, --show-responses
    	If specified, those requests that caused a match are printed with the corresponding response
  -ste, --stream-errors
    	If specified, failed requests are printed to stdout during the scan (live)
	By default, they are only printed at the end, only when the -se/--show-errors flag is provided
  -stm, --stream-matches
    	If specified, those requests that caused a match are printed to stdout during the scan (live)
	Enabled by default, can be disabled with --stream-matches=false or -stm=false

DEBUG OPTIONS:
  -v, --verbose
    	If specified, the internal logger will write warning and error log messages
  -vv, --verbose-extra
    	If specified, the internal logger will write info, warning and error log messages
  -vvv, --verbose-all
    	If specified, the internal logger will write debug, info, warning and error log messages
  -vout, --verbose-output string
    	If specified, the internal logger will write the log messages to a file
	By default, those are printed to stdout

EXAMPLES:
gbounty -u https://example.org -X POST -d "param1=value1&param2=value2" -t XSS -r 20 -a -o /tmp/results.json --json
gbounty --urls-file domains.txt -c 200 -r 10 -p /tmp/gbounty-profiles --silent --markdown -o /tmp/results.md
gbounty --raw-request 1.txt --raw-request 2.txt --blind-host yourblindhost.net
gbounty --requests-file requests.zip -r 150 --proxy-address=127.0.0.1:8080 -o /tmp/results.txt --all

Flags allow customization of GBounty’s behavior. They are categorized into:

Global Flags
Target Input
Request Customization
Profile Management
Runtime Options
Output Options
Debugging Options

Global Flags

-h, --help: Display help information.
--update: Update both the binary and profiles to the latest version.
--update-app: Update the binary only.
--update-profiles: Update profiles only.
--force-update-profiles: Force re-download of profiles.
--check-updates: Force a check for updates, overriding the daily check.

Target Input Flags

Specifying Target URLs

-u, --url: Define one or more target URLs.

gbounty -u https://example.com -u https://example.org

-uf, --urls-file: Provide a file with one target URL per line.
```
gbounty -uf urls.txt
```

Using Request Templates

-rf, --requests-file: Use a zipped file containing raw request templates.
```
gbounty -rf requests.zip
```

-rr, --raw-request: Specify raw request files for detailed crafting.

gbounty --raw-request request1.txt --raw-request request2.txt

Example of a raw request file:

https://example.com
POST /login HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

username=admin&password=1234

Note: The first line must include the domain and protocol (e.g., https://example.com).

Parameter-Based Scanning

The Parameter-Based Scanning feature allows GBounty to dynamically construct requests based on a set of parameters. This is especially useful for testing multiple parameter combinations efficiently.

-pf, --params-file: Specify a file containing parameters. Each line in the file should represent one parameter to be included in the scan. Example file:
```
param1=value1
param2=value2
param3=value3
```
-ps, --params-split: Define the number of parameters to include per request group (default: 10). Set to 1 to test each parameter individually.
-pm, --params-method: Specify the HTTP method to be used when sending parameters. Options are GET (appended to the URL) or POST (included in the body).
-pe, --params-encoding: Specify the encoding format for parameters. Options:
- url: Parameters encoded as application/x-www-form-urlencoded.
- json: Parameters encoded as application/json (requires POST method).

Example usage:

gbounty -u https://example.com -pf params.txt -ps 5 -pm POST -pe json

This command tests parameters from params.txt in groups of 5, using the POST method with JSON encoding.

Enforcing Protocols

-h2, --http2: Force HTTP/2 usage, ignoring any protocol specified in request templates.

Request Customization Options

HTTP Methods and Headers

-X, --method: Override the default HTTP method (e.g., GET, POST).

-H, --header: Add custom headers to requests. Example:

gbounty -H "Authorization: Bearer token" -H "Accept: application/json"

Request Body Data

-d, --data: Specify body data for requests.

gbounty -u https://api.example.com -X POST -d '{"key":"value"}'

Profile Management Options

Loading Profiles

-p, --profiles: Specify directories or files containing profiles. Example:
```
gbounty -p profiles/XSS.bb2 -p profiles/SQLi.bb2
```

Tag-Based Filtering

-t, --tag: Use profiles tagged with specific keywords. Example:
```
gbounty -t "Injection" -t "XSS"
```
--print-tags: Display all available tags in the specified profiles.

Active and Passive Scans

--only-active: Use only active profiles.
--only-passive: Use only passive profiles.
--only-passive-req: Use only request-based passive profiles.
--only-passive-res: Use only response-based passive profiles.
--only-poc: Only output matched requests; suppress other details.

Runtime Options

Concurrency and Rate Limits

-c, --concurrency: Sets the number of URLs to scan concurrently. The default is 10.
-r, --rps: Limits the number of requests per second per URL. The default is 10.

Match and Output Control

--stop-at-first-match, -safm: Stops scanning a specific profile, step, or entry point once a match is found.
--silent, -s: Suppresses all output to the terminal.

Scan State Management

-sos, --save-on-stop: Saves the scan state when interrupted, allowing it to resume later.
-f, --from: Resumes a scan from a saved state using its identifier.
-m, --in-memory: Stores scan data in memory instead of on disk for faster performance.

Interaction Hosts

--blind-host, -bh: Specifies a host for interaction-based vulnerabilities (e.g., blind XSS).
--email-address, -email: Injects an email address into {EMAIL} labels.

Proxy Settings

--proxy-address: Routes all requests through a specified proxy server.
```
gbounty --proxy-address 127.0.0.1:8080
```
--proxy-auth: Adds authentication credentials for the proxy server:
```
gbounty --proxy-auth username:password
```

Output Options

File Formats

-o, --output: Specifies the path and name for the output file.
-j, --json: Saves the output in JSON format.
-md, --markdown: Saves the output in Markdown format.

Detailed Results

-a, --all: Includes all requests and responses in the output.
--all-requests, -areq: Includes all requests, even those that didn’t cause matches.
--all-responses, -ares: Includes all responses, even if no vulnerabilities are found.
--show-errors, -se: Includes failed requests in the output.
--show-responses, -sr: Displays responses for matched requests in the output.
--stream-errors, -ste: Streams failed requests live during the scan.
--stream-matches, -stm: Streams matched requests live during the scan (enabled by default).

Debugging Options

-v, --verbose: Logs warnings and errors.
-vv, --verbose-extra: Adds informational logs.
-vvv, --verbose-all: Enables full debug logging, including warnings, errors, and info.
--verbose-output: Saves logs to a file.

Dynamic Labels

GBounty supports dynamic placeholders for flexible profile configuration. Examples:

Label

Description

{BH}

Interaction host specified with -bh.

{EMAIL}

Email address specified with -email.

{CURRENT_URL}

Entire original URL request.

{CURRENT_PORT}

Original request web server port.

{CURRENT_PATH}

Original request path.

{CURRENT_HOST}

Original request host.

{CURRENT_METHOD}

Original request method (e.g., GET, POST).

{CURRENT_QUERY}

Original POST data query.

{CURRENT_SUBDOMAIN}

Original request subdomain (e.g., www).

{CURRENT_FILE}

Original request file.

{CURRENT_PROTOCOL}

Original request protocol (http/https).

{CURRENT_USER_AGENT}

Original User-Agent header value.

{CURRENT_REFERER}

Original Referer header value.

{CURRENT_ORIGIN}

Original Origin header value.

{CURRENT_ACCEPT}

Original Accept header value.

{CURRENT_CONTENT_TYPE}

Original Content-Type header value.

{CURRENT_ACCEPT_LANGUAGE}

Original Accept-Language header value.

{CURRENT_ACCEPT_ENCODING}

Original Accept-Encoding header value.

{CURRENT_CONTENT_LENGTH}

Original Content-Length header value.

Examples

Simple URL Scan

gbounty -u https://example.com

Batch Scanning

gbounty -uf urls.txt -p profiles/SQLi.bb2 -c 50

POST Request with Custom Data

gbounty -u https://api.example.com -X POST -d '{"username":"admin","password":"1234"}'

Proxies and Advanced Scans

gbounty --urls-file targets.txt --proxy-address=127.0.0.1:8080 -t "SQLi" -o results.json -j

Additional Resources

Profiles Repository: GBounty profiles can be found here.
License: GBounty is distributed under the MIT License.

NextGBounty Profiles Designer

Last updated 1 month ago