> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fingerprint-only scanning for restricted environments

> Generate WFP fingerprints on a machine with no network access, move only the fingerprint file across, and scan it with scanoss-cli scan wfp from a connected machine.

## Goal

Scan code that lives on a machine that cannot reach the internet, or that policy does not allow
to send anything out. You split the work in two:

1. On the restricted machine, generate fingerprints. This step needs no network access and no API
   key.
2. On a connected machine, scan the fingerprint file. The source code never leaves the
   restricted side.

## When to use it

* Your build systems run in an isolated network.
* Your code is under an export, defence, or customer restriction that does not allow a direct
  connection to an external service.
* A third party audits your code by scanning your fingerprints, without receiving your source
  code.

If the restricted network can reach your own SCANOSS deployment instead, you do not need this
split. Point scanoss-cli at that deployment with a custom API URL. See
[Use a custom API URL](/en/latest/developer-tools/authentication#use-a-custom-api-url).

## What a fingerprint file contains

A WFP file contains, for each file:

* a hash of the whole file, its size, and its path relative to the scanned directory
* hashes of overlapping fragments of the file, used to find snippet matches

It does not contain the source code. It does contain your file paths, so if paths are
sensitive, review the file before it leaves the restricted side.

## Prerequisites

* scanoss-cli on both machines, at the same version (see [Quickstart](/en/latest/developer-tools/quickstart))
* `SCANOSS_API_KEY` on the connected machine only
* An approved way to move one file from the restricted machine to the connected one

## Step 1: Fingerprint on the restricted machine

```bash theme={null}
cd /path/to/project

# Fingerprint the project. No network access is used.
scanoss-cli wfp . --settings scanoss.json --output project.wfp

# Record a checksum to verify the transfer.
sha256sum project.wfp > project.wfp.sha256
```

Leave out `--settings scanoss.json` if the project has no `scanoss.json`. When it is present, its
skip rules decide which files scanoss-cli fingerprints.

`wfp` accepts the same file selection flags as `scan`: `--threads`, `--min-size`, `--max-size`,
`--gitignore`, `--all-extensions`, `--all-folders`, `--all-hidden`, `--skip-headers`, and
`--skip-headers-limit`. Its output is byte-for-byte reproducible. The same tree and flags give
the same file, so you can hash it, diff it, and store it as evidence.

<Warning>
  `--skip-headers` changes the fingerprints. Fingerprints made with it on do not match
  fingerprints made with it off, so use the same setting every time you fingerprint the same
  project.
</Warning>

## Step 2: Move the file

Transfer `project.wfp` and `project.wfp.sha256` with your approved process. On the connected
machine, check that the file arrived unchanged:

```bash theme={null}
sha256sum -c project.wfp.sha256
```

## Step 3: Scan the fingerprints on the connected machine

```bash theme={null}
export SCANOSS_API_KEY="<your-key>"

scanoss-cli scan wfp project.wfp \
  --settings scanoss.json \
  --include licenses,vulns \
  --output scanoss-results.json
```

`scan wfp` uploads the file as it is, waits for the result, and writes the same raw inventory as
a normal `scan`. It accepts the scan flags: `--format`, `--include`, `--settings`, `--identify`,
`--ignore`, `--ranking-threshold`, `--chunk-size`, and `--poll-interval`.

Copy the project's `scanoss.json` to the connected machine if you use one. scanoss-cli applies its BOM
rules (approved and ignored components) on this side, after the results come back. They match on the
file paths stored in the fingerprints.

scanoss-cli prints the scan ID when the upload finishes. If the connection drops while you wait, resume
with:

```bash theme={null}
scanoss-cli results <scan-id> --settings scanoss.json --include licenses,vulns --output scanoss-results.json
```

## Step 4: Use the result

The result is a normal scanoss-cli raw inventory, so every other recipe applies to it:

```bash theme={null}
# Approval gate, as in the pull request recipe (needs scanoss/unapproved.jq)
rules=scanoss.json; [ -f "$rules" ] || rules=/dev/null
unapproved="$(jq -c --slurpfile rules "$rules" -f scanoss/unapproved.jq scanoss-results.json)"
[ -z "$unapproved" ] || { echo "$unapproved"; exit 2; }

# Licence and vulnerability policy
ci/scanoss-policy.sh scanoss-results.json

# SBOMs
scanoss-cli sbom scanoss-results.json --format cyclonedx --output sbom.cdx.json
```

See [Approve components with scanoss.json](/en/latest/developer-tools/recipes/approve-components-bom-rules),
[the licence and vulnerability gate](/en/latest/developer-tools/recipes/licence-and-vulnerability-gate),
and [Generate an SBOM for each release](/en/latest/developer-tools/recipes/release-sbom).

## What you give up

| Feature | Available with fingerprints only? |
| - | - |
| Open source matches (file and snippet) | Yes |
| Licences, vulnerabilities, cryptography, geoprovenance (`--include licenses,vulns,crypto,geo`) | Yes. The API looks them up by component, not by source. |
| Declared dependencies (`--include deps`) | No. scanoss-cli reads them from manifest files in the source tree, so `scan wfp` rejects `deps`. |
| BOM rules in `scanoss.json` | Yes, applied on the connected machine |

To include declared dependencies, move the manifest files (for example `package.json`,
`package-lock.json`, or `go.mod`) to the connected machine too, if your policy allows it, and run
`scanoss-cli dependencies <dir> --extract-local --output deps.json` on that copy.

## How it fails the pipeline

| Step | Fails with |
| - | - |
| `wfp` cannot read the project | Exit code `1` |
| The checksum does not match | Non-zero from `sha256sum -c` |
| `scan wfp` cannot reach the API, or has no key | Exit code `1` |
| The result contains unapproved components, or breaks your policy | Exit code `2` from the gates in step 4 |

As with every scanoss-cli command, `scan wfp` exits `0` after a successful scan whatever it
finds. The gates in step 4 turn findings into a failure.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.