whaler

Whaler is a Go-based tool designed to reverse engineer Docker images back into their original Dockerfiles.

Key capabilities include:

• Generating a Dockerfile from an existing image.
• Searching added filenames for potential secret files.
• Extracting files added via ADD or COPY instructions.
• Displaying metadata such as open ports, the running user, and environment variables.

The simplest way to use Whaler is to run it as a Docker container. You must mount the host's Docker socket (/var/run/docker.sock) into the container so Whaler can interact with your local Docker daemon.

Note: The tool will automatically pull the target image if it is not present locally. The -sV flag (used to set a specific Docker client version) is optional.

docker pull pegleg/whaler
docker run -t --rm -v /var/run/docker.sock:/var/run/docker.sock:ro pegleg/whaler -sV=1.36 nginx:latest

To build Whaler manually, clone the repository into your $GOPATH/src directory and use the Go toolchain:

1. Clone/Get the package: go get -u github.com/P3GLEG/Whaler
2. Navigate to the directory: cd $GOPATH/src/github.com/P3GLEG/Whaler
3. Build the binary: go build .

Whaler is a tool for analyzing Docker images to inspect their history, configuration, and potential secrets. You can analyze a single image from your local Docker daemon, multiple images from a file, or a specific Docker image saved as a .tar file.

Analyze a single image

Pass the image name or ID as a positional argument:

./whaler nginx:latest

Analyze multiple images from a file

Use the -f flag to provide a file containing image IDs or names, one per line:

./whaler -f images_to_scan.txt

Analyze a Docker save tar file

Use the -t flag to point to a .tar file generated by docker save:

./whaler -t my_image.tar

# Example: Analyze a single image
./whaler nginx:latest

# Example: Analyze multiple images from a list
./whaler -f images.txt

# Example: Analyze a tarball
./whaler -t image_export.tar

Whaler provides several flags to control the analysis and output:

• -f <string>: Path to a file containing a list of images to analyze (one image per line).
• -filter: Filters out noisy filenames (e.g., node_modules). This is enabled by default.
• -sV <string>: Sets the Docker client ID to a specific version (e.g., -sV=1.36).
• -v: Verbose mode; prints all details about the image.
• -x: Saves the image layers to the current working directory.

Usage of ./Whaler:
  -f string
    	File containing images to analyze seperated by line
  -filter
    	Filters filenames that create noise such as node_modules. Check ignore.go file for more details (default true)
  -sV string
    	Set the docker client ID to a specific version -sV=1.36
  -v
    	Print all details about the image
  -x
    	Save layers to current directory

The DockerClient interface abstracts the necessary methods from the Docker SDK required for image inspection and layer extraction. This allows for easier testing and potential alternative implementations.

type DockerClient interface {
	ImageInspectWithRaw(ctx context.Context, imageID string) (image.InspectResponse, []byte, error)
	ImageSave(ctx context.Context, imageIDs []string, options ...client.ImageSaveOption) (io.ReadCloser, error)
	Close() error
}

Use scanFilename to check if a specific filename matches any registered patterns where SecretType is set to "Filename". If a match is found, it prints a success message to the console using green text, including the filename, the pattern description, the regex value, and the location.

// filename: the name of the file to scan
// loc: the location/path context for the match
scanFilename(filename string, loc string)

The scanFileContent function is intended to scan the actual data within a file using an io.Reader. Note: In the current implementation, the body of this function is a commented-out placeholder.

scanFileContent(reader io.Reader)

The scanner uses a predefined set of JSON-based patterns to identify secrets. Patterns are categorized by secretType (Filename or FileContent) and use regular expressions (value) to perform matches.

[
    {
        "description": "Azure storage standard key format", 
        "secretType": "FileContent", 
        "value": "\\b[A-Za-z0-9/+-]{86}\\b"
    }, 
    {
        "description": "Azure service configuration file", 
        "secretType": "Filename", 
        "value": "\\.cscfg$"
    }, 
    {
        "description": "AWS access key", 
        "secretType": "FileContent", 
        "value": "\\b[A-Za-z0-9/+-]{40}\\b"
    }
    // ... (many more patterns included in the source)
]

The following flags are available when running the Whaler CLI:

The Pattern struct defines the criteria used to identify sensitive information. It supports two primary modes of detection via the SecretType field: Filename (matching against the name of a file) and FileContent (matching against the contents of a file).

type Pattern struct {
	Description string
	SecretType string
	Value string
	Regex *regexp.Regexp
}