# Deep scan

> The second audit tier runs open-source skill scanners in an isolated container after each publish and merges what they find into the release audit. Learn what runs, what it sends and how to set it up.

Source: https://skaas.io/docs/deep-scan
Last updated: 2026-11-14

The static rules run inline on every publish and finish in milliseconds. The deep scan runs afterwards, in a container, and takes seconds to minutes. A release is never held back while it runs. When the scan ends, its findings join the audit of the release, and the repository policy decides what follows.

Edition and plan: the `deep_scan` feature. It is in Cloud Team and above. In the Community edition you run it yourself through the `deepscan` Compose profile.

## What does it run?

Two open-source scanners, each in a virtual environment of its own.

| Scanner               | Network and account                          | What it sends out                                                          | When it runs                                                     |
| --------------------- | -------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Cisco `skill-scanner` | None. It works offline and needs no account. | Nothing.                                                                   | By default.                                                      |
| Snyk `agent-scan`     | Needs a network and a Snyk account token.    | The text of every file of the skill goes to the vendor's analysis service. | Only when the deployment and the organization both switch it on. |

The Snyk scanner is off unless the deployment lists it in `SKAAS_SCANNER_TOOLS`, sets a token and sets the consent sentence `send-release-content-to-snyk`. Even then, the service hands such a worker only the jobs of organizations that switched the upload on. That choice is an organization setting, `deep_scan_upload_tools`, and it is off by default. Only an owner of the organization can change it, because it moves the content of the organization to a third party: an administrator who is not an owner is refused. The owner sets it with `PATCH /v1/orgs/{org}/settings`, and the change is recorded in the activity log. Turning it off takes effect from the next job that a worker claims. No environment variable holds this consent. A private skill never goes to a third party by default. Run one worker with the Snyk tool and, next to it, one without, so that every release still gets the tool that stays on the machine.

## How does a scan work?

The scanner container polls the application over HTTP. It claims a job under a lease, downloads the files of the release, runs each tool as an unprivileged user so that the tool cannot read the service credential, and reports what it found. The service merges the report into the audit. It needs no database credentials, publishes no port and has no inbound network use.

The report says whether the scan was complete. A scan that could not examine the whole release is stored as incomplete, and it keeps the earlier deep findings instead of replacing them. It is never shown as clean.

## What happens when a deep finding blocks?

Each repository has a policy. `deep_scan_action` is `notify` by default, which tells the administrators, or `yank`, which also withdraws the release from new installs. `block_on_incomplete_deep_scan` is off by default, so an incomplete scan is reported and nothing more. Turn it on if you would rather withdraw than guess. A waiver that covers a deep finding carries over to the same finding in a later scan, until it expires.

## How do I run it myself?

You need the application running, because the scanner polls it, and a credential for the scanner: a random string of at least 32 characters that the server is configured with as well. It is not an API key. `./setup-env.sh` in `deploy/selfhost/` generates one as `SKAAS_SCANNER_TOKEN` in `.env`, and writes the same value to `./secrets/scanner-token` with mode 600, which Compose mounts into the scanner as a secret. The worker refuses to start when the user that runs the tools could read that file, so keep it out of reach of other users. Then start the profile, which also starts the application.

```sh
cd deploy/selfhost
./setup-env.sh
docker compose --profile app --profile deepscan up -d --build
```

The Compose file starts the scanner with a read-only root file system, a tmpfs at `/tmp`, 2 GiB of memory and a limit of 256 processes. The worker starts as root only to start each tool as another user. The Compose file drops every capability and adds back the five that this needs: `SETUID`, `SETGID`, `CHOWN`, `DAC_OVERRIDE` and `KILL`. You do not add anything by hand. `SKAAS_SCANNER_TOOLS` chooses the tools and defaults to `cisco`, the one that needs no network. The `deploy/selfhost/scanner/README.md` file explains what each capability is for and lists every variable, such as the tool timeouts and the size limits.

Nobody has built or started the scanner image yet. `bash deploy/selfhost/verify.sh --app` covers the server and web images and not this one. Check that a scan of a test skill finishes before you rely on it: the first start is the first real check of the five capabilities.

## Does a clean deep scan mean a skill is safe?

No. The scanners report patterns that they know. No findings does not mean no risk. See [the audit and its limits](/docs/auditor).
