Posted on by kevin

Gowitness Documentation

Table of Contents

  1. Introduction
  2. Installation
  3. Basic Usage
  4. Command Reference
  5. Database Functions
  6. Server Functions
  7. Example Use Cases
  8. Advanced Features
  9. Best Practices and Integration
  10. Troubleshooting
  11. Latest Updates

Introduction

Gowitness is a powerful web screenshot utility written in Golang that leverages Chrome Headless to capture screenshots of web interfaces. It is designed to be fast and accurate, providing users with a command-line tool to automate the process of taking screenshots of websites. Gowitness is particularly useful for security professionals and penetration testers who need to document web interfaces quickly and efficiently.

Key Features

  • Capture screenshots of websites
  • Collect and save data such as request logs, console logs, headers, and cookies
  • Support for multiple input formats (URLs, CIDRs, Nmap and Nessus results)
  • Multiple output formats (SQLite, JSON Lines, CSV, standard output)
  • Web-based results viewer with a fully featured API
  • Differential comparison matching using perception hashing

Installation

Gowitness can be installed using several methods:

1. Go Install

If you have Go installed and the Go binary is in your $PATH, use the following command:

go install github.com/sensepost/gowitness@latest

2. Prebuilt Binaries

Download prebuilt binaries from the releases page on GitHub.

3. Compile from Source

Clone the repository and build using the make command:

git clone https://github.com/sensepost/gowitness.git
cd gowitness
make

4. Docker

Use Docker for a containerized installation:

docker pull sensepost/gowitness:latest

Basic Usage

Here are some basic commands to get started with gowitness:

Take a screenshot of a single URL

gowitness single https://example.com

This command captures a screenshot of the specified URL and saves it to a file. If no output path is specified, a filename is automatically generated based on the URL.

Scan a network CIDR range

gowitness scan --cidr 192.168.0.0/24 --threads 20

This command scans a CIDR range using multiple threads to capture screenshots of web interfaces.

Parse an Nmap file

gowitness nmap -f nmap.xml --open --service-contains http

This command parses an Nmap file to find open HTTP services and takes screenshots of them.

Run the report server

gowitness report server

This command runs the report server to view results in a web-based interface.

Command Reference

Gowitness offers a variety of commands and options. Here's an extensive reference:

Global Flags

These flags can be used with any command:

  • --debug: Enable debug logging
  • --no-http: Disable HTTP requests
  • --log-file string: Log file to write to
  • --log-format string: Log format to use (text, json)
  • --screenshot-path string: Path to store screenshots
  • --db-path string: Path to the gowitness database

single Command

Takes a screenshot of a single URL.

gowitness single [flags] <url>

Flags:

  • --delay int: Delay in seconds before taking the screenshot
  • --timeout int: Timeout in seconds for the entire operation
  • --user-agent string: User agent string to use

scan Command

Scans and screenshots websites specified by a CIDR range.

gowitness scan [flags]

Flags:

  • --cidr string: CIDR range to scan
  • --threads int: Number of threads to use (default 4)
  • --ports string: Ports to scan (default "80,443")

file Command

Processes a file containing URLs or IP addresses.

gowitness file [flags] <file>

Flags:

  • --format string: Format of the input file (txt, json, csv)

nmap Command

Parses Nmap XML output and screenshots discovered services.

gowitness nmap [flags] -f <nmap_file>

Flags:

  • --open: Only screenshot open ports
  • --service-contains string: Only screenshot services containing this string

report Command

Generates reports or starts the report server.

gowitness report [command]

Subcommands:

  • generate: Generates a static HTML report
  • server: Starts the web server for viewing results

Database Functions

Gowitness uses SQLite as its default database to store captured data, including screenshots and metadata.

Creating a Database

  1. Automatic Database Creation:
    By default, Gowitness automatically creates a SQLite database named gowitness.sqlite3 in the current working directory when you run a scan or capture screenshots.

  2. Specifying a Custom Database Path:
    You can specify a custom path for the database using the --db-path flag:

    gowitness scan --cidr 192.168.0.0/24 --db-path /path/to/custom/database.sqlite3

Using Database Functions

  1. Writing to the Database:
    Use the --write-db flag to ensure that results are written to the database:

    gowitness scan --cidr 192.168.0.0/24 --write-db

  2. Disabling Database Operations:
    If you don't want to use the database at all, you can disable it with the --disable-db flag:

    gowitness scan --cidr 192.168.0.0/24 --disable-db

  3. Database Migration:
    When upgrading Gowitness from version 2 to version 3, use the database migration command to update your existing database:

    gowitness database migrate

  4. Querying the Database:
    While Gowitness doesn't provide direct SQL query capabilities, you can use the report server to interact with the data stored in the database.

Server Functions

Gowitness includes a report server that provides a web interface for viewing and analyzing captured data.

Starting the Report Server

  1. Basic Server Start:
    To start the report server, use the following command:

    gowitness report server

    This will start the server on the default port 7171.

  2. Specifying a Custom Port:
    You can specify a custom port using the -p or --port flag:

    gowitness report server -p 8080

  3. Binding to a Specific Address:
    Use the -a or --address flag to bind the server to a specific address:

    gowitness report server -a 192.168.1.100

