feat(ci): preserve pull request context in scan metadata

Author: lelia

docs/ci-cd.md

@@ -2,6 +2,10 @@
 
 Use this guide for pipeline-focused CLI usage across platforms.
 
+The shell commands in the recommended patterns are CI-provider neutral. Buildkite
+pipeline equivalents and provider-specific considerations are called out alongside
+the relevant guidance below.
+
 ## Recommended patterns
 
 ### Dashboard-style reachable SARIF
@@ -27,6 +31,27 @@ socketcli \
   --strict-blocking
 ```
 
+### Buildkite: retain SARIF as a build artifact
+
+Either recommended pattern can run directly in a Buildkite command step. When the
+scan writes SARIF, add
+[`artifact_paths`](https://buildkite.com/docs/pipelines/configure/artifacts#upload-artifacts-with-a-command-step)
+so developers can download the report from the build after the command finishes:
+
+```yaml
+steps:
+  - label: ":socket: Socket reachable diff"
+    command: |
+      socketcli \
+        --reach \
+        --sarif-file results.sarif \
+        --sarif-scope diff \
+        --sarif-reachability reachable \
+        --strict-blocking
+    artifact_paths:
+      - "results.sarif"
+```
+
 ## Config file usage in CI
 
 Use `--config .socketcli.toml` or `--config .socketcli.json` to keep pipeline commands small.
@@ -60,6 +85,9 @@ Equivalent JSON:
 }
 ```
 
+The Buildkite examples below use the same checked-in `.socketcli.toml` file; no
+Buildkite-specific config-file format is required.
+
 ## Platform examples
 
 ### GitHub Actions
@@ -73,14 +101,33 @@ Equivalent JSON:
 
 ### Buildkite
 
+This example assumes a GitHub-hosted repository. Change
+`SOCKET_SCM_INTEGRATION` to `gitlab` for a GitLab-hosted repository, or `api`
+when provider association is not wanted. The doubled dollar signs defer
+Buildkite variable expansion until the command runs on an agent.
+
 ```yaml
+env:
+  SOCKET_SCM_INTEGRATION: "github"
+
 steps:
   - label: "Socket scan"
-    command: "socketcli --config .socketcli.toml --target-path ."
-    env:
-      SOCKET_SECURITY_API_TOKEN: "${SOCKET_SECURITY_API_TOKEN}"
+    command: |
+      socketcli \
+        --config .socketcli.toml \
+        --target-path . \
+        --integration "$${SOCKET_SCM_INTEGRATION:-api}" \
+        --pr-number "$${BUILDKITE_PULL_REQUEST:-0}"
+    secrets:
+      - SOCKET_SECURITY_API_TOKEN
 ```
 
