Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Changelog

## 2.13.3

### Fixed

- A diff scan that the API returns without its package lists (`artifacts` null,
missing or not an object) fails the run with the infrastructure-error code (`3`,
or the `--exit-code-on-api-error` value). It used to fall back to the streaming
comparison, which can't report an incomplete result. A response with no diff
scan object at all (for example a `204`) still falls back, as in 2.13.0.

## 2.13.2

### Added
Expand Down
3 changes: 2 additions & 1 deletion docs/ci-cd.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,8 @@ Findings block only when a [diff comparison runs](#scan-type-by-pipeline).
SCM event filters can also skip unsupported events with exit `0`; confirm a report
was created when validating a new workflow.
`--strict-blocking` also checks existing blocking alerts; an incomplete comparison
or incomplete existing-alert data is an infrastructure failure. See the
(including one the API returns without its package lists) or incomplete
existing-alert data is an infrastructure failure. See the
[2.13.0 migration table](../README.md#upgrading-to-2130) when updating existing CI rules.

## Config file usage in CI
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ build-backend = "hatchling.build"

[project]
name = "socketsecurity"
version = "2.13.2"
version = "2.13.3"
requires-python = ">= 3.11"
license = {"file" = "LICENSE"}
dependencies = [
Expand Down
2 changes: 1 addition & 1 deletion socketsecurity/__init__.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
__author__ = 'socket.dev'
__version__ = '2.13.2'
__version__ = '2.13.3'
USER_AGENT_NAME = 'socket-python-cli'
USER_AGENT = f'{USER_AGENT_NAME}/{__version__}'
34 changes: 29 additions & 5 deletions socketsecurity/core/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,9 @@
# DIFF_SCAN_POLL_MAX_INTERVAL_SECONDS to stay quota-friendly on comparisons that take
# minutes to compute. The timeout is a backstop against a diff scan that never
# completes; on expiry (or any other failure of this flow) the caller falls back to the
# legacy streaming comparison rather than failing the scan outright.
# legacy streaming comparison rather than failing the scan outright. The exception is a
# diff scan the API returned marked incomplete, or returned without its artifacts object:
# the streaming comparison has no completeness signal, so those fail the run instead.
DIFF_SCAN_POLL_INITIAL_INTERVAL_SECONDS = 5.0
DIFF_SCAN_POLL_MAX_INTERVAL_SECONDS = 10.0
DIFF_SCAN_POLL_BACKOFF_MULTIPLIER = 1.5
Expand Down Expand Up @@ -1995,7 +1997,11 @@ def get_diff_scan_artifacts(

Requires an org token with the ``diff-scans:create``, ``diff-scans:list``
and ``full-scans:list`` scopes; callers are expected to catch failures and
fall back to the legacy streaming comparison.
fall back to the legacy streaming comparison, except
``IncompleteComparisonError``: a diff scan marked incomplete, or returned
without an artifacts object, must fail the run. A response with no
``diff_scan`` object at all (the SDK's ``{}`` for a 204 or unfollowed 3xx)
says nothing about the comparison and falls back like any other failure.

Note that cached diff-scan responses always embed per-package license
details (the API ignores ``omit_license_details`` when ``cached=true``),
Expand Down Expand Up @@ -2108,16 +2114,34 @@ def get_diff_scan_artifacts(
response = {"status": "processing"}
polls += 1
if response.get("status") != "processing":
scan = response.get("diff_scan") or {}
envelope = response.get("diff_scan")
scan = envelope if isinstance(envelope, dict) else {}
if scan.get("incomplete") or response.get("incomplete"):
raise IncompleteComparisonError(
f"The scan comparison is incomplete (diff scan {diff_scan_id}): the API "
"could not compare every package, so alerts may be missing. Failing "
"instead of reporting a result that may not cover the whole change."
)
if scan.get("artifacts") is None:
if not isinstance(envelope, dict):
# No diff_scan object at all. The SDK returns {} for statuses it
# doesn't raise on (204, an unfollowed 3xx), so this says nothing
# about the comparison: fall back like any other failure of this flow.
raise Exception(
f"Error fetching diff scan {diff_scan_id}: unexpected response: {str(response)[:500]}"
f"Error fetching diff scan {diff_scan_id}: response has no diff_scan "
f"object: {str(response)[:500]}"
)
if not isinstance(scan.get("artifacts"), dict):
# The API returned the diff scan, but not its result. A finished diff
# scan always carries an artifacts object (under omit_unchanged only
# artifacts.unchanged is null). The streaming comparison is no
# substitute: its response has no incomplete flag, so falling back
# would turn a missing result into one nobody checked.
raise IncompleteComparisonError(
f"The scan comparison returned no results (diff scan {diff_scan_id}): "
"the API returned the diff scan without its artifacts object (the "
"added, removed and unchanged package lists). Failing instead of "
"falling back to the streaming comparison, which can't report "
f"whether its result is complete. Response: {str(response)[:500]}"
)
artifacts_dict = scan["artifacts"]
log.info(
Expand Down
2 changes: 1 addition & 1 deletion socketsecurity/exit_codes.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ class InfrastructureError(Exception):


class IncompleteComparisonError(InfrastructureError):
"""The API marked a scan comparison incomplete.
"""The API marked a scan comparison incomplete, or returned it without results.

An incomplete comparison can leave out alerts, so a passing result would not
mean the change is clean.
Expand Down
96 changes: 96 additions & 0 deletions tests/core/test_exit_codes.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@
from unittest.mock import MagicMock

import pytest
import requests
from socketdev.diffscans import DiffScans
from socketdev.exceptions import (
APIFailure,
APIInsufficientPermissions,
Expand Down Expand Up @@ -164,6 +166,100 @@ def test_incomplete_comparison_does_not_fall_back_to_streaming(core, incomplete_
core.sdk.fullscans.stream_diff.assert_not_called()


# A finished (non-202) diff scan without an artifacts object, whether or not it is
# marked incomplete. Covers every shape that previously fell through to streaming.
@pytest.fixture(params=[
pytest.param({"incomplete": False, "artifacts": None}, id="null-artifacts-complete"),
pytest.param({"artifacts": None}, id="null-artifacts-flag-unset"),
pytest.param({}, id="artifacts-absent-flag-unset"),
pytest.param({"artifacts": []}, id="artifacts-not-an-object"),
])
def resultless_response(request):
return {"diff_scan": {"id": "diff-scan-1", **request.param}}


def test_comparison_without_artifacts_raises(core, resultless_response):
core.sdk.diffscans.create_from_ids.return_value = {"diff_scan": {"id": "diff-scan-1"}}
core.sdk.diffscans.get.return_value = resultless_response

with pytest.raises(IncompleteComparisonError, match="returned no results"):
core.get_diff_scan_artifacts("head", "new")


def test_comparison_without_artifacts_does_not_fall_back_to_streaming(core, resultless_response):
"""The streaming response has no incomplete flag, so it can't vouch for the result."""
core.sdk.diffscans.create_from_ids.return_value = {"diff_scan": {"id": "diff-scan-1"}}
core.sdk.diffscans.get.return_value = resultless_response

with pytest.raises(IncompleteComparisonError):
core.get_added_and_removed_packages("head", "new")

core.sdk.fullscans.stream_diff.assert_not_called()


@pytest.mark.parametrize("argv, expected", [
([], 3),
(["--exit-code-on-api-error", "42"], 42),
(["--disable-blocking"], 0),
(["--disable-blocking", "--exit-code-on-api-error", "42"], 0),
])
def test_comparison_without_artifacts_follows_exit_policy(monkeypatch, argv, expected):
error = IncompleteComparisonError("The scan comparison returned no results")

assert _run_cli(monkeypatch, argv, error) == expected


class StreamingFallback(Exception):
"""Raised by the mocked stream_diff to prove the fallback path was taken."""


@pytest.mark.parametrize("response", [
pytest.param({}, id="empty-dict"),
pytest.param({"diff_scan": None}, id="diff-scan-null"),
])
def test_response_without_diff_scan_object_falls_back_to_streaming(core, response):
"""No diff_scan object says nothing about the comparison, so 2.13.0's fallback stays."""
core.sdk.diffscans.create_from_ids.return_value = {"diff_scan": {"id": "diff-scan-1"}}
core.sdk.diffscans.get.return_value = response
core.sdk.fullscans.stream_diff.side_effect = StreamingFallback

with pytest.raises(Exception, match="no diff_scan object") as error:
core.get_diff_scan_artifacts("head", "new")
assert not isinstance(error.value, IncompleteComparisonError)

with pytest.raises(StreamingFallback):
core.get_added_and_removed_packages("head", "new")
core.sdk.fullscans.stream_diff.assert_called_once()


def test_http_204_through_the_sdk_falls_back_to_streaming(core):
"""The SDK's own get() maps a 204 to {}; that must not exit 3."""
no_content = requests.Response()
no_content.status_code = 204
no_content._content = b""
api = MagicMock()
api.do_request.return_value = no_content
core.sdk.diffscans = DiffScans(api)
core.sdk.diffscans.create_from_ids = MagicMock(return_value={"diff_scan": {"id": "diff-scan-1"}})
core.sdk.fullscans.stream_diff.side_effect = StreamingFallback

with pytest.raises(StreamingFallback):
core.get_added_and_removed_packages("head", "new")


def test_omitted_unchanged_bucket_is_still_a_result(core):
"""omit_unchanged nulls the unchanged list, not the artifacts object."""
core.sdk.diffscans.create_from_ids.return_value = {"diff_scan": {"id": "diff-scan-1"}}
core.sdk.diffscans.get.return_value = {"diff_scan": {
"id": "diff-scan-1", "incomplete": False,
"artifacts": {"added": [], "removed": [], "unchanged": None, "replaced": [], "updated": []},
}}

artifacts = core.get_diff_scan_artifacts("head", "new")

assert artifacts.unchanged == []


def test_complete_comparison_is_returned(core):
core.sdk.diffscans.create_from_ids.return_value = {"diff_scan": {"id": "diff-scan-1"}}
core.sdk.diffscans.get.return_value = {
Expand Down
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.