Repository Service for TUF CLI

repository-service-tuf is a Command Line Interface for the Repository Service for TUF.

Installation

Using pip:

$ pip install repository-service-tuf
 rstuf -h

Usage: rstuf [OPTIONS] COMMAND [ARGS]...

Repository Service for TUF Command Line Interface (CLI).

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --config        -c  TEXT  Repository Service for TUF config file. [default: /Users/kairo/.rstuf.yml]                 │
│ --version                 Show the version and exit.                                                                 │
│ --autocomplete            Enable tab autocompletion and exit.                                                        │
│ --help          -h        Show this message and exit.                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ admin                             Administrative  Commands                                                           │
│ admin-legacy                      Administrative (Legacy) Commands                                                   │
│ artifact                          Artifact Management Commands                                                       │
│ key                               Cryptographic Key Commands                                                         │
│ task                              Task Management Commands                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

RSTUF CLI configuration file

rstuf will try to read the settings configuration from a configuration file. See: --config/-c, default path to the configuration file is: $HOME/.rstuf.yml.

In this file, the following optional settings can be configured:

  • SERVER - The Repository Service for TUF API URL.

  • REPOSITORIES - TUF repositories used by rstuf artifact commands.

    Note

    You can generate or update this setting automatically by using rstuf artifact repository commands.

    This setting is a list of repositories with the following fields: name, trusted_root (base64), metadata_url, artifacts_url (bool), and hash_prefix.

    Example:

    REPOSITORIES:
        myrepo:
            artifact_base_url: http://127.0.0.1:8081
            hash_prefix: false
            metadata_url: http://127.0.0.1:8080
            trusted_root: aHR0cDovLzEyNy4wLjAuMTo4MDgwLzEucm9vdC5qc29u
    
  • DEFAULT_REPOSITORY - The default repository to be used by rstuf artifact commands.

    Note

    You can generate or update this setting automatically by using rstuf artifact repository commands.

Administration (admin)

It executes administrative commands to the Repository Service for TUF.

 rstuf admin

Usage: rstuf admin [OPTIONS] COMMAND [ARGS]...

Administrative Commands

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --api-server      TEXT  URL to an RSTUF API.                                                                               │
│ --headers     -H  TEXT  Headers to include in the request. Example: 'Authorization: Bearer <token>, Content-Type:          │
│                         application/json'                                                                                  │
│ --help        -h        Show this message and exit.                                                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ceremony                         Bootstrap Ceremony to create initial root metadata and RSTUF config.                      │
│ import-artifacts                 Import artifacts information from exported CSV file and send it to RSTUF API deployment.  │
│ metadata                         Metadata management.                                                                      │
│ send                             Send a payload to an existing RSTUF API deployment                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Ceremony (ceremony)

The Repository Service for TUF Metadata uses the following Roles: root, timestamp, snapshot, targets, and bins to build the Repository Metadata (for more details, check out TUF Specification and PEP 458).

The Ceremony is a complex process that Repository Service for TUF CLI tries to simplify. You can do the Ceremony offline. This means on a disconnected computer (recommended once you will manage the keys).

 rstuf admin ceremony -h

Usage: rstuf admin ceremony [OPTIONS]

Perform ceremony and send result to API to trigger bootstrap.
* If `--out [FILENAME]` is passed, result is written to local FILENAME
(in addition to being sent to API).

* If `--dry-run` is passed, result is not sent to API.
You can still pass `--out [FILENAME]` to store the result locally.
The `--api-server` admin option and `SERVER` from config will be ignored.

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────╮
│ --out          FILENAME  Write output json result to FILENAME (default: 'ceremony-payload.json')  │
│ --dry-run                Run ceremony in dry-run mode without sending result to API.              │
│ --help     -h            Show this message and exit.                                              │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯

There are four steps in the ceremony.

Note

We recommend running the rstuf admin ceremony to simulate and check the details of the instructions. It is more detailed.

Metadata Management (metadata)

