---
title: "Troubleshooting"
description: "Troubleshooting StackHawk's HawkScan issues and errors."
url: https://docs.stackhawk.com/hawkscan/troubleshooting/
---

# Troubleshooting

We would love to hear your feedback, and are here to help should you encounter any problems. Please [contact StackHawk Support](https://docs.stackhawk.com/support/).

## Docker

To troubleshoot HawkScan errors related to networking, disk access or unexplained failures it may be necessary to inspect the [HawkScan docker container](https://hub.docker.com/r/stackhawk/hawkscan) itself.

Add the `--entrypoint=bash` option to your docker command to start the HawkScan container without running the usual entrypoint, the `shawk` command.

```shell
docker run -e API_KEY=$HAWK_API_KEY --rm --name hawkscan --entrypoint=bash -v $(pwd):/hawk -it stackhawk/hawkscan 
```

After running the above command you will be at bash terminal in the HawkScan container as the `zap` (`steve` as of HawkScan 4.0.0) user in the `/zap` (`/steve` as of HawkScan 4.0.0) directory.

### Networking Option

If the scanner is having trouble connecting to an application running on localhost, try adding the `--network=host` option.

```shell
docker run -e API_KEY=$HAWK_API_KEY --rm --name hawkscan --network=host -v $(pwd):/hawk -it stackhawk/hawkscan 
```

### Inspect scan logs

In order to retrieve scan logs, run the command `hawk download log {scanId}` with the StackHawk CLI or in the bash terminal of the HawkScan Docker container. More details on this can be found in the [StackHawk CLI Documentation](https://docs.stackhawk.com/stackhawk-cli/#hawk-download-log)

### Inspect local Docker scan logs

Run the `shawk` command in the bash terminal to kick off a scan.

```shell
$ shawk
```

When the `shawk` command completes you can check the log files for errors of interest.

HawkScan `4.0.0` and greater

```shell
$ cat /home/steve/.hawk/logs/hawkscan.log /home/steve/.hawk/sessions/*/hawkscan.log
```

The `/home/zap/.hawk/logs/hawkscan.log` (`/home/steve/.hawk/logs/hawkscan.log` as of `hawkscan 4.0.0`) file contains logs from the startup process and can be useful when troubleshooting connectivity issues to the StackHawk platform and for inspecting the command created for the HSTE scanner process.

The `/home/zap/.hawk/sessions/*/hawkscan.log` (`/home/steve/.hawk/sessions/*/hawkscan.log` as of `hawkscan 4.0.0`) file contains the HSTE scan log. The `*` is a replacement for the session directory that is created at runtime. The real directory will be the scan UUID ie: `d5b30c85-5936-489c-b530-1977e07685b7`.

### The `/hawk` volume mount

Sometimes the scanner may not have the correct permissions to access the host volume mount specified with the `-v $(pwd):/hawk` option.

Check the permissions of the `/hawk` directory by running…

```shell
$ ls -lah /hawk
```

Read permissions to the `/hawk` directory will be required for the `zap` (`steve` as of HawkScan 4.0.0) user in the HawkScan container.

### Disk permissions and access

In some cases running the HawkScan container as the root user is required for HawkScan to access the docker host machines file system. In this case you can run the docker command with the `--user=root` flag.

```shell
docker run -e API_KEY=$HAWK_API_KEY --rm --name hawkscan --user=root -v $(pwd):/hawk -it stackhawk/hawkscan 
```

### Script debugging

To debug your custom scripts you should take advantage of logging your scripts activity with a logger.

```kotlin
import org.apache.log4j.LogManager
val logger = LogManager.getLogger("my-script")
```

From the HawkScan container bash terminal run the `shawk` command and look for the log statements from your script.

```shell
$ shawk
```

As a single command…

```shell
docker run -e API_KEY=$HAWK_API_KEY --rm --name hawkscan --entrypoint=bash -v $(pwd):/hawk -it stackhawk/hawkscan -c 'shawk; cat zap.out | grep my-script'
```

HawkScan versions before `4.0.0`

```shell
$ cat /home/zap/.hawk/sessions/*/hawkscan.log | grep my-script
```

HawkScan `4.0.0` and greater

```shell
$ cat /home/steve/.hawk/sessions/*/hawkscan.log | grep my-script
```

As a single command…

HawkScan prior to `4.0.0`

```shell
docker run -e API_KEY=$HAWK_API_KEY --rm --name hawkscan --entrypoint=bash -v $(pwd):/hawk -it stackhawk/hawkscan -c 'shawk; cat /home/zap/.hawk/sessions/*/hawkscan.log | grep my-script'
```

HawkScan `4.0.0` and greater

```shell
docker run -e API_KEY=$HAWK_API_KEY --rm --name hawkscan --entrypoint=bash -v $(pwd):/hawk -it stackhawk/hawkscan -c 'shawk; cat /home/steve/.hawk/sessions/*/hawkscan.log | grep my-script'
```

## HawkScript package names

**Problem:** A custom authentication or business-logic script fails with an error like:

`TypeError: Access to host class org.zaproxy.zap.authentication.AuthenticationHelper is not allowed or does not exist.`

**Solution:** HawkScan’s scan engine uses the `com.stackhawk.hste` package namespace. Update your script imports:

- `org.zaproxy.zap` -> `com.stackhawk.hste`
- `com.stackhawk.zap` -> `com.stackhawk.hste`

For example, `org.zaproxy.zap.authentication.AuthenticationHelper` becomes `com.stackhawk.hste.authentication.AuthenticationHelper`.

## Incomplete or Missing URLs Found by Spider

To scan your application effectively, it is important that HawkScan find all the paths being served by your application. By default, HawkScan will first run a web crawler or “spider” to discover all the paths of your application before running active scans. For example you will see output on the terminal that will look something like this:

```text
[INFO] shawk 2019-10-10 17:44:20,868 Spider complete
[INFO] shawk 2019-10-10 17:44:20,875 24 URLs after spiders
  http://localhost:3000
  http://localhost:3000/about
  http://localhost:3000/assets
  http://localhost:3000/assets/account_activation.self-877aef30ae1b040ab8a3aba4e3e309a11d7f2612f44dde450b5c157aa5f95c05.js?body=1
  http://localhost:3000/assets/account_activations.self-e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.css?body=1
  http://localhost:3000/assets/action_cable.self-69fddfcddf4fdef9828648f9330d6ce108b93b82b0b8d3affffc59a114853451.js?body=1
  http://localhost:3000/contact
  http://localhost:3000/help
  http://localhost:3000/microposts
  http://localhost:3000/microposts/2
  http://localhost:3000/microposts/56
  http://localhost:3000/microposts/8
  http://localhost:3000/robots.txt
  http://localhost:3000/search
  http://localhost:3000/searchresults
  http://localhost:3000/sitemap.xml
  http://localhost:3000/users
  http://localhost:3000/users/1
  http://localhost:3000/users/1/followers
  http://localhost:3000/users/1/following
  http://localhost:3000/users/2
  http://localhost:3000/users/2/edit
  http://localhost:3000/users/2/followers
  http://localhost:3000/users/2/following
Scan status Stock-Default-Policy (http://host.docker.internal:3000) [4%]
```

If you do not see URLs and paths that you expect your application to serve, you may need to modify your `stackhawk.yml` to include form authentication or an api specification. See the [app.authentication](https://docs.stackhawk.com/hawkscan/configuration/#appauthentication), [app.openApiConf](https://docs.stackhawk.com/hawkscan/configuration/#appopenapiconf), [app.graphQLConf](https://docs.stackhawk.com/hawkscan/configuration/#appgraphqlconf), and [app.soapConf](https://docs.stackhawk.com/hawkscan/configuration/#appsoapconf) configuration help for more detail.

## Networking

**Problem:** localhost scans fail, returning the following error:

`Error: Unable to scan localhost on ports 0..1023. Please use a permitted port 1024..65535 to proceed.`

**Solution:** HawkScan reports this error when a kernel port (0..1023) is set to a scan against **localhost**.

HawkScan runs in an unprivileged container which provides permissions for the userland context only. This requires scans against **localhost** to use a permitted ephemeral port (eg. 1024-65535).

Please refer to the [Docker User Guide](https://docs.docker.com/network/links/) for more information.

**Problem:** Scans fail with TLS handshake errors, or every request returns `400` or `403` with a message such as “certificate required” or “no required SSL certificate was sent”.

**Solution:** Your application probably requires mutual TLS (mTLS) and HawkScan isn’t presenting a client certificate. Configure one with `hawk.config` as described in [Mutual TLS (Client Certificates)](https://docs.stackhawk.com/hawkscan/configuration/#mutual-tls-client-certificates). If it’s already configured, check that:

- The certificate is a PKCS#12 (`.p12` or `.pfx`) bundle. Separate PEM certificate and key files must be converted first.
- The `pkcs12.file` path points to the certificate file and is readable by the user running `hawk scan`.
- The `pkcs12.password` value is correct and any environment variable it references is set.

## Still Stuck?

Please [contact StackHawk Support](https://docs.stackhawk.com/support/). We’d love to help you out.