Troubleshooting
We would love to hear your feedback, and are here to help should you encounter any problems. Please contact StackHawk Support .
Table of contents
Docker
To troubleshoot hawkscan errors related to networking, disk access or unexplained failures it may be necessary to inspect the hawkscan docker container itself.
Add the --entrypoint=bash
option to your docker command to start the hawkscan container without running the usual entrypoint, the shawk
command.
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
user in the /zap
directory.
Networking Option
If the scanner is having trouble connecting to an application running on localhost, try adding the --network=host
option.
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
Inspect local Docker scan logs
Run the shawk
command in the bash terminal to kick off a scan.
zap@732aa0ebcfdd:/zap$ shawk
When the shawk
command completes you can check the log files for errors of interest.
HawkScan versions prior to 2.0.0
zap@732aa0ebcfdd:/zap$ cat zap.out
HawkScan 2.0.0
and greater
zap@732aa0ebcfdd:/zap$ cat /home/zap/.hawk/logs/hawkscan.log /home/zap/.hawk/sessions/*/hawkscan.log
The /home/zap/.hawk/logs/hawkscan.log
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 ZAP scanner process.
The /home/zap/.hawk/sessions/*/hawkscan.log
file contains the ZAP 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ā¦
zap@732aa0ebcfdd:/zap$ ls -lah /hawk
Read permissions to the /hawk
directory will be required for the zap
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.
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.
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.
zap@732aa0ebcfdd:/zap$ shawk
HawkScan versions prior to 2.0.0
zap@732aa0ebcfdd:/zap$ cat zap.out | grep my-script
As a single commandā¦
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 2.0.0
and greater
zap@732aa0ebcfdd:/zap$ cat /home/zap/.hawk/sessions/*/hawkscan.log | grep my-script
As a single commandā¦
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'
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:
[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,
app.openApiConf,
app.graphQLConf, and
app.soapConf 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 for more information.
Still Stuck? contact StackHawk Support
. Weād love to help you out.