❯ rstuf admin metadata

Usage: rstuf admin metadata [OPTIONS] COMMAND [ARGS]...

Metadata management.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help  -h    Show this message and exit.                                                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ sign               Add one signature to root metadata.                                                               │
│ update             Update root metadata and bump version.                                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

sign (sign)

Warning

Do not share the private key.

 rstuf admin metadata sign -h

Usage: rstuf admin metadata sign [OPTIONS]

Perform sign for pending event and send result to API.
* If `--in FILENAME` is passed, input is not read from API but from local FILENAME.
* If `--out [FILENAME]` is passed, result is written to local FILENAME (in addition to being sent to API).
* If `--dry-run` is passed, result is not sent to API. You can still pass `--out [FILENAME]` to store the result locally.
* If `--in` and `--dry-run` are passed, `--api-server` admin option and `SERVER` from config will be ignored.

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --in           FILENAME  Input file containing the JSON response from the 'GET /api/v1/metadata/sign' RSTUF API endpoint.  │
│ --out          FILENAME  Write output JSON result to FILENAME (default: 'sign-payload.json')                               │
│ --dry-run                Run sign in dry-run mode without sending result to API.                                           │
│ --help     -h            Show this message and exit.                                                                       │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

update (update)

 rstuf admin metadata update -h

Usage: rstuf admin metadata update [OPTIONS]

Perform metadata update and send result to API.
* If `--metadata-url TEXT` is passed, the latest root will be fetched from metadata storage.
* If `--in FILENAME` is passed, input is not read from API but from local FILENAME.
* If both `--metadata-url TEXT` and `--in FILENAME` are passed, then `--metadata-url TEXT` will have higher priority.
* If `--out [FILENAME]` is passed, result is written to local FILENAME (in addition to being sent to API).
* If `--dry-run` is passed, result is not sent to API. You can still pass `--out [FILENAME]` to store the result locally.
* If `--in` and `--dry-run` are passed, `--api-server` admin option and `SERVER` from config will be ignored.

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────╮
│ --in                FILENAME  Input file containing current trusted root JSON.                 │
│ --metadata-url      TEXT      URL to the RSTUF API metadata storage.                           │
│ --out               FILENAME  Write json result to FILENAME (default: 'update-payload.json')   │
│ --dry-run                     Run update in dry-run mode without sending result to API.        │
│ --help          -h            Show this message and exit.                                      │
╰────────────────────────────────────────────────────────────────────────────────────────────────╯

Send generated payload (send)

send bootstrap (sign)

 rstuf admin --api-server <api-server-url> send bootstrap --help

Usage: rstuf admin send bootstrap [OPTIONS] BOOTSTRAP_PAYLOAD

Send payload and bootstrap to an existing RSTUF API deployment.
Note: 'BOOTSTRAP_PAYLOAD' argument must be generated by using:
'rstuf admin ceremony' command.

╭─ Options ──────────────────────────────────────────╮
│ --help  -h    Show this message and exit.          │
╰────────────────────────────────────────────────────╯

send metadata update (update)

 rstuf admin --api-server <api-server-url> send update --help

Usage: rstuf admin send update [OPTIONS] METADATA_UPDATE_PAYLOAD

Send metadata update payload to an existing RSTUF API deployment.
Note: 'METADATA_UPDATE_PAYLOAD' argument must be generated by using:
'rstuf admin metadata update' command.

╭─ Options ──────────────────────────────────────────╮
│ --help  -h    Show this message and exit.          │
╰────────────────────────────────────────────────────╯

send sign (sign)

 rstuf admin --api-server <api-server-url> send update --help

Usage: rstuf admin send sign [OPTIONS] SIGN_PAYLOAD

Send sign payload to an existing RSTUF API deployment.
Note: 'SIGN_PAYLOAD' argument must be generated by using:
'rstuf admin metadata sign' command.

╭─ Options ──────────────────────────────────────────╮
│ --help  -h    Show this message and exit.          │
╰────────────────────────────────────────────────────╯

