From 009ece6cae80de6f502772a05661066d630e33f4 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Fri, 13 Nov 2026 20:56:55 -0500
Subject: [PATCH 01/11] List each finding once under --strict-blocking
create_new_diff built the unchanged package set by filtering packages
keyed by type/purl against added and removed packages keyed by artifact
ID. The keys never matched, so every added package was also treated as
unchanged, and under --strict-blocking its alerts were reported twice:
once as new and once as existing. Against an empty baseline that doubled
every finding in JSON, SARIF, Slack and GitLab output, and inflated the
"EXISTING blocking issues" count in the summary and GitLab commit status.
The exit code was not affected.
Unchanged packages are now selected and keyed by artifact ID, which also
lets transitive unchanged alerts resolve their introducing package.
select_diff_alerts additionally skips an unchanged alert already listed
as new, matching on purl and alert type like the rest of the diff.
Bumps the version to 2.12.2.
---
CHANGELOG.md | 10 +
pyproject.toml | 2 +-
socketsecurity/__init__.py | 2 +-
socketsecurity/core/__init__.py | 24 +-
socketsecurity/core/alert_selection.py | 18 +-
tests/core/test_strict_blocking_duplicates.py | 206 ++++++++++++++++++
uv.lock | 2 +-
7 files changed, 254 insertions(+), 10 deletions(-)
create mode 100644 tests/core/test_strict_blocking_duplicates.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4eed82ff..1f66871c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,15 @@
# Changelog
+## 2.12.2
+
+### Fixed: duplicate findings with `--strict-blocking`
+
+- Alerts on added packages are no longer also reported as existing alerts. Under
+ `--strict-blocking`, each finding on an added package was listed twice in JSON,
+ SARIF, Slack and GitLab output, and counted again in the summary's
+ "EXISTING blocking issues" line and the GitLab commit status. The exit code
+ was not affected.
+
## 2.12.1
### Changed: bump pinned Coana CLI to 15.15.1
diff --git a/pyproject.toml b/pyproject.toml
index 3ee6508e..76960bad 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
[project]
name = "socketsecurity"
-version = "2.12.1"
+version = "2.12.2"
requires-python = ">= 3.11"
license = {"file" = "LICENSE"}
dependencies = [
diff --git a/socketsecurity/__init__.py b/socketsecurity/__init__.py
index 01e27579..4494a36d 100644
--- a/socketsecurity/__init__.py
+++ b/socketsecurity/__init__.py
@@ -1,4 +1,4 @@
__author__ = 'socket.dev'
-__version__ = '2.12.1'
+__version__ = '2.12.2'
USER_AGENT_NAME = 'socket-python-cli'
USER_AGENT = f'{USER_AGENT_NAME}/{__version__}'
diff --git a/socketsecurity/core/__init__.py b/socketsecurity/core/__init__.py
index f78f6c19..305d6309 100644
--- a/socketsecurity/core/__init__.py
+++ b/socketsecurity/core/__init__.py
@@ -2480,11 +2480,7 @@ def create_new_diff(
external_href=external_href,
)
- # Separate unchanged packages from added/removed for --strict-blocking support
- unchanged_packages = {
- pkg_id: pkg for pkg_id, pkg in packages.items()
- if pkg_id not in added_packages and pkg_id not in removed_packages
- }
+ unchanged_packages = Core.get_unchanged_packages(packages, added_packages, removed_packages)
diff = self.create_diff_report(added_packages, removed_packages, unchanged_packages)
diff.packages = packages
@@ -2509,6 +2505,24 @@ def create_new_diff(
return diff
+ @staticmethod
+ def get_unchanged_packages(
+ packages: Dict[str, Package],
+ added_packages: Dict[str, Package],
+ removed_packages: Dict[str, Package],
+ ) -> Dict[str, Package]:
+ """Return the packages in ``packages`` that were neither added nor removed.
+
+ ``packages`` is keyed by ``type/purl`` while the added and removed dicts are
+ keyed by artifact ID, so membership is checked on ``Package.id``. The result
+ is keyed by artifact ID to match the other two, which is what
+ ``get_source_data`` expects when it resolves ``topLevelAncestors``.
+ """
+ return {
+ pkg.id: pkg for pkg in packages.values()
+ if pkg.id not in added_packages and pkg.id not in removed_packages
+ }
+
def create_diff_report(
self,
added_packages: Dict[str, Package],
diff --git a/socketsecurity/core/alert_selection.py b/socketsecurity/core/alert_selection.py
index 132be294..83cddd40 100644
--- a/socketsecurity/core/alert_selection.py
+++ b/socketsecurity/core/alert_selection.py
@@ -15,14 +15,28 @@ def select_diff_alerts(diff: Diff, strict_blocking: bool = False) -> List[Issue]
"""Select diff alerts for output rendering.
In strict blocking mode, include unchanged alerts so rendered output aligns
- with pass/fail policy evaluation.
+ with pass/fail policy evaluation. An unchanged alert that is already listed
+ as new (same purl and alert type, the key the diff consolidates on) is
+ skipped so each finding is rendered once.
"""
selected = list(getattr(diff, "new_alerts", []) or [])
if strict_blocking:
- selected.extend(getattr(diff, "unchanged_alerts", []) or [])
+ seen = {_alert_identity(alert) for alert in selected} - {None}
+ for alert in getattr(diff, "unchanged_alerts", []) or []:
+ identity = _alert_identity(alert)
+ if identity is None or identity not in seen:
+ selected.append(alert)
+ seen.add(identity)
return selected
+def _alert_identity(alert: Issue) -> Optional[Tuple[str, str]]:
+ purl = getattr(alert, "purl", "") or ""
+ if not purl:
+ return None
+ return (purl, getattr(alert, "type", "") or "")
+
+
def clone_diff_with_selected_alerts(diff: Diff, selected_alerts: List[Issue]) -> Diff:
"""Clone a diff object while replacing new_alerts with selected alerts."""
selected_diff = Diff(
diff --git a/tests/core/test_strict_blocking_duplicates.py b/tests/core/test_strict_blocking_duplicates.py
new file mode 100644
index 00000000..e4a352ff
--- /dev/null
+++ b/tests/core/test_strict_blocking_duplicates.py
@@ -0,0 +1,206 @@
+"""`--strict-blocking` lists each finding once, whatever the baseline.
+
+Added packages must not also count as unchanged. An added package that leaks into
+the unchanged set has its alerts reported twice under `--strict-blocking`, once as
+new and once as existing, doubling the JSON, SARIF, Slack and GitLab findings and
+inflating the "EXISTING blocking issues" count in the summary.
+
+These tests feed a mocked diff response through the same steps `create_new_diff`
+uses, then check what the output layer renders.
+"""
+import json
+from pathlib import Path
+from unittest.mock import Mock
+
+import pytest
+from socketdev.fullscans import StreamDiffResponse
+
+from socketsecurity.config import CliConfig
+from socketsecurity.core import Core
+from socketsecurity.core.alert_selection import select_diff_alerts
+from socketsecurity.core.classes import Diff, Issue
+from socketsecurity.core.socket_config import SocketConfig
+from socketsecurity.output import OutputHandler
+
+BUCKETS = ("added", "removed", "unchanged", "replaced", "updated")
+
+
+@pytest.fixture
+def core(mock_sdk_with_responses):
+ core = Core(config=SocketConfig(api_key="test_key"), sdk=mock_sdk_with_responses)
+ # Force the streaming diff so the mocked response below is the artifact source.
+ core.sdk.diffscans.create_from_ids.side_effect = Exception("diff-scans unavailable")
+ core.sdk.fullscans.stream_diff.side_effect = None
+ return core
+
+
+def _artifact(diff_type, artifact_id, name, alerts=None, direct=True, ancestors=None):
+ ref = {
+ "direct": direct,
+ "manifestFiles": [{"file": "package.json", "start": 0, "end": 0}] if direct else [],
+ "topLevelAncestors": ancestors or [],
+ }
+ return {
+ "diffType": diff_type,
+ "type": "npm",
+ "name": name,
+ "version": "1.0.0",
+ "id": artifact_id,
+ "head": [] if diff_type in ("removed", "replaced") else [ref],
+ "base": [ref] if diff_type in ("removed", "replaced") else [],
+ "license": "MIT",
+ "licenseDetails": [],
+ "author": [],
+ "size": 1,
+ "score": {},
+ "alerts": alerts or [],
+ }
+
+
+def _blocking_alert(key, alert_type="malware"):
+ return {
+ "key": key,
+ "type": alert_type,
+ "severity": "critical",
+ "category": "supplyChainRisk",
+ "props": {},
+ "action": "error",
+ }
+
+
+def _diff_response(**buckets):
+ raw = json.loads((Path(__file__).parent.parent / "data/fullscans/diff/stream_diff.json").read_text())
+ artifacts = {name: buckets.get(name, []) for name in BUCKETS}
+ return StreamDiffResponse.from_dict({
+ "success": raw["success"],
+ "status": raw["status"],
+ "data": {**raw["data"], "artifacts": artifacts},
+ })
+
+
+def _build_diff(core, response):
+ """Mirror the package and diff assembly in Core.create_new_diff."""
+ core.sdk.fullscans.stream_diff.return_value = response
+ added, removed, packages = core.get_added_and_removed_packages("head", "new")
+ unchanged = Core.get_unchanged_packages(packages, added, removed)
+ diff = core.create_diff_report(added, removed, unchanged)
+ diff.packages = packages
+ diff.id = "new"
+ diff.diff_url = "https://socket.dev/diff"
+ diff.report_url = "https://socket.dev/report"
+ return diff
+
+
+def _handler(strict_blocking=True):
+ config = Mock(spec=CliConfig)
+ config.disable_blocking = False
+ config.strict_blocking = strict_blocking
+ config.legal_format = "socket"
+ config.legal = False
+ config.repo = None
+ config.branch = None
+ config.commit_sha = None
+ return OutputHandler(config, Mock())
+
+
+def test_empty_baseline_lists_added_alerts_once(core):
+ """Against an empty baseline every package is added and none is unchanged."""
+ diff = _build_diff(core, _diff_response(added=[
+ _artifact("added", "a1", "alpha", [_blocking_alert("k1")]),
+ _artifact("added", "a2", "beta", [_blocking_alert("k2")]),
+ ]))
+
+ assert len(diff.new_alerts) == 2
+ assert diff.unchanged_alerts == []
+
+ handler = _handler()
+ report = handler.build_json_report(diff)
+ assert len(report["new_alerts"]) == 2
+ assert not handler.report_pass(diff)
+
+ summary = handler.build_summary_text(diff)
+ assert "NEW blocking issues: 2" in summary
+ assert "EXISTING blocking issues" not in summary
+
+
+def test_real_baseline_lists_new_and_existing_alerts_once_each(core):
+ """With a baseline, added alerts are new and unchanged alerts are existing."""
+ diff = _build_diff(core, _diff_response(
+ added=[_artifact("added", "a1", "alpha", [_blocking_alert("k1")])],
+ unchanged=[_artifact("unchanged", "u1", "gamma", [_blocking_alert("k3")])],
+ ))
+
+ assert [a.pkg_name for a in diff.new_alerts] == ["alpha"]
+ assert [a.pkg_name for a in diff.unchanged_alerts] == ["gamma"]
+
+ handler = _handler()
+ report = handler.build_json_report(diff)
+ assert sorted(a["pkg_name"] for a in report["new_alerts"]) == ["alpha", "gamma"]
+ assert not handler.report_pass(diff)
+
+ summary = handler.build_summary_text(diff)
+ assert "NEW blocking issues: 1" in summary
+ assert "EXISTING blocking issues: 1" in summary
+
+
+def test_real_baseline_fails_on_existing_alerts_alone(core):
+ """An unchanged blocking alert fails the run when the API returns it."""
+ diff = _build_diff(core, _diff_response(
+ unchanged=[_artifact("unchanged", "u1", "gamma", [_blocking_alert("k3")])],
+ ))
+
+ assert diff.new_alerts == []
+ assert not _handler(strict_blocking=True).report_pass(diff)
+ assert _handler(strict_blocking=False).report_pass(diff)
+
+
+def test_without_strict_blocking_output_is_unchanged(core):
+ diff = _build_diff(core, _diff_response(
+ added=[_artifact("added", "a1", "alpha", [_blocking_alert("k1")])],
+ unchanged=[_artifact("unchanged", "u1", "gamma", [_blocking_alert("k3")])],
+ ))
+
+ report = _handler(strict_blocking=False).build_json_report(diff)
+ assert [a["pkg_name"] for a in report["new_alerts"]] == ["alpha"]
+
+
+def test_unchanged_packages_are_keyed_by_artifact_id(core):
+ """Transitive unchanged alerts resolve their introducer through the ancestor ID."""
+ core.sdk.fullscans.stream_diff.return_value = _diff_response(unchanged=[
+ _artifact("unchanged", "top", "parent"),
+ _artifact(
+ "unchanged", "dep", "child", [_blocking_alert("k5")],
+ direct=False, ancestors=["top"],
+ ),
+ ])
+ added, removed, packages = core.get_added_and_removed_packages("head", "new")
+ unchanged = Core.get_unchanged_packages(packages, added, removed)
+
+ assert set(unchanged) == {"top", "dep"}
+ diff = core.create_diff_report(added, removed, unchanged)
+ assert diff.unchanged_alerts[0].introduced_by == [("npm/parent@1.0.0", "package.json")]
+
+
+def _issue(name, alert_type="malware"):
+ return Issue(
+ pkg_type="npm",
+ pkg_name=name,
+ pkg_version="1.0.0",
+ type=alert_type,
+ purl=f"{name}@1.0.0",
+ error=True,
+ )
+
+
+def test_select_diff_alerts_skips_unchanged_alert_already_listed_as_new():
+ diff = Diff()
+ diff.new_alerts = [_issue("alpha")]
+ diff.unchanged_alerts = [_issue("alpha"), _issue("alpha", "typosquat"), _issue("gamma")]
+
+ selected = select_diff_alerts(diff, strict_blocking=True)
+
+ assert [(a.pkg_name, a.type) for a in selected] == [
+ ("alpha", "malware"),
+ ("alpha", "typosquat"),
+ ("gamma", "malware"),
+ ]
diff --git a/uv.lock b/uv.lock
index 6077c132..98067b93 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1334,7 +1334,7 @@ wheels = [
[[package]]
name = "socketsecurity"
-version = "2.12.1"
+version = "2.12.2"
source = { editable = "." }
dependencies = [
{ name = "beautifulsoup4" },
From 4f19040d28f7e36aabe40a3ed69999e51a576498 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 16:23:03 -0500
Subject: [PATCH 02/11] Include the ecosystem in the strict-blocking dedupe key
Issue.purl holds only name and version, so an npm and a PyPI package can
share it. Keying the dedupe on purl and alert type alone would hide an
existing PyPI alert behind a new npm alert with the same name, version
and type.
The regression tests now run Core.create_new_diff with the scan upload
mocked out, instead of repeating its package assembly, so they fail if
create_new_diff goes back to filtering unchanged packages by purl key.
---
socketsecurity/core/alert_selection.py | 9 ++--
tests/core/test_strict_blocking_duplicates.py | 47 +++++++++++--------
2 files changed, 32 insertions(+), 24 deletions(-)
diff --git a/socketsecurity/core/alert_selection.py b/socketsecurity/core/alert_selection.py
index 83cddd40..8c89c8b5 100644
--- a/socketsecurity/core/alert_selection.py
+++ b/socketsecurity/core/alert_selection.py
@@ -16,8 +16,9 @@ def select_diff_alerts(diff: Diff, strict_blocking: bool = False) -> List[Issue]
In strict blocking mode, include unchanged alerts so rendered output aligns
with pass/fail policy evaluation. An unchanged alert that is already listed
- as new (same purl and alert type, the key the diff consolidates on) is
- skipped so each finding is rendered once.
+ as new (same ecosystem, purl and alert type) is skipped so each finding is
+ rendered once. The ecosystem is part of the key because ``Issue.purl`` holds
+ only name and version, so an npm and a PyPI package can share it.
"""
selected = list(getattr(diff, "new_alerts", []) or [])
if strict_blocking:
@@ -30,11 +31,11 @@ def select_diff_alerts(diff: Diff, strict_blocking: bool = False) -> List[Issue]
return selected
-def _alert_identity(alert: Issue) -> Optional[Tuple[str, str]]:
+def _alert_identity(alert: Issue) -> Optional[Tuple[str, str, str]]:
purl = getattr(alert, "purl", "") or ""
if not purl:
return None
- return (purl, getattr(alert, "type", "") or "")
+ return (getattr(alert, "pkg_type", "") or "", purl, getattr(alert, "type", "") or "")
def clone_diff_with_selected_alerts(diff: Diff, selected_alerts: List[Issue]) -> Diff:
diff --git a/tests/core/test_strict_blocking_duplicates.py b/tests/core/test_strict_blocking_duplicates.py
index e4a352ff..a37f67cc 100644
--- a/tests/core/test_strict_blocking_duplicates.py
+++ b/tests/core/test_strict_blocking_duplicates.py
@@ -5,15 +5,16 @@
new and once as existing, doubling the JSON, SARIF, Slack and GitLab findings and
inflating the "EXISTING blocking issues" count in the summary.
-These tests feed a mocked diff response through the same steps `create_new_diff`
-uses, then check what the output layer renders.
+These tests run `Core.create_new_diff` against a mocked diff response, with the
+scan upload mocked out, then check what the output layer renders.
"""
import json
from pathlib import Path
+from types import SimpleNamespace
from unittest.mock import Mock
import pytest
-from socketdev.fullscans import StreamDiffResponse
+from socketdev.fullscans import FullScanParams, StreamDiffResponse
from socketsecurity.config import CliConfig
from socketsecurity.core import Core
@@ -79,16 +80,15 @@ def _diff_response(**buckets):
def _build_diff(core, response):
- """Mirror the package and diff assembly in Core.create_new_diff."""
+ """Run Core.create_new_diff with the upload mocked out and `response` as the diff."""
core.sdk.fullscans.stream_diff.return_value = response
- added, removed, packages = core.get_added_and_removed_packages("head", "new")
- unchanged = Core.get_unchanged_packages(packages, added, removed)
- diff = core.create_diff_report(added, removed, unchanged)
- diff.packages = packages
- diff.id = "new"
- diff.diff_url = "https://socket.dev/diff"
- diff.report_url = "https://socket.dev/report"
- return diff
+ core.resolve_base_full_scan_id = Mock(return_value="head")
+ core.create_full_scan = Mock(return_value=SimpleNamespace(id="new"))
+ params = FullScanParams(repo="repo", branch="feature")
+ params.include_license_details = True
+ return core.create_new_diff(
+ ["/repo"], params, explicit_files=["/repo/package.json"],
+ )
def _handler(strict_blocking=True):
@@ -166,24 +166,20 @@ def test_without_strict_blocking_output_is_unchanged(core):
def test_unchanged_packages_are_keyed_by_artifact_id(core):
"""Transitive unchanged alerts resolve their introducer through the ancestor ID."""
- core.sdk.fullscans.stream_diff.return_value = _diff_response(unchanged=[
+ diff = _build_diff(core, _diff_response(unchanged=[
_artifact("unchanged", "top", "parent"),
_artifact(
"unchanged", "dep", "child", [_blocking_alert("k5")],
direct=False, ancestors=["top"],
),
- ])
- added, removed, packages = core.get_added_and_removed_packages("head", "new")
- unchanged = Core.get_unchanged_packages(packages, added, removed)
+ ]))
- assert set(unchanged) == {"top", "dep"}
- diff = core.create_diff_report(added, removed, unchanged)
assert diff.unchanged_alerts[0].introduced_by == [("npm/parent@1.0.0", "package.json")]
-def _issue(name, alert_type="malware"):
+def _issue(name, alert_type="malware", pkg_type="npm"):
return Issue(
- pkg_type="npm",
+ pkg_type=pkg_type,
pkg_name=name,
pkg_version="1.0.0",
type=alert_type,
@@ -204,3 +200,14 @@ def test_select_diff_alerts_skips_unchanged_alert_already_listed_as_new():
("alpha", "typosquat"),
("gamma", "malware"),
]
+
+
+def test_select_diff_alerts_keeps_same_purl_from_another_ecosystem():
+ """`Issue.purl` has no ecosystem, so npm and PyPI packages can share one."""
+ diff = Diff()
+ diff.new_alerts = [_issue("alpha", pkg_type="npm")]
+ diff.unchanged_alerts = [_issue("alpha", pkg_type="pypi")]
+
+ selected = select_diff_alerts(diff, strict_blocking=True)
+
+ assert [a.pkg_type for a in selected] == ["npm", "pypi"]
From 51ada53c13c326ce0ecbf9267a32dcc717d82ade Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 16:58:28 -0500
Subject: [PATCH 03/11] Decide exit codes in one place so the exit flags apply
to every run
Failures that are not security findings now raise InfrastructureError
instead of calling sys.exit, and cli() maps them through --disable-blocking
and --exit-code-on-api-error. Before, a missing API or SCM token, missing
reachability dependencies, an ineligible plan, a failed repository create
and a failed reachability run each exited with a hard-coded 2 or 3 that
ignored both flags.
- Invalid flags and config values exit 2, the code argparse already uses
for its own usage errors, instead of 1, which means blocking findings.
--disable-blocking does not apply to them.
- Ctrl+C exits 130 instead of 2, so it no longer shares a code with usage
errors.
- A diff scan the API marks incomplete fails as an infrastructure error
instead of reporting a result that may be missing alerts. It does not
fall back to the streaming comparison, which reads the same scans.
- A repository lookup that fails with 401 or 403 is reported as a missing
repo:list scope instead of being treated as a missing repository and
ending in a repo:create failure.
---
socketsecurity/config.py | 77 ++++++---------
socketsecurity/core/__init__.py | 45 ++++++---
socketsecurity/core/scm/github.py | 7 +-
socketsecurity/core/scm/gitlab.py | 4 +-
socketsecurity/exit_codes.py | 42 ++++++++
socketsecurity/socketcli.py | 80 ++++++++-------
tests/core/test_exit_codes.py | 158 ++++++++++++++++++++++++++++++
tests/core/test_sdk_methods.py | 64 +++++-------
tests/unit/test_config.py | 10 +-
tests/unit/test_exclude_paths.py | 6 +-
tests/unit/test_gitlab_auth.py | 7 +-
tests/unit/test_socketcli.py | 4 +-
12 files changed, 349 insertions(+), 155 deletions(-)
create mode 100644 socketsecurity/exit_codes.py
create mode 100644 tests/core/test_exit_codes.py
diff --git a/socketsecurity/config.py b/socketsecurity/config.py
index 9e8f1580..96d906bc 100644
--- a/socketsecurity/config.py
+++ b/socketsecurity/config.py
@@ -2,15 +2,22 @@
import json
import logging
import os
+import sys
import tomllib
from dataclasses import asdict, dataclass, field
-from typing import List, Optional
+from typing import List, NoReturn, Optional
from socketdev import INTEGRATION_TYPES, IntegrationType
from socketsecurity import __version__
+from socketsecurity.exit_codes import EXIT_USAGE
+def _usage_error(message: str) -> NoReturn:
+ """Log an invalid flag or config value and exit like an argparse usage error."""
+ logging.error(message)
+ sys.exit(EXIT_USAGE)
+
def get_plugin_config_from_env(prefix: str) -> dict:
config_str = os.getenv(f"{prefix}_CONFIG_JSON", "{}")
try:
@@ -65,18 +72,14 @@ def load_cli_config_file(config_path: str) -> dict:
elif config_path.lower().endswith(".toml"):
data = tomllib.load(f)
else:
- logging.error("--config must be a .json or .toml file")
- exit(1)
+ _usage_error("--config must be a .json or .toml file")
except FileNotFoundError:
- logging.error(f"Config file not found: {config_path}")
- exit(1)
+ _usage_error(f"Config file not found: {config_path}")
except (json.JSONDecodeError, tomllib.TOMLDecodeError) as e:
- logging.error(f"Invalid config file format: {e}")
- exit(1)
+ _usage_error(f"Invalid config file format: {e}")
if not isinstance(data, dict):
- logging.error("Config file must contain a top-level object/table")
- exit(1)
+ _usage_error("Config file must contain a top-level object/table")
scoped = data.get("socketcli")
if isinstance(scoped, dict):
@@ -106,7 +109,7 @@ def validate_exclude_paths(patterns: List[str]) -> None:
Patterns are scan-root-relative globs. Reject the cases coana's --exclude-dirs / fast-glob
cannot honor: negation, absolute paths, ``..`` traversal, and degenerate match-everything.
- Exits with code 1 on the first invalid pattern.
+ Exits with the usage-error code (2) on the first invalid pattern.
"""
# Degenerate match-everything forms, compared against the trailing-slash-stripped pattern
# (so "**/" reduces to "**" and is rejected, matching Node's stripTrailingSlash + check).
@@ -114,17 +117,13 @@ def validate_exclude_paths(patterns: List[str]) -> None:
for p in patterns:
norm = (p or "").strip().replace("\\", "/")
if norm.startswith("!"):
- logging.error(f"--exclude-paths: negation patterns are not supported: {p!r}")
- exit(1)
+ _usage_error(f"--exclude-paths: negation patterns are not supported: {p!r}")
if norm.startswith("/"):
- logging.error(f"--exclude-paths: patterns must be scan-root relative (no leading '/'): {p!r}")
- exit(1)
+ _usage_error(f"--exclude-paths: patterns must be scan-root relative (no leading '/'): {p!r}")
if norm == ".." or norm.startswith("../") or "/../" in norm or norm.endswith("/.."):
- logging.error(f"--exclude-paths: '..' path traversal is not allowed: {p!r}")
- exit(1)
+ _usage_error(f"--exclude-paths: '..' path traversal is not allowed: {p!r}")
if norm.rstrip("/") in degenerate:
- logging.error(f"--exclude-paths: pattern would exclude everything: {p!r}")
- exit(1)
+ _usage_error(f"--exclude-paths: pattern would exclude everything: {p!r}")
@dataclass
@@ -416,11 +415,9 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
try:
config_args["excluded_ecosystems"] = json.loads(excluded_ecosystems.replace("'", '"'))
except json.JSONDecodeError:
- logging.error(f"Unable to parse excluded_ecosystems: {excluded_ecosystems}")
- exit(1)
+ _usage_error(f"Unable to parse excluded_ecosystems: {excluded_ecosystems}")
else:
- logging.error(f"Unable to parse excluded_ecosystems: {excluded_ecosystems}")
- exit(1)
+ _usage_error(f"Unable to parse excluded_ecosystems: {excluded_ecosystems}")
# Build Slack plugin config, merging CLI arg with env config
slack_config = get_plugin_config_from_env("SOCKET_SLACK")
if args.slack_webhook:
@@ -444,21 +441,18 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
# Validate that sub_paths and workspace_name are used together
if args.sub_paths and not args.workspace_name:
- logging.error("--sub-path requires --workspace-name to be specified")
- exit(1)
+ _usage_error("--sub-path requires --workspace-name to be specified")
if args.workspace_name and not args.sub_paths:
- logging.error("--workspace-name requires --sub-path to be specified")
- exit(1)
+ _usage_error("--workspace-name requires --sub-path to be specified")
# The API validates the repo as a slug, which can't contain "/", so an
# owner/repo value would otherwise fail later at repository creation.
if args.repo and "/" in args.repo:
suggested = args.repo.rstrip("/").rsplit("/", 1)[-1]
- logging.error(
+ _usage_error(
f"--repo takes the repository slug without its owner, but got '{args.repo}'. "
f"Use --repo {suggested}, and --workspace for the owner if your repositories use one."
)
- exit(1)
if args.pending_head:
logging.warning(
@@ -469,21 +463,16 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
# argparse only enforces the mutually exclusive group for real CLI args;
# this also catches both values arriving via a --config file.
if args.base_scan_id and args.base_commit_sha:
- logging.error("--base-scan-id and --base-commit-sha are mutually exclusive")
- exit(1)
+ _usage_error("--base-scan-id and --base-commit-sha are mutually exclusive")
if args.sarif_scope == "full" and not args.reach:
- logging.error("--sarif-scope full requires --reach to be specified")
- exit(1)
+ _usage_error("--sarif-scope full requires --reach to be specified")
if args.sarif_reachability != "all" and not args.reach:
- logging.error("--sarif-reachability requires --reach to be specified")
- exit(1)
+ _usage_error("--sarif-reachability requires --reach to be specified")
if args.sarif_grouping == "alert" and args.sarif_scope != "full":
- logging.error("--sarif-grouping alert currently requires --sarif-scope full")
- exit(1)
+ _usage_error("--sarif-grouping alert currently requires --sarif-scope full")
if args.sarif_reachability in ("potentially", "reachable-or-potentially") and args.sarif_scope != "full":
- logging.error("--sarif-reachability potentially/reachable-or-potentially requires --sarif-scope full")
- exit(1)
+ _usage_error("--sarif-reachability potentially/reachable-or-potentially requires --sarif-scope full")
# Validate --exclude-paths patterns up front (mirrors Node's assertValidExcludePaths).
if config_args.get("exclude_paths"):
@@ -491,23 +480,19 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
# Validate that only_facts_file requires reach
if args.only_facts_file and not args.reach:
- logging.error("--only-facts-file requires --reach to be specified")
- exit(1)
+ _usage_error("--only-facts-file requires --reach to be specified")
# Validate that reach_use_only_pregenerated_sboms requires reach
if args.reach_use_only_pregenerated_sboms and not args.reach:
- logging.error("--reach-use-only-pregenerated-sboms requires --reach to be specified")
- exit(1)
+ _usage_error("--reach-use-only-pregenerated-sboms requires --reach to be specified")
# Validate reach_concurrency is >= 1 if provided
if args.reach_concurrency is not None and args.reach_concurrency < 1:
- logging.error("--reach-concurrency must be >= 1")
- exit(1)
+ _usage_error("--reach-concurrency must be >= 1")
# Validate max_purl_batch_size is within allowed range
if args.max_purl_batch_size < 1 or args.max_purl_batch_size > 9999:
- logging.error("--max-purl-batch-size must be between 1 and 9999")
- exit(1)
+ _usage_error("--max-purl-batch-size must be between 1 and 9999")
return cls(**config_args)
diff --git a/socketsecurity/core/__init__.py b/socketsecurity/core/__init__.py
index 305d6309..407cc58b 100644
--- a/socketsecurity/core/__init__.py
+++ b/socketsecurity/core/__init__.py
@@ -8,7 +8,6 @@
import random
import re
import shutil
-import sys
import tarfile
import tempfile
import time
@@ -32,6 +31,7 @@
from socketsecurity import USER_AGENT, __version__
from socketsecurity.core.classes import Alert, Diff, FullScan, Issue, Package, Purl
from socketsecurity.core.exceptions import APIResourceNotFound
+from socketsecurity.exit_codes import IncompleteComparisonError, InfrastructureError
from .resource_utils import check_file_count_against_ulimit
from .socket_config import SocketConfig
@@ -1501,7 +1501,8 @@ def get_repo_info(self, repo_slug: str, default_branch: str = "socket-default-br
RepositoryInfo object
Raises:
- Exception: If API request fails
+ InfrastructureError: If the token can't read the repository, or the
+ repository doesn't exist and can't be created.
"""
try:
# Need to switch to either standard logger or not call our module logging so that there isn't a conflict
@@ -1517,7 +1518,15 @@ def get_repo_info(self, repo_slug: str, default_branch: str = "socket-default-br
if not response.success:
log.error(f"Failed to get repository: {response.status}")
# log.error(response.message)
- except APIFailure:
+ except APIFailure as lookup_error:
+ # Only a missing repository should be created. A token without the
+ # repo:list scope gets 401/403 here, and treating that as "doesn't
+ # exist" would end in a confusing repo:create failure instead.
+ if lookup_error.status_code in (401, 403):
+ raise InfrastructureError(
+ f"Failed to get repository {repo_slug} (HTTP {lookup_error.status_code}). "
+ "The API token may be missing the repo:list scope."
+ ) from lookup_error
log.warning(f"Failed to get repository {repo_slug}, attempting to create it")
try:
@@ -1541,10 +1550,10 @@ def get_repo_info(self, repo_slug: str, default_branch: str = "socket-default-br
# The SDK appends the request path and response headers after the first line,
# and some subclasses carry no message at all.
reason = str(e).split("\n", 1)[0] or type(e).__name__
- log.error(f"API failure while creating repository {repo_slug}{status}: {reason}")
+ message = f"API failure while creating repository {repo_slug}{status}: {reason}"
if e.status_code == 403 and not isinstance(e, (APIInsufficientQuota, APIOrganizationNotAllowed)):
- log.error("A 403 here usually means the API token is missing the repo:create scope.")
- sys.exit(2) # Exit here with code 2. Code 1 indicates a successfully-detected security issue.
+ message += "\nA 403 here usually means the API token is missing the repo:create scope."
+ raise InfrastructureError(message) from e
return response.data
@@ -1864,16 +1873,13 @@ def resolve_base_full_scan_id(self, params: FullScanParams) -> Optional[str]:
"the merge base."
)
else:
- log.error(
+ raise InfrastructureError(
f"No full scan found for commit {commit_sha} in repo {params.repo} "
"(--base-commit-sha), and no scanned ancestor within "
f"{ANCESTOR_WALK_MAX_DEPTH} commits of it. Ensure a scan was "
"created for that commit (e.g. the CLI runs on default-branch "
"pushes), or pass --base-scan-id instead."
)
- if self.cli_config.disable_blocking:
- sys.exit(0)
- sys.exit(self.cli_config.exit_code_on_api_error)
log.info(
f"Baseline selected: source={baseline_source} "
f"scan_id={json.dumps(scan_id)} commit={json.dumps(baseline_commit)}"
@@ -1892,14 +1898,11 @@ def resolve_base_full_scan_id(self, params: FullScanParams) -> Optional[str]:
# Returning None would make the caller create an empty baseline scan,
# reporting every dependency as newly added, so fail loudly like the
# --base-commit-sha path above.
- log.error(
- f"Failed to resolve the matching head scan for repo {params.repo}: {error}"
- )
if self.cli_config is None:
raise
- if self.cli_config.disable_blocking:
- sys.exit(0)
- sys.exit(self.cli_config.exit_code_on_api_error)
+ raise InfrastructureError(
+ f"Failed to resolve the matching head scan for repo {params.repo}: {error}"
+ ) from error
if scan_id:
log.info(
"Baseline selected: source=repository-head "
@@ -2106,6 +2109,12 @@ def get_diff_scan_artifacts(
f"Error fetching diff scan {diff_scan_id}: unexpected response: {str(response)[:500]}"
)
artifacts_dict = scan["artifacts"]
+ 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."
+ )
log.info(
"Diff scan comparison ready in "
f"{time.monotonic() - poll_start:.2f}s: id={diff_scan_id}, "
@@ -2215,6 +2224,10 @@ def get_added_and_removed_packages(
new_full_scan_id,
external_href=external_href,
)
+ except IncompleteComparisonError:
+ # The streaming comparison reads the same scans, so falling back to it
+ # would only hide that the result is partial.
+ raise
except Exception as error:
# SDK error messages can span many lines (path + response headers); the
# first line carries the status, which is all the warning needs.
diff --git a/socketsecurity/core/scm/github.py b/socketsecurity/core/scm/github.py
index dcfa5607..5248fc87 100644
--- a/socketsecurity/core/scm/github.py
+++ b/socketsecurity/core/scm/github.py
@@ -11,6 +11,7 @@
from socketsecurity.core.exceptions import APIFailure
from socketsecurity.core.git_remote import parse_git_remote
from socketsecurity.core.scm_comments import Comments
+from socketsecurity.exit_codes import InfrastructureError
from socketsecurity.socketcli import CliClient
@@ -54,8 +55,7 @@ def from_env(cls, pr_number: Optional[str] = None) -> 'GithubConfig':
"""Create config from environment variables with optional overrides"""
token = os.getenv('GH_API_TOKEN')
if not token:
- log.error("Unable to get Github API Token from GH_API_TOKEN")
- sys.exit(2)
+ raise InfrastructureError("Unable to get Github API Token from GH_API_TOKEN")
is_buildkite = os.getenv("BUILDKITE") == "true"
buildkite_pr = os.getenv("BUILDKITE_PULL_REQUEST")
@@ -172,8 +172,7 @@ def __init__(
self._ignore_permission_cache: dict[str, Optional[bool]] = {}
if not self.config.token:
- log.error("Unable to get Github API Token")
- sys.exit(2)
+ raise InfrastructureError("Unable to get Github API Token")
def check_event_type(self) -> str:
if self.config.event_name.lower() in ["push", "workflow_dispatch"]:
diff --git a/socketsecurity/core/scm/gitlab.py b/socketsecurity/core/scm/gitlab.py
index d1fd1119..a7b2bd3a 100644
--- a/socketsecurity/core/scm/gitlab.py
+++ b/socketsecurity/core/scm/gitlab.py
@@ -11,6 +11,7 @@
from socketsecurity.core import log
from socketsecurity.core.classes import Comment
from socketsecurity.core.scm_comments import Comments
+from socketsecurity.exit_codes import InfrastructureError
from socketsecurity.socketcli import CliClient
@@ -37,8 +38,7 @@ class GitlabConfig:
def from_env(cls) -> 'GitlabConfig':
token = os.getenv('GITLAB_TOKEN')
if not token:
- log.error("Unable to get GitLab API Token from GITLAB_TOKEN")
- sys.exit(2)
+ raise InfrastructureError("Unable to get GitLab API Token from GITLAB_TOKEN")
project_name = os.getenv('CI_PROJECT_NAME', '')
if "/" in project_name:
diff --git a/socketsecurity/exit_codes.py b/socketsecurity/exit_codes.py
new file mode 100644
index 00000000..2be3d2a7
--- /dev/null
+++ b/socketsecurity/exit_codes.py
@@ -0,0 +1,42 @@
+"""Process exit codes, and the exceptions that map onto them.
+
+``socketcli.cli()`` is the only place that turns an outcome into an exit code,
+so ``--disable-blocking`` and ``--exit-code-on-api-error`` apply to every run
+that gets past argument parsing:
+
+* ``EXIT_OK`` (0): no blocking findings, or ``--disable-blocking`` is set.
+* ``EXIT_BLOCKING`` (1): blocking security findings.
+* ``EXIT_USAGE`` (2): invalid flags or configuration. The same code argparse uses
+ for its own usage errors. ``--disable-blocking`` does not apply, because a
+ misconfigured run never got far enough to scan anything.
+* ``EXIT_INFRASTRUCTURE`` (3): missing credentials, API or environment failures.
+ ``--exit-code-on-api-error`` replaces it; ``--disable-blocking`` turns it into 0.
+* ``EXIT_INTERRUPTED`` (130): Ctrl+C / SIGINT, the POSIX 128 + signal number
+ convention. ``--disable-blocking`` turns it into 0.
+
+This module imports nothing from the package so config parsing can use it
+without pulling in ``socketsecurity.core``.
+"""
+
+EXIT_OK = 0
+EXIT_BLOCKING = 1
+EXIT_USAGE = 2
+EXIT_INFRASTRUCTURE = 3
+EXIT_INTERRUPTED = 130
+
+
+class InfrastructureError(Exception):
+ """A run that cannot continue for a reason other than its own findings.
+
+ Raise it instead of calling ``sys.exit`` so ``cli()`` can apply
+ ``--disable-blocking`` and ``--exit-code-on-api-error``. The message is
+ logged as is, without a traceback.
+ """
+
+
+class IncompleteComparisonError(InfrastructureError):
+ """The API marked a scan comparison incomplete.
+
+ An incomplete comparison can leave out alerts, so a passing result would not
+ mean the change is clean.
+ """
diff --git a/socketsecurity/socketcli.py b/socketsecurity/socketcli.py
index 066fe2df..86f79bcd 100644
--- a/socketsecurity/socketcli.py
+++ b/socketsecurity/socketcli.py
@@ -4,7 +4,7 @@
import sys
import traceback
from datetime import datetime, timezone
-from typing import List, Optional, Tuple
+from typing import List, NoReturn, Optional, Tuple
from uuid import uuid4
from dotenv import load_dotenv
@@ -29,6 +29,12 @@
from socketsecurity.core.scm_comments import Comments
from socketsecurity.core.socket_config import SocketConfig, module_folder_dirs
from socketsecurity.core.streaming import StreamingLogs
+from socketsecurity.exit_codes import (
+ EXIT_INTERRUPTED,
+ EXIT_OK,
+ EXIT_USAGE,
+ InfrastructureError,
+)
from socketsecurity.fossa_compat import build_fossa_attribution_payload
from socketsecurity.output import OutputHandler
@@ -257,25 +263,27 @@ def cli():
main_code()
except KeyboardInterrupt:
log.info("Keyboard Interrupt detected, exiting")
- config = CliConfig.from_args() # Get current config
- if not config.disable_blocking:
- sys.exit(2)
- else:
- sys.exit(0)
+ config = CliConfig.from_args()
+ sys.exit(EXIT_OK if config.disable_blocking else EXIT_INTERRUPTED)
+ except InfrastructureError as error:
+ _exit_for_infrastructure_error(str(error), include_traceback=False)
except Exception as error:
- config = CliConfig.from_args() # Get current config
- _emit_infrastructure_error(
+ _exit_for_infrastructure_error(
f"Unexpected error when running the CLI: {error}",
include_traceback=True,
)
- # --disable-blocking forces a clean exit for ALL outcomes (it takes
- # precedence over --exit-code-on-api-error); otherwise infra/API errors
- # exit with the configurable code (default 3), keeping them distinct
- # from blocking security findings (exit 1).
- if not config.disable_blocking:
- sys.exit(config.exit_code_on_api_error)
- else:
- sys.exit(0)
+
+
+def _exit_for_infrastructure_error(message: str, include_traceback: bool) -> NoReturn:
+ """Exit for a failure that is not a security finding.
+
+ --disable-blocking takes precedence and exits 0. Otherwise the code is
+ --exit-code-on-api-error (default 3), which keeps these failures distinct
+ from blocking findings (1) and usage errors (2). See socketsecurity.exit_codes.
+ """
+ config = CliConfig.from_args()
+ _emit_infrastructure_error(message, include_traceback=include_traceback)
+ sys.exit(EXIT_OK if config.disable_blocking else config.exit_code_on_api_error)
def main_code():
@@ -290,10 +298,11 @@ def main_code():
# Validate API token
if not config.api_token:
- log.info("Socket API Token not found. Please set it using either:\n"
- "1. Command line: --api-token YOUR_TOKEN\n"
- "2. Environment variable: SOCKET_SECURITY_API_TOKEN")
- sys.exit(3)
+ raise InfrastructureError(
+ "Socket API Token not found. Please set it using either:\n"
+ "1. Command line: --api-token YOUR_TOKEN\n"
+ "2. Environment variable: SOCKET_SECURITY_API_TOKEN"
+ )
sdk = build_socket_sdk(config)
# Suppress urllib3 InsecureRequestWarning when using --allow-unverified
@@ -360,10 +369,11 @@ def main_code():
missing_deps.append(dep)
if missing_deps:
- log.error(f"Reachability analysis requires the following dependencies: {', '.join(required_deps)}")
- log.error(f"Missing dependencies: {', '.join(missing_deps)}")
- log.error("Please install the missing dependencies and try again.")
- sys.exit(3)
+ raise InfrastructureError(
+ f"Reachability analysis requires the following dependencies: {', '.join(required_deps)}\n"
+ f"Missing dependencies: {', '.join(missing_deps)}\n"
+ "Please install the missing dependencies and try again."
+ )
log.info(f"All required dependencies found: {', '.join(found_deps)}")
@@ -378,15 +388,17 @@ def main_code():
# Check if plan matches enterprise* pattern (enterprise, enterprise_trial, etc.)
if not org_plan.startswith('enterprise'):
- log.error("Reachability analysis is only available for enterprise plans.")
- log.error(f"Your organization plan is: {org_plan}")
- log.error("Please upgrade to an enterprise plan to use reachability analysis.")
- sys.exit(3)
+ raise InfrastructureError(
+ "Reachability analysis is only available for enterprise plans.\n"
+ f"Your organization plan is: {org_plan}\n"
+ "Please upgrade to an enterprise plan to use reachability analysis."
+ )
log.info(f"Organization plan verified: {org_plan}")
else:
- log.error("Unable to retrieve organization information for plan verification.")
- sys.exit(3)
+ raise InfrastructureError(
+ "Unable to retrieve organization information for plan verification."
+ )
# Parse files argument
try:
@@ -420,7 +432,7 @@ def main_code():
log.error(f"Error details: {error}")
log.debug(f"Files type: {type(config.files)}")
log.debug(f"Files repr: {repr(config.files)}")
- sys.exit(3)
+ sys.exit(EXIT_USAGE)
# Determine if files were explicitly specified
files_explicitly_specified = config.files != "[]" and len(specified_files) > 0
@@ -579,9 +591,11 @@ def main_code():
log.info(f"Pre-generated SBOMs mode: will submit {len(sbom_files_to_submit)} files (CDX, SPDX, and facts file)")
except Exception as e:
- log.error(f"Reachability analysis failed: {str(e)}")
+ # With --disable-blocking the scan carries on without reachability
+ # data instead of exiting 0 before anything is reported.
if not config.disable_blocking:
- sys.exit(3)
+ raise InfrastructureError(f"Reachability analysis failed: {e}") from e
+ log.error(f"Reachability analysis failed: {str(e)}")
log.info("Continuing with normal scan flow...")
diff --git a/tests/core/test_exit_codes.py b/tests/core/test_exit_codes.py
new file mode 100644
index 00000000..f9713b3e
--- /dev/null
+++ b/tests/core/test_exit_codes.py
@@ -0,0 +1,158 @@
+"""Exit codes are decided in one place, so the exit flags apply to every run.
+
+Failures that are not security findings raise InfrastructureError and reach
+``socketcli.cli()``, which applies ``--disable-blocking`` and
+``--exit-code-on-api-error``. Invalid flags exit 2 like argparse's own usage
+errors, and Ctrl+C exits 130. See socketsecurity.exit_codes.
+"""
+import sys
+from unittest.mock import MagicMock
+
+import pytest
+from socketdev.exceptions import (
+ APIFailure,
+ APIInsufficientPermissions,
+ APIResourceNotFound,
+)
+
+from socketsecurity import socketcli
+from socketsecurity.config import CliConfig
+from socketsecurity.core import Core
+from socketsecurity.core.socket_config import SocketConfig
+from socketsecurity.exit_codes import IncompleteComparisonError, InfrastructureError
+
+
+def _run_cli(monkeypatch, argv, error):
+ def fail_main_code():
+ raise error
+
+ monkeypatch.setattr(socketcli, "main_code", fail_main_code)
+ monkeypatch.setattr(sys, "argv", ["socketcli", "--api-token", "test", *argv])
+ with pytest.raises(SystemExit) as exc_info:
+ socketcli.cli()
+ return exc_info.value.code
+
+
+@pytest.mark.parametrize(
+ "argv, expected",
+ [
+ ([], 3),
+ (["--exit-code-on-api-error", "100"], 100),
+ (["--disable-blocking"], 0),
+ (["--disable-blocking", "--exit-code-on-api-error", "100"], 0),
+ ],
+)
+def test_infrastructure_error_honors_exit_flags(monkeypatch, capsys, argv, expected):
+ code = _run_cli(monkeypatch, argv, InfrastructureError("token missing a scope"))
+
+ assert code == expected
+ # Expected failures are reported without a traceback.
+ assert "Traceback" not in capsys.readouterr().err
+
+
+def test_infrastructure_error_message_is_logged(monkeypatch, caplog):
+ _run_cli(monkeypatch, [], InfrastructureError("Unable to get GitLab API Token"))
+
+ assert "Unable to get GitLab API Token" in caplog.text
+
+
+def test_keyboard_interrupt_with_disable_blocking_exits_0(monkeypatch):
+ assert _run_cli(monkeypatch, ["--disable-blocking"], KeyboardInterrupt()) == 0
+
+
+def test_invalid_flags_exit_2_even_with_disable_blocking():
+ """A misconfigured run never scanned anything, so --disable-blocking doesn't apply."""
+ with pytest.raises(SystemExit) as exc_info:
+ CliConfig.from_args([
+ "--api-token", "test", "--disable-blocking",
+ "--base-scan-id", "a", "--base-commit-sha", "b",
+ ])
+ assert exc_info.value.code == 2
+
+
+@pytest.mark.parametrize("argv, expected", [([], 3), (["--disable-blocking"], 0)])
+def test_missing_api_token_honors_exit_flags(monkeypatch, caplog, argv, expected):
+ """A fork pull request has no secrets; --disable-blocking should keep it green."""
+ monkeypatch.delenv("SOCKET_SECURITY_API_TOKEN", raising=False)
+ monkeypatch.delenv("SOCKET_SECURITY_API_KEY", raising=False)
+ monkeypatch.setattr(sys, "argv", ["socketcli", *argv])
+
+ with pytest.raises(SystemExit) as exc_info:
+ socketcli.cli()
+
+ assert exc_info.value.code == expected
+ assert "Socket API Token not found" in caplog.text
+
+
+# --- Repository lookup ---------------------------------------------------------------
+
+
+@pytest.fixture
+def core():
+ sdk = MagicMock()
+ return Core(config=SocketConfig(api_key="test_key"), sdk=sdk)
+
+
+def test_repo_lookup_permission_error_does_not_try_to_create(core):
+ """A token without repo:list is reported as such, not as a missing repository."""
+ core.sdk.repos.repo.side_effect = APIInsufficientPermissions(status_code=403)
+
+ with pytest.raises(InfrastructureError, match="repo:list"):
+ core.get_repo_info("my-repo")
+
+ core.sdk.repos.post.assert_not_called()
+
+
+def test_repo_lookup_not_found_creates_the_repository(core):
+ created = MagicMock(data="repo-info")
+ core.sdk.repos.repo.side_effect = [APIResourceNotFound(status_code=404), created]
+ core.sdk.repos.post.return_value = {"id": "repo"}
+
+ assert core.get_repo_info("my-repo") == "repo-info"
+ core.sdk.repos.post.assert_called_once()
+
+
+def test_repo_creation_failure_raises_infrastructure_error(core):
+ core.sdk.repos.repo.side_effect = APIResourceNotFound(status_code=404)
+ core.sdk.repos.post.side_effect = APIFailure("forbidden", status_code=403)
+
+ with pytest.raises(InfrastructureError, match="repo:create"):
+ core.get_repo_info("my-repo")
+
+
+# --- Incomplete comparisons ----------------------------------------------------------
+
+
+@pytest.fixture
+def incomplete_response():
+ return {"diff_scan": {"id": "diff-scan-1", "incomplete": True, "artifacts": {}}}
+
+
+def test_incomplete_comparison_raises(core, incomplete_response):
+ core.sdk.diffscans.create_from_ids.return_value = {"diff_scan": {"id": "diff-scan-1"}}
+ core.sdk.diffscans.get.return_value = incomplete_response
+
+ with pytest.raises(IncompleteComparisonError, match="incomplete"):
+ core.get_diff_scan_artifacts("head", "new")
+
+
+def test_incomplete_comparison_does_not_fall_back_to_streaming(core, incomplete_response):
+ """The streaming comparison reads the same scans, so it can't fill the gap."""
+ core.sdk.diffscans.create_from_ids.return_value = {"diff_scan": {"id": "diff-scan-1"}}
+ core.sdk.diffscans.get.return_value = incomplete_response
+
+ with pytest.raises(IncompleteComparisonError):
+ core.get_added_and_removed_packages("head", "new")
+
+ core.sdk.fullscans.stream_diff.assert_not_called()
+
+
+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 = {
+ "diff_scan": {"id": "diff-scan-1", "incomplete": False, "artifacts": {}},
+ }
+
+ artifacts = core.get_diff_scan_artifacts("head", "new")
+
+ assert artifacts.added == []
diff --git a/tests/core/test_sdk_methods.py b/tests/core/test_sdk_methods.py
index 9235bc6b..b69d57a1 100644
--- a/tests/core/test_sdk_methods.py
+++ b/tests/core/test_sdk_methods.py
@@ -13,6 +13,7 @@
from socketsecurity.config import CliConfig
from socketsecurity.core import ANCESTOR_SCAN_LOOKUP_LIMIT, SCAN_LOOKUP_PAGE_SIZE, Core
from socketsecurity.core.socket_config import SocketConfig
+from socketsecurity.exit_codes import InfrastructureError
@pytest.fixture
@@ -54,7 +55,7 @@ def test_get_repo_info(core, mock_sdk_with_responses):
def test_get_repo_info_logs_why_repo_creation_failed(core, mock_sdk_with_responses, caplog):
- """A repo that isn't in Socket yet and can't be created exits 2 with the reason logged"""
+ """A repo that isn't in Socket yet and can't be created fails with the reason"""
mock_sdk_with_responses.repos.repo.side_effect = APIResourceNotFound(status_code=404)
# Mirrors the SDK, which appends the request path and response headers to the message
mock_sdk_with_responses.repos.post.side_effect = APIAccessDenied(
@@ -62,14 +63,13 @@ def test_get_repo_info_logs_why_repo_creation_failed(core, mock_sdk_with_respons
status_code=403,
)
- with caplog.at_level(logging.INFO, logger="socketdev"), pytest.raises(SystemExit) as exit_info:
+ with caplog.at_level(logging.INFO, logger="socketdev"), pytest.raises(InfrastructureError) as error_info:
core.get_repo_info("new-repo")
- assert exit_info.value.code == 2
messages = [record.getMessage() for record in caplog.records]
assert "Failed to get repository new-repo, attempting to create it" in messages
- assert "API failure while creating repository new-repo (HTTP 403): Insufficient permissions" in messages
- assert any("repo:create" in message for message in messages)
+ assert "API failure while creating repository new-repo (HTTP 403): Insufficient permissions" in str(error_info.value)
+ assert "repo:create" in str(error_info.value)
@pytest.mark.parametrize(
@@ -86,12 +86,12 @@ def test_get_repo_info_repo_creation_failure_reason(
mock_sdk_with_responses.repos.repo.side_effect = APIResourceNotFound(status_code=404)
mock_sdk_with_responses.repos.post.side_effect = error
- with caplog.at_level(logging.INFO, logger="socketdev"), pytest.raises(SystemExit):
+ with pytest.raises(InfrastructureError) as error_info:
core.get_repo_info("new-repo")
- messages = [record.getMessage() for record in caplog.records]
- assert f"API failure while creating repository new-repo (HTTP 403): {expected_reason}" in messages
- assert any("repo:create" in message for message in messages) is expects_scope_hint
+ message = str(error_info.value)
+ assert f"API failure while creating repository new-repo (HTTP 403): {expected_reason}" in message
+ assert ("repo:create" in message) is expects_scope_hint
def test_get_repo_info_restores_log_level_after_creating_repo(
@@ -339,28 +339,19 @@ def test_resolve_base_full_scan_id_scopes_head_to_workspace(core):
},
)
-def test_resolve_base_full_scan_id_workspace_lookup_failure_exits(core):
- """A failed workspace lookup fails the run instead of diffing against an empty scan"""
- core.cli_config = make_cli_config()
- core.sdk.fullscans.get.return_value = {}
-
- params = make_full_scan_params(workspace="customer-a")
-
- with pytest.raises(SystemExit) as exc_info:
- core.resolve_base_full_scan_id(params)
- assert exc_info.value.code == core.cli_config.exit_code_on_api_error
-
+@pytest.mark.parametrize("flags", [(), ("--disable-blocking",)])
+def test_resolve_base_full_scan_id_workspace_lookup_failure_fails(core, flags):
+ """A failed workspace lookup fails the run instead of diffing against an empty scan.
-def test_resolve_base_full_scan_id_workspace_lookup_failure_disable_blocking(core):
- """--disable-blocking keeps the failed lookup from failing the build"""
- core.cli_config = make_cli_config("--disable-blocking")
+ The exit flags are applied by cli(), so the failure is raised either way.
+ """
+ core.cli_config = make_cli_config(*flags)
core.sdk.fullscans.get.return_value = {}
params = make_full_scan_params(workspace="customer-a")
- with pytest.raises(SystemExit) as exc_info:
+ with pytest.raises(InfrastructureError, match="Failed to resolve the matching head scan"):
core.resolve_base_full_scan_id(params)
- assert exc_info.value.code == 0
def test_resolve_base_full_scan_id_workspace_lookup_failure_without_cli_config(core):
@@ -486,7 +477,7 @@ def test_resolve_base_full_scan_id_ancestor_fallback_skips_temporary_scans(core,
lambda self, sha, depth: ["unscanned-sha", "ancestor-1"],
)
- with pytest.raises(SystemExit):
+ with pytest.raises(InfrastructureError):
core.resolve_base_full_scan_id(make_full_scan_params())
@@ -499,27 +490,18 @@ def test_resolve_base_full_scan_id_ancestor_fallback_needs_local_history(core, m
]
monkeypatch.setattr(Core, "first_parent_commits", lambda self, sha, depth: [])
- with pytest.raises(SystemExit):
+ with pytest.raises(InfrastructureError):
core.resolve_base_full_scan_id(make_full_scan_params())
-def test_resolve_base_full_scan_id_commit_sha_not_found_exits(core):
- """A --base-commit-sha with no scan is a hard error (exit_code_on_api_error)"""
- core.cli_config = make_cli_config("--base-commit-sha", "abc123")
- core.sdk.fullscans.get.return_value = {"results": [], "nextPage": None}
-
- with pytest.raises(SystemExit) as exc_info:
- core.resolve_base_full_scan_id(make_full_scan_params())
- assert exc_info.value.code == core.cli_config.exit_code_on_api_error
-
-def test_resolve_base_full_scan_id_commit_sha_not_found_disable_blocking(core):
- """--disable-blocking keeps the missing-base error from failing the build"""
- core.cli_config = make_cli_config("--base-commit-sha", "abc123", "--disable-blocking")
+@pytest.mark.parametrize("flags", [(), ("--disable-blocking",)])
+def test_resolve_base_full_scan_id_commit_sha_not_found_fails(core, flags):
+ """A --base-commit-sha with no scan is an infrastructure error; cli() applies the exit flags"""
+ core.cli_config = make_cli_config("--base-commit-sha", "abc123", *flags)
core.sdk.fullscans.get.return_value = {"results": [], "nextPage": None}
- with pytest.raises(SystemExit) as exc_info:
+ with pytest.raises(InfrastructureError, match="No full scan found for commit abc123"):
core.resolve_base_full_scan_id(make_full_scan_params())
- assert exc_info.value.code == 0
def test_get_full_scan(core, mock_sdk_with_responses, head_scan_metadata, head_scan_stream):
"""Test getting an existing full scan"""
diff --git a/tests/unit/test_config.py b/tests/unit/test_config.py
index 50047caa..d22b81ff 100644
--- a/tests/unit/test_config.py
+++ b/tests/unit/test_config.py
@@ -94,7 +94,7 @@ def test_sarif_scope_full_without_reach_exits(self):
"""--sarif-scope full without --reach should exit with code 1"""
with pytest.raises(SystemExit) as exc_info:
CliConfig.from_args(self.BASE_ARGS + ["--sarif-scope", "full"])
- assert exc_info.value.code == 1
+ assert exc_info.value.code == 2
def test_sarif_scope_full_with_reach_succeeds(self):
"""--sarif-scope full with --reach should parse successfully"""
@@ -105,7 +105,7 @@ def test_sarif_scope_full_with_reach_succeeds(self):
def test_sarif_reachability_without_reach_exits(self):
with pytest.raises(SystemExit) as exc_info:
CliConfig.from_args(self.BASE_ARGS + ["--sarif-reachability", "reachable"])
- assert exc_info.value.code == 1
+ assert exc_info.value.code == 2
def test_sarif_reachability_with_reach_succeeds(self):
config = CliConfig.from_args(
@@ -117,7 +117,7 @@ def test_sarif_reachability_with_reach_succeeds(self):
def test_sarif_grouping_alert_requires_full_scope(self):
with pytest.raises(SystemExit) as exc_info:
CliConfig.from_args(self.BASE_ARGS + ["--reach", "--sarif-grouping", "alert"])
- assert exc_info.value.code == 1
+ assert exc_info.value.code == 2
def test_sarif_reachability_reachable_with_reach_succeeds(self):
config = CliConfig.from_args(self.BASE_ARGS + ["--reach", "--sarif-reachability", "reachable"])
@@ -175,7 +175,7 @@ class TestRepoAndPendingHeadFlags:
def test_repo_with_owner_exits_with_suggestion(self, repo, caplog):
with pytest.raises(SystemExit) as exc_info:
CliConfig.from_args(["--api-token", "test-token", "--repo", repo])
- assert exc_info.value.code == 1
+ assert exc_info.value.code == 2
assert "Use --repo my-repo" in caplog.text
def test_repo_slug_is_accepted(self):
@@ -235,7 +235,7 @@ def test_config_file_values_are_mutually_exclusive(self, tmp_path):
)
with pytest.raises(SystemExit) as exc_info:
CliConfig.from_args(self.BASE_ARGS + ["--config", str(config_path)])
- assert exc_info.value.code == 1
+ assert exc_info.value.code == 2
def test_config_file_sets_base_commit_sha(self, tmp_path):
config_path = tmp_path / "socketcli.toml"
diff --git a/tests/unit/test_exclude_paths.py b/tests/unit/test_exclude_paths.py
index 32271a1a..0abce732 100644
--- a/tests/unit/test_exclude_paths.py
+++ b/tests/unit/test_exclude_paths.py
@@ -92,13 +92,13 @@ def test_reach_exclude_paths_still_works_and_warns(caplog):
def test_exclude_paths_validation_rejects(bad):
with pytest.raises(SystemExit) as exc:
CliConfig.from_args(BASE_ARGS + ["--exclude-paths", bad])
- assert exc.value.code == 1
+ assert exc.value.code == 2
def test_exclude_paths_validation_rejects_within_csv():
with pytest.raises(SystemExit) as exc:
CliConfig.from_args(BASE_ARGS + ["--exclude-paths", "src,..,tests"])
- assert exc.value.code == 1
+ assert exc.value.code == 2
def _write_config(tmp_path, value):
@@ -126,7 +126,7 @@ def test_exclude_paths_from_config_file_is_validated(tmp_path):
cfg = _write_config(tmp_path, ["../escape"])
with pytest.raises(SystemExit) as exc:
CliConfig.from_args(BASE_ARGS + ["--config", cfg])
- assert exc.value.code == 1
+ assert exc.value.code == 2
def test_exclude_paths_valid_globs_accepted():
diff --git a/tests/unit/test_gitlab_auth.py b/tests/unit/test_gitlab_auth.py
index 42c5e6bc..65f3e180 100644
--- a/tests/unit/test_gitlab_auth.py
+++ b/tests/unit/test_gitlab_auth.py
@@ -6,6 +6,7 @@
from socketsecurity import USER_AGENT
from socketsecurity.core.scm.gitlab import GitlabConfig
+from socketsecurity.exit_codes import InfrastructureError
class TestGitlabAuthHeaders:
@@ -107,10 +108,10 @@ def test_from_env_with_private_token(self):
assert config.headers['PRIVATE-TOKEN'] == 'custom-token'
assert 'Authorization' not in config.headers
- def test_from_env_missing_token_exits(self):
- """from_env should exit when GITLAB_TOKEN is missing"""
+ def test_from_env_missing_token_raises_infrastructure_error(self):
+ """A missing GITLAB_TOKEN goes through cli()'s exit handling, so the exit flags apply."""
with patch.dict(os.environ, {}, clear=True):
- with pytest.raises(SystemExit):
+ with pytest.raises(InfrastructureError, match="GITLAB_TOKEN"):
GitlabConfig.from_env()
diff --git a/tests/unit/test_socketcli.py b/tests/unit/test_socketcli.py
index 765150e9..1f298e0c 100644
--- a/tests/unit/test_socketcli.py
+++ b/tests/unit/test_socketcli.py
@@ -59,11 +59,11 @@ def test_disable_blocking_overrides_exit_code_on_api_error(monkeypatch):
assert code == 0
-def test_keyboard_interrupt_still_exits_2(monkeypatch):
+def test_keyboard_interrupt_exits_130(monkeypatch):
code = _run_cli_expecting_exit(
monkeypatch, ["socketcli", "--api-token", "test"], boom=KeyboardInterrupt()
)
- assert code == 2
+ assert code == 130
@pytest.mark.parametrize("scm", ["github", "gitlab"])
From c769f2b869d1f979e296743733b7147a7a239941 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 17:01:51 -0500
Subject: [PATCH 04/11] Keep each advisory when collapsing repeat alerts
The diff collapsed alerts on (purl, alert type) so a package pulled in by
several manifests reports each finding once. Every CVE of one severity on a
package shares an alert type, so a package's second advisory was dropped
from every output, and a blocking advisory could be dropped behind a
warning on the same package, letting the run pass.
Alerts now collapse on Issue.consolidation_key, which adds the ecosystem
and the GHSA or CVE ID. The PR comment shows that ID next to the title, so
two advisories on one package no longer render as identical rows.
---
socketsecurity/core/__init__.py | 35 ++++----
socketsecurity/core/alert_selection.py | 13 ++-
socketsecurity/core/classes.py | 35 +++++++-
socketsecurity/core/messages.py | 16 +++-
tests/core/test_alert_consolidation.py | 115 +++++++++++++++++++++++++
5 files changed, 185 insertions(+), 29 deletions(-)
create mode 100644 tests/core/test_alert_consolidation.py
diff --git a/socketsecurity/core/__init__.py b/socketsecurity/core/__init__.py
index 407cc58b..d62bde16 100644
--- a/socketsecurity/core/__init__.py
+++ b/socketsecurity/core/__init__.py
@@ -1357,13 +1357,13 @@ def create_full_scan_with_report_url(
packages=packages
)
- consolidated: Set[str] = set()
+ consolidated: Set[Tuple[str, str, str, str]] = set()
for alert_key, alerts in all_alerts_collection.items():
for alert in alerts:
- alert_str = f"{alert.purl},{alert.type}"
- if (alert.error or alert.warn) and alert_str not in consolidated:
+ finding_key = alert.consolidation_key()
+ if (alert.error or alert.warn) and finding_key not in consolidated:
diff.new_alerts.append(alert)
- consolidated.add(alert_str)
+ consolidated.add(finding_key)
diff.alerts_fetched = True
sbom_end = time.time()
@@ -2880,29 +2880,27 @@ def get_new_alerts(
if alert_key not in removed_package_alerts:
new_alerts = added_package_alerts[alert_key]
for alert in new_alerts:
- # Consolidate by package and alert type, not by manifest details
- alert_str = f"{alert.purl},{alert.type}"
+ finding_key = alert.consolidation_key()
if alert.error or alert.warn:
- if alert_str not in consolidated_alerts:
+ if finding_key not in consolidated_alerts:
alerts.append(alert)
- consolidated_alerts.add(alert_str)
+ consolidated_alerts.add(finding_key)
else:
new_alerts = added_package_alerts[alert_key]
removed_alerts = removed_package_alerts[alert_key]
for alert in new_alerts:
- # Consolidate by package and alert type, not by manifest details
- alert_str = f"{alert.purl},{alert.type}"
+ finding_key = alert.consolidation_key()
# Only add if:
# 1. Alert isn't in removed packages (or we're not ignoring readded alerts)
# 2. We haven't already recorded this alert
# 3. It's an error or warning
- if (not ignore_readded or alert not in removed_alerts) and alert_str not in consolidated_alerts:
+ if (not ignore_readded or alert not in removed_alerts) and finding_key not in consolidated_alerts:
if alert.error or alert.warn:
alerts.append(alert)
- consolidated_alerts.add(alert_str)
+ consolidated_alerts.add(finding_key)
return alerts
@@ -2927,13 +2925,12 @@ def get_unchanged_alerts(
for alert_key in unchanged_package_alerts:
for alert in unchanged_package_alerts[alert_key]:
- # Consolidate by package and alert type
- alert_str = f"{alert.purl},{alert.type}"
+ finding_key = alert.consolidation_key()
# Only include error or warning alerts
- if (alert.error or alert.warn) and alert_str not in consolidated_alerts:
+ if (alert.error or alert.warn) and finding_key not in consolidated_alerts:
alerts.append(alert)
- consolidated_alerts.add(alert_str)
+ consolidated_alerts.add(finding_key)
return alerts
@@ -2957,10 +2954,10 @@ def get_removed_alerts(
for alert_key in removed_package_alerts:
for alert in removed_package_alerts[alert_key]:
- alert_str = f"{alert.purl},{alert.type}"
+ finding_key = alert.consolidation_key()
- if alert_str not in consolidated_alerts:
+ if finding_key not in consolidated_alerts:
alerts.append(alert)
- consolidated_alerts.add(alert_str)
+ consolidated_alerts.add(finding_key)
return alerts
diff --git a/socketsecurity/core/alert_selection.py b/socketsecurity/core/alert_selection.py
index 8c89c8b5..d775b17b 100644
--- a/socketsecurity/core/alert_selection.py
+++ b/socketsecurity/core/alert_selection.py
@@ -15,10 +15,8 @@ def select_diff_alerts(diff: Diff, strict_blocking: bool = False) -> List[Issue]
"""Select diff alerts for output rendering.
In strict blocking mode, include unchanged alerts so rendered output aligns
- with pass/fail policy evaluation. An unchanged alert that is already listed
- as new (same ecosystem, purl and alert type) is skipped so each finding is
- rendered once. The ecosystem is part of the key because ``Issue.purl`` holds
- only name and version, so an npm and a PyPI package can share it.
+ with pass/fail policy evaluation. An unchanged alert already listed as new
+ (same Issue.consolidation_key) is skipped so each finding is rendered once.
"""
selected = list(getattr(diff, "new_alerts", []) or [])
if strict_blocking:
@@ -31,11 +29,10 @@ def select_diff_alerts(diff: Diff, strict_blocking: bool = False) -> List[Issue]
return selected
-def _alert_identity(alert: Issue) -> Optional[Tuple[str, str, str]]:
- purl = getattr(alert, "purl", "") or ""
- if not purl:
+def _alert_identity(alert: Issue) -> Optional[Tuple[str, str, str, str]]:
+ if not (getattr(alert, "purl", "") or ""):
return None
- return (getattr(alert, "pkg_type", "") or "", purl, getattr(alert, "type", "") or "")
+ return alert.consolidation_key()
def clone_diff_with_selected_alerts(diff: Diff, selected_alerts: List[Issue]) -> Diff:
diff --git a/socketsecurity/core/classes.py b/socketsecurity/core/classes.py
index fd8fabcd..98e8a213 100644
--- a/socketsecurity/core/classes.py
+++ b/socketsecurity/core/classes.py
@@ -1,7 +1,7 @@
import json
import logging
from dataclasses import dataclass, field
-from typing import Dict, List, Optional, TypedDict
+from typing import Dict, List, Optional, Tuple, TypedDict
from socketdev.fullscans import (
FullScanMetadata,
@@ -19,6 +19,11 @@
# one path segment that cannot be split back into two, and the page does not resolve.
NAMESPACE_REQUIRED_TYPES = frozenset({"maven"})
+# Alert props that name a vulnerability advisory, in the order Issue.advisory_id
+# reads them. Alerts reach Issue.props from several sources, so both spellings
+# appear; "cve" is the older field name.
+ADVISORY_ID_PROPS = ("ghsaId", "ghsa_id", "cveId", "cve_id", "cve")
+
__all__ = [
"Report",
"Score",
@@ -354,6 +359,34 @@ def __init__(self, **kwargs):
if not hasattr(self, "ignore"):
self.ignore = False
+ def advisory_id(self) -> str:
+ """The GHSA or CVE identifier in the alert's props, upper-cased, or ""."""
+ props = getattr(self, "props", None) or {}
+ for prop_name in ADVISORY_ID_PROPS:
+ value = props.get(prop_name)
+ if isinstance(value, (list, tuple)):
+ value = next((v for v in value if isinstance(v, str) and v.strip()), "")
+ if isinstance(value, str) and value.strip():
+ return value.strip().upper()
+ return ""
+
+ def consolidation_key(self) -> Tuple[str, str, str, str]:
+ """Identity used to collapse repeat sightings of one finding into one alert.
+
+ The same alert arrives once per manifest that pulls the package in, so the
+ key leaves manifest details out. It keeps the advisory ID because every CVE
+ of a given severity on a package shares one alert type (``criticalCVE``,
+ ``cve`` and so on): without it, a package's second advisory would be dropped,
+ and with it any blocking action that advisory carried. It keeps the
+ ecosystem because ``purl`` holds only name and version.
+ """
+ return (
+ getattr(self, "pkg_type", "") or "",
+ getattr(self, "purl", "") or "",
+ getattr(self, "type", "") or "",
+ self.advisory_id(),
+ )
+
def __str__(self):
return json.dumps(self.__dict__)
diff --git a/socketsecurity/core/messages.py b/socketsecurity/core/messages.py
index b2229f65..28e11f5a 100644
--- a/socketsecurity/core/messages.py
+++ b/socketsecurity/core/messages.py
@@ -925,6 +925,19 @@ def get_view_report_url(diff: Diff) -> str:
return diff.report_url
return ""
+ @staticmethod
+ def alert_title_with_advisory(alert: Issue) -> str:
+ """The alert title, followed by its GHSA or CVE ID when it has one.
+
+ Every CVE of one severity shares a title ("Critical CVE"), so without the
+ ID two advisories on the same package render as identical rows.
+ """
+ title = getattr(alert, "title", "") or ""
+ advisory = alert.advisory_id() if hasattr(alert, "advisory_id") else ""
+ if advisory and advisory not in title.upper():
+ return f"{title} ({advisory})"
+ return title
+
@staticmethod
def security_comment_template(diff: Diff, config=None) -> str:
"""
@@ -993,6 +1006,7 @@ def security_comment_template(diff: Diff, config=None) -> str:
manifest_url = Messages.get_manifest_file_url(diff, alert.manifests, config)
pkg_label = Messages.html_text(f"{alert.pkg_name}@{alert.pkg_version}")
pkg_marker = Messages.comment_marker_text(f"{alert.pkg_name}@{alert.pkg_version}")
+ alert_title = Messages.alert_title_with_advisory(alert)
# Generate a table row for each alert
ignore_html = (
f"
Mark as acceptable risk: To ignore this alert only in this pull request, reply with:
"
@@ -1009,7 +1023,7 @@ def security_comment_template(diff: Diff, config=None) -> str:
- {pkg_label} - {Messages.html_text(alert.title)}
+ {pkg_label} - {Messages.html_text(alert_title)}
Note: {Messages.html_text(alert.description)}
{patched_version_html}
Source: Manifest File
diff --git a/tests/core/test_alert_consolidation.py b/tests/core/test_alert_consolidation.py
new file mode 100644
index 00000000..b0fe79b4
--- /dev/null
+++ b/tests/core/test_alert_consolidation.py
@@ -0,0 +1,115 @@
+"""Repeat sightings of one finding collapse into one alert; distinct advisories don't.
+
+The same alert arrives once per manifest that pulls a package in, so the diff
+collapses alerts on Issue.consolidation_key. Every CVE of one severity on a
+package shares an alert type, so the key has to include the advisory ID, or a
+package's second advisory is dropped along with any blocking action it carries.
+"""
+from unittest.mock import Mock
+
+from socketsecurity.config import CliConfig
+from socketsecurity.core import Core
+from socketsecurity.core.classes import Diff, Issue
+from socketsecurity.core.messages import Messages
+from socketsecurity.output import OutputHandler
+
+
+def _cve(advisory, error=False, warn=False, pkg_type="npm", key=None, props_field="ghsaId"):
+ return Issue(
+ pkg_type=pkg_type,
+ pkg_name="lodash",
+ pkg_version="4.17.20",
+ purl="lodash@4.17.20",
+ type="criticalCVE",
+ severity="critical",
+ title="Critical CVE",
+ description="A vulnerability.",
+ suggestion="Upgrade.",
+ url="https://socket.dev/npm/package/lodash",
+ key=key or f"key-{advisory}",
+ props={props_field: advisory},
+ error=error,
+ warn=warn,
+ )
+
+
+def test_two_advisories_on_one_package_are_both_new_alerts():
+ alerts = {
+ "k1": [_cve("GHSA-aaaa-aaaa-aaaa", error=True)],
+ "k2": [_cve("GHSA-bbbb-bbbb-bbbb", error=True)],
+ }
+
+ new_alerts = Core.get_new_alerts(alerts, {})
+
+ assert sorted(a.advisory_id() for a in new_alerts) == [
+ "GHSA-AAAA-AAAA-AAAA",
+ "GHSA-BBBB-BBBB-BBBB",
+ ]
+
+
+def test_blocking_advisory_is_not_hidden_behind_a_warning():
+ """The kept advisory is a warning; dropping the second would pass the run."""
+ alerts = {
+ "k1": [_cve("GHSA-aaaa-aaaa-aaaa", warn=True)],
+ "k2": [_cve("GHSA-bbbb-bbbb-bbbb", error=True)],
+ }
+ diff = Diff()
+ diff.new_alerts = Core.get_new_alerts(alerts, {})
+
+ config = Mock(spec=CliConfig)
+ config.disable_blocking = False
+ config.strict_blocking = False
+ assert not OutputHandler(config, Mock()).report_pass(diff)
+
+
+def test_same_advisory_from_two_manifests_is_one_alert():
+ alerts = {
+ "k1": [_cve("GHSA-aaaa-aaaa-aaaa", error=True), _cve("GHSA-aaaa-aaaa-aaaa", error=True)],
+ }
+
+ assert len(Core.get_new_alerts(alerts, {})) == 1
+
+
+def test_unchanged_and_removed_alerts_keep_each_advisory():
+ alerts = {
+ "k1": [_cve("CVE-2026-0001", error=True, props_field="cveId")],
+ "k2": [_cve("CVE-2026-0002", error=True, props_field="cveId")],
+ }
+
+ assert len(Core.get_unchanged_alerts(alerts)) == 2
+ assert len(Core.get_removed_alerts(alerts)) == 2
+
+
+def test_consolidation_key_includes_ecosystem_and_ignores_advisory_case():
+ npm = _cve("ghsa-aaaa-aaaa-aaaa")
+ pypi = _cve("GHSA-AAAA-AAAA-AAAA", pkg_type="pypi")
+
+ assert npm.consolidation_key() != pypi.consolidation_key()
+ assert npm.consolidation_key()[3] == pypi.consolidation_key()[3]
+
+
+def test_non_advisory_alerts_still_collapse_per_package_and_type():
+ """Alerts with no advisory ID keep the per-package, per-type collapse."""
+ first = Issue(pkg_type="npm", purl="a@1.0.0", type="envVars", props={}, warn=True, key="k1")
+ second = Issue(pkg_type="npm", purl="a@1.0.0", type="envVars", props={}, warn=True, key="k2")
+
+ assert len(Core.get_new_alerts({"k1": [first], "k2": [second]}, {})) == 1
+
+
+def test_pr_comment_rows_name_the_advisory():
+ diff = Diff()
+ diff.new_alerts = [_cve("GHSA-aaaa-aaaa-aaaa", error=True), _cve("GHSA-bbbb-bbbb-bbbb", error=True)]
+ diff.diff_url = "https://socket.dev/diff"
+ diff.report_url = "https://socket.dev/report"
+
+ comment = Messages.security_comment_template(diff)
+
+ assert "Critical CVE (GHSA-AAAA-AAAA-AAAA)" in comment
+ assert "Critical CVE (GHSA-BBBB-BBBB-BBBB)" in comment
+
+
+def test_title_already_naming_the_advisory_is_left_alone():
+ alert = _cve("GHSA-aaaa-aaaa-aaaa")
+ alert.title = "GHSA-aaaa-aaaa-aaaa in lodash"
+
+ assert Messages.alert_title_with_advisory(alert) == "GHSA-aaaa-aaaa-aaaa in lodash"
From 3274b99faa4de915a37ad66e0aaef493c4433c96 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 17:06:05 -0500
Subject: [PATCH 05/11] Report existing alerts from the full scan, and list
them in the PR comment
The cached diff-scans endpoint returns unchanged artifacts with no alerts,
so --strict-blocking had nothing to block on and passed runs with blocking
alerts on packages the change didn't touch. The GitLab security report and
FOSSA-format output, which list every current finding, missed the same
alerts.
When one of those outputs is enabled, the CLI now reads the alerts on
unchanged packages from the new full scan. It skips that request when the
comparison already carries them, as the streaming fallback does, and fails
the run if the request fails rather than reporting no existing alerts.
Under --strict-blocking the PR comment lists existing alerts in their own
table after the new ones, blocking first, and stops adding rows before the
comment reaches GitHub's size limit. Ignore comments apply to existing
alerts too, since they now fail the run and each row offers the command.
---
socketsecurity/core/__init__.py | 82 ++++++++
socketsecurity/core/messages.py | 177 ++++++++++++-----
socketsecurity/socketcli.py | 9 +-
tests/core/test_existing_alerts.py | 293 +++++++++++++++++++++++++++++
4 files changed, 511 insertions(+), 50 deletions(-)
create mode 100644 tests/core/test_existing_alerts.py
diff --git a/socketsecurity/core/__init__.py b/socketsecurity/core/__init__.py
index d62bde16..9debddd1 100644
--- a/socketsecurity/core/__init__.py
+++ b/socketsecurity/core/__init__.py
@@ -2494,6 +2494,8 @@ def create_new_diff(
)
unchanged_packages = Core.get_unchanged_packages(packages, added_packages, removed_packages)
+ if unchanged_packages and self._requires_unchanged_alerts():
+ self.add_existing_alerts_from_full_scan(unchanged_packages, new_full_scan.id)
diff = self.create_diff_report(added_packages, removed_packages, unchanged_packages)
diff.packages = packages
@@ -2518,6 +2520,86 @@ def create_new_diff(
return diff
+ def _requires_unchanged_alerts(self) -> bool:
+ """Whether an enabled output reads alerts on unchanged packages.
+
+ ``--strict-blocking`` fails the run on them, and the GitLab security report
+ and FOSSA-format output list every current finding, not only new ones.
+ A subset of _requires_unchanged_artifacts.
+ """
+ config = self.cli_config
+ if config is None:
+ return False
+ return bool(
+ getattr(config, "strict_blocking", False)
+ or getattr(config, "enable_gitlab_security", False)
+ or getattr(config, "legal_format", "socket") == "fossa"
+ )
+
+ def add_existing_alerts_from_full_scan(
+ self, unchanged_packages: Dict[str, Package], full_scan_id: str
+ ) -> None:
+ """Fill in the alerts on unchanged packages from the new full scan.
+
+ The cached diff-scans endpoint returns unchanged artifacts with an empty
+ ``alerts`` list, because it keeps only the alerts it counts as new. The full
+ scan of the same commit carries every package's alerts with their policy
+ actions, so they are read from there. Packages are matched by artifact ID,
+ then by ecosystem, namespace, name and version.
+
+ Skipped when any unchanged package already has alerts: the comparison then
+ came from an endpoint that includes them, such as the streaming fallback.
+ A failed fetch raises, because reporting existing alerts as absent would
+ let ``--strict-blocking`` pass a run it should fail.
+ """
+ if any(package.alerts for package in unchanged_packages.values()):
+ log.debug("The comparison already includes alerts on unchanged packages")
+ return
+
+ start = time.time()
+ by_id: Dict[str, List[dict]] = {}
+ by_identity: Dict[Tuple[str, str, str, str], List[dict]] = {}
+ for artifact in self.get_sbom_data(full_scan_id).values():
+ data = asdict(artifact)
+ alerts = data.get("alerts") or []
+ by_id[data["id"]] = alerts
+ by_identity[Core._package_identity(
+ data["type"], data.get("namespace"), data["name"], data["version"]
+ )] = alerts
+
+ matched = 0
+ alert_count = 0
+ for package in unchanged_packages.values():
+ alerts = by_id.get(package.id)
+ if alerts is None:
+ alerts = by_identity.get(Core._package_identity(
+ package.type, package.namespace, package.name, package.version
+ ))
+ if alerts is None:
+ continue
+ package.alerts = alerts
+ matched += 1
+ alert_count += len(alerts)
+
+ log.info(
+ f"Loaded {alert_count} alerts for {matched} of {len(unchanged_packages)} "
+ f"unchanged packages from full scan {full_scan_id} in {time.time() - start:.2f}s"
+ )
+ if matched < len(unchanged_packages):
+ log.warning(
+ f"{len(unchanged_packages) - matched} unchanged packages were not found in "
+ f"full scan {full_scan_id}, so their existing alerts are not reported"
+ )
+
+ @staticmethod
+ def _package_identity(package_type, namespace, name, version) -> Tuple[str, str, str, str]:
+ return (
+ str(Package.normalize_type(package_type) or ""),
+ (namespace or "").strip("/"),
+ name or "",
+ version or "",
+ )
+
@staticmethod
def get_unchanged_packages(
packages: Dict[str, Package],
diff --git a/socketsecurity/core/messages.py b/socketsecurity/core/messages.py
index 28e11f5a..530f2d21 100644
--- a/socketsecurity/core/messages.py
+++ b/socketsecurity/core/messages.py
@@ -925,6 +925,57 @@ def get_view_report_url(diff: Diff) -> str:
return diff.report_url
return ""
+ @staticmethod
+ def security_alert_row(alert: Issue, diff: Diff, config, show_ignore: bool) -> str:
+ """One row of the security comment table for a non-license alert."""
+ severity_icon = Messages.get_severity_icon(alert.severity)
+ action = "Block" if alert.error else "Warn"
+ details_open = ""
+ patched_version = Messages.get_patched_version(alert)
+ patched_version_html = (
+ "Patched version: "
+ f"{Messages.html_text(patched_version)} "
+ if patched_version else ""
+ )
+ # Generate proper manifest URL
+ manifest_url = Messages.get_manifest_file_url(diff, alert.manifests, config)
+ pkg_label = Messages.html_text(f"{alert.pkg_name}@{alert.pkg_version}")
+ pkg_marker = Messages.comment_marker_text(f"{alert.pkg_name}@{alert.pkg_version}")
+ alert_title = Messages.alert_title_with_advisory(alert)
+ # Generate a table row for each alert
+ ignore_html = (
+ f"Mark as acceptable risk: To ignore this alert only in this pull request, reply with: "
+ f"@SocketSecurity ignore {Messages.html_text(alert.pkg_type)}/{pkg_label} "
+ f"Or ignore all future alerts with: "
+ f"@SocketSecurity ignore-all "
+ ) if show_ignore else ""
+ return f"""
+
+
+ | {action} |
+
+
+ |
+
+
+ {pkg_label} - {Messages.html_text(alert_title)}
+ Note: {Messages.html_text(alert.description)}
+ {patched_version_html}
+ Source: Manifest File
+ ℹ️ Read more on:
+ This package |
+ This alert |
+ What is known malware?
+
+ Suggestion: {Messages.html_text(alert.suggestion)}
+ {ignore_html}
+
+
+ |
+
+
+ """
+
@staticmethod
def alert_title_with_advisory(alert: Issue) -> str:
"""The alert title, followed by its GHSA or CVE ID when it has one.
@@ -962,10 +1013,11 @@ def security_comment_template(diff: Diff, config=None) -> str:
security_alerts.append(alert)
view_report_url = Messages.get_view_report_url(diff)
+ existing_alerts = Messages.existing_comment_alerts(diff, config)
# Without this the caution banner would sit above a table with no rows,
# which is how a comment looks once every alert it raised is resolved.
- if not security_alerts and not license_groups:
+ if not security_alerts and not license_groups and not existing_alerts:
return Messages.security_comment_no_alerts_template(view_report_url)
# Start of the comment
@@ -993,53 +1045,7 @@ def security_comment_template(diff: Diff, config=None) -> str:
# Loop through security alerts (non-license), dynamically generating rows
for alert in security_alerts:
- severity_icon = Messages.get_severity_icon(alert.severity)
- action = "Block" if alert.error else "Warn"
- details_open = ""
- patched_version = Messages.get_patched_version(alert)
- patched_version_html = (
- "Patched version: "
- f"{Messages.html_text(patched_version)} "
- if patched_version else ""
- )
- # Generate proper manifest URL
- manifest_url = Messages.get_manifest_file_url(diff, alert.manifests, config)
- pkg_label = Messages.html_text(f"{alert.pkg_name}@{alert.pkg_version}")
- pkg_marker = Messages.comment_marker_text(f"{alert.pkg_name}@{alert.pkg_version}")
- alert_title = Messages.alert_title_with_advisory(alert)
- # Generate a table row for each alert
- ignore_html = (
- f"Mark as acceptable risk: To ignore this alert only in this pull request, reply with: "
- f"@SocketSecurity ignore {Messages.html_text(alert.pkg_type)}/{pkg_label} "
- f"Or ignore all future alerts with: "
- f"@SocketSecurity ignore-all "
- ) if show_ignore else ""
- comment += f"""
-
-
- | {action} |
-
-
- |
-
-
- {pkg_label} - {Messages.html_text(alert_title)}
- Note: {Messages.html_text(alert.description)}
- {patched_version_html}
- Source: Manifest File
- ℹ️ Read more on:
- This package |
- This alert |
- What is known malware?
-
- Suggestion: {Messages.html_text(alert.suggestion)}
- {ignore_html}
-
-
- |
-
-
- """
+ comment += Messages.security_alert_row(alert, diff, config, show_ignore)
# Add license policy violation entries grouped by PURL
for purl_key, alerts in license_groups.items():
@@ -1099,17 +1105,90 @@ def security_comment_template(diff: Diff, config=None) -> str:
"""
+ if not security_alerts and not license_groups:
+ comment += """
+
+ | No new alerts in this change. |
+
+"""
+
# Close table
- comment += f"""
+ comment += """
+"""
+ if existing_alerts:
+ comment += Messages.existing_alerts_section(
+ existing_alerts, diff, config, show_ignore, view_report_url, len(comment)
+ )
+ comment += f"""
[View full report]({view_report_url}?action=error%2Cwarn)
"""
return Messages.normalize_comment_html(comment)
+ # GitHub rejects comment bodies over 65,536 characters. The existing-alerts
+ # section is the open-ended part of the security comment, so it stops adding
+ # rows at this size and links to the full report for the rest.
+ SECURITY_COMMENT_SIZE_BUDGET = 60000
+
+ @staticmethod
+ def existing_comment_alerts(diff: Diff, config) -> list:
+ """Alerts on unchanged packages to show in the PR comment.
+
+ Only under --strict-blocking, where they fail the run: without it they
+ don't affect the result, and listing them would bury the new ones.
+ """
+ if not (config and getattr(config, "strict_blocking", False)):
+ return []
+ new_keys = {alert.consolidation_key() for alert in getattr(diff, "new_alerts", []) or []}
+ return [
+ alert for alert in getattr(diff, "unchanged_alerts", []) or []
+ if (alert.error or alert.warn) and alert.consolidation_key() not in new_keys
+ ]
+
+ @staticmethod
+ def existing_alerts_section(
+ alerts: list, diff: Diff, config, show_ignore: bool, view_report_url: str, size_so_far: int
+ ) -> str:
+ """Table of alerts on packages this change didn't touch, blocking ones first."""
+ ordered = sorted(alerts, key=lambda alert: not alert.error)
+ blocking = sum(1 for alert in ordered if alert.error)
+ section = f"""
+
+**Existing alerts ({len(ordered)}).** These are on dependencies this change didn't add or update. `--strict-blocking` fails the run on the {blocking} with a **Block** action.
+
+
+
+
+ | Action |
+ Severity |
+ Alert (click for details) |
+
+
+
+"""
+ closing = """
+
+
+"""
+ shown = 0
+ for alert in ordered:
+ row = Messages.security_alert_row(alert, diff, config, show_ignore)
+ if size_so_far + len(section) + len(row) + len(closing) > Messages.SECURITY_COMMENT_SIZE_BUDGET:
+ break
+ section += row
+ shown += 1
+ section += closing
+ if shown < len(ordered):
+ section += (
+ f"\n{len(ordered) - shown} more existing alert(s) are not shown here to keep "
+ f"this comment within GitHub's size limit. See the [full report]({view_report_url}?action=error%2Cwarn).\n"
+ )
+ return section + "\n"
+
@staticmethod
def get_severity_icon(severity: str) -> str:
"""
diff --git a/socketsecurity/socketcli.py b/socketsecurity/socketcli.py
index 86f79bcd..96b9d630 100644
--- a/socketsecurity/socketcli.py
+++ b/socketsecurity/socketcli.py
@@ -875,6 +875,13 @@ def _is_unprocessed(c):
diff.new_alerts = Comments.remove_alerts(comments, diff.new_alerts)
ignored_alerts = [a for a in alerts_before if a not in diff.new_alerts]
+ # Under --strict-blocking, existing alerts fail the run and appear in
+ # the comment with the same ignore instructions, so an ignore has to
+ # apply to them as well.
+ if config.strict_blocking and diff.unchanged_alerts:
+ existing_before = list(diff.unchanged_alerts)
+ diff.unchanged_alerts = Comments.remove_alerts(comments, diff.unchanged_alerts)
+ ignored_alerts += [a for a in existing_before if a not in diff.unchanged_alerts]
# Emit telemetry per-comment so each event carries the comment author.
unprocessed_ignore = [
c for c in comments.get("ignore", [])
@@ -957,7 +964,7 @@ def _is_unprocessed(c):
new_security_comment = should_write_comment(
config.disable_security_issue,
- len(diff.new_alerts) > 0,
+ len(diff.new_alerts) > 0 or bool(Messages.existing_comment_alerts(diff, config)),
update_old_security_comment,
)
if not new_security_comment:
diff --git a/tests/core/test_existing_alerts.py b/tests/core/test_existing_alerts.py
new file mode 100644
index 00000000..5f31f558
--- /dev/null
+++ b/tests/core/test_existing_alerts.py
@@ -0,0 +1,293 @@
+"""Alerts on unchanged packages come from the full scan when the comparison omits them.
+
+The cached diff-scans endpoint returns unchanged artifacts with an empty
+``alerts`` list, so ``--strict-blocking`` had nothing to block on and passed.
+The new full scan carries every package's alerts, so the CLI reads them from
+there whenever an output needs them: ``--strict-blocking``, the GitLab security
+report and FOSSA-format output.
+"""
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+from socketdev.exceptions import APIFailure
+from socketdev.fullscans import (
+ FullScanParams,
+ FullScanStreamResponse,
+ StreamDiffResponse,
+)
+
+from socketsecurity.config import CliConfig
+from socketsecurity.core import Core
+from socketsecurity.core.classes import Diff, Issue
+from socketsecurity.core.messages import Messages
+from socketsecurity.core.socket_config import SocketConfig
+from socketsecurity.output import OutputHandler
+
+BUCKETS = ("added", "removed", "unchanged", "replaced", "updated")
+
+
+def _alert(key, action="error", alert_type="malware"):
+ return {
+ "key": key,
+ "type": alert_type,
+ "severity": "critical",
+ "category": "supplyChainRisk",
+ "props": {},
+ "action": action,
+ }
+
+
+def _diff_artifact(diff_type, artifact_id, name, alerts=None):
+ ref = {
+ "direct": True,
+ "manifestFiles": [{"file": "package.json", "start": 0, "end": 0}],
+ "topLevelAncestors": [],
+ }
+ return {
+ "diffType": diff_type,
+ "type": "npm",
+ "name": name,
+ "version": "1.0.0",
+ "id": artifact_id,
+ "head": [ref],
+ "base": [],
+ "license": "MIT",
+ "licenseDetails": [],
+ "author": [],
+ "size": 1,
+ "score": {},
+ "alerts": alerts or [],
+ }
+
+
+def _scan_artifact(artifact_id, name, alerts):
+ return {
+ "type": "npm",
+ "name": name,
+ "version": "1.0.0",
+ "id": artifact_id,
+ "direct": True,
+ "manifestFiles": [{"file": "package.json", "start": 0, "end": 0}],
+ "topLevelAncestors": [],
+ "license": "MIT",
+ "licenseDetails": [],
+ "author": [],
+ "size": 1,
+ "score": {},
+ "alerts": alerts,
+ }
+
+
+def _diff_response(**buckets):
+ raw = json.loads((Path(__file__).parent.parent / "data/fullscans/diff/stream_diff.json").read_text())
+ artifacts = {name: buckets.get(name, []) for name in BUCKETS}
+ return StreamDiffResponse.from_dict({
+ "success": raw["success"],
+ "status": raw["status"],
+ "data": {**raw["data"], "artifacts": artifacts},
+ })
+
+
+def _scan_response(*artifacts):
+ return FullScanStreamResponse.from_dict({
+ "success": True,
+ "status": 200,
+ "artifacts": {artifact["id"]: artifact for artifact in artifacts},
+ })
+
+
+@pytest.fixture
+def core(mock_sdk_with_responses):
+ core = Core(config=SocketConfig(api_key="test_key"), sdk=mock_sdk_with_responses)
+ core.sdk.diffscans.create_from_ids.side_effect = Exception("diff-scans unavailable")
+ core.sdk.fullscans.stream_diff.side_effect = None
+ core.sdk.fullscans.stream.side_effect = None
+ core.resolve_base_full_scan_id = Mock(return_value="head")
+ core.create_full_scan = Mock(return_value=SimpleNamespace(id="new"))
+ return core
+
+
+def _run(core, *flags, unchanged_alerts=None, scan_alerts=None, scan_id="u1"):
+ core.cli_config = CliConfig.from_args(["--api-token", "test", *flags])
+ core.sdk.fullscans.stream_diff.return_value = _diff_response(
+ added=[_diff_artifact("added", "a1", "alpha", [_alert("k1")])],
+ unchanged=[_diff_artifact("unchanged", "u1", "gamma", unchanged_alerts)],
+ )
+ core.sdk.fullscans.stream.return_value = _scan_response(
+ _scan_artifact("a1", "alpha", [_alert("k1")]),
+ _scan_artifact(scan_id, "gamma", scan_alerts if scan_alerts is not None else [_alert("k3")]),
+ )
+ params = FullScanParams(repo="repo", branch="feature")
+ params.include_license_details = True
+ return core.create_new_diff(["/repo"], params, explicit_files=["/repo/package.json"])
+
+
+def _handler(strict_blocking=True):
+ config = Mock(spec=CliConfig)
+ config.disable_blocking = False
+ config.strict_blocking = strict_blocking
+ return OutputHandler(config, Mock())
+
+
+def test_strict_blocking_reads_existing_alerts_from_the_full_scan(core):
+ diff = _run(core, "--strict-blocking")
+
+ assert [a.pkg_name for a in diff.unchanged_alerts] == ["gamma"]
+ assert diff.unchanged_alerts[0].error
+ core.sdk.fullscans.stream.assert_called_once()
+
+
+def test_strict_blocking_fails_on_an_existing_blocking_alert(core):
+ """The exit-0 case: the only blocking alert is on a package the change didn't touch."""
+ core.cli_config = CliConfig.from_args(["--api-token", "test", "--strict-blocking"])
+ core.sdk.fullscans.stream_diff.return_value = _diff_response(
+ unchanged=[_diff_artifact("unchanged", "u1", "gamma")],
+ )
+ core.sdk.fullscans.stream.return_value = _scan_response(_scan_artifact("u1", "gamma", [_alert("k3")]))
+ params = FullScanParams(repo="repo", branch="feature")
+ params.include_license_details = True
+
+ diff = core.create_new_diff(["/repo"], params, explicit_files=["/repo/package.json"])
+
+ assert diff.new_alerts == []
+ assert not _handler(strict_blocking=True).report_pass(diff)
+
+
+def test_existing_alerts_match_by_package_when_artifact_ids_differ(core):
+ diff = _run(core, "--strict-blocking", scan_id="other-id")
+
+ assert [a.pkg_name for a in diff.unchanged_alerts] == ["gamma"]
+
+
+def test_existing_warnings_are_kept_and_ignored_alerts_are_not(core):
+ diff = _run(
+ core, "--strict-blocking",
+ scan_alerts=[_alert("k3", action="warn"), _alert("k4", action="ignore", alert_type="envVars")],
+ )
+
+ assert [(a.pkg_name, a.warn, a.error) for a in diff.unchanged_alerts] == [("gamma", True, False)]
+
+
+@pytest.mark.parametrize("flags", [("--enable-gitlab-security",), ("--legal-format", "fossa")])
+def test_full_scope_reports_also_read_existing_alerts(core, flags):
+ diff = _run(core, *flags)
+
+ assert [a.pkg_name for a in diff.unchanged_alerts] == ["gamma"]
+
+
+def test_no_extra_fetch_when_no_output_reads_existing_alerts(core):
+ diff = _run(core)
+
+ core.sdk.fullscans.stream.assert_not_called()
+ assert diff.unchanged_alerts == []
+
+
+def test_no_extra_fetch_when_the_comparison_already_has_existing_alerts(core):
+ """The streaming comparison includes them, and so will diff-scans once the API does."""
+ diff = _run(core, "--strict-blocking", unchanged_alerts=[_alert("k3")])
+
+ core.sdk.fullscans.stream.assert_not_called()
+ assert [a.pkg_name for a in diff.unchanged_alerts] == ["gamma"]
+
+
+def test_failed_full_scan_fetch_fails_the_run(core):
+ """Reporting no existing alerts after a failed fetch would let the run pass."""
+ core.cli_config = CliConfig.from_args(["--api-token", "test", "--strict-blocking"])
+ core.sdk.fullscans.stream_diff.return_value = _diff_response(
+ unchanged=[_diff_artifact("unchanged", "u1", "gamma")],
+ )
+ core.sdk.fullscans.stream.return_value = FullScanStreamResponse.from_dict(
+ {"success": False, "status": 500, "message": "boom"}
+ )
+ params = FullScanParams(repo="repo", branch="feature")
+ params.include_license_details = True
+
+ with pytest.raises(APIFailure):
+ core.create_new_diff(["/repo"], params, explicit_files=["/repo/package.json"])
+
+
+# --- PR comment ------------------------------------------------------------------------
+
+
+def _issue(name, error=True, warn=False):
+ return Issue(
+ pkg_type="npm",
+ pkg_name=name,
+ pkg_version="1.0.0",
+ purl=f"{name}@1.0.0",
+ type="malware",
+ severity="critical",
+ title="Known malware",
+ description="Bad.",
+ suggestion="Remove it.",
+ url=f"https://socket.dev/npm/package/{name}",
+ props={},
+ key=f"key-{name}",
+ error=error,
+ warn=warn,
+ )
+
+
+def _comment_diff(new=(), existing=()):
+ diff = Diff()
+ diff.new_alerts = list(new)
+ diff.unchanged_alerts = list(existing)
+ diff.diff_url = "https://socket.dev/diff"
+ diff.report_url = "https://socket.dev/report"
+ return diff
+
+
+def _config(strict_blocking=True):
+ return SimpleNamespace(strict_blocking=strict_blocking, disable_ignore=False, scm="github")
+
+
+def test_pr_comment_lists_existing_alerts_under_strict_blocking():
+ diff = _comment_diff(new=[_issue("alpha")], existing=[_issue("gamma", error=False, warn=True), _issue("delta")])
+
+ comment = Messages.security_comment_template(diff, _config())
+
+ assert "Existing alerts (2)" in comment
+ assert "fails the run on the 1 with a **Block** action" in comment
+ # Blocking existing alerts come first.
+ assert comment.index("delta@1.0.0 - Known malware") < comment.index("gamma@1.0.0 - Known malware")
+ assert comment.index("alpha@1.0.0") < comment.index("Existing alerts")
+
+
+def test_pr_comment_leaves_existing_alerts_out_without_strict_blocking():
+ diff = _comment_diff(new=[_issue("alpha")], existing=[_issue("gamma")])
+
+ comment = Messages.security_comment_template(diff, _config(strict_blocking=False))
+
+ assert "Existing alerts" not in comment
+ assert "gamma" not in comment
+
+
+def test_pr_comment_with_only_existing_alerts_says_nothing_new():
+ diff = _comment_diff(existing=[_issue("gamma")])
+
+ comment = Messages.security_comment_template(diff, _config())
+
+ assert "No new alerts in this change." in comment
+ assert "Existing alerts (1)" in comment
+
+
+def test_pr_comment_does_not_repeat_an_existing_alert_listed_as_new():
+ diff = _comment_diff(new=[_issue("alpha")], existing=[_issue("alpha"), _issue("gamma")])
+
+ comment = Messages.security_comment_template(diff, _config())
+
+ assert "Existing alerts (1)" in comment
+
+
+def test_pr_comment_stays_within_the_size_budget(monkeypatch):
+ monkeypatch.setattr(Messages, "SECURITY_COMMENT_SIZE_BUDGET", 6000)
+ diff = _comment_diff(existing=[_issue(f"pkg{i}") for i in range(20)])
+
+ comment = Messages.security_comment_template(diff, _config())
+
+ assert len(comment) < 6500
+ assert "more existing alert(s) are not shown" in comment
+ assert "Existing alerts (20)" in comment
From 52272983bcba87945cf69664603acc88a0b5f5d8 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 17:07:38 -0500
Subject: [PATCH 06/11] Release 2.13.0 with upgrade notes for the exit-code
changes
Bumps the minor version because exit codes change: invalid flags exit 2
instead of 1, Ctrl+C exits 130 instead of 2, more failures honor
--disable-blocking and --exit-code-on-api-error, and --strict-blocking now
fails on existing blocking alerts. The CHANGELOG lists each change a CI
step matching on exit codes needs to know about, and the README exit-code
table and the --disable-blocking and --strict-blocking docs describe the
new behavior.
---
CHANGELOG.md | 72 ++++++++++++++++++++++++++++++---
README.md | 21 +++++-----
docs/cli-reference.md | 4 +-
pyproject.toml | 2 +-
socketsecurity/__init__.py | 2 +-
socketsecurity/core/messages.py | 1 -
uv.lock | 2 +-
7 files changed, 84 insertions(+), 20 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1f66871c..e895fb7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,14 +1,74 @@
# Changelog
-## 2.12.2
+## 2.13.0
+
+### Upgrade notes
+
+This release changes exit codes. Check any CI step that matches on a specific
+code.
+
+- **Invalid flags exit `2`, not `1`.** `1` now always means blocking security
+ findings. `2` is the code argparse already used for its own usage errors.
+ `--disable-blocking` does not apply to usage errors.
+- **Ctrl+C exits `130`, not `2`.** `130` is the POSIX code for a process stopped
+ by SIGINT.
+- **`--disable-blocking` and `--exit-code-on-api-error` apply to more failures.**
+ A missing API token, `GITLAB_TOKEN` or `GH_API_TOKEN`, missing reachability
+ dependencies, a plan without reachability, and a repository that can't be
+ created used to exit with a hard-coded `2` or `3`. They now exit `3`, or your
+ `--exit-code-on-api-error` value, and `--disable-blocking` turns them into `0`.
+- **`--strict-blocking` now fails on existing blocking alerts.** It didn't
+ before, because the scan comparison doesn't include alerts on unchanged
+ packages. Runs that passed with existing blocking alerts will now fail, which
+ is what the flag documents. To roll it out gradually, see
+ [Strict Blocking Mode](docs/cli-reference.md#strict-blocking-mode).
+- **An incomplete scan comparison fails the run** with the infrastructure-error
+ code instead of reporting a result that may be missing alerts.
+
+### Changed: exit codes are decided in one place
+
+- Failures that are not security findings raise one error type, and the
+ top-level handler applies `--disable-blocking` and `--exit-code-on-api-error`
+ to all of them. See [Exit codes](README.md#exit-codes).
+
+### Fixed: `--strict-blocking` passed with existing blocking alerts
+
+- The CLI reads alerts on unchanged packages from the new full scan, because
+ the scan comparison returns those packages without their alerts. This costs
+ one more API request per run, and only runs when an output needs existing
+ alerts: `--strict-blocking`, `--enable-gitlab-security` or
+ `--legal-format fossa`. The GitLab security report and FOSSA output, which
+ list every current finding, were missing the same alerts.
+- If that request fails, the run fails with the infrastructure-error code
+ rather than passing without the existing alerts.
### Fixed: duplicate findings with `--strict-blocking`
-- Alerts on added packages are no longer also reported as existing alerts. Under
- `--strict-blocking`, each finding on an added package was listed twice in JSON,
- SARIF, Slack and GitLab output, and counted again in the summary's
- "EXISTING blocking issues" line and the GitLab commit status. The exit code
- was not affected.
+- Alerts on added packages are no longer also reported as existing alerts. Each
+ finding on an added package was listed twice in JSON, SARIF, Slack and GitLab
+ output, and counted again in the summary's "EXISTING blocking issues" line and
+ the GitLab commit status.
+
+### Fixed: a package's second CVE was dropped
+
+- Alerts were collapsed on package and alert type, and every CVE of one
+ severity shares an alert type, so only one advisory per package and severity
+ was reported. A blocking advisory could be dropped behind a warning on the
+ same package, letting the run pass. Each GHSA or CVE is now reported, and the
+ PR comment shows its ID next to the title.
+
+### Added: existing alerts in PR/MR comments
+
+- Under `--strict-blocking`, the security comment lists existing alerts in
+ their own table after the new ones, blocking first. `@SocketSecurity ignore`
+ applies to them too. The table stops before the comment reaches GitHub's size
+ limit and links to the full report for the rest.
+
+### Fixed: a token without `repo:list` was reported as a missing repository
+
+- A repository lookup that fails with 401 or 403 now says the token may be
+ missing the `repo:list` scope. Before, the CLI treated it as a missing
+ repository, tried to create it, and failed with a `repo:create` error.
## 2.12.1
diff --git a/README.md b/README.md
index 5221daf1..b4e8f842 100644
--- a/README.md
+++ b/README.md
@@ -217,12 +217,13 @@ Minimal pattern:
## Exit codes
-| Code | Meaning |
-|------|---------|
-| `0` | Clean scan — no blocking issues (or `--disable-blocking` set) |
-| `1` | Blocking security finding(s) detected |
-| `2` | Scan interrupted (SIGINT / Ctrl+C) |
-| `3` | Infrastructure or API error (timeout, network failure, unexpected error) |
+| Code | Meaning |
+|-------|---------|
+| `0` | Clean scan — no blocking issues (or `--disable-blocking` set) |
+| `1` | Blocking security finding(s) detected |
+| `2` | Invalid flags or configuration (usage error), including argparse's own errors |
+| `3` | Infrastructure or API error: missing API or SCM token, permission or plan problem, timeout, network failure, incomplete scan comparison, unexpected error |
+| `130` | Scan interrupted (SIGINT / Ctrl+C) |
`--exit-code-on-api-error ` remaps the infrastructure-error code (`3`) to any
value — e.g. a Buildkite
@@ -239,9 +240,11 @@ error, so the supervisor's exit status (commonly 124 or 137) takes precedence.
The two flags that affect exit codes can cancel each other out, so the order of
precedence matters:
-- **`--disable-blocking` wins over everything.** It forces exit `0` for *all*
- outcomes — security findings *and* infrastructure errors. If you set it,
- `--exit-code-on-api-error` has no effect (you'll always get `0`).
+- **`--disable-blocking` wins for every run that gets past flag parsing.** It
+ forces exit `0` for security findings, infrastructure errors and interrupts.
+ If you set it, `--exit-code-on-api-error` has no effect (you'll always get `0`).
+ It does not apply to usage errors (`2`): a run with invalid flags never scanned
+ anything, so it always fails.
- **`--exit-code-on-api-error` only applies when `--disable-blocking` is *not*
set.** It changes the infra-error code (and the generic-error code); it never
touches the security-finding code (`1`).
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 1dcec13e..76a8cdcc 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -437,7 +437,7 @@ The CLI runs a pinned version of the Coana CLI, the analysis engine; it does **n
| Parameter | Required | Default | Description |
|:-------------------------|:---------|:--------|:----------------------------------------------------------------------|
| `--ignore-commit-files` | False | False | Compare regardless of which files changed, scanning every manifest |
-| `--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-blocking` | False | False | Non-blocking CI mode: the CLI exits **0** even when blocking alerts are present (including with `--strict-blocking`). Also exits 0 on infrastructure errors (missing API or SCM token, Socket API failures, uncaught runtime errors) and interrupts, so the job is treated as successful while findings and errors are still logged. Invalid flags still exit **2**. 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. 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. |
@@ -643,6 +643,8 @@ Security issues detected by Socket Security:
- **Diff Mode Only**: The flag only works in diff mode (with SCM integration). In API mode, a warning is logged.
- **Error-Level Only**: Only fails on `error=True` alerts (blocking severity), not warnings.
+- **Existing alerts come from the full scan**: The scan comparison doesn't carry alerts on unchanged packages, so the CLI reads them from the new full scan, at the cost of one more API request per run. If that request fails, the run fails with the infrastructure-error code rather than passing without them.
+- **PR/MR comments**: Existing alerts are listed in their own table after the new ones, blocking first. `@SocketSecurity ignore` applies to them too. Very large sets are cut off before the comment reaches GitHub's size limit, with a link to the full report.
- **Priority**: `--disable-blocking` takes precedence - if both flags are set, the build will always pass.
- **First Scan**: On the very first scan of a repository, there are no "existing" violations, so behavior is identical to standard mode.
diff --git a/pyproject.toml b/pyproject.toml
index 76960bad..0924672a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
[project]
name = "socketsecurity"
-version = "2.12.2"
+version = "2.13.0"
requires-python = ">= 3.11"
license = {"file" = "LICENSE"}
dependencies = [
diff --git a/socketsecurity/__init__.py b/socketsecurity/__init__.py
index 4494a36d..08835ec8 100644
--- a/socketsecurity/__init__.py
+++ b/socketsecurity/__init__.py
@@ -1,4 +1,4 @@
__author__ = 'socket.dev'
-__version__ = '2.12.2'
+__version__ = '2.13.0'
USER_AGENT_NAME = 'socket-python-cli'
USER_AGENT = f'{USER_AGENT_NAME}/{__version__}'
diff --git a/socketsecurity/core/messages.py b/socketsecurity/core/messages.py
index 530f2d21..5768b9c4 100644
--- a/socketsecurity/core/messages.py
+++ b/socketsecurity/core/messages.py
@@ -942,7 +942,6 @@ def security_alert_row(alert: Issue, diff: Diff, config, show_ignore: bool) -> s
pkg_label = Messages.html_text(f"{alert.pkg_name}@{alert.pkg_version}")
pkg_marker = Messages.comment_marker_text(f"{alert.pkg_name}@{alert.pkg_version}")
alert_title = Messages.alert_title_with_advisory(alert)
- # Generate a table row for each alert
ignore_html = (
f"Mark as acceptable risk: To ignore this alert only in this pull request, reply with: "
f"@SocketSecurity ignore {Messages.html_text(alert.pkg_type)}/{pkg_label} "
diff --git a/uv.lock b/uv.lock
index 98067b93..a6271a3d 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1334,7 +1334,7 @@ wheels = [
[[package]]
name = "socketsecurity"
-version = "2.12.2"
+version = "2.13.0"
source = { editable = "." }
dependencies = [
{ name = "beautifulsoup4" },
From 879e40b01bc3651b0d4c8a54013b58e9ed46e178 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 17:13:18 -0500
Subject: [PATCH 07/11] Group the 2.13.0 changelog entry by change type, like
2.12.0
---
CHANGELOG.md | 86 +++++++++++++++++-----------------------------------
1 file changed, 27 insertions(+), 59 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e895fb7c..b616216a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,71 +4,39 @@
### Upgrade notes
-This release changes exit codes. Check any CI step that matches on a specific
-code.
-
-- **Invalid flags exit `2`, not `1`.** `1` now always means blocking security
- findings. `2` is the code argparse already used for its own usage errors.
- `--disable-blocking` does not apply to usage errors.
-- **Ctrl+C exits `130`, not `2`.** `130` is the POSIX code for a process stopped
- by SIGINT.
-- **`--disable-blocking` and `--exit-code-on-api-error` apply to more failures.**
- A missing API token, `GITLAB_TOKEN` or `GH_API_TOKEN`, missing reachability
- dependencies, a plan without reachability, and a repository that can't be
- created used to exit with a hard-coded `2` or `3`. They now exit `3`, or your
- `--exit-code-on-api-error` value, and `--disable-blocking` turns them into `0`.
-- **`--strict-blocking` now fails on existing blocking alerts.** It didn't
- before, because the scan comparison doesn't include alerts on unchanged
- packages. Runs that passed with existing blocking alerts will now fail, which
- is what the flag documents. To roll it out gradually, see
- [Strict Blocking Mode](docs/cli-reference.md#strict-blocking-mode).
-- **An incomplete scan comparison fails the run** with the infrastructure-error
- code instead of reporting a result that may be missing alerts.
-
-### Changed: exit codes are decided in one place
-
-- Failures that are not security findings raise one error type, and the
- top-level handler applies `--disable-blocking` and `--exit-code-on-api-error`
- to all of them. See [Exit codes](README.md#exit-codes).
-
-### Fixed: `--strict-blocking` passed with existing blocking alerts
-
-- The CLI reads alerts on unchanged packages from the new full scan, because
- the scan comparison returns those packages without their alerts. This costs
- one more API request per run, and only runs when an output needs existing
- alerts: `--strict-blocking`, `--enable-gitlab-security` or
- `--legal-format fossa`. The GitLab security report and FOSSA output, which
- list every current finding, were missing the same alerts.
-- If that request fails, the run fails with the infrastructure-error code
- rather than passing without the existing alerts.
-
-### Fixed: duplicate findings with `--strict-blocking`
+Exit codes change in this release. Check any CI step that matches on a specific
+code; see [Exit codes](README.md#exit-codes).
+
+- Invalid flags and config values exit `2` instead of `1`, so `1` always means
+ blocking findings. `--disable-blocking` doesn't apply to them.
+- Ctrl+C exits `130` instead of `2`.
+- A missing API or SCM token, missing reachability dependencies, a plan without
+ reachability, and a repository that can't be created now honor
+ `--disable-blocking` and `--exit-code-on-api-error`.
+- `--strict-blocking` now fails on existing blocking alerts, as documented, so
+ runs that passed with them will fail.
-- Alerts on added packages are no longer also reported as existing alerts. Each
- finding on an added package was listed twice in JSON, SARIF, Slack and GitLab
- output, and counted again in the summary's "EXISTING blocking issues" line and
- the GitLab commit status.
-
-### Fixed: a package's second CVE was dropped
+### Added
-- Alerts were collapsed on package and alert type, and every CVE of one
- severity shares an alert type, so only one advisory per package and severity
- was reported. A blocking advisory could be dropped behind a warning on the
- same package, letting the run pass. Each GHSA or CVE is now reported, and the
- PR comment shows its ID next to the title.
+- Under `--strict-blocking`, PR/MR comments list existing alerts in their own
+ table after the new ones. `@SocketSecurity ignore` applies to them.
-### Added: existing alerts in PR/MR comments
+### Changed
-- Under `--strict-blocking`, the security comment lists existing alerts in
- their own table after the new ones, blocking first. `@SocketSecurity ignore`
- applies to them too. The table stops before the comment reaches GitHub's size
- limit and links to the full report for the rest.
+- An incomplete scan comparison fails the run with the infrastructure-error
+ code instead of reporting a result that may be missing alerts.
-### Fixed: a token without `repo:list` was reported as a missing repository
+### Fixed
-- A repository lookup that fails with 401 or 403 now says the token may be
- missing the `repo:list` scope. Before, the CLI treated it as a missing
- repository, tried to create it, and failed with a `repo:create` error.
+- `--strict-blocking` passed with existing blocking alerts, because the scan
+ comparison returns unchanged packages without their alerts. The CLI now reads
+ them from the full scan, at the cost of one more API request. The GitLab
+ security report and FOSSA output get the same alerts.
+- `--strict-blocking` listed each finding on an added package twice.
+- A package with several CVEs of the same severity reported only one, so a
+ blocking advisory could be dropped behind a warning.
+- A token without the `repo:list` scope was reported as a missing repository,
+ ending in a `repo:create` error.
## 2.12.1
From 60ddc10638b945d9f50f422a14445d85e38aa4d9 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 17:17:25 -0500
Subject: [PATCH 08/11] Keep each CVE apart in GitLab reports, and group
existing license alerts
GitLab finding IDs were built from package, alert type and severity, so
two CVEs of one severity on a package shared an ID and the report kept
only one. The ID now includes the advisory ID when the alert has one;
other findings keep the IDs GitLab already tracks them by. A repeated ID
is skipped, since GitLab expects each finding once per report.
In the PR comment's existing-alerts table, license policy violations are
grouped per package with the license row, as in the new-alerts table,
instead of rendering as security findings with a malware link.
The 2.13.0 changelog entry is cut to short bullets of observable
behavior.
---
CHANGELOG.md | 33 +++--
socketsecurity/core/messages.py | 168 +++++++++++++++----------
tests/core/test_alert_consolidation.py | 21 ++++
tests/core/test_existing_alerts.py | 13 ++
4 files changed, 152 insertions(+), 83 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b616216a..e3fc605a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,36 +7,33 @@
Exit codes change in this release. Check any CI step that matches on a specific
code; see [Exit codes](README.md#exit-codes).
-- Invalid flags and config values exit `2` instead of `1`, so `1` always means
- blocking findings. `--disable-blocking` doesn't apply to them.
+- Invalid flags exit `2` instead of `1`. `--disable-blocking` doesn't apply to
+ them.
- Ctrl+C exits `130` instead of `2`.
-- A missing API or SCM token, missing reachability dependencies, a plan without
- reachability, and a repository that can't be created now honor
- `--disable-blocking` and `--exit-code-on-api-error`.
-- `--strict-blocking` now fails on existing blocking alerts, as documented, so
- runs that passed with them will fail.
+- Missing tokens and other setup failures now honor `--disable-blocking` and
+ `--exit-code-on-api-error`.
+- `--strict-blocking` now fails on existing blocking alerts.
### Added
- Under `--strict-blocking`, PR/MR comments list existing alerts in their own
- table after the new ones. `@SocketSecurity ignore` applies to them.
+ table.
### Changed
- An incomplete scan comparison fails the run with the infrastructure-error
- code instead of reporting a result that may be missing alerts.
+ code.
+- GitLab security report IDs for CVE findings include the advisory ID, so
+ existing CVE findings get new IDs once.
### Fixed
-- `--strict-blocking` passed with existing blocking alerts, because the scan
- comparison returns unchanged packages without their alerts. The CLI now reads
- them from the full scan, at the cost of one more API request. The GitLab
- security report and FOSSA output get the same alerts.
-- `--strict-blocking` listed each finding on an added package twice.
-- A package with several CVEs of the same severity reported only one, so a
- blocking advisory could be dropped behind a warning.
-- A token without the `repo:list` scope was reported as a missing repository,
- ending in a `repo:create` error.
+- `--strict-blocking`, the GitLab security report and FOSSA output include
+ alerts on unchanged packages.
+- `--strict-blocking` no longer lists findings on added packages twice.
+- Every CVE on a package is reported, not one per severity.
+- A token without `repo:list` is reported as a missing scope, not a missing
+ repository.
## 2.12.1
diff --git a/socketsecurity/core/messages.py b/socketsecurity/core/messages.py
index 5768b9c4..48345384 100644
--- a/socketsecurity/core/messages.py
+++ b/socketsecurity/core/messages.py
@@ -622,6 +622,12 @@ def generate_uuid_from_alert_gitlab(alert: Issue) -> str:
"""
# Create unique string from alert key properties
unique_str = f"{alert.pkg_name}:{alert.pkg_version}:{alert.type}:{alert.severity}"
+ # Every CVE of one severity on a package shares a type, so the advisory ID
+ # keeps them apart. It's appended only when present, so other findings
+ # keep the IDs GitLab already tracks them by.
+ advisory = alert.advisory_id() if hasattr(alert, "advisory_id") else ""
+ if advisory:
+ unique_str += f":{advisory}"
# Generate UUID5 (deterministic) from namespace and unique string
namespace = uuid.UUID('6ba7b810-9dad-11d1-80b4-00c04fd430c8') # DNS namespace
@@ -772,9 +778,15 @@ def create_security_comment_gitlab(diff: Diff) -> dict:
dep_files_map: dict = {}
all_alerts = list(diff.new_alerts) + list(getattr(diff, 'unchanged_alerts', []))
+ seen_ids = set()
for alert in all_alerts:
+ vulnerability_id = Messages.generate_uuid_from_alert_gitlab(alert)
+ # GitLab expects each finding ID once per report.
+ if vulnerability_id in seen_ids:
+ continue
+ seen_ids.add(vulnerability_id)
vulnerability = {
- "id": Messages.generate_uuid_from_alert_gitlab(alert),
+ "id": vulnerability_id,
"category": "dependency_scanning",
"name": alert.title if hasattr(alert, 'title') else f"{alert.type} in {alert.pkg_name}",
"message": f"{alert.pkg_name}@{alert.pkg_version}: {alert.title if hasattr(alert, 'title') else alert.type}",
@@ -925,6 +937,67 @@ def get_view_report_url(diff: Diff) -> str:
return diff.report_url
return ""
+ @staticmethod
+ def license_group_row(alerts: list, diff: Diff, config, show_ignore: bool) -> str:
+ """One row of the security comment table for a package's license policy violations."""
+ row = ""
+ action = "Block" if any(alert.error for alert in alerts) else "Warn"
+ first_alert = alerts[0]
+
+ # Use orange diamond for license policy violations
+ license_icon = "🔶"
+
+ license_label = Messages.html_text(
+ f"{first_alert.pkg_name}@{first_alert.pkg_version}"
+ )
+ license_marker = Messages.comment_marker_text(
+ f"{first_alert.pkg_name}@{first_alert.pkg_version}"
+ )
+
+ # Build license findings list
+ license_findings = []
+ for alert in alerts:
+ license_findings.append(alert.title)
+
+ row += f"""
+
+
+ | {action} |
+ {license_icon} |
+
+
+ {license_label} has a License Policy Violation.
+ License findings:
+
+"""
+ for finding in license_findings:
+ row += f" - {Messages.html_text(finding)}
\n"
+
+
+ # Generate proper manifest URL for license violations
+ license_manifest_url = Messages.get_manifest_file_url(diff, first_alert.manifests, config)
+
+ license_ignore_html = (
+ f"Mark the package as acceptable risk: To ignore this alert only in this pull request, reply with the comment "
+ f"@SocketSecurity ignore {Messages.html_text(first_alert.pkg_type)}/{license_label}. "
+ f"You can also ignore all packages with @SocketSecurity ignore-all. "
+ f"To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert. "
+ ) if show_ignore else ""
+ row += f"""
+ From: Manifest File
+ ℹ️ Read more on: This package | What is a license policy violation?
+
+ Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev.
+ Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license.
+ {license_ignore_html}
+
+
+ |
+
+
+ """
+ return row
+
@staticmethod
def security_alert_row(alert: Issue, diff: Diff, config, show_ignore: bool) -> str:
"""One row of the security comment table for a non-license alert."""
@@ -1048,61 +1121,7 @@ def security_comment_template(diff: Diff, config=None) -> str:
# Add license policy violation entries grouped by PURL
for purl_key, alerts in license_groups.items():
- action = "Block" if any(alert.error for alert in alerts) else "Warn"
- first_alert = alerts[0]
-
- # Use orange diamond for license policy violations
- license_icon = "🔶"
-
- license_label = Messages.html_text(
- f"{first_alert.pkg_name}@{first_alert.pkg_version}"
- )
- license_marker = Messages.comment_marker_text(
- f"{first_alert.pkg_name}@{first_alert.pkg_version}"
- )
-
- # Build license findings list
- license_findings = []
- for alert in alerts:
- license_findings.append(alert.title)
-
- comment += f"""
-
-
- | {action} |
- {license_icon} |
-
-
- {license_label} has a License Policy Violation.
- License findings:
-
-"""
- for finding in license_findings:
- comment += f" - {Messages.html_text(finding)}
\n"
-
-
- # Generate proper manifest URL for license violations
- license_manifest_url = Messages.get_manifest_file_url(diff, first_alert.manifests, config)
-
- license_ignore_html = (
- f"Mark the package as acceptable risk: To ignore this alert only in this pull request, reply with the comment "
- f"@SocketSecurity ignore {Messages.html_text(first_alert.pkg_type)}/{license_label}. "
- f"You can also ignore all packages with @SocketSecurity ignore-all. "
- f"To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert. "
- ) if show_ignore else ""
- comment += f"""
- From: Manifest File
- ℹ️ Read more on: This package | What is a license policy violation?
-
- Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev.
- Suggestion: Find a package that does not violate your license policy or adjust your policy to allow this package's license.
- {license_ignore_html}
-
-
- |
-
-
- """
+ comment += Messages.license_group_row(alerts, diff, config, show_ignore)
if not security_alerts and not license_groups:
comment += """
@@ -1152,12 +1171,28 @@ def existing_comment_alerts(diff: Diff, config) -> list:
def existing_alerts_section(
alerts: list, diff: Diff, config, show_ignore: bool, view_report_url: str, size_so_far: int
) -> str:
- """Table of alerts on packages this change didn't touch, blocking ones first."""
- ordered = sorted(alerts, key=lambda alert: not alert.error)
- blocking = sum(1 for alert in ordered if alert.error)
+ """Table of alerts on packages this change didn't touch, blocking ones first.
+
+ License policy violations are grouped per package, as in the table of new
+ alerts.
+ """
+ entries = []
+ license_groups: dict = {}
+ for alert in alerts:
+ if alert.type == "licenseSpdxDisj":
+ purl_key = f"{alert.pkg_type}/{alert.pkg_name}@{alert.pkg_version}"
+ if purl_key not in license_groups:
+ license_groups[purl_key] = []
+ entries.append(license_groups[purl_key])
+ license_groups[purl_key].append(alert)
+ else:
+ entries.append([alert])
+ entries.sort(key=lambda group: not any(alert.error for alert in group))
+
+ blocking = sum(1 for alert in alerts if alert.error)
section = f"""
-**Existing alerts ({len(ordered)}).** These are on dependencies this change didn't add or update. `--strict-blocking` fails the run on the {blocking} with a **Block** action.
+**Existing alerts ({len(alerts)}).** These are on dependencies this change didn't add or update. `--strict-blocking` fails the run on the {blocking} with a **Block** action.
@@ -1174,16 +1209,19 @@ def existing_alerts_section(
"""
shown = 0
- for alert in ordered:
- row = Messages.security_alert_row(alert, diff, config, show_ignore)
+ for group in entries:
+ if group[0].type == "licenseSpdxDisj":
+ row = Messages.license_group_row(group, diff, config, show_ignore)
+ else:
+ row = Messages.security_alert_row(group[0], diff, config, show_ignore)
if size_so_far + len(section) + len(row) + len(closing) > Messages.SECURITY_COMMENT_SIZE_BUDGET:
break
section += row
- shown += 1
+ shown += len(group)
section += closing
- if shown < len(ordered):
+ if shown < len(alerts):
section += (
- f"\n{len(ordered) - shown} more existing alert(s) are not shown here to keep "
+ f"\n{len(alerts) - shown} more existing alert(s) are not shown here to keep "
f"this comment within GitHub's size limit. See the [full report]({view_report_url}?action=error%2Cwarn).\n"
)
return section + "\n"
diff --git a/tests/core/test_alert_consolidation.py b/tests/core/test_alert_consolidation.py
index b0fe79b4..64c0c4d3 100644
--- a/tests/core/test_alert_consolidation.py
+++ b/tests/core/test_alert_consolidation.py
@@ -113,3 +113,24 @@ def test_title_already_naming_the_advisory_is_left_alone():
alert.title = "GHSA-aaaa-aaaa-aaaa in lodash"
assert Messages.alert_title_with_advisory(alert) == "GHSA-aaaa-aaaa-aaaa in lodash"
+
+
+def test_gitlab_report_keeps_each_advisory_as_its_own_finding():
+ diff = Diff()
+ diff.new_alerts = [_cve("GHSA-aaaa-aaaa-aaaa", error=True), _cve("GHSA-bbbb-bbbb-bbbb", error=True)]
+
+ report = Messages.create_security_comment_gitlab(diff)
+
+ ids = [v["id"] for v in report["vulnerabilities"]]
+ assert len(ids) == 2
+ assert len(set(ids)) == 2
+
+
+def test_gitlab_ids_for_findings_without_an_advisory_are_unchanged():
+ """GitLab tracks findings by ID across pipelines, so these must not move."""
+ import uuid
+
+ alert = Issue(pkg_name="a", pkg_version="1.0.0", type="malware", severity="critical", props={})
+ expected = uuid.uuid5(uuid.UUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8"), "a:1.0.0:malware:critical")
+
+ assert Messages.generate_uuid_from_alert_gitlab(alert) == str(expected)
diff --git a/tests/core/test_existing_alerts.py b/tests/core/test_existing_alerts.py
index 5f31f558..5f32f4c5 100644
--- a/tests/core/test_existing_alerts.py
+++ b/tests/core/test_existing_alerts.py
@@ -291,3 +291,16 @@ def test_pr_comment_stays_within_the_size_budget(monkeypatch):
assert len(comment) < 6500
assert "more existing alert(s) are not shown" in comment
assert "Existing alerts (20)" in comment
+
+
+def test_existing_license_violations_use_the_license_row():
+ license_alert = _issue("gamma")
+ license_alert.type = "licenseSpdxDisj"
+ license_alert.title = "License policy violation: GPL-3.0"
+ diff = _comment_diff(new=[_issue("alpha")], existing=[license_alert])
+
+ comment = Messages.security_comment_template(diff, _config())
+ existing = comment[comment.index("Existing alerts"):]
+
+ assert "gamma@1.0.0 has a License Policy Violation." in existing
+ assert "What is known malware?" not in existing
From 1b8089493916ad0cca3ea5bbae417d44b1a11980 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 17:29:04 -0500
Subject: [PATCH 09/11] Fail on missing existing alerts and preserve distinct
findings
---
CHANGELOG.md | 4 +-
docs/cli-reference.md | 2 +-
socketsecurity/core/__init__.py | 10 ++--
socketsecurity/core/messages.py | 21 ++++---
socketsecurity/core/scm_comments.py | 11 +++-
tests/core/test_alert_consolidation.py | 63 +++++++++++++++++++--
tests/core/test_existing_alerts.py | 76 +++++++++++++++++++++++++-
tests/unit/test_disable_ignore.py | 75 +++++++++++++++++++++++++
8 files changed, 237 insertions(+), 25 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e3fc605a..ac6c7738 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,8 +23,8 @@ code; see [Exit codes](README.md#exit-codes).
- An incomplete scan comparison fails the run with the infrastructure-error
code.
-- GitLab security report IDs for CVE findings include the advisory ID, so
- existing CVE findings get new IDs once.
+- GitLab security report IDs include the ecosystem, full package coordinate and
+ advisory ID, so existing findings get new IDs once.
### Fixed
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 76a8cdcc..439c174b 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -643,7 +643,7 @@ Security issues detected by Socket Security:
- **Diff Mode Only**: The flag only works in diff mode (with SCM integration). In API mode, a warning is logged.
- **Error-Level Only**: Only fails on `error=True` alerts (blocking severity), not warnings.
-- **Existing alerts come from the full scan**: The scan comparison doesn't carry alerts on unchanged packages, so the CLI reads them from the new full scan, at the cost of one more API request per run. If that request fails, the run fails with the infrastructure-error code rather than passing without them.
+- **Existing alerts come from the full scan**: The scan comparison doesn't carry alerts on unchanged packages, so the CLI reads them from the new full scan, at the cost of one more API request per run. If that request fails or omits an unchanged package, the run fails with the infrastructure-error code rather than passing without them.
- **PR/MR comments**: Existing alerts are listed in their own table after the new ones, blocking first. `@SocketSecurity ignore` applies to them too. Very large sets are cut off before the comment reaches GitHub's size limit, with a link to the full report.
- **Priority**: `--disable-blocking` takes precedence - if both flags are set, the build will always pass.
- **First Scan**: On the very first scan of a repository, there are no "existing" violations, so behavior is identical to standard mode.
diff --git a/socketsecurity/core/__init__.py b/socketsecurity/core/__init__.py
index 9debddd1..1720a0fa 100644
--- a/socketsecurity/core/__init__.py
+++ b/socketsecurity/core/__init__.py
@@ -2549,8 +2549,8 @@ def add_existing_alerts_from_full_scan(
Skipped when any unchanged package already has alerts: the comparison then
came from an endpoint that includes them, such as the streaming fallback.
- A failed fetch raises, because reporting existing alerts as absent would
- let ``--strict-blocking`` pass a run it should fail.
+ A failed fetch or an unmatched package raises, because reporting existing
+ alerts as absent would let ``--strict-blocking`` pass a run it should fail.
"""
if any(package.alerts for package in unchanged_packages.values()):
log.debug("The comparison already includes alerts on unchanged packages")
@@ -2586,9 +2586,9 @@ def add_existing_alerts_from_full_scan(
f"unchanged packages from full scan {full_scan_id} in {time.time() - start:.2f}s"
)
if matched < len(unchanged_packages):
- log.warning(
- f"{len(unchanged_packages) - matched} unchanged packages were not found in "
- f"full scan {full_scan_id}, so their existing alerts are not reported"
+ raise InfrastructureError(
+ f"{len(unchanged_packages) - matched} of {len(unchanged_packages)} unchanged packages "
+ f"were not found in full scan {full_scan_id}; unable to evaluate all existing alerts."
)
@staticmethod
diff --git a/socketsecurity/core/messages.py b/socketsecurity/core/messages.py
index 48345384..2c09ed2f 100644
--- a/socketsecurity/core/messages.py
+++ b/socketsecurity/core/messages.py
@@ -620,14 +620,19 @@ def generate_uuid_from_alert_gitlab(alert: Issue) -> str:
Generate deterministic UUID for vulnerability based on alert properties.
This ensures consistent IDs across runs for the same vulnerability.
"""
- # Create unique string from alert key properties
- unique_str = f"{alert.pkg_name}:{alert.pkg_version}:{alert.type}:{alert.severity}"
- # Every CVE of one severity on a package shares a type, so the advisory ID
- # keeps them apart. It's appended only when present, so other findings
- # keep the IDs GitLab already tracks them by.
+ # Names alone collide across ecosystems and namespaces. Full scans and
+ # comparisons use different PURL prefixes, so normalize those while
+ # retaining the namespace and version in the package coordinate.
+ ecosystem = getattr(alert, "pkg_type", "") or ""
+ purl = getattr(alert, "purl", "") or f"{alert.pkg_name}@{alert.pkg_version}"
+ coordinate = purl.removeprefix("pkg:").lstrip("/").removeprefix(f"{ecosystem}/")
+ # Every CVE of one severity on a package shares a type, so keep the
+ # advisory ID as well. Manifest details do not affect finding identity.
advisory = alert.advisory_id() if hasattr(alert, "advisory_id") else ""
- if advisory:
- unique_str += f":{advisory}"
+ unique_str = json.dumps(
+ [ecosystem, coordinate, alert.type, alert.severity, advisory],
+ separators=(",", ":"),
+ )
# Generate UUID5 (deterministic) from namespace and unique string
namespace = uuid.UUID('6ba7b810-9dad-11d1-80b4-00c04fd430c8') # DNS namespace
@@ -1151,6 +1156,7 @@ def security_comment_template(diff: Diff, config=None) -> str:
# section is the open-ended part of the security comment, so it stops adding
# rows at this size and links to the full report for the rest.
SECURITY_COMMENT_SIZE_BUDGET = 60000
+ EXISTING_ALERTS_TRUNCATED_MARKER = ""
@staticmethod
def existing_comment_alerts(diff: Diff, config) -> list:
@@ -1221,6 +1227,7 @@ def existing_alerts_section(
section += closing
if shown < len(alerts):
section += (
+ f"\n{Messages.EXISTING_ALERTS_TRUNCATED_MARKER}\n"
f"\n{len(alerts) - shown} more existing alert(s) are not shown here to keep "
f"this comment within GitHub's size limit. See the [full report]({view_report_url}?action=error%2Cwarn).\n"
)
diff --git a/socketsecurity/core/scm_comments.py b/socketsecurity/core/scm_comments.py
index 3ef0e3a6..c794583f 100644
--- a/socketsecurity/core/scm_comments.py
+++ b/socketsecurity/core/scm_comments.py
@@ -230,6 +230,12 @@ def process_updated_security_comment(
lines = []
ignore_section = False
kept_alert = False # Whether any alert row survived the ignore commands
+ # Individual ignore commands only account for the rows we can see. A
+ # truncated comment still has undisplayed findings unless ignore-all was
+ # explicitly requested, even after its last visible row is removed.
+ has_undisplayed_alerts = not ignore_all and any(
+ Messages.EXISTING_ALERTS_TRUNCATED_MARKER in line for line in comment.body_list
+ )
pkg_name = pkg_version = "" # Track current package and version
# Loop through the comment lines
@@ -270,9 +276,8 @@ def process_updated_security_comment(
elif not ignore_section:
lines.append(line)
- # Every row was ignored, so drop the table rather than leaving the caution
- # banner sitting above an empty one.
- if not kept_alert:
+ # Drop a fully resolved table only when no undisplayed findings remain.
+ if not kept_alert and not has_undisplayed_alerts:
return Messages.security_comment_no_alerts_template(
Comments.extract_report_url("\n".join(comment.body_list))
)
diff --git a/tests/core/test_alert_consolidation.py b/tests/core/test_alert_consolidation.py
index 64c0c4d3..1dcde3a7 100644
--- a/tests/core/test_alert_consolidation.py
+++ b/tests/core/test_alert_consolidation.py
@@ -7,6 +7,8 @@
"""
from unittest.mock import Mock
+import pytest
+
from socketsecurity.config import CliConfig
from socketsecurity.core import Core
from socketsecurity.core.classes import Diff, Issue
@@ -126,11 +128,60 @@ def test_gitlab_report_keeps_each_advisory_as_its_own_finding():
assert len(set(ids)) == 2
-def test_gitlab_ids_for_findings_without_an_advisory_are_unchanged():
- """GitLab tracks findings by ID across pipelines, so these must not move."""
- import uuid
+@pytest.mark.parametrize("advisory", ["", "GHSA-aaaa-aaaa-aaaa"])
+@pytest.mark.parametrize("coordinates", [
+ (("npm", "lodash@4.17.20"), ("pypi", "lodash@4.17.20")),
+ (("maven", "org.first/lodash@4.17.20"), ("maven", "org.second/lodash@4.17.20")),
+])
+def test_gitlab_report_keeps_distinct_package_coordinates(advisory, coordinates):
+ alerts = []
+ for index, (ecosystem, purl) in enumerate(coordinates):
+ alert = _cve(advisory, pkg_type=ecosystem)
+ alert.purl = purl
+ alert.manifests = f"manifest-{index}.json"
+ alerts.append(alert)
+ diff = Diff(new_alerts=alerts[:1], unchanged_alerts=alerts[1:])
+
+ report = Messages.create_security_comment_gitlab(diff)
+
+ ids = {v["id"] for v in report["vulnerabilities"]}
+ assert len(ids) == 2
+ assert {f["path"] for f in report["dependency_files"]} == {"manifest-0.json", "manifest-1.json"}
+ # IDs remain stable if either package is the only one present next time.
+ for alert in alerts:
+ single = Messages.create_security_comment_gitlab(Diff(new_alerts=[alert]))
+ assert single["vulnerabilities"][0]["id"] in ids
+
+
+def test_gitlab_report_deduplicates_a_finding_listed_as_new_and_existing():
+ first = _cve("GHSA-aaaa-aaaa-aaaa")
+ repeat = _cve("GHSA-aaaa-aaaa-aaaa")
+ diff = Diff(new_alerts=[first], unchanged_alerts=[repeat])
- alert = Issue(pkg_name="a", pkg_version="1.0.0", type="malware", severity="critical", props={})
- expected = uuid.uuid5(uuid.UUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8"), "a:1.0.0:malware:critical")
+ report = Messages.create_security_comment_gitlab(diff)
+
+ assert len(report["vulnerabilities"]) == 1
+
+
+@pytest.mark.parametrize("purl", [
+ "org.first/lodash@4.17.20", "maven/org.first/lodash@4.17.20",
+ "pkg:maven/org.first/lodash@4.17.20",
+])
+def test_gitlab_ids_are_stable_across_full_scan_and_diff_purl_formats(purl):
+ alert = _cve("GHSA-aaaa-aaaa-aaaa", pkg_type="maven")
+ alert.purl = "org.first/lodash@4.17.20"
+ expected = Messages.generate_uuid_from_alert_gitlab(alert)
+ alert.purl = purl
+
+ assert Messages.generate_uuid_from_alert_gitlab(alert) == expected
+
+
+def test_gitlab_ids_for_findings_without_an_advisory_ignore_manifest_changes():
+ alert = Issue(
+ pkg_type="npm", pkg_name="a", pkg_version="1.0.0", purl="a@1.0.0",
+ type="malware", severity="critical", props={}, manifests="package.json",
+ )
+ expected = Messages.generate_uuid_from_alert_gitlab(alert)
+ alert.manifests = "nested/package.json"
- assert Messages.generate_uuid_from_alert_gitlab(alert) == str(expected)
+ assert Messages.generate_uuid_from_alert_gitlab(alert) == expected
diff --git a/tests/core/test_existing_alerts.py b/tests/core/test_existing_alerts.py
index 5f32f4c5..139577dd 100644
--- a/tests/core/test_existing_alerts.py
+++ b/tests/core/test_existing_alerts.py
@@ -7,6 +7,7 @@
report and FOSSA-format output.
"""
import json
+import re
from pathlib import Path
from types import SimpleNamespace
from unittest.mock import Mock
@@ -21,9 +22,11 @@
from socketsecurity.config import CliConfig
from socketsecurity.core import Core
-from socketsecurity.core.classes import Diff, Issue
+from socketsecurity.core.classes import Comment, Diff, Issue
from socketsecurity.core.messages import Messages
+from socketsecurity.core.scm_comments import Comments
from socketsecurity.core.socket_config import SocketConfig
+from socketsecurity.exit_codes import InfrastructureError
from socketsecurity.output import OutputHandler
BUCKETS = ("added", "removed", "unchanged", "replaced", "updated")
@@ -209,6 +212,39 @@ def test_failed_full_scan_fetch_fails_the_run(core):
core.create_new_diff(["/repo"], params, explicit_files=["/repo/package.json"])
+@pytest.mark.parametrize("flags", [
+ ("--strict-blocking",), ("--enable-gitlab-security",), ("--legal-format", "fossa"),
+])
+@pytest.mark.parametrize("response_kind", ["missing", "malformed", "empty"])
+def test_incomplete_existing_alert_data_fails_the_run(core, flags, response_kind):
+ """A successful response can still omit packages, including SDK parse failures."""
+ core.cli_config = CliConfig.from_args(["--api-token", "test", *flags])
+ core.sdk.fullscans.stream_diff.return_value = _diff_response(unchanged=[
+ _diff_artifact("unchanged", "u1", "gamma"),
+ _diff_artifact("unchanged", "u2", "delta"),
+ ])
+ artifacts = [_scan_artifact("u2", "delta", [])]
+ if response_kind == "malformed":
+ broken = _scan_artifact("u1", "gamma", [_alert("k3")])
+ del broken["alerts"][0]["key"]
+ artifacts.append(broken)
+ elif response_kind == "empty":
+ artifacts = []
+ core.sdk.fullscans.stream.return_value = _scan_response(*artifacts)
+ params = FullScanParams(repo="repo", branch="feature")
+ params.include_license_details = True
+
+ with pytest.raises(InfrastructureError, match="unchanged packages.*full scan new"):
+ core.create_new_diff(["/repo"], params, explicit_files=["/repo/package.json"])
+
+
+def test_matched_package_without_alerts_is_a_clean_result(core):
+ diff = _run(core, "--strict-blocking", scan_alerts=[])
+
+ assert diff.unchanged_alerts == []
+ core.sdk.fullscans.stream.assert_called_once()
+
+
# --- PR comment ------------------------------------------------------------------------
@@ -293,6 +329,44 @@ def test_pr_comment_stays_within_the_size_budget(monkeypatch):
assert "Existing alerts (20)" in comment
+@pytest.mark.parametrize("budget", [6000, 1])
+def test_ignoring_visible_alerts_keeps_the_truncation_warning(monkeypatch, budget):
+ monkeypatch.setattr(Messages, "SECURITY_COMMENT_SIZE_BUDGET", budget)
+ diff = _comment_diff(existing=[_issue(f"pkg{i}") for i in range(20)])
+ body = Messages.security_comment_template(diff, _config())
+ visible = re.findall(r"", body)
+ assert len(visible) < len(diff.unchanged_alerts)
+ if budget > 1:
+ assert visible
+ comments = {"ignore": [
+ Comment(body_list=[f"@SocketSecurity ignore npm/{package}"])
+ for package in visible
+ ]}
+ assert Comments.remove_alerts(comments, diff.unchanged_alerts)
+
+ updated = Comments.process_security_comment(Comment(body_list=body.splitlines()), comments)
+
+ assert "No dependency alerts to report" not in updated
+ assert "more existing alert(s) are not shown" in updated
+ assert "[full report](https://socket.dev/diff?action=error%2Cwarn)" in updated
+ # Reprocessing the comment must not lose the undisplayed findings either.
+ assert Comments.process_security_comment(Comment(body_list=updated.splitlines()), comments) == updated
+
+
+def test_ignore_all_clears_even_truncated_existing_alerts(monkeypatch):
+ monkeypatch.setattr(Messages, "SECURITY_COMMENT_SIZE_BUDGET", 6000)
+ diff = _comment_diff(existing=[_issue(f"pkg{i}") for i in range(20)])
+ body = Messages.security_comment_template(diff, _config())
+ assert "more existing alert(s) are not shown" in body
+ comments = {"ignore": [Comment(body_list=["@SocketSecurity ignore-all"])]}
+
+ updated = Comments.process_security_comment(Comment(body_list=body.splitlines()), comments)
+
+ assert "No dependency alerts to report" in updated
+ assert "more existing alert(s)" not in updated
+ assert "[View full report](https://socket.dev/diff)" in updated
+
+
def test_existing_license_violations_use_the_license_row():
license_alert = _issue("gamma")
license_alert.type = "licenseSpdxDisj"
diff --git a/tests/unit/test_disable_ignore.py b/tests/unit/test_disable_ignore.py
index 93ae4e8c..898f139f 100644
--- a/tests/unit/test_disable_ignore.py
+++ b/tests/unit/test_disable_ignore.py
@@ -1,10 +1,17 @@
"""Tests for the --disable-ignore flag."""
+import sys
+from contextlib import nullcontext
from dataclasses import dataclass
+from unittest.mock import MagicMock, Mock
+import pytest
+
+from socketsecurity import socketcli
from socketsecurity.config import CliConfig
from socketsecurity.core.classes import Comment, Diff, Issue
from socketsecurity.core.messages import Messages
+from socketsecurity.core.scm.github import Github
from socketsecurity.core.scm_comments import Comments
# --- CLI flag parsing tests ---
@@ -131,6 +138,74 @@ def test_ignore_all_suppresses_all_alerts(self):
assert len(result) == 0
+@pytest.mark.parametrize("command", [
+ "@SocketSecurity ignore npm/lodash@4.17.21", "@SocketSecurity ignore-all",
+])
+@pytest.mark.parametrize("authorized, disable_ignore, expected_exit", [
+ (True, False, 0), (True, True, 1), (False, False, 1), (False, True, 1),
+])
+def test_cli_existing_blocker_respects_ignore_authorization_and_flag(
+ monkeypatch, command, authorized, disable_ignore, expected_exit
+):
+ """Exercise the SCM CLI path with real ignore filtering and exit-code handling."""
+ argv = [
+ "socketcli", "--api-token", "test", "--scm", "github", "--strict-blocking",
+ "--repo", "repo", "--branch", "feature", "--pr-number", "42",
+ "--files", '["package.json"]',
+ ]
+ if disable_ignore:
+ argv.append("--disable-ignore")
+ monkeypatch.setattr(sys, "argv", argv)
+ for key, value in {
+ "GH_API_TOKEN": "test", "GITHUB_EVENT_NAME": "pull_request",
+ "EVENT_ACTION": "synchronize", "GITHUB_REPOSITORY": "acme/repo",
+ "DEFAULT_BRANCH": "false",
+ }.items():
+ monkeypatch.setenv(key, value)
+
+ alert = _make_alert()
+ diff = Diff(id="scan", new_alerts=[], unchanged_alerts=[alert])
+ diff.diff_url = "https://socket.dev/diff"
+ raw_comments = {
+ 1: _make_comment(command),
+ 2: _make_comment("", comment_id=2),
+ }
+ monkeypatch.setattr(Github, "get_comments_for_pr", lambda self: Comments.check_for_socket_comments(
+ raw_comments, is_authorized=lambda comment: authorized,
+ ))
+ posted = Mock()
+ monkeypatch.setattr(Github, "add_socket_comments", posted)
+ monkeypatch.setattr(Github, "handle_ignore_reactions", Mock())
+ sdk = MagicMock()
+ sdk.org.get.return_value = {"organizations": {"org-id": {"slug": "acme"}}}
+ monkeypatch.setattr(socketcli, "build_socket_sdk", Mock(return_value=sdk))
+ client = Mock()
+ monkeypatch.setattr(socketcli, "CliClient", Mock(return_value=client))
+ monkeypatch.setattr(socketcli, "StreamingLogs", lambda **kwargs: nullcontext(Mock()))
+ monkeypatch.setattr(socketcli, "apply_git_context", lambda config: (False, None))
+ scan = Mock(return_value=diff)
+ monkeypatch.setattr(socketcli.Core, "create_new_diff", scan)
+ monkeypatch.setattr(socketcli.Core, "has_manifest_files", Mock(return_value=True))
+ monkeypatch.setattr(socketcli.OutputHandler, "handle_output", Mock())
+
+ with pytest.raises(SystemExit) as result:
+ socketcli.cli()
+
+ assert result.value.code == expected_exit
+ scan.assert_called_once()
+ posted.assert_called_once()
+ security_body = posted.call_args.args[0]
+ if expected_exit == 0:
+ assert diff.unchanged_alerts == []
+ assert "No dependency alerts to report" in security_body
+ events = client.post_telemetry_events.call_args.args[1]
+ assert [event["artifact_purl"] for event in events] == [alert.purl]
+ else:
+ assert diff.unchanged_alerts == [alert]
+ assert "Existing alerts (1)" in security_body
+ client.post_telemetry_events.assert_not_called()
+
+
# --- Comment output tests ---
@dataclass
From 5a6a3f8e8b1b870347c899f6228b86cef4e12036 Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 17:32:19 -0500
Subject: [PATCH 10/11] Document exit-code migration and CI failure policies
---
CHANGELOG.md | 7 +++++--
README.md | 29 ++++++++++++++++++++++-------
docs/ci-cd.md | 38 +++++++++++++++++++++++++++++++++++++-
docs/cli-reference.md | 22 ++++++++++++++++++----
docs/troubleshooting.md | 12 ++++++++++++
5 files changed, 94 insertions(+), 14 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ac6c7738..9075b492 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,8 +21,8 @@ code; see [Exit codes](README.md#exit-codes).
### Changed
-- An incomplete scan comparison fails the run with the infrastructure-error
- code.
+- Incomplete scan comparisons or existing-alert results fail the run with the
+ infrastructure-error code.
- GitLab security report IDs include the ecosystem, full package coordinate and
advisory ID, so existing findings get new IDs once.
@@ -32,6 +32,9 @@ code; see [Exit codes](README.md#exit-codes).
alerts on unchanged packages.
- `--strict-blocking` no longer lists findings on added packages twice.
- Every CVE on a package is reported, not one per severity.
+- GitLab reports keep findings from different ecosystems and namespaces separate.
+- PR/MR comments group existing license violations and retain warnings about
+ omitted findings after individual ignores.
- A token without `repo:list` is reported as a missing scope, not a missing
repository.
diff --git a/README.md b/README.md
index b4e8f842..ddb7ad3d 100644
--- a/README.md
+++ b/README.md
@@ -240,14 +240,12 @@ error, so the supervisor's exit status (commonly 124 or 137) takes precedence.
The two flags that affect exit codes can cancel each other out, so the order of
precedence matters:
-- **`--disable-blocking` wins for every run that gets past flag parsing.** It
- forces exit `0` for security findings, infrastructure errors and interrupts.
- If you set it, `--exit-code-on-api-error` has no effect (you'll always get `0`).
- It does not apply to usage errors (`2`): a run with invalid flags never scanned
- anything, so it always fails.
+- **`--disable-blocking` forces exit `0` for findings, infrastructure errors and
+ interrupts.** It takes precedence over `--exit-code-on-api-error` and
+ `--strict-blocking`. Usage errors still exit `2`.
- **`--exit-code-on-api-error` only applies when `--disable-blocking` is *not*
- set.** It changes the infra-error code (and the generic-error code); it never
- touches the security-finding code (`1`).
+ set.** It changes the infrastructure-error code, including unexpected runtime
+ failures. Findings (`1`), usage errors (`2`) and Ctrl+C (`130`) keep their codes.
So for the common "don't let Socket outages block my pipeline, but still fail on
real findings" goal, use `--exit-code-on-api-error` **without** `--disable-blocking`:
@@ -266,6 +264,23 @@ scan exit `0` on *both* findings and outages — the `soft_fail: 100` rule would
never match, and real findings would stop blocking. That's usually not what you
want.
+### Upgrading to 2.13.0
+
+Update pipeline rules and wrapper scripts that match specific exit codes:
+
+| Outcome | Before 2.13.0 | From 2.13.0 |
+|---------|---------------|-------------|
+| Invalid flags or configuration | CLI validation: `1`; argparse: `2` | `2` for both; never suppressed by `--disable-blocking` |
+| Ctrl+C | `2` | `130`, or `0` with `--disable-blocking` |
+| Missing token or other setup failure | Fixed `2` or `3`, depending on the failure | Infrastructure-error code (`3` by default); both exit-code flags now apply |
+
+Blocking findings still exit `1`. With `--strict-blocking`, existing blocking
+alerts can now fail jobs that previously passed. GitLab report findings also get
+new IDs once; see the [release notes](CHANGELOG.md#2130).
+
+For a compact comparison of failure-handling policies, see
+[Exit codes in CI](docs/ci-cd.md#exit-codes-in-ci).
+
## Common gotchas
See [`docs/troubleshooting.md`](https://github.com/SocketDev/socket-python-cli/blob/main/docs/troubleshooting.md#common-gotchas).
diff --git a/docs/ci-cd.md b/docs/ci-cd.md
index cb6ee629..fbcd1de4 100644
--- a/docs/ci-cd.md
+++ b/docs/ci-cd.md
@@ -52,6 +52,42 @@ steps:
- "results.sarif"
```
+## Exit codes in CI
+
+Choose which outcomes may leave your scan step green. The values below are the
+CLI's exit status; CI cancellation and external timeouts can have their own status.
+
+| Outcome | Default | `--exit-code-on-api-error 100` | `--disable-blocking` |
+|---------|---------|--------------------------------|----------------------|
+| No blocking findings | `0` | `0` | `0` |
+| Blocking findings | `1` | `1` | `0` |
+| Invalid flags or configuration | `2` | `2` | `2` |
+| Setup, API or runtime failure | `3` | `100` | `0` |
+| Ctrl+C handled by the CLI | `130` | `130` | `0` |
+
+Use a custom infrastructure code with your CI provider's exit-code allowlist; the
+[Buildkite example](../README.md#how-these-options-interact) shows this pattern.
+For providers without that feature, remap infrastructure errors to `0`:
+
+```bash
+# Keep findings blocking; allow setup/API failures to pass.
+socketcli --config .socketcli.toml --exit-code-on-api-error 0
+
+# Report-only mode: findings, infrastructure failures and Ctrl+C exit 0.
+# Invalid flags/configuration still exit 2.
+socketcli --config .socketcli.toml --disable-blocking
+```
+
+Combining the flags gives `--disable-blocking` precedence. Avoid blanket shell
+`|| true` or job-wide `continue-on-error` when only API failures should be allowed:
+they also hide findings and usage errors. Even with exit `0`, a setup/API failure
+does not mean a clean scan; check the logs for a completed report.
+
+Findings block only when a [diff comparison runs](#scan-type-by-pipeline).
+`--strict-blocking` also checks existing blocking alerts; an incomplete comparison
+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
Use `--config .socketcli.toml` or `--config .socketcli.json` to keep pipeline commands small.
@@ -465,7 +501,7 @@ 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 |
+| Pull request / merge request | Diff scan against the repository's baseline | Yes, on new blocking alerts; also existing blockers with `--strict-blocking` |
| 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
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 439c174b..6a951823 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -430,6 +430,8 @@ Sample config files:
### CI/CD usage tips
For CI-specific examples and guidance, see [`ci-cd.md`](ci-cd.md).
+Exit statuses and flag precedence are listed in [Exit codes](../README.md#exit-codes),
+with pipeline examples in [Exit codes in CI](ci-cd.md#exit-codes-in-ci).
The CLI runs a pinned version of the Coana CLI, the analysis engine; it does **not** auto-update the engine. It downloads the engine from the Socket API on first use and keeps it in `$XDG_CACHE_HOME/socket/coana/v1` (`~/.cache/socket/coana/v1` when `XDG_CACHE_HOME` is unset). Pass `--reach-version latest` to opt into the newest published version. Use `--reach` to enable reachability analysis during a full scan, or add `--only-facts-file` (with `--reach`) to submit only the reachability facts file (`.socket.facts.json`) when creating the full scan.
@@ -437,6 +439,7 @@ The CLI runs a pinned version of the Coana CLI, the analysis engine; it does **n
| Parameter | Required | Default | Description |
|:-------------------------|:---------|:--------|:----------------------------------------------------------------------|
| `--ignore-commit-files` | False | False | Compare regardless of which files changed, scanning every manifest |
+| `--exit-code-on-api-error` | False | 3 | Remap infrastructure failures, including missing tokens, setup failures, incomplete scan data and unexpected runtime errors. Findings (`1`), usage errors (`2`) and Ctrl+C (`130`) are unaffected. `--disable-blocking` takes precedence. |
| `--disable-blocking` | False | False | Non-blocking CI mode: the CLI exits **0** even when blocking alerts are present (including with `--strict-blocking`). Also exits 0 on infrastructure errors (missing API or SCM token, Socket API failures, uncaught runtime errors) and interrupts, so the job is treated as successful while findings and errors are still logged. Invalid flags still exit **2**. 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. 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). |
@@ -641,10 +644,10 @@ Security issues detected by Socket Security:
### Important Notes
-- **Diff Mode Only**: The flag only works in diff mode (with SCM integration). In API mode, a warning is logged.
+- **Diff Mode Only**: The flag applies when a scan comparison runs, with or without SCM integration. A full scan logs a warning and does not evaluate existing violations; see [Scan type by pipeline](ci-cd.md#scan-type-by-pipeline).
- **Error-Level Only**: Only fails on `error=True` alerts (blocking severity), not warnings.
- **Existing alerts come from the full scan**: The scan comparison doesn't carry alerts on unchanged packages, so the CLI reads them from the new full scan, at the cost of one more API request per run. If that request fails or omits an unchanged package, the run fails with the infrastructure-error code rather than passing without them.
-- **PR/MR comments**: Existing alerts are listed in their own table after the new ones, blocking first. `@SocketSecurity ignore` applies to them too. Very large sets are cut off before the comment reaches GitHub's size limit, with a link to the full report.
+- **PR/MR comments**: Existing alerts are listed in their own table after the new ones, blocking first, with license violations grouped per package. `@SocketSecurity ignore` applies to them too. Very large sets are cut off before the comment reaches GitHub's size limit, with a link to the full report. Ignoring every displayed alert preserves the warning about omitted findings; `ignore-all` also clears omitted findings.
- **Priority**: `--disable-blocking` takes precedence - if both flags are set, the build will always pass.
- **First Scan**: On the very first scan of a repository, there are no "existing" violations, so behavior is identical to standard mode.
@@ -883,9 +886,16 @@ The GitLab Security Dashboard report and the JSON/SARIF diff outputs use differe
### Alert Ignoring via PR/MR Comments
-When using the CLI with SCM integration (`--scm github` or `--scm gitlab`), users can ignore specific alerts by reacting to Socket's PR/MR comments. Ignored alerts are removed from `--enable-json`, `--enable-sarif`, and console output.
+In SCM diff mode (`--scm github` or `--scm gitlab`), an authorized
+`@SocketSecurity ignore /@` or
+`@SocketSecurity ignore-all` comment removes matching new alerts from the CLI's
+reports, including the GitLab report. With `--strict-blocking`, it also removes
+matching existing alerts from blocking checks and reports. Without strict blocking,
+the GitLab report still includes existing findings.
-However, the GitLab Security Dashboard report includes **all** alerts matching your security policy (new and existing), regardless of comment-based ignores. This ensures the Security Dashboard always reflects the full set of known issues. To suppress a vulnerability from the GitLab report, adjust the alert's policy in Socket's dashboard rather than ignoring it via a PR comment.
+`--disable-ignore` disables these commands. See [Who can ignore an alert](#who-can-ignore-an-alert)
+for authorization rules. To suppress a finding across future PRs, update its policy
+or triage state in Socket's dashboard.
### Report Schema
@@ -902,6 +912,10 @@ Socket CLI generates reports compliant with [GitLab Dependency Scanning schema v
**Schema compatibility:** The v15.0.0 schema is supported across all GitLab versions 12.0+ (both self-hosted and cloud). The report includes the `dependency_files` field, which is required by v15.0.0 and accepted as an optional extra by newer schema versions, ensuring maximum compatibility across GitLab instances.
+Finding IDs distinguish the ecosystem, full package coordinate and advisory, so
+different namespaces or CVEs remain separate findings. Upgrading to 2.13.0 changes
+existing finding IDs once; GitLab may show them as newly detected on the first report.
+
### Performance Notes
When `--enable-gitlab-security` (or `--enable-json` / `--enable-sarif`) is used with a full scan (non-diff mode), the CLI fetches package and alert data from the scan results to populate the report. This adds time proportional to the number of packages in the scan. Without these output flags, no additional data is fetched and scan performance is unchanged.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 4161dc3f..ea2454b4 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,5 +1,17 @@
# Troubleshooting
+## Unexpected CI exit status
+
+| Symptom | What to check |
+|---------|---------------|
+| Exit `2`, even with `--disable-blocking` | Fix the flags or configuration reported in the logs. Usage errors are never suppressed. |
+| Exit `3` with no reported findings | Check tokens, scopes, baseline lookup and scan-completeness errors. This is a failed evaluation; `--exit-code-on-api-error` can remap its code. |
+| Ctrl+C is treated as a configuration error | Update wrapper/CI rules: Ctrl+C changed from `2` to `130` in 2.13.0. |
+| Exit `0` despite expected blockers | Check `--disable-blocking`, remapping to `0`, and whether the run produced a full scan instead of a diff. Full scans do not gate on findings. |
+
+See [Exit codes in CI](ci-cd.md#exit-codes-in-ci) for the flag combinations and
+[upgrade guidance](../README.md#upgrading-to-2130) for older pipeline rules.
+
## API token scopes for scan comparisons
PR/MR runs compare the new scan against the repository's head scan. That comparison
From 766e50bdf201daeae6521095fc1c1c26bc4d2dbc Mon Sep 17 00:00:00 2001
From: lelia <2418071+lelia@users.noreply.github.com>
Date: Tue, 17 Nov 2026 17:43:04 -0500
Subject: [PATCH 11/11] Audit CLI exit policy and validate configuration before
setup
---
CHANGELOG.md | 5 +-
README.md | 7 +-
docs/ci-cd.md | 2 +
docs/cli-reference.md | 13 +-
docs/development.md | 6 +
docs/troubleshooting.md | 2 +-
pytest.ini | 2 +-
socketsecurity/config.py | 72 ++++++-
socketsecurity/core/__init__.py | 19 +-
socketsecurity/exit_codes.py | 8 +-
socketsecurity/socketcli.py | 62 ++----
tests/core/test_cli_exit_contract.py | 288 +++++++++++++++++++++++++++
tests/core/test_exit_codes.py | 25 ++-
tests/unit/test_socketcli.py | 2 +-
14 files changed, 435 insertions(+), 78 deletions(-)
create mode 100644 tests/core/test_cli_exit_contract.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9075b492..dac3ace8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@ code; see [Exit codes](README.md#exit-codes).
- Missing tokens and other setup failures now honor `--disable-blocking` and
`--exit-code-on-api-error`.
- `--strict-blocking` now fails on existing blocking alerts.
+- Config-file booleans, integers and choices are validated before scan setup.
### Added
@@ -35,8 +36,10 @@ code; see [Exit codes](README.md#exit-codes).
- GitLab reports keep findings from different ecosystems and namespaces separate.
- PR/MR comments group existing license violations and retain warnings about
omitted findings after individual ignores.
+- Invalid file lists and unreadable config files exit with the usage-error code.
+- Exit-code flags retain their startup values if the config file changes during a run.
- A token without `repo:list` is reported as a missing scope, not a missing
- repository.
+ repository. Only a missing repository triggers a create request.
## 2.12.1
diff --git a/README.md b/README.md
index ddb7ad3d..831c0c0d 100644
--- a/README.md
+++ b/README.md
@@ -219,7 +219,7 @@ Minimal pattern:
| Code | Meaning |
|-------|---------|
-| `0` | Clean scan — no blocking issues (or `--disable-blocking` set) |
+| `0` | Successful report, skipped SCM event, or `--disable-blocking` set; findings gate only evaluated diffs |
| `1` | Blocking security finding(s) detected |
| `2` | Invalid flags or configuration (usage error), including argparse's own errors |
| `3` | Infrastructure or API error: missing API or SCM token, permission or plan problem, timeout, network failure, incomplete scan comparison, unexpected error |
@@ -278,6 +278,11 @@ Blocking findings still exit `1`. With `--strict-blocking`, existing blocking
alerts can now fail jobs that previously passed. GitLab report findings also get
new IDs once; see the [release notes](CHANGELOG.md#2130).
+Configuration is validated before credentials or network setup. Use native
+JSON/TOML booleans such as `false`, a positive integer `timeout`, and an array of
+file paths for `files`. Invalid or unreadable configuration exits `2` even when
+credentials are missing or blocking is disabled.
+
For a compact comparison of failure-handling policies, see
[Exit codes in CI](docs/ci-cd.md#exit-codes-in-ci).
diff --git a/docs/ci-cd.md b/docs/ci-cd.md
index fbcd1de4..88210ed1 100644
--- a/docs/ci-cd.md
+++ b/docs/ci-cd.md
@@ -84,6 +84,8 @@ they also hide findings and usage errors. Even with exit `0`, a setup/API failur
does not mean a clean scan; check the logs for a completed report.
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
[2.13.0 migration table](../README.md#upgrading-to-2130) when updating existing CI rules.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 6a951823..5c03e763 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -358,7 +358,7 @@ If you don't want to provide the Socket API Token every time then you can use th
**Reachability Analysis Requirements:**
-The Python CLI verifies the following **up front** (before invoking the analysis engine) and exits with code **3** if any are unmet:
+The Python CLI verifies the following **up front** (before invoking the analysis engine). Missing requirements use the infrastructure-error code (`3` by default), subject to `--exit-code-on-api-error` and `--disable-blocking`:
- `node` - Required to run the analysis engine (the Coana CLI). The engine needs Node.js 22.13 or later.
- `uv` - Required by the analysis engine
- An **Enterprise** Socket organization plan (any `enterprise*` plan, including Enterprise trials)
@@ -372,7 +372,7 @@ Separately, the analysis engine (coana) needs the **per-ecosystem build toolchai
| Host | Used for | If blocked |
|---|---|---|
| `api.socket.dev` | Socket API calls, and a signed URL for the engine download | The CLI fails |
-| `storage.googleapis.com` | Downloading the engine and its analyzers (about 120 MB) | The CLI exits with code **3**: `Failed to run reachability analysis: HTTPSConnectionPool(host='storage.googleapis.com', ...)` |
+| `storage.googleapis.com` | Downloading the engine and its analyzers (about 120 MB) | The CLI reports an infrastructure error (`3` by default, subject to the exit-code flags): `Failed to run reachability analysis: HTTPSConnectionPool(host='storage.googleapis.com', ...)` |
| The package registry of each scanned ecosystem, for example `registry.npmjs.org` | Installing your project's dependencies for analysis | The scan still completes, but the affected vulnerabilities are reported as `INSTALL ERROR` with no reachability result |
The engine comes from Socket, not npm, so an npm mirror or registry proxy does not cover the engine download. The registry row does not apply when your dependencies are already installed in the target path, for example a `node_modules` directory from an earlier `npm ci`. The engine is cached as described below; with a warm cache, `storage.googleapis.com` is not contacted.
@@ -389,6 +389,13 @@ Socket's reachability analysis comes in three forms, referred to by their full n
## Config file support
+Values are validated after CLI overrides and before scan setup. Boolean options
+use native JSON/TOML booleans; integer options use integers, with `timeout` greater
+than zero. `files` accepts an array of nonempty file paths, or its JSON string
+representation. Invalid values and unreadable config files exit `2`, including
+with `--disable-blocking`. Runtime exit policy uses the configuration loaded at
+startup; changing or removing the file during a run does not change its exit code.
+
Use `--config ` to load defaults from a `.toml` or `.json` file.
CLI arguments always take precedence over config file values.
@@ -446,7 +453,7 @@ The CLI runs a pinned version of the Coana CLI, the analysis engine; it does **n
| `--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 |
-| `--timeout` | False | 1200 | Timeout in seconds for each API request. This is not a total CLI runtime limit and does not limit local discovery, Git, or reachability analysis. |
+| `--timeout` | False | 1200 | Positive integer timeout in seconds for each API request. This is not a total CLI runtime limit and does not limit local discovery, Git, or reachability analysis. |
#### Plugins
diff --git a/docs/development.md b/docs/development.md
index 9bab1ce7..d78d11af 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -40,6 +40,12 @@ Run tests:
make test
```
+This runs both the unit and core suites. To focus on the CLI exit-code contract:
+
+```bash
+uv run pytest tests/core/test_cli_exit_contract.py tests/core/test_exit_codes.py
+```
+
Run lint/format checks:
```bash
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index ea2454b4..706b0a41 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -4,7 +4,7 @@
| Symptom | What to check |
|---------|---------------|
-| Exit `2`, even with `--disable-blocking` | Fix the flags or configuration reported in the logs. Usage errors are never suppressed. |
+| Exit `2`, even with `--disable-blocking` | Fix the flags or configuration reported in the logs. Check config-file readability, native boolean/integer values, a positive timeout and the `files` array. Usage errors are never suppressed. |
| Exit `3` with no reported findings | Check tokens, scopes, baseline lookup and scan-completeness errors. This is a failed evaluation; `--exit-code-on-api-error` can remap its code. |
| Ctrl+C is treated as a configuration error | Update wrapper/CI rules: Ctrl+C changed from `2` to `130` in 2.13.0. |
| Exit `0` despite expected blockers | Check `--disable-blocking`, remapping to `0`, and whether the run produced a full scan instead of a diff. Full scans do not gate on findings. |
diff --git a/pytest.ini b/pytest.ini
index 69591c0b..9aa506b7 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -1,5 +1,5 @@
[pytest]
-testpaths = tests/unit
+testpaths = tests/unit tests/core
; addopts = -vv --no-cov --tb=short -ra
addopts = -vv --tb=short -ra --cov=socketsecurity --cov-report=term-missing
python_files = test_*.py
diff --git a/socketsecurity/config.py b/socketsecurity/config.py
index 96d906bc..a11ad252 100644
--- a/socketsecurity/config.py
+++ b/socketsecurity/config.py
@@ -75,17 +75,41 @@ def load_cli_config_file(config_path: str) -> dict:
_usage_error("--config must be a .json or .toml file")
except FileNotFoundError:
_usage_error(f"Config file not found: {config_path}")
- except (json.JSONDecodeError, tomllib.TOMLDecodeError) as e:
+ except (json.JSONDecodeError, tomllib.TOMLDecodeError, UnicodeDecodeError) as e:
_usage_error(f"Invalid config file format: {e}")
+ except OSError as e:
+ _usage_error(f"Unable to read config file {config_path}: {e}")
if not isinstance(data, dict):
_usage_error("Config file must contain a top-level object/table")
scoped = data.get("socketcli")
+ if "socketcli" in data and not isinstance(scoped, dict):
+ _usage_error("The socketcli config section must be an object/table")
if isinstance(scoped, dict):
return scoped
return data
+
+def parse_files(value) -> List[str]:
+ """Read CLI/config file lists before credentials or scan setup are evaluated."""
+ if isinstance(value, str):
+ encoded = value.strip()
+ if len(encoded) >= 2 and encoded[0] == encoded[-1] and encoded[0] in ("'", '"'):
+ inner = encoded[1:-1]
+ if inner.startswith("[") and inner.endswith("]"):
+ encoded = inner
+ try:
+ value = json.loads(encoded)
+ except json.JSONDecodeError:
+ try:
+ value = json.loads(encoded.replace("'", '"'))
+ except json.JSONDecodeError:
+ _usage_error("--files must be a JSON array of file paths")
+ if not isinstance(value, list) or any(not isinstance(path, str) or not path.strip() for path in value):
+ _usage_error("--files must be a JSON array of nonempty file paths")
+ return value
+
def normalize_exclude_paths(value) -> Optional[List[str]]:
"""Normalize a --exclude-paths value into a clean list of patterns.
@@ -238,6 +262,13 @@ def __post_init__(self):
@classmethod
def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
+ try:
+ return cls._from_args(args_list)
+ except (TypeError, ValueError, AttributeError) as error:
+ _usage_error(f"Invalid CLI configuration: {error}")
+
+ @classmethod
+ def _from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
parser = create_argument_parser()
pre_parser = argparse.ArgumentParser(add_help=False)
@@ -255,6 +286,23 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
parser.set_defaults(**normalized_defaults)
args = parser.parse_args(args_list)
+ # argparse validates explicit flags, but typed JSON/TOML defaults bypass
+ # some checks (notably booleans and choices). Validate effective values
+ # after CLI overrides, so a string "false" cannot enable nonblocking mode.
+ for action in parser._actions:
+ value = getattr(args, action.dest, None)
+ if value is None:
+ continue
+ option = action.option_strings[0] if action.option_strings else action.dest
+ if isinstance(action, (argparse._StoreTrueAction, argparse._StoreFalseAction)) and not isinstance(value, bool):
+ parser.error(f"{option} must be a boolean")
+ if action.type is int and (not isinstance(value, int) or isinstance(value, bool)):
+ parser.error(f"{option} must be an integer")
+ if action.choices is not None and value not in action.choices:
+ parser.error(f"{option}: invalid choice: {value!r}")
+ parse_files(args.files)
+ if args.timeout is not None and args.timeout <= 0:
+ parser.error("--timeout must be greater than zero")
integration_explicit = hasattr(args, "integration")
pr_number_explicit = hasattr(args, "pr_number")
@@ -418,6 +466,10 @@ def from_args(cls, args_list: Optional[List[str]] = None) -> 'CliConfig':
_usage_error(f"Unable to parse excluded_ecosystems: {excluded_ecosystems}")
else:
_usage_error(f"Unable to parse excluded_ecosystems: {excluded_ecosystems}")
+ if not isinstance(config_args["excluded_ecosystems"], list) or any(
+ not isinstance(ecosystem, str) for ecosystem in config_args["excluded_ecosystems"]
+ ):
+ _usage_error("--excluded-ecosystems must be an array of ecosystem names")
# Build Slack plugin config, merging CLI arg with env config
slack_config = get_plugin_config_from_env("SOCKET_SLACK")
if args.slack_webhook:
@@ -502,7 +554,9 @@ def to_dict(self) -> dict:
def create_argument_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="socketcli",
- description="The Socket Security CLI will get the head scan for the provided repo from Socket, create a new one, and then report any alerts introduced by the changes. Any new alerts will cause the CLI to exit with a non-Zero exit code (1 for error alerts, 5 for warnings)."
+ description="Scan dependencies and report security alerts. In diff mode, blocking findings exit 1; "
+ "warnings alone exit 0. Invalid flags or configuration exit 2, infrastructure "
+ "failures exit 3 by default, and Ctrl+C exits 130."
)
# Authentication
@@ -956,9 +1010,9 @@ def create_argument_parser() -> argparse.ArgumentParser:
dest="disable_blocking",
action="store_true",
help=(
- "Non-blocking CI mode: always exit 0, even when blocking alerts are present "
- "(including with --strict-blocking), on uncaught errors, or on Socket API failures. "
- "Findings and errors are still logged. Overrides --strict-blocking."
+ "Non-blocking CI mode: exit 0 for blocking findings (including with --strict-blocking), "
+ "setup/API/runtime failures and interrupts. Invalid flags or configuration still exit 2. "
+ "Findings and errors are still logged. Overrides --strict-blocking and --exit-code-on-api-error."
),
)
advanced_group.add_argument(
@@ -1022,7 +1076,7 @@ def create_argument_parser() -> argparse.ArgumentParser:
"--timeout",
type=int,
metavar="",
- help="Timeout in seconds for API requests",
+ help="Timeout in seconds for API requests (must be greater than zero)",
required=False
)
advanced_group.add_argument(
@@ -1033,10 +1087,12 @@ def create_argument_parser() -> argparse.ArgumentParser:
metavar="",
help=(
"Exit code to use when the CLI fails on an API or infrastructure error "
- "(timeout, network failure, unexpected exception). Default: 3. Useful for "
+ "(missing credentials, setup failure, incomplete scan data, timeout, network failure, "
+ "unexpected exception). Default: 3. Findings (1), usage errors (2) and Ctrl+C (130) "
+ "are unaffected. Useful for "
"distinguishing infrastructure failures from security findings (exit 1) in "
"CI -- e.g. set to a Buildkite soft_fail code. NOTE: --disable-blocking "
- "forces exit 0 for ALL outcomes and therefore overrides this flag; do not "
+ "overrides this flag but never suppresses usage errors; do not "
"combine the two if you want the custom code to take effect."
)
)
diff --git a/socketsecurity/core/__init__.py b/socketsecurity/core/__init__.py
index 1720a0fa..6f6b5986 100644
--- a/socketsecurity/core/__init__.py
+++ b/socketsecurity/core/__init__.py
@@ -1516,8 +1516,7 @@ def get_repo_info(self, repo_slug: str, default_branch: str = "socket-default-br
# This module logs through "socketdev" too, so a failed lookup must not leave it muted.
sdk_logger.setLevel(original_level)
if not response.success:
- log.error(f"Failed to get repository: {response.status}")
- # log.error(response.message)
+ raise APIFailure(response.message or "Repository lookup failed", status_code=response.status)
except APIFailure as lookup_error:
# Only a missing repository should be created. A token without the
# repo:list scope gets 401/403 here, and treating that as "doesn't
@@ -1527,6 +1526,10 @@ def get_repo_info(self, repo_slug: str, default_branch: str = "socket-default-br
f"Failed to get repository {repo_slug} (HTTP {lookup_error.status_code}). "
"The API token may be missing the repo:list scope."
) from lookup_error
+ if lookup_error.status_code != 404:
+ status = f" (HTTP {lookup_error.status_code})" if lookup_error.status_code else ""
+ reason = str(lookup_error).split("\n", 1)[0] or type(lookup_error).__name__
+ raise InfrastructureError(f"Failed to get repository {repo_slug}{status}: {reason}") from lookup_error
log.warning(f"Failed to get repository {repo_slug}, attempting to create it")
try:
@@ -1543,6 +1546,8 @@ def get_repo_info(self, repo_slug: str, default_branch: str = "socket-default-br
raise Exception("Failed to create repository: empty response")
else:
response = self.sdk.repos.repo(self.config.org_slug, repo_slug, use_types=True)
+ if not response.success:
+ raise APIFailure(response.message or "Repository lookup failed", status_code=response.status)
return response.data
except APIFailure as e:
@@ -2104,17 +2109,17 @@ def get_diff_scan_artifacts(
polls += 1
if response.get("status") != "processing":
scan = response.get("diff_scan") or {}
- if scan.get("artifacts") is None:
- raise Exception(
- f"Error fetching diff scan {diff_scan_id}: unexpected response: {str(response)[:500]}"
- )
- artifacts_dict = scan["artifacts"]
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:
+ raise Exception(
+ f"Error fetching diff scan {diff_scan_id}: unexpected response: {str(response)[:500]}"
+ )
+ artifacts_dict = scan["artifacts"]
log.info(
"Diff scan comparison ready in "
f"{time.monotonic() - poll_start:.2f}s: id={diff_scan_id}, "
diff --git a/socketsecurity/exit_codes.py b/socketsecurity/exit_codes.py
index 2be3d2a7..4901d017 100644
--- a/socketsecurity/exit_codes.py
+++ b/socketsecurity/exit_codes.py
@@ -1,10 +1,10 @@
"""Process exit codes, and the exceptions that map onto them.
-``socketcli.cli()`` is the only place that turns an outcome into an exit code,
-so ``--disable-blocking`` and ``--exit-code-on-api-error`` apply to every run
-that gets past argument parsing:
+``socketcli.cli()`` applies runtime failure policy using the configuration loaded
+at startup. Argument validation exits with ``EXIT_USAGE`` directly; successful
+reports and findings use OutputHandler, and SCM event filters may skip a run.
-* ``EXIT_OK`` (0): no blocking findings, or ``--disable-blocking`` is set.
+* ``EXIT_OK`` (0): successful report, skipped event, or ``--disable-blocking``.
* ``EXIT_BLOCKING`` (1): blocking security findings.
* ``EXIT_USAGE`` (2): invalid flags or configuration. The same code argparse uses
for its own usage errors. ``--disable-blocking`` does not apply, because a
diff --git a/socketsecurity/socketcli.py b/socketsecurity/socketcli.py
index 96b9d630..1a05a302 100644
--- a/socketsecurity/socketcli.py
+++ b/socketsecurity/socketcli.py
@@ -1,3 +1,4 @@
+import copy
import json
import os
import shutil
@@ -13,7 +14,7 @@
from socketdev.fullscans import FullScanParams
from socketsecurity import USER_AGENT_NAME
-from socketsecurity.config import CliConfig, truncate_commit_message
+from socketsecurity.config import CliConfig, parse_files, truncate_commit_message
from socketsecurity.core import Core
from socketsecurity.core.classes import Diff
from socketsecurity.core.cli_client import CliClient
@@ -32,7 +33,6 @@
from socketsecurity.exit_codes import (
EXIT_INTERRUPTED,
EXIT_OK,
- EXIT_USAGE,
InfrastructureError,
)
from socketsecurity.fossa_compat import build_fossa_attribution_payload
@@ -259,35 +259,40 @@ def build_socket_sdk(config: CliConfig) -> socketdev:
def cli():
+ config = CliConfig.from_args()
+ # main_code adds repository context and can temporarily disable findings for
+ # a full scan. Runtime failures must retain the user's original exit policy.
+ exit_config = copy.copy(config)
try:
- main_code()
+ main_code(config)
except KeyboardInterrupt:
log.info("Keyboard Interrupt detected, exiting")
- config = CliConfig.from_args()
- sys.exit(EXIT_OK if config.disable_blocking else EXIT_INTERRUPTED)
+ sys.exit(EXIT_OK if exit_config.disable_blocking else EXIT_INTERRUPTED)
except InfrastructureError as error:
- _exit_for_infrastructure_error(str(error), include_traceback=False)
+ _exit_for_infrastructure_error(str(error), include_traceback=False, config=exit_config)
except Exception as error:
_exit_for_infrastructure_error(
f"Unexpected error when running the CLI: {error}",
include_traceback=True,
+ config=exit_config,
)
-def _exit_for_infrastructure_error(message: str, include_traceback: bool) -> NoReturn:
+def _exit_for_infrastructure_error(message: str, include_traceback: bool, config: CliConfig) -> NoReturn:
"""Exit for a failure that is not a security finding.
--disable-blocking takes precedence and exits 0. Otherwise the code is
--exit-code-on-api-error (default 3), which keeps these failures distinct
from blocking findings (1) and usage errors (2). See socketsecurity.exit_codes.
"""
- config = CliConfig.from_args()
_emit_infrastructure_error(message, include_traceback=include_traceback)
sys.exit(EXIT_OK if config.disable_blocking else config.exit_code_on_api_error)
-def main_code():
- config = CliConfig.from_args()
+def main_code(config: Optional[CliConfig] = None):
+ config = config if config is not None else CliConfig.from_args()
+ specified_files = parse_files(config.files)
+ files_explicitly_specified = bool(specified_files)
log.info(f"Starting Socket Security CLI version {config.version}")
log.debug(f"config: {config.to_dict()}")
@@ -400,43 +405,6 @@ def main_code():
"Unable to retrieve organization information for plan verification."
)
- # Parse files argument
- try:
- if isinstance(config.files, list):
- # Already a list, use as-is
- specified_files = config.files
- elif isinstance(config.files, str):
- # Handle different string formats
- files_str = config.files.strip()
-
- # If the string is wrapped in extra quotes, strip them
- if ((files_str.startswith('"') and files_str.endswith('"')) or
- (files_str.startswith("'") and files_str.endswith("'"))):
- # Check if the inner content looks like JSON
- inner_str = files_str[1:-1]
- if inner_str.startswith('[') and inner_str.endswith(']'):
- files_str = inner_str
-
- # Try to parse as JSON
- try:
- specified_files = json.loads(files_str)
- except json.JSONDecodeError:
- # If JSON parsing fails, try replacing single quotes with double quotes
- files_str = files_str.replace("'", '"')
- specified_files = json.loads(files_str)
- else:
- # Default to empty list
- specified_files = []
- except Exception as error:
- log.error(f"Unable to parse files argument: {config.files}")
- log.error(f"Error details: {error}")
- log.debug(f"Files type: {type(config.files)}")
- log.debug(f"Files repr: {repr(config.files)}")
- sys.exit(EXIT_USAGE)
-
- # Determine if files were explicitly specified
- files_explicitly_specified = config.files != "[]" and len(specified_files) > 0
-
# Variable to track if we need to override files with facts file
facts_file_to_submit = None
# Variable to track SBOM files to submit when using --reach-use-only-pregenerated-sboms
diff --git a/tests/core/test_cli_exit_contract.py b/tests/core/test_cli_exit_contract.py
new file mode 100644
index 00000000..d3988f91
--- /dev/null
+++ b/tests/core/test_cli_exit_contract.py
@@ -0,0 +1,288 @@
+"""Exercise the public exit contract through argument parsing and the CLI flow."""
+
+import json
+import os
+import signal
+import subprocess
+import sys
+from contextlib import nullcontext
+from types import SimpleNamespace
+from unittest.mock import MagicMock, Mock
+
+import pytest
+
+from socketsecurity import socketcli
+from socketsecurity.config import CliConfig, create_argument_parser, parse_files
+from socketsecurity.core import Core
+from socketsecurity.core.classes import Diff, Issue, Package
+from socketsecurity.exit_codes import InfrastructureError
+
+POLICIES = [
+ pytest.param([], 3, id="default"),
+ pytest.param(["--exit-code-on-api-error", "100"], 100, id="remap"),
+ pytest.param(["--exit-code-on-api-error", "0"], 0, id="remap-zero"),
+ pytest.param(["--disable-blocking"], 0, id="nonblocking"),
+ pytest.param(["--disable-blocking", "--exit-code-on-api-error", "100"], 0, id="both"),
+]
+TOKEN_VARS = (
+ "SOCKET_SECURITY_API_KEY", "SOCKET_SECURITY_API_TOKEN", "SOCKET_API_KEY", "SOCKET_API_TOKEN",
+ "GH_API_TOKEN", "GITLAB_TOKEN",
+)
+
+
+@pytest.fixture
+def cli_runtime(monkeypatch):
+ for name in TOKEN_VARS:
+ monkeypatch.delenv(name, raising=False)
+ sdk = MagicMock()
+ sdk.org.get.return_value = {"organizations": {"org-id": {"slug": "acme", "plan": "enterprise"}}}
+ monkeypatch.setattr(socketcli, "build_socket_sdk", Mock(return_value=sdk))
+ monkeypatch.setattr(socketcli, "CliClient", Mock())
+ monkeypatch.setattr(socketcli, "StreamingLogs", lambda **kwargs: nullcontext(Mock()))
+ monkeypatch.setattr(socketcli, "apply_git_context", lambda config: (False, None))
+ monkeypatch.setattr(Core, "has_manifest_files", Mock(return_value=True))
+ monkeypatch.setattr(Core, "find_files", Mock(return_value=[]))
+ diff = Diff(id="scan")
+ scan = Mock(return_value=diff)
+ monkeypatch.setattr(Core, "create_new_diff", scan)
+ monkeypatch.setattr(socketcli.OutputHandler, "handle_output", Mock())
+ monkeypatch.setattr(socketcli.shutil, "which", lambda dep: f"/bin/{dep}")
+
+ def run(flags=(), *, token=True):
+ argv = ["socketcli", "--enable-diff", "--repo", "repo", "--branch", "feature"]
+ if token:
+ argv += ["--api-token", "test"]
+ monkeypatch.setattr(sys, "argv", [*argv, *flags])
+ with pytest.raises(SystemExit) as result:
+ socketcli.cli()
+ return result.value.code
+
+ return SimpleNamespace(sdk=sdk, scan=scan, diff=diff, run=run)
+
+
+@pytest.mark.parametrize("policy, infrastructure_code", POLICIES)
+@pytest.mark.parametrize("stage", [
+ "socket-token", "github-token", "gitlab-token", "reach-dependency", "reach-plan", "reach-org",
+])
+def test_setup_failures_follow_exit_policy(cli_runtime, monkeypatch, policy, infrastructure_code, stage):
+ flags = list(policy)
+ if stage.endswith("-token") and stage != "socket-token":
+ flags += ["--scm", stage.removesuffix("-token")]
+ elif stage.startswith("reach-"):
+ flags += ["--reach"]
+ if stage == "reach-dependency":
+ monkeypatch.setattr(socketcli.shutil, "which", lambda dep: None)
+ elif stage == "reach-plan":
+ cli_runtime.sdk.org.get.return_value["organizations"]["org-id"]["plan"] = "free"
+ elif stage == "reach-org":
+ cli_runtime.sdk.org.get.return_value = {"organizations": {}}
+
+ assert cli_runtime.run(flags, token=stage != "socket-token") == infrastructure_code
+ cli_runtime.scan.assert_not_called()
+
+
+@pytest.mark.parametrize("policy, infrastructure_code", POLICIES)
+@pytest.mark.parametrize("outcome, expected", [
+ ("clean", 0), ("warning", 0), ("new-blocker", 1), ("existing-blocker", 0),
+ ("strict-existing-blocker", 1), ("infrastructure", 3), ("interrupt", 130),
+])
+def test_scan_outcomes_follow_exit_policy(cli_runtime, policy, infrastructure_code, outcome, expected):
+ flags = list(policy)
+ if outcome in ("new-blocker", "warning"):
+ cli_runtime.diff.new_alerts = [Issue(error=outcome == "new-blocker", warn=outcome == "warning")]
+ elif outcome.endswith("existing-blocker"):
+ cli_runtime.diff.unchanged_alerts = [Issue(error=True)]
+ if outcome.startswith("strict-"):
+ flags.append("--strict-blocking")
+ elif outcome == "infrastructure":
+ cli_runtime.scan.side_effect = RuntimeError("unexpected scan failure")
+ expected = infrastructure_code
+ elif outcome == "interrupt":
+ cli_runtime.scan.side_effect = KeyboardInterrupt()
+ if "--disable-blocking" in policy:
+ expected = 0
+
+ assert cli_runtime.run(flags) == expected
+ cli_runtime.scan.assert_called_once()
+
+
+@pytest.mark.parametrize("policy, infrastructure_code", POLICIES)
+@pytest.mark.parametrize("flags", [
+ ["--files", "not-json"], ["--files", "null"], ["--files", "{}"],
+ ["--files", "[1]"], ["--timeout", "0"], ["--timeout", "-1"],
+])
+def test_usage_errors_fail_before_setup(cli_runtime, policy, infrastructure_code, flags):
+ # Missing credentials must not hide invalid input, even in nonblocking mode.
+ assert cli_runtime.run([*policy, *flags], token=False) == 2
+ socketcli.build_socket_sdk.assert_not_called()
+
+
+@pytest.mark.parametrize("setting", [
+ {"strict_blocking": "false"}, {"timeout": 0}, {"timeout": 1.5},
+ {"sarif_scope": "invalid"}, {"target_path": 123}, {"socketcli": []},
+])
+def test_invalid_config_file_is_a_usage_error(tmp_path, setting):
+ path = tmp_path / "socketcli.json"
+ path.write_text(json.dumps(setting))
+ with pytest.raises(SystemExit) as result:
+ CliConfig.from_args(["--config", str(path), "--disable-blocking"])
+ assert result.value.code == 2
+
+
+def test_config_cannot_enable_nonblocking_mode_with_a_string(tmp_path):
+ path = tmp_path / "socketcli.json"
+ path.write_text(json.dumps({"disable_blocking": "false"}))
+
+ with pytest.raises(SystemExit) as result:
+ CliConfig.from_args(["--config", str(path)])
+
+ assert result.value.code == 2
+
+
+def test_cli_overrides_invalid_config_defaults_before_validation(tmp_path):
+ path = tmp_path / "socketcli.json"
+ path.write_text(json.dumps({"strict_blocking": "false", "timeout": 0, "sarif_scope": "invalid"}))
+
+ config = CliConfig.from_args([
+ "--config", str(path), "--strict-blocking", "--timeout", "30", "--sarif-scope", "diff",
+ ])
+
+ assert config.strict_blocking is True
+ assert config.timeout == 30
+ assert config.sarif_scope == "diff"
+
+
+@pytest.mark.parametrize("config_kind", ["directory", "invalid-utf8"])
+def test_unreadable_config_is_a_usage_error(tmp_path, config_kind):
+ path = tmp_path / "socketcli.json"
+ if config_kind == "directory":
+ path.mkdir()
+ else:
+ path.write_bytes(b"\xff")
+
+ with pytest.raises(SystemExit) as result:
+ CliConfig.from_args(["--config", str(path), "--disable-blocking"])
+
+ assert result.value.code == 2
+
+
+@pytest.mark.parametrize("files", [
+ '["package.json"]', "['package.json']", "'[\"package.json\"]'", ["package.json"],
+])
+def test_supported_file_list_formats_are_preserved(files):
+ assert parse_files(files) == ["package.json"]
+
+
+def test_help_describes_the_current_exit_contract():
+ help_text = " ".join(create_argument_parser().format_help().split())
+
+ assert "warnings alone exit 0" in help_text
+ assert "Invalid flags or configuration still exit 2" in help_text
+ assert "Ctrl+C (130) are unaffected" in help_text
+ assert "5 for warnings" not in help_text
+
+
+@pytest.mark.parametrize("policy, infrastructure_code", POLICIES)
+def test_exit_policy_survives_config_file_removal(
+ cli_runtime, tmp_path, policy, infrastructure_code
+):
+ path = tmp_path / "socketcli.json"
+ path.write_text("{}")
+
+ def fail_after_config_cleanup(*args, **kwargs):
+ path.unlink()
+ raise InfrastructureError("scan comparison failed")
+
+ cli_runtime.scan.side_effect = fail_after_config_cleanup
+
+ assert cli_runtime.run([*policy, "--config", str(path)]) == infrastructure_code
+
+
+@pytest.mark.parametrize("policy, infrastructure_code", POLICIES)
+def test_temporary_findings_override_does_not_change_error_policy(
+ cli_runtime, monkeypatch, policy, infrastructure_code
+):
+ def fail_after_findings_override(handler, diff):
+ handler.config.disable_blocking = True
+ raise InfrastructureError("commit status failed")
+
+ monkeypatch.setattr(socketcli.OutputHandler, "handle_output", fail_after_findings_override)
+
+ assert cli_runtime.run(policy) == infrastructure_code
+
+
+@pytest.mark.parametrize("policy, infrastructure_code", POLICIES)
+def test_missing_existing_alert_data_reaches_cli_exit_policy(cli_runtime, policy, infrastructure_code):
+ package = Package(id="pkg", type="npm", name="pkg", version="1", score={}, alerts=[])
+ cli_runtime.sdk.fullscans.stream.return_value = SimpleNamespace(success=True, artifacts={})
+ # Run the real hydration step from the scan boundary without making any network request.
+ def compare(*args, **kwargs):
+ core = Core.__new__(Core)
+ core.sdk = cli_runtime.sdk
+ core.config = SimpleNamespace(org_slug="acme")
+ core.add_existing_alerts_from_full_scan({package.id: package}, "new")
+
+ cli_runtime.scan.side_effect = compare
+
+ assert cli_runtime.run([*policy, "--strict-blocking"]) == infrastructure_code
+
+
+@pytest.mark.parametrize("policy, infrastructure_code", POLICIES)
+def test_real_sigint_uses_documented_exit_status(policy, infrastructure_code):
+ script = """
+import time
+from socketsecurity import socketcli
+def wait_for_interrupt(config=None):
+ print("READY", flush=True)
+ time.sleep(30)
+socketcli.main_code = wait_for_interrupt
+socketcli.cli()
+"""
+ env = {key: value for key, value in os.environ.items() if key not in TOKEN_VARS}
+ with subprocess.Popen(
+ [sys.executable, "-c", script, "--api-token", "test", *policy],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, env=env,
+ ) as process:
+ try:
+ assert process.stdout.readline().strip() == "READY"
+ process.send_signal(signal.SIGINT)
+ _, stderr = process.communicate(timeout=10)
+ assert process.returncode == (0 if "--disable-blocking" in policy else 130), stderr
+ finally:
+ if process.poll() is None:
+ process.kill()
+ process.communicate()
+
+
+@pytest.mark.parametrize("output_flag", [[], ["--enable-json"], ["--enable-sarif"], ["--enable-gitlab-security"]])
+@pytest.mark.parametrize("strict", [False, True])
+def test_branch_full_scan_does_not_gate_on_findings(cli_runtime, monkeypatch, output_flag, strict):
+ monkeypatch.setenv("GH_API_TOKEN", "test")
+ monkeypatch.setenv("GITHUB_EVENT_NAME", "push")
+ monkeypatch.setenv("GITHUB_REPOSITORY", "acme/repo")
+ monkeypatch.setenv("BUILDKITE", "false")
+ monkeypatch.delenv("PR_NUMBER", raising=False)
+ full_scan = Mock(return_value=Diff(id="full", new_alerts=[Issue(error=True)]))
+ monkeypatch.setattr(Core, "create_full_scan_with_report_url", full_scan)
+ flags = ["--scm", "github", "--pr-number", "0", *output_flag]
+ if strict:
+ flags.append("--strict-blocking")
+
+ assert cli_runtime.run(flags) == 0
+ full_scan.assert_called_once()
+ cli_runtime.scan.assert_not_called()
+
+
+@pytest.mark.parametrize("scm, event, action", [
+ ("github", "pull_request", "closed"), ("github", "unsupported", ""),
+ ("gitlab", "unsupported", ""),
+])
+def test_scm_event_filters_skip_without_scanning(cli_runtime, monkeypatch, scm, event, action):
+ monkeypatch.setenv("GH_API_TOKEN", "test")
+ monkeypatch.setenv("GITLAB_TOKEN", "test")
+ monkeypatch.setenv("GITHUB_EVENT_NAME", event)
+ monkeypatch.setenv("EVENT_ACTION", action)
+ monkeypatch.setenv("CI_PIPELINE_SOURCE", event)
+
+ assert cli_runtime.run(["--scm", scm]) == 0
+ cli_runtime.scan.assert_not_called()
diff --git a/tests/core/test_exit_codes.py b/tests/core/test_exit_codes.py
index f9713b3e..9ecda02c 100644
--- a/tests/core/test_exit_codes.py
+++ b/tests/core/test_exit_codes.py
@@ -23,7 +23,7 @@
def _run_cli(monkeypatch, argv, error):
- def fail_main_code():
+ def fail_main_code(config=None):
raise error
monkeypatch.setattr(socketcli, "main_code", fail_main_code)
@@ -103,6 +103,20 @@ def test_repo_lookup_permission_error_does_not_try_to_create(core):
core.sdk.repos.post.assert_not_called()
+@pytest.mark.parametrize("status", [401, 403, 429, 500, 503])
+@pytest.mark.parametrize("response_kind", ["exception", "response"])
+def test_repo_lookup_only_creates_for_not_found(core, status, response_kind):
+ if response_kind == "exception":
+ core.sdk.repos.repo.side_effect = APIFailure("lookup failed", status_code=status)
+ else:
+ core.sdk.repos.repo.return_value = MagicMock(success=False, status=status, message="lookup failed")
+
+ with pytest.raises(InfrastructureError, match=f"HTTP {status}"):
+ core.get_repo_info("my-repo")
+
+ core.sdk.repos.post.assert_not_called()
+
+
def test_repo_lookup_not_found_creates_the_repository(core):
created = MagicMock(data="repo-info")
core.sdk.repos.repo.side_effect = [APIResourceNotFound(status_code=404), created]
@@ -123,9 +137,12 @@ def test_repo_creation_failure_raises_infrastructure_error(core):
# --- Incomplete comparisons ----------------------------------------------------------
-@pytest.fixture
-def incomplete_response():
- return {"diff_scan": {"id": "diff-scan-1", "incomplete": True, "artifacts": {}}}
+@pytest.fixture(params=[{}, None, "omitted"])
+def incomplete_response(request):
+ scan = {"id": "diff-scan-1", "incomplete": True}
+ if request.param != "omitted":
+ scan["artifacts"] = request.param
+ return {"diff_scan": scan}
def test_incomplete_comparison_raises(core, incomplete_response):
diff --git a/tests/unit/test_socketcli.py b/tests/unit/test_socketcli.py
index 1f298e0c..6fea85a1 100644
--- a/tests/unit/test_socketcli.py
+++ b/tests/unit/test_socketcli.py
@@ -20,7 +20,7 @@
def _run_cli_expecting_exit(monkeypatch, argv, boom=None):
- def fail_main_code():
+ def fail_main_code(config=None):
raise (boom or RuntimeError("infra boom"))
monkeypatch.setattr(socketcli, "main_code", fail_main_code)
|