Repository Scanning

Repository Scanning

prowl repo <git-url> [flags]

Clone a remote git repository and scan it. Works with any git URL — GitHub, GitLab, Bitbucket, or a self-hosted server. The repository is cloned into a temporary directory, scanned, and the checkout is removed afterwards; nothing is left on disk.

To scan many repositories at once, see Org-Wide Scanning. To scan a built container image instead of source, see Container Scanning; to scan an S3 / GCS prefix, see Cloud Storage Scanning.

By default prowl repo does a fast shallow clone (depth 1) of the remote's default branch and scans the resulting working tree. Add --history to scan every blob in the repository's history instead.

prowl repo accepts every prowl scan flag (verification, fail-on gating, output format, rule selection, baselines, …) in addition to the clone-specific flags below.

Flags

Flag	Description
--history	Scan EVERY blob in the repository's history (git rev-list --objects --all) instead of just the working tree. Forces a full clone; --depth is ignored.
--branch NAME	Clone a specific branch or tag instead of the remote's default branch. Adds --single-branch.
--depth N	Shallow-clone depth (positive integer, default 1). Ignored with --history.
+ all scan flags	--verify, --verified-only, --fail-on, --format, -o/--output, --rules-dir, --rules, --tags, --exclude-tags, --rule-severity, --baseline, --exclude, --workers, --timeout, logging flags, … See Scanning Files.

Value flags accept both --flag value and --flag=value.

Tree scan vs. --history

Mode	What it clones	What it scans
default	A shallow clone (depth --depth, default 1) of the default branch (or --branch).	The checked-out working tree — the files as they exist at the tip of that branch.
--history	A full clone (all refs, full depth).	Every blob ever committed across all refs. Catches secrets that were removed from HEAD but still live in history.

Use the default mode for a quick "is there anything live in the current tree" pass; use --history when you need to know whether a secret was ever committed (the case that requires rotation even after a "fix" commit). A full-history scan is slower and downloads the whole repository, so combine it with --timeout on large repositories — partial results are still reported.

Authentication

prowl repo shells out to your local git, so it uses whatever credentials git already has. Private repositories work three ways:

• SSH keys — clone over SSH and your agent / ~/.ssh keys are used:

  prowl repo git@github.com:org/private-repo.git

• Credential helper — an HTTPS clone uses your configured git credential helper (the OS keychain, gh auth, a .git-credentials store, etc.), exactly as git clone would.

• Token in the URL — embed a personal access token / deploy token directly:

  prowl repo https://<token>@github.com/org/private-repo.git
  prowl repo https://oauth2:<token>@gitlab.com/group/private-repo.git

No prowl-specific credential configuration exists; if git clone <url> works in your shell, prowl repo <url> works.

Transport security

The clone is transport-hardened so a hostile URL cannot turn a scan into command execution:

• Only explicit, non-RCE transports are accepted: https://, http://, ssh://, git://, and the scp-like git@host:path form. A bare .git suffix is not sufficient — prowl repo ext::sh -c … is rejected outright.
• The git ext remote helper (which would run an arbitrary command from the URL) is disabled (protocol.ext.allow=never), and the file helper is restricted to the invoking user.
• The URL is passed after a -- separator so it can never be reinterpreted as a git flag.

This is the same hardening prowl rules update applies to remote rule sources. http:// is permitted here (unlike rule installation) because the target is a read-only scan target you chose, not executable rules. See Security Model.

Examples

# GitHub over HTTPS — shallow clone of the default branch, scan the tree
prowl repo https://github.com/org/repo

# GitLab over SSH — full history, gate CI on any high-or-worse finding
prowl repo git@gitlab.com:group/repo.git --history --fail-on high

# Bitbucket — scan a specific release branch
prowl repo https://bitbucket.org/team/repo --branch release

# Confirm hits are live against the provider's API
prowl repo https://github.com/org/repo --verify --verified-only

# SARIF artifact for a code-scanning dashboard, JSON logs for CI
prowl repo https://github.com/org/repo --format sarif -o repo.sarif --log-format json

See also

• Scanning Files
• CI/CD Integration
• Security Model
• Home