The jf scan and jf docker scan commands enable developers to perform on-demand security scans of their binaries directly from their terminal, ensuring early detection of CVEs, licenses, operational risk, and exposed secrets. By integrating seamlessly into the developer workflow, it helps catch security risks of binaries before uploading them into JFrog Artifactory — reducing remediation costs and enhancing software integrity. The scan results are displayed in the terminal for immediate feedback and are also available in the JFrog Platform’s On-Demand Scans pane, providing centralized visibility.

However, it's important to note that on-demand scanning is not a best practice for overall binary security; it is typically used for specific cases where immediate feedback is needed. For comprehensive security, organizations should implement continuous scanning as part of their CI/CD pipeline, ensuring ongoing monitoring and threat detection throughout the software development lifecycle.

📘
On-demand scan results are retained for seven days before being automatically deleted.

📘
On-demand scans may not detect certain components, such as C++ libraries or ELF files (e.g., .so files and compiled binaries), since these are not included in the CLI (indexer-app) analysis.

📘
The grace period setting in the "fail build" policy is not applied during jf docker scan (on-demand Docker image scanning), resulting in the build failing immediately despite the configured grace period.

Scan Binaries

Scanning Files on the Local File System

Use the jf scan command to scan files on your local file system with JFrog Xray.

Command: scan, s

Commands Parameters

Parameter	Optional/Default	Description
`--server-id`	Optional	Server ID configured using `jf c add`. Defaults to the configured server if not specified.
`--spec`	Optional	Path to a file specifying files to scan. Cannot be used with the `pattern` argument.
`--project`	Optional	JFrog project key for security violations. Mutually exclusive with `--repo-path` and `--watches`.
`--repo-path`	Optional	Artifactory repository path for determining violations. Mutually exclusive with `--project` and `--watches`.
`--insecure-tls`	Default: `false`	Set to true to skip TLS certificates verification.
`--watches`	Optional	Comma-separated list of Xray watches. Supported violations are CVEs, Operational Risks, and Licenses. Mutually exclusive with `--project` and `--repo-path`.
`--licenses`	Default: `false`	Display license information.
`--format`	Default: `table`	Outputs scan results in `table`, `json`, `simple-json`, `sarif`, and `cyclonedx` format.
`--sbom`	Default: `false`	Displays the Software Bill of Materials (SBOM) for the project when set to true. Only applicable if the `--sca` flag is also used and the output format is `table` or `cyclonedx`.
`--vuln`	Optional	Display all vulnerabilities, regardless of Xray policy settings.
`--fail`	Default: `true`	When one of `--watches`, `--project`, or `--repo-path` is used and a 'Fail build' rule is matched, returns exit code `3`. Set to `false` to see violations with exit code `0`.
`--sca`	Default: `false`	Selective scanners mode: run the SCA sub-scan. `--sca` alone also runs Contextual Analysis; combine with `--without-contextual-analysis` to run SCA only. Can be combined with `--secrets`.
`--without-contextual-analysis`	Default: `false`	Disable Contextual Analysis after `--sca`. Relevant only with `--sca`.
`--secrets`	Default: `false`	Selective scanners mode: run the Secrets sub-scan. Can be combined with `--sca`.
`--validate-secrets`	Default: `false`	Trigger token validation on found secrets. Relevant only with `--secrets`.
`--min-severity`	Optional	Minimum severity of issues to display: `Low`, `Medium`, `High`, `Critical`, or `Scanned - No Issues`.
`--fixable-only`	Default: `false`	Display only issues that have a fix version.
`--extended-table`	Default: `false`	Include extended fields such as CVSS and Xray Issue Id in the table. Ignored unless `--format` is `table`.
`--bypass-archive-limits`	Default: `false`	Bypass the indexer-app archive size limits. Required for archives that exceed Xray's default size limit.
`--threads`	Default: `3`	Number of parallel threads used to scan.
`--recursive`	Default: `true`	Set to false to skip collecting artifacts in sub-folders.
`--ant`	Default: `false`	Use an Ant pattern instead of wildcards to collect files to scan.
`--regexp`	Default: `false`	Use a regular expression instead of wildcards to collect files to scan.

Arguments

Argument	Description
`Pattern`	Specifies the file system path to artifacts. Supports wildcards.

Examples

Scan with a specific watch: Scans all files at path/to/files/ using the watch1 defined in Xray.

jf s "path/to/files/" --watches "watch1"

Scan with multiple watches: Scans files using watch1 and watch2 defined in Xray.

jf s "path/to/files/" --watches "watch1,watch2"

Scan specific file types: Scans .zip files using watch1 and watch2.

jf s "path/to/files/*.zip" --watches "watch1,watch2"

Scan with project policies: Scans .tgz files using policies defined for project-1.

jf s "path/to/files/*.tgz" --project "project-1"

Scan with repository path: Scans .tgz files using policies for libs-local/release-artifacts/.

jf s "*.tgz" --repo-path "libs-local/release-artifacts/"

