socketsecurity 2.8.1__tar.gz → 2.9.0__tar.gz

{socketsecurity-2.8.1 → socketsecurity-2.9.0}/CHANGELOG.md

@@ -1,5 +1,160 @@
 # Changelog
 
+## 2.9.0
+
+### Added: patched versions in human-readable security output
+
+- The native console alert table now includes a `Patched Version` column,
+  populated from `props.firstPatchedVersionIdentifier` when the API provides it.
+- GitHub pull request and GitLab merge request security comments now show the
+  patched version in each applicable alert's details.
+
+### Fixed: CLI scans retain pull request context in the Socket Dashboard
+
+- Pull request numbers are detected from standard GitHub Actions, GitLab CI,
+  and Azure Pipelines environments when `--pr-number` is not supplied. An
+  explicitly supplied value, including `0`, remains authoritative.
+- The Buildkite workflow and CI/CD guide now forward `BUILDKITE_PULL_REQUEST`
+  explicitly and document provider selection for Dashboard PR association. With
+  `--integration github` or `--integration gitlab`, the repository slug and host
+  for the link are read from `BUILDKITE_REPO`, covering self-hosted installations.
+- `--scm github` and `--scm gitlab` now imply the matching scan integration
+  unless `--integration` is explicitly supplied.
+- Diff scans include the detected pull request or merge request URL as their
+  external link, allowing Dashboard reports to retain their CI change context.
+  Re-running a comparison over an already-compared scan pair now applies the
+  link to the existing diff scan instead of leaving that report unassociated.
+- A `--pr-number` value that is not a positive integer is now normalized to `0`
+  before the GitHub adapter reads it, so Buildkite's `false` on a branch build no
+  longer makes that build look like a pull request event.
+
+### Changed: GitHub and GitLab branch pipelines create full scans
+
+- With `--scm github` or `--scm gitlab`, only pull request and merge request
+  events create diff scans. Every other pipeline, including default-branch
+  pushes, creates a full scan. The detected event type is authoritative:
+  `--enable-diff` and `--ignore-commit-files` no longer opt an SCM branch run
+  into comparison mode.
+- Those runs no longer set a blocking exit code. A full scan has no baseline, so
+  it cannot distinguish newly introduced alerts from pre-existing ones; the CLI
+  now behaves as if `--disable-blocking` was supplied, matching how it already
+  treats a run with no supported manifest files. Pull request and merge request
+  pipelines are unaffected and still block.
+- `--generate-license` and `--legal-format fossa` fetch the package list on this
+  path, so attribution files generated from a branch pipeline are complete rather
+  than empty.
+- Console-only full scans link to the Socket report and state that findings were
+  not fetched for console output instead of presenting an empty local alert list
+  as "No issues found."
+- License enrichment keeps the package namespace in PURL requests and response
+  matching, so scoped npm packages and namespaced Maven packages receive their
+  license details.
+
+### Changed: `@SocketSecurity ignore` requires write access
+
+- An ignore command suppresses a security alert, but the CLI honored one from any
+  commenter, including a drive-by comment from someone with no access to the
+  repository. Commands are now accepted only from an author with write access.
+- On GitHub this is read from the effective repository permission and cached per
+  commenter for the run. Write, maintain, or admin access is required; relationship
+  labels such as `MEMBER` and `COLLABORATOR` are not treated as permissions.
+- A 404 from GitHub's collaborator-permission endpoint is treated as a definitive
+  denial rather than an unreadable permission, so the default `enforce` policy does
+  not honor ignore commands from users outside the repository.
+- GitLab notes carry no equivalent field, so project membership is read once per
+  run (only when an ignore command is present) and Developer or above is required.
+  If that lookup cannot be answered — a `CI_JOB_TOKEN` generally cannot read the
+  members API — the command is still honored and a warning names the author, so
+  enabling this does not silently break pipelines that relied on ignore commands.
+  Use a `GITLAB_TOKEN` with API read access to get enforcement.
+- A rejected command is logged and is also absent from the ignore telemetry, which
+  records what was acted on. No acknowledgement reaction is added to a comment that
+  was not honored.
+- `--ignore-authorization` selects the policy: `enforce` (default) requires write
+  access and honors the command with a warning where the provider cannot report it,
+  `strict` rejects it in that case instead, and `off` performs no check.
+
+### Fixed: GitLab authentication fallback never ran
+
+- When a GitLab token's type cannot be inferred from its shape, the CLI guesses
+  between Bearer and PRIVATE-TOKEN and retries once under the other scheme on a
+  401. That retry never happened: the retry caught `requests.exceptions.HTTPError`,
+  but the HTTP client translates every request error into `APIFailure` first, so a
+  misclassified token failed the run instead of falling back.
+- API failures raised by the CLI's HTTP client now carry their HTTP status code.
+  Without it a 401 was indistinguishable from any other failure, and
+  `is_transient_error` could not classify one either.
+- The CLI's `APIFailure` now subclasses the SDK exception of the same name. They
+  were independent types, so an `except APIFailure` importing the SDK's — which is
+  what every handler in `socketsecurity.core` does — did not catch a failure raised
+  by the HTTP client.
+
+### Fixed: pull request and merge request comment accuracy
+
+- Per-alert ignore instructions now use ecosystem-qualified package names and
+  accept scoped packages while remaining compatible with older bare-name replies.
+  A leading npm scope is no longer mistaken for an ecosystem, so
+  `ignore @types/node@*` no longer also ignores the package named `node`.
+- Ignore telemetry uses the same package matcher as alert suppression, so legacy
+  bare-name commands generate an event for the alert they suppress.
+- Dependency overviews preserve added, updated, removed, and replaced package
+  classifications instead of presenting updates as new dependencies. Added and
+  updated rows keep their diff badge; removed and replaced, which have no
+  published badge, use a text label.
+- Shared security comment copy no longer describes GitLab merge request output
+  as Socket for GitHub.
+- Updating a security comment in the legacy table format no longer raises on a
+  malformed row. Each row was unpacked through four consecutive splits with no
+  bounds checks, so a cell carrying an extra `|`, a package cell that is not a
+  markdown link, or a name with no version ended the run before it reported
+  status — and a scoped package name in Socket's own table was enough to trigger
+  it. Rows are now parsed defensively, and a row that cannot be read keeps its
+  alert reported. Ignore commands for a scoped package are accepted there in both
+  the ecosystem-qualified and bare forms.
+- Server URLs read from `GITHUB_SERVER_URL` and `CI_SERVER_URL` are validated as
+  http(s) URLs before being composed into a diff scan's external link, matching
+  the check already applied to the other repository URLs read from CI.
+- Repository-derived values are escaped before they are rendered into a pull
+  request or merge request comment. Manifest paths and sources are file paths from
+  the scanned repository, and alert text comes from the API; neither is markup the
+  CLI authored, so both are now escaped at the point they are interpolated. The
+  alert markers can no longer be terminated early by a package name. Slack, Jira
+  and console output are unchanged, since none of them render HTML.
+## 2.8.3
+
+### Fixed: GitLab report serialization and workspace baselines
+
+- Full-scan package identities and Socket links now preserve namespaced packages
+  when the SDK returns enum-backed ecosystem values.
+- Namespaced package links separate the namespace from the name instead of
+  concatenating them, so Maven links no longer fuse groupId and artifactId into a
+  single unresolvable path segment. A namespaced package whose namespace is
+  missing now logs a warning rather than emitting a broken link silently.
+- GitLab dependency-scanning reports emit CVE and GHSA identifiers from current
+  API fields while remaining compatible with legacy CVE data.
+- GitLab report findings record the manifest they came from when the package's
+  introducing chain is unavailable, instead of reporting the location as
+  `unknown`, and report whether a dependency is direct from the package record
+  rather than inferring it from a dependency-path string that is never produced.
+- `--base-commit-sha` degrades to the nearest scanned ancestor of the requested
+  commit instead of failing the run, and logs which commit was used and how far
+  back it is. Squash merges, rebases, and multi-commit pushes all leave a merge
+  base unscanned even when default-branch scanning is configured correctly. The
+  lookup follows paginated scan history and the run still fails when no scanned
+  ancestor is reachable or the exact-commit lookup itself fails.
+- Implicit diff baselines are selected from the same workspace, scan type,
+  repository, and default branch, including when no workspace is supplied. A
+  baseline lookup that fails is reported as an API error instead of resolving to
+  an empty baseline, and temporary scans are skipped when selecting one.
+## 2.8.2
+
+### Changed: bump pinned @coana-tech/cli to 15.10.41
+
+- Bumped the pinned reachability engine (`@coana-tech/cli`) from `15.10.40` to
+  `15.10.41`. See the
+  [reachability analysis changelog](https://docs.socket.dev/docs/reachability-analysis-changelog)
+  for engine changes.
+
 ## 2.8.1
 
 ### Changed: bump pinned @coana-tech/cli to 15.10.40

{socketsecurity-2.8.1 → socketsecurity-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: socketsecurity
-Version: 2.8.1
+Version: 2.9.0
 Summary: Socket Security CLI for CI/CD
 Project-URL: Homepage, https://socket.dev
 Author-email: Douglas Coburn <douglas@socket.dev>
@@ -104,21 +104,22 @@ socketcli --enable-gitlab-security --gitlab-security-file gl-dependency-scanning
 
 ### PR scan diffed against the merge base
 
-By default, PR scans are diffed against the repository's latest head scan. To diff against
-the exact commit your PR branched from instead, pass the merge base as the baseline:
+By default, PR scans are diffed against the repository's latest matching head scan. To
+prefer the commit your PR branched from as the baseline, pass the merge base:
 
 ```bash
 BASE_SHA=$(git merge-base origin/main HEAD)
 socketcli --pr-number 123 --base-commit-sha "$BASE_SHA"
 ```
 
-> **Requirement:** `--base-commit-sha` only works if Socket already has a full scan for that
-> exact commit. In practice this means your CI must run `socketcli` on **every commit that
-> lands on your default branch** — not just some of them. If merges can land without a scan
-> (skipped/canceled builds, `[skip ci]`, path-filtered pipelines), the PR scan will fail with
-> exit code 3 rather than silently diff against the wrong baseline. See
+> The CLI uses the exact commit's newest matching full scan when one exists. Otherwise, it
+> searches up to 100 first-parent commits in the local checkout and uses the nearest scanned
+> ancestor, with a warning that the diff is wider than the merge base. Run `socketcli`
+> regularly on your default branch and ensure PR checkouts contain enough history for that
+> walk. The run fails with the configured API-error exit code only when no scanned ancestor
+> is reachable (or when the scan lookup itself fails). See
 > [`docs/cli-reference.md`](https://github.com/SocketDev/socket-python-cli/blob/main/docs/cli-reference.md)
-> for the full requirements and a backfill pattern that makes PR jobs self-sufficient.
+> for the full behavior and an optional exact-baseline backfill pattern.
 
 A specific full scan ID also works: `--base-scan-id <id>`.
 

{socketsecurity-2.8.1 → socketsecurity-2.9.0}/README.md

@@ -44,21 +44,22 @@ socketcli --enable-gitlab-security --gitlab-security-file gl-dependency-scanning
 
 ### PR scan diffed against the merge base
 
-By default, PR scans are diffed against the repository's latest head scan. To diff against
-the exact commit your PR branched from instead, pass the merge base as the baseline:
+By default, PR scans are diffed against the repository's latest matching head scan. To
+prefer the commit your PR branched from as the baseline, pass the merge base:
 
 ```bash
 BASE_SHA=$(git merge-base origin/main HEAD)
 socketcli --pr-number 123 --base-commit-sha "$BASE_SHA"
 ```
 
-> **Requirement:** `--base-commit-sha` only works if Socket already has a full scan for that
-> exact commit. In practice this means your CI must run `socketcli` on **every commit that
-> lands on your default branch** — not just some of them. If merges can land without a scan
-> (skipped/canceled builds, `[skip ci]`, path-filtered pipelines), the PR scan will fail with
-> exit code 3 rather than silently diff against the wrong baseline. See
+> The CLI uses the exact commit's newest matching full scan when one exists. Otherwise, it
+> searches up to 100 first-parent commits in the local checkout and uses the nearest scanned
+> ancestor, with a warning that the diff is wider than the merge base. Run `socketcli`
+> regularly on your default branch and ensure PR checkouts contain enough history for that
+> walk. The run fails with the configured API-error exit code only when no scanned ancestor
+> is reachable (or when the scan lookup itself fails). See
 > [`docs/cli-reference.md`](https://github.com/SocketDev/socket-python-cli/blob/main/docs/cli-reference.md)
-> for the full requirements and a backfill pattern that makes PR jobs self-sufficient.
+> for the full behavior and an optional exact-baseline backfill pattern.
 
 A specific full scan ID also works: `--base-scan-id <id>`.
 

{socketsecurity-2.8.1 → socketsecurity-2.9.0}/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
@@ -306,14 +334,33 @@ initial timeout signal or 137 if `SIGKILL` is involved.
 
 ### 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.
+
 The CLI reads Buildkite's native `BUILDKITE_COMMIT`, `BUILDKITE_BRANCH`,
 `BUILDKITE_PULL_REQUEST`, and `BUILDKITE_PULL_REQUEST_BASE_BRANCH` variables.
 For pull-request builds, ensure the checkout contains the base branch and the
@@ -321,11 +368,12 @@ checked-out head commit. The CLI uses those local refs first and performs a
 targeted fetch only when a required ref or its comparison history is missing;
 it does not fetch every remote ref and tag during startup.
 
-When `--scm github` is used from Buildkite, the CLI also derives GitHub comment
-context from `BUILDKITE_REPO`, `BUILDKITE_BUILD_CHECKOUT_PATH`, and the variables
-above. Set `GH_API_TOKEN` to a GitHub token with the required repository access.
-GitHub Enterprise users should also set `GITHUB_API_URL`; GitHub.com defaults to
-`https://api.github.com`.
+When `--scm github` is used from Buildkite, the CLI also posts GitHub PR comments.
+It identifies the repository from `BUILDKITE_REPO` and takes the rest of the build
+context from `BUILDKITE_BUILD_CHECKOUT_PATH` and the variables above — see
+[Buildkite PR context](#buildkite-pr-context). Set `GH_API_TOKEN` to a GitHub token
+with the required repository access. GitHub Enterprise users should also set
+`GITHUB_API_URL`; GitHub.com defaults to `https://api.github.com`.
 
 #### Merge-base baselines in Buildkite (dynamic pipelines)
 
@@ -347,11 +395,14 @@ generator rather than a static YAML file:
   BASE_SHA=$(git merge-base "origin/${TARGET}" HEAD)
   ```
 
-- **Emit the backfill step conditionally from the generator.** The generator is the
-  natural place for the "does a baseline scan exist?" check
+- **If an exact baseline is required, emit a backfill step conditionally from the
+  generator.** The generator is the natural place for the "does an exact baseline
+  scan exist?" check
   (`GET /orgs/{org}/full-scans?repo=<repo>&commit_hash=$BASE_SHA&per_page=1`): only
   emit the baseline-scan step when it returns nothing. The emitted pipeline then shows
-  in the UI whether a backfill will run.
+  in the UI whether a backfill will run. Without a backfill, the CLI automatically
+  uses the nearest scanned first-parent ancestor within 100 commits and warns that
+  the diff is wider.
 
 - **Keep the backfill inside one command step.** The checkout-base → scan →
   checkout-PR sequence must not be split across steps — steps can land on different
@@ -360,17 +411,18 @@ generator rather than a static YAML file:
   checkout: `git worktree add /tmp/socket-base "$BASE_SHA"` then
   `socketcli --target-path /tmp/socket-base --branch "$TARGET" --disable-blocking`.
 
-- **Soft-fail infra errors, not findings.** A missing baseline (or any API error)
-  exits with code 3 (`--exit-code-on-api-error` to change it); real findings exit 1.
+- **Soft-fail infra errors, not findings.** No reachable scanned ancestor (or any API
+  error) exits with code 3 (`--exit-code-on-api-error` to change it); real findings exit 1.
   [`soft_fail: [{exit_status: 3}]`](https://buildkite.com/docs/pipelines/configure/step-types/command-step)
   on the PR scan step keeps infra errors from blocking merges while security findings
   still do.
 
 - **["Cancel intermediate builds"](https://buildkite.com/docs/pipelines/configure/canceling-builds#cancel-running-intermediate-builds)
-  on the default branch is the main source of baseline gaps.** Canceled builds never
-  scan their commit, so merge-base lookups for PRs based on those commits fail. The
-  conditional backfill step above is the remedy; there is no per-step exemption from
-  build cancellation in Buildkite. If you need strict scan-once semantics for
+  on the default branch is a common source of exact-baseline gaps.** Canceled builds
+  never scan their commit, so these PRs fall back to an older scanned ancestor. Use
+  the conditional backfill step above when an exact merge-base comparison is required;
+  there is no per-step exemption from build cancellation in Buildkite. If you need
+  strict scan-once semantics for
   concurrent backfills of the same merge base, serialize the backfill step with a
   [concurrency group](https://buildkite.com/docs/pipelines/configure/workflows/controlling-concurrency)
   keyed on the merge-base SHA.
@@ -385,6 +437,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
@@ -395,6 +459,69 @@ pipelines:
           - socketcli --config .socketcli.toml --target-path .
 ```
 
+## Scan type by pipeline
+
+With `--scm github` or `--scm gitlab`, the detected event decides the scan type:
+
+| Event | Scan | Blocks the build |
+|:------|:-----|:-----------------|
+| Pull request / merge request | Diff scan against the repository's baseline | Yes, on newly introduced alerts |
+| Any other pipeline, including default-branch pushes | Full scan | No |
+
+A full scan has no baseline, so it cannot tell a newly introduced alert from one
+that was already there. Rather than block on a number that would mean something
+different depending on which output format was enabled, those runs behave as if
+`--disable-blocking` was supplied and report through the Dashboard instead. This
+matches how the CLI already treats a run with no supported manifest files.
+
+The event type is authoritative once `--scm` is set: `--enable-diff` and
+`--ignore-commit-files` do not turn a branch pipeline into a comparison. To diff
+a branch build, drop `--scm` and use `--enable-diff` with `--integration`, which
+runs the comparison without the PR comment adapter.
+
+`--generate-license` and `--legal-format fossa` work on both paths; a full scan
+fetches the package list for them.
+
+## 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. Any value that
+is not a positive integer, including Buildkite's `false`, means no pull request.
+
+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. The CLI identifies the repository from
+[`BUILDKITE_REPO`](https://buildkite.com/docs/pipelines/configure/environment-variables#BUILDKITE_REPO),
+taking both the slug and the host from it, so github.com, GitLab.com, and self-hosted
+installations all build a correct pull request or merge request link without extra
+configuration. That same value identifies the repository for GitHub PR comments when
+`--scm github` is set. `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:
@@ -411,3 +538,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.

{socketsecurity-2.8.1 → socketsecurity-2.9.0}/docs/cli-reference.md

@@ -238,7 +238,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)                                                        |
@@ -252,28 +252,26 @@ 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` |
-| `--base-commit-sha`| False    |         | Commit SHA to diff against, overriding the repository's head scan as the baseline. The most recent full scan for that commit is used; the CLI errors (exit code 3, or `--exit-code-on-api-error`) if no scan exists for it. Mutually exclusive with `--base-scan-id` |
+| `--base-commit-sha`| False    |         | Commit SHA to prefer as the diff baseline, overriding the repository's head scan. The CLI uses its most recent matching full scan or the nearest scanned first-parent ancestor within 100 local commits. It errors (exit code 3, or `--exit-code-on-api-error`) if no scanned ancestor is reachable. Mutually exclusive with `--base-scan-id` |
 
-> **Diffing against the merge base** — by default, PR scans are diffed against the repository's *latest* head scan, which may include newer default-branch commits than your PR branched from. To diff against the exact commit your PR is based on, compute the merge base and pass it as the baseline:
+> **Diffing against the merge base** — by default, PR scans are diffed against the repository's latest matching head scan, which may include newer default-branch commits than your PR branched from. To prefer the commit your PR is based on, compute the merge base and pass it as the baseline:
 >
 > ```shell
 > BASE_SHA=$(git merge-base origin/main HEAD)
 > socketcli --pr-number 123 --base-commit-sha "$BASE_SHA"
 > ```
 >
-> **Requirement: a full scan must already exist for the merge-base commit.** `--base-commit-sha` does not create a scan of that commit; it looks up an existing one. That lookup only succeeds if your CI runs `socketcli` on **every commit that lands on your default branch** — every merge and direct push, not just periodic or latest-only scans. Common ways commits slip through without a scan:
+> `--base-commit-sha` does not create a scan of that commit. The CLI first looks for the newest non-temporary scan matching the repository, workspace, scan type, and exact commit. If the exact commit was not scanned, it walks up to 100 first-parent commits from that SHA in the local checkout and uses the nearest matching scanned ancestor. It logs a warning with the selected commit and distance because this produces a wider diff than the merge base.
 >
-> - CI settings that cancel or skip intermediate builds when newer commits land (e.g. Buildkite's ["cancel intermediate builds"](https://buildkite.com/docs/pipelines/configure/canceling-builds#cancel-running-intermediate-builds))
-> - `[skip ci]` commits, path-filtered pipelines, or failed/canceled scan steps
-> - merge-base commits that predate your Socket rollout
+> Run `socketcli` regularly on the default branch so recent ancestors have scans. PR checkouts must also retain the merge base and enough first-parent history; shallow clones can shorten the search. Gaps are expected when CI cancels intermediate builds, commits use `[skip ci]`, pipelines are path-filtered, or the merge base predates your Socket rollout.
 >
-> If no scan exists for the commit, the CLI **fails** (exit code 3, or your `--exit-code-on-api-error` value; exit 0 with `--disable-blocking`) instead of silently falling back to the head scan — a wrong baseline would misreport which alerts the PR introduces. Don't adopt this flag without default-branch scan coverage in place; you'll fail PR builds on lookup misses.
+> If no scanned ancestor is reachable within the local 100-commit walk, the CLI **fails** (exit code 3, or your `--exit-code-on-api-error` value; exit 0 with `--disable-blocking`) instead of silently falling back to the repository head. API or permission failures also fail rather than being treated as a missing exact scan.
 >
-> **Backfill pattern** — if your default-branch coverage has gaps, the PR job can create the missing baseline itself before scanning:
+> **Optional exact-baseline backfill** — if the wider ancestor fallback is not acceptable, the PR job can create the missing exact baseline before scanning:
 >
 > ```shell
 > BASE_SHA=$(git merge-base origin/main HEAD)
@@ -285,7 +283,7 @@ If you don't want to provide the Socket API Token every time then you can use th
 > socketcli --pr-number 123 --base-commit-sha "$BASE_SHA"
 > ```
 >
-> Run the baseline step with `--disable-blocking` (findings on the default branch must not fail the PR job) and an explicit `--branch`, since branch auto-detection is unreliable at a detached HEAD.
+> Run the baseline step with `--disable-blocking` (findings on the default branch must not fail the PR job) and an explicit `--branch`, since branch auto-detection is unreliable at a detached HEAD. Without this step, the CLI automatically uses the nearest scanned ancestor.
 >
 > Buildkite users with dynamically generated pipelines: see [Merge-base baselines in Buildkite](ci-cd.md#merge-base-baselines-in-buildkite-dynamic-pipelines) for generation-time vs. step-time guidance.
 
@@ -338,7 +336,7 @@ If you don't want to provide the Socket API Token every time then you can use th
 | Parameter                        | Required | Default | Description                                                                                                                |
 |:---------------------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------|
 | `--reach`                          | False    | False   | Enable reachability analysis to identify which vulnerable functions are actually called by your code. Creates a full application reachability scan (`scan_type=socket_tier1`). |
-| `--reach-version`                  | False    | 15.10.40 | Version of @coana-tech/cli to use. Defaults to the pinned version that ships with this CLI release, so the engine only changes when you upgrade the Socket CLI. Pass `latest` to always use the newest published version (opt-in auto-update), or an explicit version (e.g. `1.2.3`) to pin it. |
+| `--reach-version`                  | False    | 15.10.41 | Version of @coana-tech/cli to use. Defaults to the pinned version that ships with this CLI release, so the engine only changes when you upgrade the Socket CLI. Pass `latest` to always use the newest published version (opt-in auto-update), or an explicit version (e.g. `1.2.3`) to pin it. |
 | `--reach-analysis-timeout`         | False    | 10m     | Timeout for each reachability analysis run, e.g. `90s`, `10m` or `1h`. Omitted by default, so coana applies its own default (`10m`). Alias: `--reach-timeout` |
 | `--reach-analysis-memory-limit`    | False    | 8GB     | Memory limit for each reachability analysis run, e.g. `512MB` or `8GB`. Omitted by default, so coana applies its own default (`8GB`). Alias: `--reach-memory-limit` |
 | `--reach-concurrency`              | False    | 1       | Control parallel analysis execution (must be >= 1). Omitted by default, so coana applies its own default.                  |
@@ -431,7 +429,8 @@ The launcher can be tuned via the `SOCKET_CLI_COANA_LAUNCHER` environment variab
 |:-------------------------|:---------|:--------|:----------------------------------------------------------------------|
 | `--ignore-commit-files`    | False    | False   | Ignore commit files                                                   |
 | `--disable-blocking`       | False    | False   | Non-blocking CI mode: the CLI always exits **0**, even when blocking alerts are present (including with `--strict-blocking`). Also exits 0 on uncaught runtime errors and Socket API failures, so the job is treated as successful while findings and errors are still logged. Takes precedence over `--strict-blocking`. |
-| `--disable-ignore`         | False    | False   | Disable support for `@SocketSecurity ignore` commands in PR comments. When set, alerts cannot be suppressed via comments and ignore instructions are hidden from comment output. |
+| `--disable-ignore`         | False    | False   | Disable support for `@SocketSecurity ignore` commands in PR comments. When set, alerts cannot be suppressed via comments and ignore instructions are hidden from comment output. See [Who can ignore an alert](#who-can-ignore-an-alert). |
+| `--ignore-authorization`   | False    | enforce | Who may suppress alerts with `@SocketSecurity ignore`. `enforce` requires write access and honors the command with a warning when the provider cannot report it; `strict` rejects it in that case; `off` honors any commenter. See [Who can ignore an alert](#who-can-ignore-an-alert). |
 | `--strict-blocking`        | False    | False   | Fail on ANY security policy violations (blocking severity), not just new ones. Only works in diff mode. See [Strict Blocking Mode](#strict-blocking-mode) for details. |
 | `--enable-diff`            | False    | False   | Enable diff mode even when using `--integration api` (forces diff mode without SCM integration) |
 | `--scm`                    | False    | api     | Source control management type                                        |
@@ -690,6 +689,37 @@ The CLI uses intelligent default branch detection with the following priority:
 
 Both `--default-branch` and `--pending-head` parameters are automatically synchronized to ensure consistent behavior.
 
+## Who can ignore an alert
+
+`@SocketSecurity ignore <ecosystem>/<package>@<version>` and
+`@SocketSecurity ignore-all` suppress security findings, so the CLI honors them
+only from a commenter with write access to the repository. A command from anyone
+else is skipped, logged with the author's name, and the alerts it named stay
+reported. `--disable-ignore` turns the feature off entirely.
+
+| Provider | How access is determined | If it cannot be determined |
+|:---------|:-------------------------|:---------------------------|
+| GitHub | Effective repository permission, read once per commenter per run. Write, maintain, or admin access is honored. | The command is honored and a warning is logged. |
+| GitLab | Project membership, read once per run when an ignore command is present. Developer (30) or above is honored. | The command is honored and a warning is logged. |
+
+The GitHub check needs a token that can read repository metadata. GitLab notes
+carry no permission field, so that check needs a `GITLAB_TOKEN` that can read
+`GET /projects/:id/members/all`. A `CI_JOB_TOKEN` generally cannot.
+
+`--ignore-authorization` decides what happens when access cannot be determined:
+
+| Value | Verified write access | Access cannot be determined |
+|:------|:----------------------|:----------------------------|
+| `enforce` (default) | Honored | Honored, with a warning naming the author |
+| `strict` | Honored | Rejected |
+| `off` | Honored | Honored, no check performed |
+
+`enforce` closes the hole wherever the provider can answer, without breaking a
+pipeline whose token cannot read membership. `strict` closes it everywhere, at the
+cost of failing those pipelines. `off` restores the prior behavior and should be
+paired with `--disable-ignore` unless you specifically need comment-driven ignores
+from unverified authors.
+
 ## GitLab Token Configuration
 
 GitLab token/auth behavior and CI examples are documented in [`ci-cd.md`](ci-cd.md).

{socketsecurity-2.8.1 → socketsecurity-2.9.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.8.1"
+version = "2.9.0"
 requires-python = ">= 3.11"
 license = {"file" = "LICENSE"}
 dependencies = [

{socketsecurity-2.8.1 → socketsecurity-2.9.0}/socketsecurity/__init__.py

@@ -1,3 +1,3 @@
 __author__ = 'socket.dev'
-__version__ = '2.8.1'
+__version__ = '2.9.0'
 USER_AGENT = f'SocketPythonCLI/{__version__}'