Import Artifacts (import-artifacts)

This feature imports a large number of artifacts directly to RSTUF Database. RSTUF doesn’t recommend using this feature for regular flow, but in case you’re onboarding an existent repository that contains a large number of artifacts.

This feature requires extra dependencies:

pip install repository-service-tuf[psycopg2,sqlachemy]

To use this feature, you need to create CSV files with the content to be imported by RSTUF CLI.

This content requires the following data:

  • path: The artifact path

  • size: The artifact size

  • hash-type: The defined hash as a metafile. Example: blak2b-256

  • hash: The hash

The CSV must use a semicolon as the separator, following the format path;size;hash-type;hash without a header.

See the below CSV file example:

relaxed_germainv1.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
vigilant_keldyshv2.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
adoring_teslav3.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
funny_greiderv4.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
clever_ardinghelliv5.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
pbeat_galileov6.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
wonderful_gangulyv7.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
sweet_ardinghelliv8.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
brave_mendelv9.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
nice_ridev10.tar.gz;12345;blake2b-256;716f6e863f744b9ac22c97ec7b76ea5f5908bc5b2f67c61510bfc4751384ea7a
 rstuf admin import-artifacts -h

Usage: rstuf admin import-artifacts [OPTIONS]

Import artifacts information from exported CSV file and send it to RSTUF API deployment.
Note: there are two additional requirements for this command:

1) sqlalchemy needs to be installed in order to use this command:
pip install repository-service-tuf[sqlalchemy,psycopg2]

2) '--api-server' admin option or 'SERVER' in RSTUF config set

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ * –db-uri TEXT RSTUF DB URI. i.e.: postgresql://postgres:secret@127.0.0.1:5433 [required] │ │ * –csv TEXT CSV file to import. Multiple –csv parameters are allowed. See rstuf CLI guide for more details. [required] │ │ –skip-publish-artifacts Skip publishing artifacts in TUF Metadata. │ │ –help -h Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

❯ rstuf admin import-artifacts –db-uri postgresql://postgres:secret@127.0.0.1:5433 –csv artifacts-1of2.csv –csv artifacts-2of2.csv –api-server http://127.0.0.1:80/ Import status: Loading data from ../repository-service-tuf/tests/data/artifacts-1of2.csv Import status: Importing ../repository-service-tuf/tests/data/artifacts-1of2.csv data Import status: ../repository-service-tuf/tests/data/artifacts-1of2.csv imported Import status: Loading data from ../repository-service-tuf/tests/data/artifacts-2of2.csv Import status: Importing ../repository-service-tuf/tests/data/artifacts-2of2.csv data Import status: ../repository-service-tuf/tests/data/artifacts-2of2.csv imported Import status: Commiting all data to the RSTUF database Import status: All data imported to RSTUF DB Import status: Submitting action publish artifacts Import status: Publish artifacts task id is dd1cbf2320ad4df6bda9ca62cdc0ef82 Import status: task STARTED Import status: task SUCCESS Import status: Finished.

Artifact Management (artifact)

Manages artifacts using the RSTUF REST API.

❯ rstuf artifact

Usage: rstuf artifact [OPTIONS] COMMAND [ARGS]...

Artifact Management Commands

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help  -h    Show this message and exit.                                                                             │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ add                       Add artifacts to the TUF metadata.                                                          │
│ delete                    Delete artifacts to the TUF metadata.                                                       │
│ download                  Downloads artifacts to the TUF metadata.                                                    │
│ repository                Repository management.                                                                      │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Artifact Addition (add)

This command adds the provided artifact to the TUF Metadata using the RSTUF REST API.

❯ rstuf artifact add --help

Usage: rstuf artifact add [OPTIONS] FILEPATH

Add artifacts to the TUF metadata.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────------╮
│ --path        -p  TEXT  A custom path (`TARGETPATH`) for the file, defined in the metadata. [required] |
| --api-server      TEXT  URL to an RSTUF API.                                                           │
│ --help        -h        Show this message and exit.                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────------╯

