Bitbucket

Picket can scan Bitbucket Cloud and Bitbucket Data Center repositories through native source enumeration for picket scan.

Bitbucket Cloud

Repository Scans

picket scan --bitbucket-repository willibrandon/picket --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Repository scans resolve the main branch when --bitbucket-ref is omitted, list repository directories through the Bitbucket source API, and download raw file bytes through the same source endpoint:

picket scan --bitbucket-repository willibrandon/picket --bitbucket-ref main --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Workspace scans list repositories in a workspace and scan each visible repository. When --bitbucket-ref is provided, the same branch, tag, or commit is used for each repository; otherwise Picket resolves each repository’s main branch:

picket scan --bitbucket-workspace willibrandon --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Project scans validate the project key, list matching workspace repositories through Bitbucket’s repository filter, and scan each returned repository:

picket scan --bitbucket-workspace willibrandon --bitbucket-project CORE --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Workspace snippet scans are explicit opt-ins and run alongside workspace repository scanning:

picket scan --bitbucket-workspace willibrandon --bitbucket-include-snippets --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Repository download artifacts are explicit opt-ins:

picket scan --bitbucket-repository willibrandon/picket --bitbucket-include-downloads --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Download artifact scans list the repository downloads, request each artifact by filename, accept Bitbucket’s documented redirect response, and fetch the redirected artifact URL without forwarding the Bitbucket credential. Archive artifacts are expanded with the native archive limits.

Pipeline step logs are explicit opt-ins for a selected repository pipeline:

picket scan --bitbucket-repository willibrandon/picket --bitbucket-pipeline-id pipeline-uuid --bitbucket-include-pipeline-logs --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Pipeline log scans list the selected pipeline’s steps, request each step log, accept Bitbucket’s documented redirect response, and fetch redirected log bytes without forwarding the Bitbucket credential.

Workspace snippet scans list snippets in the selected workspace, fetch snippet metadata to discover file names, and download raw snippet files through the snippet file API. Snippet raw-file redirects are followed only when they stay on the configured Bitbucket API endpoint, because those redirected API requests still require the Bitbucket credential.

Pull request scans resolve the source commit through the Bitbucket pull requests API, switch to the returned source repository when the pull request comes from a fork, and then scan that source commit:

picket scan --bitbucket-repository willibrandon/picket --bitbucket-pull-request 7 --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Repository URLs are accepted:

picket scan --bitbucket-repository https://bitbucket.org/willibrandon/picket --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Self-hosted tests or explicitly accepted gateway deployments can use an explicit API endpoint:

picket scan --bitbucket-api-endpoint https://api.bitbucket.org/2.0/ --bitbucket-repository team/platform --bitbucket-token-env PICKET_BITBUCKET_SOURCE_TOKEN --report-format jsonl

Options

Option	Behavior
--bitbucket-repository	Repository to scan as a workspace/repository path or repository URL.
--bitbucket-workspace	Workspace whose visible repositories should be scanned. Cannot be combined with --bitbucket-repository or --bitbucket-pull-request.
--bitbucket-project	Project key used to limit workspace repository scanning. Requires --bitbucket-workspace; cannot be combined with --bitbucket-include-snippets.
--bitbucket-ref	Optional branch, tag, or commit SHA. Empty uses the repository main branch.
--bitbucket-pull-request	Optional pull request ID. Resolves and scans the source commit. Cannot be combined with --bitbucket-ref.
--bitbucket-include-downloads	Also scan repository download artifacts. With --bitbucket-workspace, applies to each enumerated repository. Cannot be combined with --bitbucket-pull-request.
--bitbucket-pipeline-id	Pipeline ID whose step logs should be scanned. Requires --bitbucket-repository and --bitbucket-include-pipeline-logs; cannot be combined with --bitbucket-pull-request.
--bitbucket-include-pipeline-logs	Also scan step logs from the selected Bitbucket pipeline. Requires --bitbucket-pipeline-id.
--bitbucket-include-snippets	Also scan workspace snippet files. Requires --bitbucket-workspace.
--bitbucket-token-env	Environment variable containing the Bitbucket token or app password.
--bitbucket-token-kind	Credential mode. bearer is the default. app-password uses HTTP Basic authentication.
--bitbucket-username-env	Environment variable containing the Bitbucket username for app-password mode.
--bitbucket-api-endpoint	Bitbucket Cloud API endpoint used for repository enumeration. Defaults to https://api.bitbucket.org/2.0/.
--allow-non-public-source-endpoints	Permit private, loopback, link-local, or otherwise non-public endpoint addresses for trusted tests.
--allow-insecure-source-endpoints	Permit HTTP endpoints for trusted local tests or explicitly accepted deployments; source credentials may be sent in cleartext.

