NAME

sq-git - A tool to help protect a project's supply chain.

SYNOPSIS

sq-git init [OPTIONS]
sq-git policy [OPTIONS] SUBCOMMAND
sq-git log [OPTIONS] COMMIT_RANGE
sq-git verify [OPTIONS]
sq-git update-hook [OPTIONS] REF_NAME OLD_OBJECT NEW_OBJECT
sq-git version [OPTIONS]

DESCRIPTION

sq-git is a tool that can help improve a project's supply chain security.

To use sq-git, you add a policy file (`openpgp-policy.toml`) to the root of a git repository. The policy file includes a list of OpenPGP certificates, and the types of changes they are authorized to make. The capabilities include adding a commit, and authorizing a new certificate. See the sq-git init and sq-git policy subcommands for more details.

A commit is considered authorized if the commit is signed, and at least one immediate parent commit's policy authorizes the signer's certificate to make that type of change.

A downstream user authenticates a version of the project using the sq-git log subcommand. They specify a trust root (a commit), which they've presumably audited, and sq-git log looks for an authenticated path from the trust root to the current HEAD. If there is an authenticated path, then there is evidence that the project's maintainers authorized all of the intermediate changes.

To find an authenticated path, sq-git starts with the current commit, and tries to authenticate it using each of its parent commits. It repeats this process for each parent commit that authenticated it. If the trust root is reached, then the version is considered authenticated.

OPTIONS

Global options

--cert-store=PATH

Specify the location of the certificate store

By default, sq-git uses the OpenPGP certificate directory in Sequoia's home directory (see --home), $HOME/.local/share/pgp.cert.d. This can be overridden by using this options, or setting the either the SEQUOIA_CERT_STORE or the PGP_CERT_D environment variable.

Use default to explicitly use the default cert store, use none to not use a cert store.

-h, --help

Print help (see a summary with '-h')

--home=PATH

Set the home directory

Sequoia's default home directory is $HOME. When using the default location, files are placed according to the local standard, e.g., the XDG Base Directory Specification. When an alternate location is specified, the user data, configuration files, and cache data are placed under a single, unified directory. This is a lightweight way to partially isolate Sequoia programs.

Use default to explicitly use the default location, use none to not use a home directory.

--output-format=FORMAT

Produces output in the specified format, if possible

[default: human-readable]

[possible values: human-readable, json]

SUBCOMMANDS

sq-git init

Suggests how to create a policy.

Suggests how to create a policy by analyzing recent commits. The heuristic considers signed commits on the current branch that were made over the past half year, and suggests that the most frequent committer be made the project maintainer, and other committers be made committers.

Note: This is a *simple* heuristic; its recommendations should be viewed as a starting point. In particular, you still need to do some due diligance. It is essential that you review the suggested roles, and check that people actually control the certificates. Ideally, you should ask each person for their OpenPGP fingerprint in person. But in the very least you should ask them via email.

sq-git policy

Describe, update, and change the OpenPGP policy.

sq-git log

Lists and verifies commits.

Lists and verifies that the commits from the given trust root to the target commit adhere to the policy.

A version is considered authenticated if there is a path from the trust root to the target commit on which each commit can be authenticated by its parent.

If the key used to sign a commit is hard revoked, then the commit is considered bad. sq-git looks for hard revocations in all of the commits that it examines. Thus, if a project maintainer adds a hard revocation to a commit's policy file, it will cause later *and* earlier commits signed with that key to be considered invalid. This is useful when a key has been compromised.

When a key has been hard revoked, downstream users either need to start using a more recent trust root, or the upstream project maintainers need to audit the relevant commits. If the commits are considered benign, they can be added to a goodlist using sq-git policy goodlist. When a commit is considered authenticated, but the certificate has been hard revoked, sq-git looks to see whether the commit has been goodlisted by a commit that is on an authenticated path from the commit in question to the target. If so, the commit is considered to be authenticated.

sq-git verify

Verifies signatures on archives like release tarballs.

sq-git update-hook

A git update hook that enforces the policy.

Insert the following line into hooks/update on the shared git server to make it enforce the policy embedded in the repository starting at the trust root COMMIT.

sq-git update-hook --trust-root=<COMMIT> "$@"

When a branch is pushed that is not previously known to the server, sq-git update-hook checks that all commits starting from the trust root to the pushed commit adhere to the policy.

When a branch is pushed that is previously known to the server, i.e. the branch is updated, sq-git update-hook checks that all new commits starting from the commit previously known to the server to the pushed commit adhere to the policy. If there is no path from the previously known commit to the new one, the branch has been rebased. Then, we fall back to searching for a path from the trust root.

sq-git version

Detailed version and output version information.

With no further options, this command lists the version of sq-git, the version of the underlying OpenPGP implementation sequoia-openpgp, and which cryptographic library it uses.

ENVIRONMENT

SEQUOIA_CERT_STORE=PATH

Specify the location of the certificate store

By default, sq-git uses the OpenPGP certificate directory in Sequoia's home directory (see --home), $HOME/.local/share/pgp.cert.d. This can be overridden by using this options, or setting the either the SEQUOIA_CERT_STORE or the PGP_CERT_D environment variable.

Use default to explicitly use the default cert store, use none to not use a cert store.

SEQUOIA_HOME=PATH

Set the home directory

Sequoia's default home directory is $HOME. When using the default location, files are placed according to the local standard, e.g., the XDG Base Directory Specification. When an alternate location is specified, the user data, configuration files, and cache data are placed under a single, unified directory. This is a lightweight way to partially isolate Sequoia programs.

Use default to explicitly use the default location, use none to not use a home directory.

EXAMPLES

sq-git init

Inspects the current branch and suggests how to create a policy.

sq-git init

SEE ALSO

sq-git-init(1), sq-git-policy(1), sq-git-log(1), sq-git-verify(1), sq-git-update-hook(1), sq-git-version(1).

For the full documentation see <https://sequoia-pgp.gitlab.io/sequoia-git>.

VERSION

0.4.0