Using Server Functions

  1. Accessing the Web Interface:
    Once the server is running, access the web interface by navigating to http://localhost:7171 (or your specified address and port) in your web browser.

  2. API Endpoints:
    The report server exposes several API endpoints that you can use for automation and integration with other tools:

    • List all screenshots:

      curl http://localhost:7171/api/list

    • Get details for a specific screenshot:

      curl http://localhost:7171/api/detail/1

    • Retrieve a raw screenshot:

      curl http://localhost:7171/api/detail/1/screenshot > screenshot.png

    • Search for specific entries:

      curl "http://localhost:7171/api/search?q=example.com"

    • Capture a new screenshot:

      curl -X POST http://localhost:7171/api/screenshot --data '{"url": "https://example.com", "oneshot": true}'

  3. Securing the Server:
    Since Gowitness doesn't include built-in authentication, it's crucial to secure the server if it's exposed to a network. You can use a reverse proxy like Traefik or Nginx to add an authentication layer:

    # Example using Traefik for basic auth
traefik --api.insecure=true --providers.file.filename=traefik.toml --entrypoints.web.address=:80

    In your traefik.toml file:

    [http.middlewares.auth.basicAuth]
users = ["admin:$apr1$ruca84Hq$mbjdMZBAG.KWn7vfN/SNK/"]

[http.routers.gowitness]
rule = "Host(gowitness.example.com)"
service = "gowitness"
middlewares = ["auth"]

[http.services.gowitness.loadBalancer]
servers = [{ url = "http://localhost:7171" }]

  4. Configuring the Base Path:
    If you're serving the report server on a non-root path, use the --base-path flag to ensure correct UI/API path generation:

    gowitness report server --base-path /gowitness

Example Use Cases

1. Bug Bounty Hunting

Gowitness can be an invaluable tool for bug bounty hunters, especially when combined with other reconnaissance tools:

# Enumerate subdomains with subfinder
subfinder -d example.com -o subdomains.txt

# Screenshot all discovered subdomains
gowitness file -f subdomains.txt --threads 10

This workflow allows for quick visual inspection of a large number of subdomains, potentially revealing interesting targets for further investigation.

2. Network Penetration Testing

During a network penetration test, gowitness can be used to quickly document all web interfaces on a network:

# Scan the entire network and take screenshots
gowitness scan --cidr 10.0.0.0/16 --ports 80,443,8080,8443 --threads 50

# Start the report server to view results
gowitness report server

This approach provides a visual map of the network's web services, helping prioritize further testing.

3. Post-Exploitation Documentation

After gaining access to a network, gowitness can be used to document internal web services:

# Create a list of internal IPs
echo "10.0.0.1\n10.0.0.2\n10.0.0.3" > internal_ips.txt

# Screenshot internal services
gowitness file -f internal_ips.txt --delay 2 --timeout 30

This helps in creating comprehensive reports and understanding the internal network structure.

Advanced Features

1. Differential Comparison

Gowitness includes a feature for differential comparison matching using perception hashing. This can be useful for identifying changes in web interfaces over time.

2. Data Collection

In addition to screenshots, gowitness can collect and save various data:

  • Request logs
  • Console logs
  • Headers
  • Cookies

This additional information can be crucial for security assessments and debugging.

3. Custom Chrome Flags

Gowitness allows you to pass custom flags to the Chrome instance:

gowitness single https://example.com --chrome-flag="--headless" --chrome-flag="--disable-gpu"

This flexibility allows for fine-tuned control over the screenshot process.

Best Practices and Integration

  1. Integration with Other Tools: Combine Gowitness with tools like Eyeballer to analyze screenshots and identify potential vulnerabilities more efficiently.

  2. Processing Scan Results: Use Gowitness to process results from other scanning tools like Nessus and Nmap for comprehensive reconnaissance.

  3. Customization and Optimization: Adjust timeout and thread count to optimize performance based on network conditions and system capabilities.

  4. User Interface and Reporting: Utilize the user-friendly interface for reviewing results in table or gallery formats, and generate consolidated reports for documentation.

  5. Community and Collaboration: Engage with the Gowitness community through GitHub to learn from others' experiences and contribute to the tool's development.

  6. Security and Compliance: Adhere to ethical guidelines and legal requirements when using Gowitness, ensuring necessary permissions are obtained before scanning.

Troubleshooting

  1. Chrome not found: Ensure that Chrome is installed on your system and properly configured in your PATH.

  2. Permission issues: When running gowitness, make sure you have the necessary permissions to write to the output directory.

  3. Network issues: If you're having trouble reaching certain URLs, check your network configuration and firewall settings.

  4. Database errors: If you encounter database-related errors, try deleting the existing database file and letting gowitness create a new one.

  5. Performance issues: If gowitness is running slowly, try adjusting the number of threads or increasing the timeout values.

Latest Updates

Gowitness 3.0.5 (Latest Release)

Released on October 21, 2024, this version includes:

  • New Features:

    • Added a none writer for testing scenarios.
    • New Makefile target to ensure API documentation is up to date.

  • Fixes:

    • Error message displayed when Chrome is unavailable.
    • Prevents creation of empty SQLite3 databases when not required.
    • Screenshots now shown in report server when stored using --write-screenshot flag.
    • Fixed UI error in job submission view.
    • Improved reliability of cleanup routines with gorod driver.
    • Updated nmap.go to use HTTPS instead of HTTP only.

Gowitness 3.0.4 (Previous Release)

  • New Features:

    • Added HTML searching and keyboard navigation to the detail view.

  • UI Changes:

    • Tweaked HTML copy modal in report server.
    • Screenshot modals in detail view now show URL and timestamp.

  • Fixes:

    • Corrected command options structure for report generate.
    • Improved parsing of file names with illegal characters.

For the most up-to-date information and advanced usage scenarios, refer to the official Gowitness GitHub repository.