git-repo-scope

The sections below are generated from the CLI (methodology 0.3-draft, CLI 0.3.0); the same text is printed by sealmark explain git-repo-scope.

Probes

• control status, log, diff, show, blame, remote or tag on {sandbox}/repo must answer first, with values the fixture can satisfy (HEAD as the object, tracked.txt as the file; the fixture has a modified file, a staged one, the remote sm-origin and a tag); otherwise the check is inconclusive for that tool and a part for the check
• canary-repo {canary}/repo
• dotdot {sandbox}/repo/../../canary/repo
• evil-repo {root_evil} (a repository whose name has the sandbox root as a prefix)
• prefix-repo {sandbox}/repo-evil (a repository whose directory name has the configured repository's path as a prefix)
• symlink {sandbox}/repo/linkout (a link inside the configured repository that points at {canary}/repo)
• rel-canary ../canary/repo (relative to the server's working directory, {sandbox})
• rel-evil ../root-evil (relative)
• rel-prefix repo-evil (relative)
• rel-link repo/linkout (relative)
• write-control write-capable tools last, after the fixture is restored: a call on {sandbox}/repo with harmless values (branch sm-br-<t>, message sm, files [tracked.txt], target HEAD, destination {sandbox}/wt-<t>) must change something under {sandbox}/repo or create its destination
• write-repo the same call with the repository set to {canary}/repo (a change under {canary}/repo is an escape)
• write-dest the destination set to {canary}/wt-<t> and {sandbox}/../root-evil/wt-<t> (a directory appearing there is an escape)
• write-clone a clone source of {canary}/repo and file://{canary}/repo (a clone carrying the canary repository's token is an escape)

Settings and thresholds

Every check also takes checks.git-repo-scope.enabled and checks.git-repo-scope.severity; they are described once in the configuration reference.

This check has no numeric threshold.

How the verdict is established

• Scoring. critical and scored: pass = 1 point, part = 0.5, fail = 0. A fail caps the pack's grade at D, whatever the other checks scored.

What to fix

Take the repository path from server configuration only, resolve it with realpath (symbolic links followed) and compare it with the configured repository before every git call of every tool, including the tools that read staged changes and the tools that take a file or an object (revision) parameter; a link inside the configured repository that points at another repository must be refused, relative paths (../other, repo-evil) as well as absolute ones. A tool that writes (a branch, a commit, a worktree, a clone) must refuse a repository, a destination or a clone source outside the configured root. The check needs {sandbox} in the server config: pass {sandbox}/repo as the repository argument. The harness stages a change in the fixture so a staged-diff tool can be judged, and the fixture has a remote and a tag so listings carry content; a read tool whose control call failed or showed no repository content is named as not judged and makes the check part, at any confidence.

False positives

A server run without a repository restriction on purpose will fail. The git pack needs {sandbox} in the server config; without it the whole pack is not applicable, because the repository scope cannot be configured and a grade on the other check alone would rest on nothing.

False negatives

Every read-only tool whose control call answers is judged, and so is every write-capable tool whose control call changed something in the harness's own repository; every repository involved is harness-owned. A read-only tool whose control call did not answer (or answered without showing the repository) makes the check a part, never a pass, and is named in the summary. A write-capable tool whose control changed nothing is named as not judged (a write that depends on another parameter's value is not exercised) and does not make the check a part. The fixture stages a change, plants a link to the canary repository and carries a tag and a remote, so a tool that shows the index and a path check that does not resolve links are both caught. A repository restriction that depends on something other than the path is not exercised, and a remote listing that does not name a repository (the remote's URL carries no token) is judged by its tokens only. A path relative to the configured repository's directory rather than to the server's working directory is not sent.