API Flow

Source	API behavior
Workspace repositories	Lists repositories in a workspace with pagelen=100, follows Bitbucket pagination, and scans each returned repository path.
Project metadata	Validates --bitbucket-project through the workspace project API before listing repositories.
Project repositories	Lists workspace repositories with a project.key query filter and scans each returned repository path.
Workspace snippets	Lists snippets in a workspace with pagelen=100, fetches snippet metadata for file names, and downloads raw snippet files through the snippet file API.
Repository metadata	Resolves the main branch when --bitbucket-ref is omitted.
Pull request metadata	Resolves the source commit hash and source repository when --bitbucket-pull-request is used.
Directory listings	Lists repository directory contents page by page with pagelen=100. Picket walks returned commit_directory entries instead of relying on max_depth.
Raw repository files	Downloads raw bytes for returned commit_file entries.
Download artifacts	Lists repository downloads with pagelen=100, requests each artifact by filename, follows Bitbucket’s artifact redirect without credentials, and scans the downloaded bytes.
Pipeline step logs	Lists pipeline steps with pagelen=100, requests each step log, follows Bitbucket’s log redirect without credentials, and scans the downloaded bytes.

Limits

Workspace repository and directory listing pagination follows Bitbucket’s next response field while more entries are available. Picket caps each paged list at 1,000 pages and emits a warning if that safety limit is reached.

Remote downloads use a 100 decimal MB default cap. --max-target-megabytes overrides that cap with a positive value. Zero keeps its local-scan compatibility meaning, but remote Bitbucket sources reject zero because remote HTTP bodies are always bounded.

Provider metadata JSON responses are capped at 10 decimal MB and skipped with a warning when the cap is exceeded.

Oversized directory entries are skipped before download when Bitbucket returns a size.

Oversized download artifacts are skipped before download when Bitbucket returns a size. Download artifact archives respect --max-archive-depth, --max-archive-entries, --max-archive-megabytes, --max-archive-ratio, and --max-target-megabytes.

Pipeline step logs use the same remote byte cap as repository files.

Snippet file downloads use the same remote byte cap as repository files. Raw snippet redirects are followed only when the redirected URI stays on the configured API endpoint.

Credentials

Credentials are read from environment variables. Bearer mode sends Authorization: Bearer .... App-password mode sends HTTP Basic authentication using the username from --bitbucket-username-env and the app password from --bitbucket-token-env.

Least-privilege repository and workspace enumeration requires read-only repository access for repository listings, repository metadata, source directory listings, raw source file content, and download artifacts. Project-scoped scans also require read-only project access for project metadata. Pull request scans also require read-only pull request access. Snippet scans require read-only snippet access. Pipeline log scans require read-only pipeline access. For OAuth-style tokens, Bitbucket documents the repository scope for source and download enumeration, the project scope for project metadata, the pullrequest scope for pull request metadata, the snippet scope for snippet enumeration, and the pipeline scope for pipeline step and log enumeration. For API tokens, Bitbucket documents read:repository:bitbucket, read:project:bitbucket, read:pullrequest:bitbucket, read:snippet:bitbucket, and read:pipeline:bitbucket.

Bitbucket Data Center

The Data Center selector requires the REST API base path, project key, and an environment variable containing the credential. Specify a repository slug to scan one repository:

picket scan --bitbucket-data-center-api-endpoint https://bitbucket.example/rest/api/1.0/ --bitbucket-data-center-project CORE --bitbucket-data-center-repository picket --bitbucket-data-center-token-env PICKET_BITBUCKET_DC_TOKEN --report-format jsonl

Omit the repository to list and scan every readable repository in the project:

picket scan --bitbucket-data-center-api-endpoint https://bitbucket.example/rest/api/1.0/ --bitbucket-data-center-project CORE --bitbucket-data-center-token-env PICKET_BITBUCKET_DC_TOKEN --report-format jsonl

An explicit branch, tag, or commit is resolved to an immutable commit before file enumeration:

picket scan --bitbucket-data-center-api-endpoint https://bitbucket.example/rest/api/1.0/ --bitbucket-data-center-project CORE --bitbucket-data-center-repository picket --bitbucket-data-center-ref main --bitbucket-data-center-token-env PICKET_BITBUCKET_DC_TOKEN --report-format jsonl

Pull request scans resolve and scan the source commit and source repository, including a fork when Bitbucket returns one:

picket scan --bitbucket-data-center-api-endpoint https://bitbucket.example/rest/api/1.0/ --bitbucket-data-center-project CORE --bitbucket-data-center-repository picket --bitbucket-data-center-pull-request 7 --bitbucket-data-center-token-env PICKET_BITBUCKET_DC_TOKEN --report-format jsonl