+The `secrets` block expects a
+[Buildkite secret](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets)
+named `SOCKET_SECURITY_API_TOKEN`. If your organization uses an external secrets
+plugin or an agent hook instead, remove that block and inject the same environment
+variable through your existing mechanism. Do not store the token in pipeline YAML.
+
 #### Merge-base baselines in Buildkite (dynamic pipelines)
 
 Notes for using `--base-commit-sha` (see the
@@ -139,6 +186,18 @@ socket_scan:
     SOCKET_SECURITY_API_TOKEN: $SOCKET_SECURITY_API_TOKEN
 ```
 
+### Azure Pipelines
+
+```yaml
+- script: |
+    socketcli \
+      --integration azure \
+      --enable-diff \
+      --target-path "$(Build.SourcesDirectory)"
+  env:
+    SOCKET_SECURITY_API_TOKEN: $(SOCKET_SECURITY_API_TOKEN)
+```
+
 ### Bitbucket Pipelines
 
 ```yaml
@@ -149,6 +208,44 @@ pipelines:
           - socketcli --config .socketcli.toml --target-path .
 ```
 
+## Pull request and Dashboard association
+
+The CLI sends the resolved pull request number with each full scan and attaches
+the pull request URL to diff scans so the Socket Dashboard can associate the
+report with its originating change. If `--pr-number` is supplied, it wins;
+passing `--pr-number 0` explicitly disables automatic association.
+
+Without an explicit value, the CLI recognizes:
+
+- GitHub Actions: `PR_NUMBER`, then the PR number in `GITHUB_REF`.
+- GitLab CI: `CI_MERGE_REQUEST_IID`.
+- Azure Pipelines: `SYSTEM_PULLREQUEST_PULLREQUESTNUMBER` for GitHub-hosted
+  repositories, otherwise `SYSTEM_PULLREQUEST_PULLREQUESTID` for Azure Repos.
+
+### Buildkite PR context
+
+Buildkite is SCM-provider neutral, so the CLI does not infer a provider or consume
+its PR variable automatically. Pass Buildkite's
+[`BUILDKITE_PULL_REQUEST`](https://buildkite.com/docs/pipelines/configure/environment-variables#BUILDKITE_PULL_REQUEST)
+value to
+`--pr-number` and identify the repository host with `--integration`, as shown in
+the Buildkite platform example above. Buildkite sets `BUILDKITE_PULL_REQUEST` to
+`false` outside PR builds; the CLI treats that value as no PR.
+
+Use `--integration github` for GitHub-hosted repositories and `--integration gitlab`
+for GitLab-hosted ones. In both cases the CLI reads the repository slug and host from
+[`BUILDKITE_REPO`](https://buildkite.com/docs/pipelines/configure/environment-variables#BUILDKITE_REPO)
+to build the pull request or merge request link, so github.com, GitLab.com, and
+self-hosted installations all work without extra configuration. Setting
+`CI_PROJECT_URL` still overrides the derived GitLab project URL. Keep `--scm api`
+unless you also intend to configure an existing GitHub or GitLab comment adapter and
+its provider token.
+
+`--scm github` and `--scm gitlab` also imply the matching scan integration for
+Dashboard metadata unless `--integration` was explicitly supplied. PR comments
+remain limited to the existing GitHub and GitLab SCM adapters; Azure receives
+console output and Dashboard association but does not post a PR comment.
+
 ## Workflow templates
 
 Prebuilt examples in this repo:
@@ -165,3 +262,11 @@ Prebuilt examples in this repo:
 - `--sarif-grouping alert` currently applies to `--sarif-scope full`.
 - Diff-based SARIF can validly be empty when there are no matching net-new alerts.
 - Keep API tokens in secret stores (`SOCKET_SECURITY_API_TOKEN`), not in config files.
+- In Buildkite pipeline YAML, follow its
+  [runtime interpolation](https://buildkite.com/docs/pipelines/configure/environment-variables#runtime-variable-interpolation)
+  guidance and use `$$` for variables that must expand when the command runs rather
+  than when the pipeline is uploaded.
+- Security findings with `props.firstPatchedVersionIdentifier` show that value in
+  the console table, including native Buildkite job logs, and in GitHub/GitLab
+  security comments when that SCM adapter is configured. Findings without a known
+  patched release leave the console cell blank and omit the comment field.

docs/cli-reference.md

@@ -175,7 +175,7 @@ If you don't want to provide the Socket API Token every time then you can use th
 | `--repo`           | False    | *auto*  | Repository name in owner/repo format (auto-detected from git remote)                                             |
 | `--workspace`      | False    |         | The Socket workspace to associate the scan with (e.g. `my-org` in `my-org/my-repo`). See note below.           |
 | `--repo-is-public` | False    | False   | If set, flags a new repository creation as public. Defaults to false.                                            |
-| `--integration`    | False    | api     | Integration type (api, github, gitlab, azure, bitbucket)                                                         |
+| `--integration`    | False    | api     | Integration type (api, github, gitlab, azure, bitbucket). When omitted, `--scm github` or `--scm gitlab` implies the matching integration. |
 | `--owner`          | False    |         | Name of the integration owner, defaults to the socket organization slug                                          |
 | `--branch`         | False    | *auto*  | Branch name (auto-detected from git)                                                                             |
 | `--committers`     | False    | *auto*  | Committer(s) to filter by (auto-detected from git commit)                                                        |
@@ -189,7 +189,7 @@ If you don't want to provide the Socket API Token every time then you can use th
 #### Pull Request and Commit
 | Parameter        | Required | Default | Description                                    |
 |:-----------------|:---------|:--------|:-----------------------------------------------|
-| `--pr-number`      | False    | "0"     | Pull request number                            |
+| `--pr-number`      | False    | *auto*   | Pull request number. Auto-detected in GitHub Actions, GitLab CI, and Azure Pipelines; explicitly passing `0` disables detection. |
 | `--commit-message` | False    | *auto*  | Commit message (auto-detected from git)       |
 | `--commit-sha`     | False    | *auto*  | Commit SHA (auto-detected from git)           |
 | `--base-scan-id`   | False    |         | Full scan ID to diff against, overriding the repository's head scan as the baseline. Mutually exclusive with `--base-commit-sha` |

socketsecurity/config.py

@@ -1,12 +1,14 @@
 import argparse
+import json
 import logging
 import os
+import tomllib
 from dataclasses import asdict, dataclass, field
 from typing import List, Optional
-from socketsecurity import __version__
+
 from socketdev import INTEGRATION_TYPES, IntegrationType
-import json
-import tomllib
+
+from socketsecurity import __version__
 
 
 def get_plugin_config_from_env(prefix: str) -> dict:
@@ -113,6 +115,7 @@ class CliConfig:
     branch: str = ""
     committers: Optional[List[str]] = None
     pr_number: str = "0"
+    pr_number_explicit: bool = False
     commit_message: Optional[str] = None
     default_branch: bool = False
     target_path: str = "./"
@@ -206,17 +209,28 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
         pre_parser.add_argument("--config", dest="config_file", default=None)
         pre_args, _ = pre_parser.parse_known_args(args_list)
 
+        normalized_defaults = {}
         if pre_args.config_file:
             config_defaults = load_cli_config_file(pre_args.config_file)
             valid_dests = {action.dest for action in parser._actions if action.dest != "help"}
-            normalized_defaults = {}
             for key, value in config_defaults.items():
                 dest = str(key).replace("-", "_")
                 if dest in valid_dests:
                     normalized_defaults[dest] = value
             parser.set_defaults(**normalized_defaults)
 
         args = parser.parse_args(args_list)
+        integration_explicit = hasattr(args, "integration")
+        pr_number_explicit = hasattr(args, "pr_number")
+
+        integration_type = getattr(args, "integration", "api")
+        pr_number = getattr(args, "pr_number", "0")
+        if (
+            not integration_explicit and
+            integration_type == "api" and
+            args.scm in ("github", "gitlab")
+        ):
+            integration_type = args.scm
 
         if args.reach_exclude_paths:
             logging.warning(
@@ -260,7 +274,8 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
             'repo': args.repo,
             'branch': args.branch,
             'committers': args.committers,
-            'pr_number': args.pr_number,
+            'pr_number': pr_number,
+            'pr_number_explicit': pr_number_explicit,
             'commit_message': commit_message,
             'default_branch': args.default_branch,
             'target_path': os.path.expanduser(args.target_path),
@@ -292,7 +307,7 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
             'disable_ignore': args.disable_ignore,
             'upload_logs': args.upload_logs,
             'strict_blocking': args.strict_blocking,
-            'integration_type': args.integration,
+            'integration_type': integration_type,
             'pending_head': args.pending_head,
             'timeout': args.timeout,
             'exit_code_on_api_error': args.exit_code_on_api_error,
@@ -517,8 +532,12 @@ def create_argument_parser() -> argparse.ArgumentParser:
         "--integration",
         choices=INTEGRATION_TYPES,
         metavar="<type>",
-        help="Integration type of api, github, gitlab, azure, or bitbucket. Defaults to api",
-        default="api"
+        help=(
+            "Integration type of api, github, gitlab, azure, or bitbucket. "
+            "Defaults to api; --scm github/gitlab implies the matching integration "
+            "when this option is omitted"
+        ),
+        default=argparse.SUPPRESS
     )
     integration_group.add_argument(
         "--owner",
@@ -533,13 +552,17 @@ def create_argument_parser() -> argparse.ArgumentParser:
         "--pr-number",
         dest="pr_number",
         metavar="<number>",
-        help="Pull request number",
-        default="0"
+        help=(
+            "Pull request number. Auto-detected in supported CI environments when omitted; "
+            "pass 0 explicitly to disable detection"
+        ),
+        default=argparse.SUPPRESS
     )
     pr_group.add_argument(
         "--pr_number",
         dest="pr_number",
-        help=argparse.SUPPRESS
+        help=argparse.SUPPRESS,
+        default=argparse.SUPPRESS
     )
     pr_group.add_argument(
         "--commit-message",

socketsecurity/core/__init__.py

@@ -1329,7 +1329,8 @@ def get_license_text_via_purl(self, packages: dict[str, Package], batch_size: in
     def get_diff_scan_artifacts(
             self,
             head_full_scan_id: str,
-            new_full_scan_id: str
+            new_full_scan_id: str,
+            external_href: Optional[str] = None
     ) -> DiffArtifacts:
         """Compare two full scans via the diff-scans endpoints, polling for the result.
 
@@ -1352,6 +1353,8 @@ def get_diff_scan_artifacts(
         Args:
             head_full_scan_id: The before/base full scan ID
             new_full_scan_id: The after/head full scan ID
+            external_href: Optional pull request or merge request URL to associate
+                with the diff scan in the Socket Dashboard
 
         Returns:
             DiffArtifacts with the added/removed/unchanged/replaced/updated lists
@@ -1361,6 +1364,8 @@ def get_diff_scan_artifacts(
             "after": new_full_scan_id,
             "description": f"Socket Security CLI v{__version__} scan comparison",
         }
+        if external_href:
+            create_params["external_href"] = external_href
         try:
             result = self.sdk.diffscans.create_from_ids(self.config.org_slug, create_params)
             diff_scan = result.get("diff_scan") or {}
@@ -1444,7 +1449,8 @@ def get_added_and_removed_packages(
             self,
             head_full_scan_id: str,
             new_full_scan_id: str,
-            include_license_details: bool = False
+            include_license_details: bool = False,
+            external_href: Optional[str] = None
     ) -> Tuple[Dict[str, Package], Dict[str, Package], Dict[str, Package]]:
         """
         Get packages that were added and removed between scans.
@@ -1477,6 +1483,8 @@ def get_added_and_removed_packages(
                 is retained as an explicit override seam, not wired to the
                 ``--exclude-license-details`` user flag (which still governs the
                 human-facing dashboard report URL).
+            external_href: Optional pull request or merge request URL to associate
+                with the primary diff-scan resource
 
         Returns:
             Tuple of (added_packages, removed_packages) dictionaries
@@ -1488,7 +1496,8 @@ def get_added_and_removed_packages(
         try:
             diff_artifacts = self.get_diff_scan_artifacts(
                 head_full_scan_id,
-                new_full_scan_id
+                new_full_scan_id,
+                external_href=external_href,
             )
         except Exception as error:
             # SDK error messages can span many lines (path + response headers); the
@@ -1592,7 +1601,8 @@ def create_new_diff(
             save_files_list_path: Optional[str] = None,
             save_manifest_tar_path: Optional[str] = None,
             base_paths: Optional[List[str]] = None,
-            explicit_files: Optional[List[str]] = None
+            explicit_files: Optional[List[str]] = None,
+            external_href: Optional[str] = None
     ) -> Diff:
         """Create a new diff using the Socket SDK.
 
@@ -1604,6 +1614,8 @@ def create_new_diff(
             save_manifest_tar_path: Optional path to save manifest files tar.gz archive
             base_paths: List of base paths for the scan (optional)
             explicit_files: Optional list of explicit files to use instead of discovering files
+            external_href: Optional pull request or merge request URL to associate
+                with the diff scan
         """
         log.debug(f"starting create_new_diff with no_change: {no_change}")
         if no_change:
@@ -1728,7 +1740,8 @@ def create_new_diff(
         ) = self.get_added_and_removed_packages(
             head_full_scan_id,
             new_full_scan.id,
-            include_license_details=False
+            include_license_details=False,
+            external_href=external_href,
         )
 
         # Separate unchanged packages from added/removed for --strict-blocking support