> For the complete documentation index, see [llms.txt](https://docs.cloudcyte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudcyte.com/troubleshooting/troubleshooting-external-asset-scanner.md).

# Troubleshooting External Asset Scanner

### Purpose

This document describes the basic inspection and troubleshooting steps to follow when the CyberCyte External Asset Scanner service is not operating as expected, scan results are not generated, or an issue is reported for a specific organisation/domain.

### Scanner Installation Directory

First, navigate to the directory where the External Asset Scanner is installed.

`cd /opt/CyberCyteExternalAssetScanner/`

To review the contents of the installation directory:

`ls –la`

### Restarting the Scanner Service

If an issue with the Scanner service is suspected, one of the initial troubleshooting actions is to restart the service.

`./CyberCyteExternalAssetScanner --restart`

The `--restart` parameter resets the scanner intervals and restarts the service. After the restart, scheduled scans are expected to resume.

{% hint style="info" %}
IMPORTANT: The restart operation requires administrative privileges.
{% endhint %}

### Scanner Service Parameters

| **Parameter**         | **English Description**                                      | **Requires Root Previledge** |
| --------------------- | ------------------------------------------------------------ | ---------------------------- |
| -h, --help            | Prints usage information                                     | No                           |
| -v, --version         | Displays the agent version                                   | No                           |
| --restart             | Resets intervals and restarts the service                    | Yes                          |
| --uninstall           | Uninstalls and deletes the agent                             | Yes                          |
| --install-service     | Creates and starts the agent service                         | Yes                          |
| --uninstall-service   | Stops and removes the agent service                          | Yes                          |
| --overwrite           | Overwrites the existing installation                         | Yes                          |
| --status              | Reports service status, resource usage and running processes | Yes                          |
| --setup               | Sets up a new installation                                   | Yes                          |
| --debug               | Turns on debug mode                                          | No                           |
| --once                | Runs the daemon loop once only                               | No                           |
| --use-local-extension | Builds the browser upload extension locally                  | No                           |
| --force               | Runs without requiring user input                            | No                           |

{% hint style="info" %}
Operational Note: These parameters may modify the service or installation and should not be used as initial troubleshooting steps.
{% endhint %}

### Checking Scanner Status

To check the current Scanner status:

`cd /opt/CyberCyteExternalAssetScanner/`\
`./CyberCyteExternalAssetScanner --status`

The output provides information about service status, resource usage and running processes.

<figure><img src="https://1723175359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LuHp6M9xm4Gdg2pWusc%2Fuploads%2FcIjVWXruGCiBgQFhx2sR%2Fimage.png?alt=media&amp;token=bad9da17-b430-4447-91a9-8958d8e07e20" alt=""><figcaption></figcaption></figure>

### Accessing the Log Directory

To review Scanner logs, navigate to the following directory.

`cd /opt/CyberCyteExternalAssetScanner/logs`

To list available log files:

`ls –lah`

<figure><img src="https://1723175359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LuHp6M9xm4Gdg2pWusc%2Fuploads%2F4F8PTMqxPuHbNe0OIob6%2Fimage.png?alt=media&amp;token=be1333ac-ba68-46bd-b8d6-a2023399606f" alt=""><figcaption></figcaption></figure>

### Reviewing Scanner Logs for a Specific Organisation

The \`grep\` command can be used to search Scanner logs for a specific organisation/domain.

`cat xx_xx_scanner.txt | grep domain.com`

Example:

`cat 10_05_scanner.txt | grep example.com`

<figure><img src="https://1723175359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LuHp6M9xm4Gdg2pWusc%2Fuploads%2FFS9jCZoUPkX07cJzRiCe%2Fimage.png?alt=media&amp;token=224b2ead-18b8-442f-8076-71d043f1cedb" alt=""><figcaption></figcaption></figure>

Alternatively, grep can be run directly against the file:

`grep "domain.com" xx_xx_scanner.txt`

For a case-insensitive search:

`grep -i "domain.com" xx_xx_scanner.txt`

### Reviewing ZAP Queue Logs

If an issue is suspected with ZAP-related processing within the External Scanner, the \`zapqueue\` logs should be reviewed.

`cat xx_xx_zapqueue.txt | grep domain.com`

Example:

`cat 10_05_zapqueue.txt | grep example.com`

These records can provide information about ZAP queue processing for the specified domain.

### Recommended Troubleshooting Flow

1\. Check Scanner status

`cd /opt/CyberCyteExternalAssetScanner/`\
`./CyberCyteExternalAssetScanner --status`

2\. Review the relevant Scanner log

`cd /opt/CyberCyteExternalAssetScanner/logs`\
`grep "domain.com" xx_xx_scanner.txt`

3\. Review the ZAP queue log

`grep "domain.com" xx_xx_zapqueue.txt`

4\. Restart the Scanner service if required

`cd /opt/CyberCyteExternalAssetScanner/`\
`./CyberCyteExternalAssetScanner --restart`

5\. Check status again after restart

`./CyberCyteExternalAssetScanner --status`

6\. Review new log entries

`grep "domain.com" xx_xx_scanner.txt`\
`grep "domain.com" xx_xx_zapqueue.txt`

## Important Troubleshooting Notes

·       Always check the service status using `--status` first.

·       Even if the service appears to be running, logs for the affected domain should still be reviewed.

·       Scanner-related issues should be distinguished from ZAP queue-related issues.

·       After a restart, verify whether new log entries are being generated.

·       Destructive operations such as uninstall/reinstall should not be performed during initial troubleshooting.

·       If the issue persists, review the Scanner logs, ZAP queue logs, status output and relevant error messages together.

## Recommended Information Before Escalation

·       Affected organisation / domain

·       Date and approximate time of the issue

·       Output of `./CyberCyteExternalAssetScanner --status`

·       Relevant \`\*\_scanner.txt\` log entries

·       Relevant \`\*\_zapqueue.txt\` log entries

·       Error messages observed

·       Whether the service was restarted and the result after restart