Options

Option	Behavior
--bitbucket-data-center-api-endpoint	Required REST API endpoint, including the rest/api/1.0 path. No public default is assumed.
--bitbucket-data-center-project	Required project key. When no repository is supplied, every readable repository in the project is scanned.
--bitbucket-data-center-repository	Optional repository slug. Required for pull request scans.
--bitbucket-data-center-ref	Optional branch, tag, or 40- or 64-character commit ID. Empty resolves the repository default branch.
--bitbucket-data-center-pull-request	Optional positive pull request ID. Resolves the source repository and commit; cannot be combined with --bitbucket-data-center-ref.
--bitbucket-data-center-token-env	Required environment variable containing an HTTP access token or Basic credential.
--bitbucket-data-center-token-kind	Credential mode: bearer by default or basic.
--bitbucket-data-center-username-env	Environment variable containing the username required by basic mode.
--allow-non-public-source-endpoints	Permit a trusted private, loopback, or otherwise non-public Data Center endpoint. Most private installations require this explicit opt-in.
--allow-insecure-source-endpoints	Permit HTTP for an explicitly accepted endpoint. HTTPS remains the default because credentials otherwise travel in cleartext.

API Flow

Source	API behavior
Project repositories	Lists /projects/{projectKey}/repos with limit=100 and follows the server-provided nextPageStart cursor.
Default branch	Reads /default-branch, with the older /branches/default route as a compatibility fallback, and uses the returned immutable commit when available.
Named ref	Resolves a branch or tag through the commits API with until={ref} and scans the returned commit ID.
Pull request	Reads fromRef.latestCommit and its repository/project identity, then scans that exact source commit.
Repository files	Lists /files recursively at the resolved commit with limit=100 and follows nextPageStart.
Raw file content	Downloads /raw/{path} at the resolved commit only after path filtering.

Safety and Limits

• Endpoint safety is checked before the first request and again for the address used by the HTTP connection.
• HTTPS is required unless insecure source endpoints are explicitly allowed.
• Redirects are disabled. Responses already redirected by an injected handler are rejected.
• Retryable throttling and service responses are retried once with bounded Retry-After handling.
• Provider metadata JSON is capped at 10 decimal MB.
• Project and file pagination stop at 1,000 pages. Picket uses nextPageStart exactly as returned and stops on missing, non-numeric, or non-advancing cursors.
• File downloads use a 100 decimal MB default cap. A positive --max-target-megabytes overrides it, and the streamed body remains capped when Content-Length is missing or understated.
• Provider paths are normalized before request and display-path construction. Duplicate paths and globally ignored paths are skipped before download.

Credentials

Bearer mode sends Authorization: Bearer .... Basic mode sends HTTP Basic authentication using the username from --bitbucket-data-center-username-env and the credential from --bitbucket-data-center-token-env. Credential values are read from the environment and are not written to command lines, reports, or warnings.

The selected account or access token needs read access to the project, repository metadata, commit and branch metadata, file listings, and raw file content. Pull request scans also need read access to pull request metadata. Picket does not require repository write, project administration, or token administration permissions.

Current Scope

Bitbucket Cloud supports repository files, workspace repositories, project-scoped workspace repositories, workspace snippets, pull request source heads, repository download artifacts, and repository pipeline step logs. Pipeline artifact downloads are not exposed as a direct Bitbucket Cloud REST download endpoint; scan those artifacts through repository downloads or another supported source.

Bitbucket Data Center supports one repository, every readable repository in a project, an explicit ref, and a pull request source head. Download artifacts, pipeline logs, and snippets remain Cloud-only selectors.

References

• Bitbucket Cloud REST API: https://developer.atlassian.com/cloud/bitbucket/rest/
• Bitbucket source API: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-source/
• Bitbucket repository API: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/
• Bitbucket projects API: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-projects/
• Bitbucket pull requests API: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/
• Bitbucket downloads API: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-downloads/
• Bitbucket pipelines API: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines/
• Bitbucket snippets API: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-snippets/
• Bitbucket Data Center REST introduction: https://developer.atlassian.com/server/bitbucket/rest/v1000/intro/
• Bitbucket Data Center repository API: https://developer.atlassian.com/server/bitbucket/rest/v1000/api-group-repository/
• Bitbucket Data Center pull requests API: https://developer.atlassian.com/server/bitbucket/rest/v1000/api-group-pull-requests/
• Bitbucket Data Center personal access tokens: https://confluence.atlassian.com/bitbucketserver/managing-personal-access-tokens-1005339986.html