Scan without specific policies: Shows all known vulnerabilities for .tgz files.

jf s "*.tgz"

Scanning Docker Containers on the Local File System

Use jf docker scan to scan Docker containers locally using the Docker client and JFrog Xray. With Advanced Security enabled, this command also runs contextual analysis and exposures scanners on the image and returns applicability results in the output.

For packaging requirements that help contextual analysis succeed inside container images, see Package Applications in Docker for Contextual Analysis.

Commands Parameters

Parameter	Optional/Default	Description
`--server-id`	Optional	Configured server ID.
`--project`	Optional	JFrog project key for security violations.
`--repo-path`	Optional	Artifactory repository path for determining violations.
`--insecure-tls`	Default: `false`	Set to true to skip TLS certificates verification.
`--watches`	Optional	Comma-separated list of Xray watches.
`--licenses`	Default: `false`	Display license information.
`--validate-secrets`	Default: `false`	Trigger token validation on found secrets. Relevant only with `--secrets`.
`--format`	Default: `table`	Outputs scan results in `table`, `json`, `simple-json`, `sarif`, and `cyclonedx` format.
`--vuln`	Optional	Show all vulnerabilities.
`--sbom`	Default: `false`	Displays the Software Bill of Materials (SBOM) for the project when set to true. Only applicable if the `--sca` flag is also used and the output format is `table` or `cyclonedx`.
`--fail`	Default: `true`	When one of `--watches`, `--project`, or `--repo-path` is used and a 'Fail build' rule is matched, returns exit code `3`. Set to `false` to see violations with exit code `0`.
`--sca`	Default: `false`	Selective scanners mode: run the SCA sub-scan. `--sca` alone also runs Contextual Analysis; combine with `--without-contextual-analysis` to run SCA only. Can be combined with `--secrets`.
`--without-contextual-analysis`	Default: `false`	Disable Contextual Analysis after `--sca`. Relevant only with `--sca`.
`--secrets`	Default: `false`	Selective scanners mode: run the Secrets sub-scan. Can be combined with `--sca`.
`--min-severity`	Optional	Minimum severity of issues to display: `Low`, `Medium`, `High`, `Critical`, or `Scanned - No Issues`.
`--fixable-only`	Default: `false`	Display only issues that have a fix version.
`--extended-table`	Default: `false`	Include extended fields such as CVSS and Xray Issue Id. Ignored unless `--format` is `table`.
`--bypass-archive-limits`	Default: `false`	Bypass the indexer-app archive size limits. May be required for large layers.

Arguments

Argument	Description
`Pattern`	Specifies the file system path to artifacts. Supports wildcards.

Examples

Scan all vulnerabilities: Scans img1:1.0.0 and displays all known vulnerabilities.

jf docker scan reg1/repo1/img1:1.0.0

Scan with project policies: Displays violations for my-project.

jf docker scan reg1/repo1/img1:1.0.0 --project my-project

Scan with Xray watch: Shows violations based on my-watch.

jf docker scan reg1/repo1/img1:1.0.0 --watches my-watch

Scan with repository path: Displays violations for releases-local/app1/.

jf docker scan reg1/repo1/img1:1.0.0 --repo-path releases-local/app1/

Scanning Image Tarballs on the Local File System

Use the scan command to scan tarballs of Docker and OCI images saved on the local file system.

It requires saving the image as a tar file using a compliant tool and then scanning it with the jf s command.

Examples

Using Docker

Save and scan an image:

docker save --output my-image-docker.tar my-image:1.0.0
jf s my-image-docker.tar

Using Skopeo

Scan Docker format:

skopeo copy docker-daemon:my-image:1.0.0 docker-archive:my-image-docker.tar
jf s my-image-docker.tar

Scan OCI format:

skopeo copy docker-daemon:my-image:1.0.0 oci-archive:my-image-oci.tar
jf s my-image-oci.tar

Using Podman

Scan Docker format:

podman save --format=docker-archive -o my-image-docker.tar my-image:1.0.0
jf s my-image-docker.tar

Scan OCI format:

podman save --format=oci -o my-image-oci.tar my-image:1.0.0
jf s my-image-oci.tar

Using Kaniko

Build and scan an image:

docker run -it --rm -v $(pwd):/workspace gcr.io/kaniko-project/executor:v1.8.1-debug -f Dockerfile --no-push --tarPath my-image.tar -d my-image:1.0 -c . --cleanup
jf s my-image.tar

View Binary Scan Results

This topic describes how to view scan results as part of On-Demand Binary scans.

View Results in Your CLI

Using the --format command, results are returned in a table format by default.

View Results in the JFrog Platform

In the platform, navigate to Platform > Xray > On-Demand Scanning.
A list with all the on-demand binary scans is displayed.
Select a scan from the list to view the results.
The overview window opens, showing security and license violations, security vulnerabilities, discovered licenses, and descendants.
(Optional) Export the scan results to CSV, PDF, and JSON formats by clicking on the action icon in the scan list.