Command Line Interface

A scanpipe command can be executed through the docker compose command line interface with:

docker compose exec -it web scanpipe COMMAND

Alternatively, you can start a bash session in a new Docker container to execute multiple scanpipe commands:

docker compose run web bash
scanpipe COMMAND
scanpipe COMMAND
...

Warning

In order to add local input files to a project using the Command Line Interface, extra arguments need to be passed to the docker compose command.

For instance --volume /path/on/host:/target/path/in/container:ro will mount and make available the host path inside the container (:ro stands for read only).

docker compose run --volume /home/sources:/sources:ro \
    web scanpipe create-project my_project --input-file="/sources/image.tar"

Note

In a local development installation, the scanpipe command is directly available as an entry point in your virtualenv and is located at <scancode.io_root_dir>/bin/scanpipe.

$ scanpipe –help

Lists all sub-commands available, including Django built-in commands. ScanPipe’s own commands are listed under the [scanpipe] section:

$ scanpipe --help
...
[scanpipe]
    add-input
    add-pipeline
    archive-project
    create-project
    delete-project
    execute
    graph
    list-project
    output
    show-pipeline
    status

$ scanpipe <subcommand> –help

Displays help for the provided sub-command.

For example:

$ scanpipe create-project --help
usage: scanpipe create-project [--input-file INPUTS_FILES]
    [--input-url INPUT_URLS] [--copy-codebase SOURCE_DIRECTORY]
    [--pipeline PIPELINES] [--execute] [--async]
    name

Create a ScanPipe project.

positional arguments:
  name                  Project name.

$ scanpipe create-project <name>

Creates a ScanPipe project using <name> as a Project name. The project name must be unique.

Optional arguments:

--pipeline PIPELINES Pipelines names to add on the project.
--input-file INPUTS_FILES Input file locations to copy in the input/ work directory.
--input-url INPUT_URLS Input URLs to download in the input/ work directory.
--copy-codebase SOURCE_DIRECTORY Copy the content of the provided source directory into the codebase/ work directory.
--execute Execute the pipelines right after project creation.
--async Add the pipeline run to the tasks queue for execution by a worker instead of running in the current thread. Applies only when --execute is provided.

Warning

Pipelines are added and are executed in order.

$ scanpipe list-project [–search SEARCH] [–include-archived]

Lists ScanPipe projects.

Optional arguments:

--search SEARCH Limit the projects list to this search results.
--include-archived Include archived projects.

Tip

Only the project names are listed by default. You can display more details about each project by providing the --verbosity 2 or --verbosity 3 options.

$ scanpipe add-input –project PROJECT [–input-file FILES] [–input-url URLS]

Adds input files in the project’s work directory.

--input-file INPUTS_FILES Input file locations to copy in the input/ work directory.
--input-url INPUT_URLS Input URLs to download in the input/ work directory.
--copy-codebase SOURCE_DIRECTORY Copy the content of the provided source directory into the codebase/ work directory.

For example, assuming you have created beforehand a project named “foo”, this will copy ~/docker/alpine-base.tar to the foo project input/ directory:

$ scanpipe add-input --project foo --input-file ~/docker/alpine-base.tar

Warning

Make sure to mount your local sources volume in the Docker setup:

--volume /host/sources:/sources:ro --input-file /sources/image.tar

You can also provide URLs of files to be downloaded to the foo project input/ directory:

$ scanpipe add-input --project foo --input-url https://github.com/nexB/scancode.io-tutorial/releases/download/sample-images/30-alpine-nickolashkraus-staticbox-latest.tar

Note

Docker images can be provided as input using their Docker reference with the docker://docker-reference syntax. For example:

$ [...] --input-url docker://redis
$ [...] --input-url docker://postgres:13
$ [...] --input-url docker://docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2

See https://docs.docker.com/engine/reference/builder/ for more details about references.

$ scanpipe add-pipeline –project PROJECT PIPELINE_NAME [PIPELINE_NAME …]

Adds the PIPELINE_NAME to a given PROJECT. You can use more than one PIPELINE_NAME to add multiple pipelines at once.

Warning

Pipelines are added and are executed in order.

For example, assuming you have created beforehand a project named “foo”, this will add the docker pipeline to your project:

$ scanpipe add-pipeline --project foo docker

$ scanpipe execute –project PROJECT

Executes the next pipeline of the PROJECT project queue.

Optional arguments:

--async Add the pipeline run to the tasks queue for execution by a worker instead of running in the current thread.

$ scanpipe show-pipeline –project PROJECT

Lists all the pipelines added to the PROJECT project.

$ scanpipe status –project PROJECT

Displays status information about the PROJECT project.

Note

The full logs of each pipeline execution are displayed by default. This can be disabled providing the --verbosity 0 option.

$ scanpipe output –project PROJECT –format {json,csv,xlsx,spdx,cyclonedx,attribution}

Outputs the PROJECT results as JSON, XLSX, CSV, SPDX, CycloneDX, and Attribution. The output files are created in the PROJECT output/ directory.

Multiple formats can be provided at once:

$ scanpipe output --project foo --format json xlsx spdx cyclonedx attribution

Optional arguments:

--print Print the output to stdout instead of creating a file. This is not compatible with the XLSX and CSV formats. It cannot be used when multiple formats are provided.

$ scanpipe graph [PIPELINE_NAME …]

Generates one or more pipeline graph image as PNG using Graphviz. The output images are named using the pipeline name with a .png extension.

Optional arguments:

--list Displays a list of all available pipelines.
--output OUTPUT Specifies the directory to which the output is written.

Note

By default, output files are created in the current working directory.

$ scanpipe archive-project –project PROJECT

Archives a project and remove selected work directories.

Optional arguments:

--remove-input Remove the input/ directory.
--remove-codebase Remove the codebase/ directory.
--remove-output Remove the output/ directory.
--no-input Does not prompt the user for input of any kind.

$ scanpipe reset-project –project PROJECT

Resets a project removing all database entrie and all data on disks except for the input/ directory.

Optional arguments:

--no-input Does not prompt the user for input of any kind.

$ scanpipe delete-project –project PROJECT

Deletes a project and its related work directories.

Optional arguments:

--no-input Does not prompt the user for input of any kind.

$ scanpipe create-user <username>

Note

This command is to be used when ScanCode.io’s authentication system SCANCODEIO_REQUIRE_AUTHENTICATION is enabled.

Creates a user and generates an API key for authentication.

You will be prompted for a password. After you enter one, the user will be created immediately.

The API key for the new user account will be displayed on the terminal output.

User <username> created with API key: abcdef123456

The API key can also be retrieved from the Profile settings menu in the UI.

Warning

Your API key is like a password and should be treated with the same care.

By default, this command will prompt for a password for the new user account. When run non-interactively with the --no-input option, no password will be set, and the user account will only be able to authenticate with the REST API using its API key.

Optional arguments:

--no-input Does not prompt the user for input of any kind.