Artifact Download (download)

This command allows downloading an artifact from a provided repository using the RSTUF REST API.

> rstuf artifact download --help

Usage: rstuf artifact download [OPTIONS] ARTIFACT_NAME

Downloads an artifact using TUF metadata from a given artifacts URL.
Note: all options for this command can be configured.
Read 'rstuf artifact repository' documentation for more information.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --root              -r  TEXT  A metadata URL to the initial trusted root or a local file.        │
│ --metadata-url      -m  TEXT  TUF Metadata repository URL.                                       │
│ --artifacts-url     -a  TEXT  An artifacts base URL to fetch from.                               │
│ --hash-prefix       -p        A flag to prefix an artifact with a hash.                          │
│ --directory-prefix  -P  TEXT  A prefix for the download dir.                                     │
│ --help              -h        Show this message and exit.                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

Artifact Repository (repository)

This command provides artifact repository management for the RSTUF repository config.

❯ rstuf artifact repository --help

Usage: rstuf artifact repository [OPTIONS] COMMAND [ARGS]...

Repository management.

╭─ Options ────────────────────────────────────────────────────────────────╮
│ --help  -h    Show this message and exit.                                │
╰──────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────╮
│ add                              Add a new repository.                   │
│ delete                           Delete a repository.                    │
│ set                              Switch current repository.              │
│ show                             List configured repositories.           │
│ update                           Update repository.                      │
╰──────────────────────────────────────────────────────────────────────────╯
❯ rstuf artifact repository add --help

Usage: rstuf artifact repository add [OPTIONS]

Add a new repository.

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *  --name           -n  TEXT  The repository name. [required]                                              │
│ *  --root           -r  TEXT  The metadata URL to the initial trusted root or a local file. [required]     │
│ *  --metadata-url   -m  TEXT  TUF Metadata repository URL. [required]                                      │
│ *  --artifacts-url  -a  TEXT  The artifacts base URL to fetch from. [required]                             │
│    --hash-prefix    -p        Whether to add a hash prefix to artifact names.                              │
│    --help           -h        Show this message and exit.                                                  │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
❯ rstuf artifact repository delete --help

Usage: rstuf artifact repository delete [OPTIONS] REPOSITORY

Delete a repository.
❯ rstuf artifact repository set --help

Usage: rstuf artifact repository set [OPTIONS] REPOSITORY

Switch current repository.
❯ rstuf artifact repository show --help

Usage: rstuf artifact repository show [OPTIONS] [REPOSITORY]

List configured repositories.
❯ rstuf artifact repository update --help

Usage: rstuf artifact repository update [OPTIONS] REPOSITORY

Update repository.

╭─ Options ─────────────────────────────────────────────────────────────────────────────────╮
│ --root           -r  TEXT  The metadata URL to the initial trusted root or a local file.  │
│ --metadata-url   -m  TEXT  TUF Metadata repository URL.                                   │
│ --artifacts-url  -a  TEXT  The artifacts base URL to fetch from.                          │
│ --hash-prefix    -p        Whether to add a hash prefix to artifact names.                │
│ --help           -h        Show this message and exit.                                    │
╰───────────────────────────────────────────────────────────────────────────────────────────╯

Task Management (task)

Manages tasks using the RSTUF REST API.

❯ rstuf task

Usage: rstuf task [OPTIONS] COMMAND [ARGS]...

Task Management Commands

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          -h    Show this message and exit.                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│ info          Retrieve task state.                                                               │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

Task Information (info)

This command retrieves the task state of the given task ID using the RSTUF REST API.

❯ rstuf task info --help

Usage: rstuf task info [OPTIONS] TASK_ID

Retrieve task state.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
│ --api-server      TEXT  RSTUF API URL, i.e., http://127.0.0.1                                    │
│ --help          -h    Show this message and exit.                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