Skip to content

Commit bc5b3b7

Browse files
leliaclaude
andcommitted
feat(enums): make every API-sourced enum forward-compatible
Five of the six enums populated from API responses coerced strictly, so a value the backend added would raise ValueError inside from_dict and empty an entire response rather than degrade one field. That is the mechanism behind issue #78 and the unknown `generic` purl type; each was fixed on the single enum that fired, leaving the rest holding the same landmine. All five now fall back to a documented member and log the unrecognized value. The fallbacks are chosen rather than convenient: SocketIssueSeverity and DiffType gain an explicit UNKNOWN, since guessing an existing level would either hide a real finding or invent one, and SecurityAction defers. A generalized test discovers every enum in the package, including ones added later, and fails if any raises. A drift check compares the enums against the public OpenAPI spec; it found 10 purl types the SDK was missing, which are added here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent e3a80b8 commit bc5b3b7

8 files changed

Lines changed: 407 additions & 20 deletions

File tree

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: API Drift Check
2+
3+
# Compares this SDK's hand-maintained enums against the live Socket OpenAPI
4+
# spec. The spec is public and unauthenticated, so this job needs no secrets,
5+
# no org and no fixture data.
6+
#
7+
# Deliberately NOT a pull_request trigger: it tests the API, not the diff, and a
8+
# backend change must never block an unrelated SDK pull request.
9+
#
10+
# TODO: once this has run green manually a few times, uncomment the schedule
11+
# below to turn it into an early-warning signal instead of a manual check.
12+
on:
13+
workflow_dispatch:
14+
# schedule:
15+
# - cron: '0 14 * * 1' # Mondays, 14:00 UTC
16+
17+
permissions:
18+
contents: read
19+
20+
jobs:
21+
enum-drift:
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
25+
with:
26+
fetch-depth: 1
27+
persist-credentials: false
28+
29+
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
30+
with:
31+
python-version: "3.12"
32+
33+
- name: Install the SDK
34+
run: python -m pip install .
35+
36+
- name: Compare SDK enums against the live OpenAPI spec
37+
run: python scripts/check_api_enum_drift.py

‎CHANGELOG.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,40 @@
11
# Changelog
22

3+
## 3.6.0
4+
5+
### Changed: every API-sourced enum now tolerates unknown values
6+
7+
- `SocketIssueSeverity`, `SocketCategory`, `DiffType`, `ScanType` and
8+
`SecurityAction` now fall back to a documented member instead of raising
9+
`ValueError` when the API sends a value this release does not know about.
10+
`SocketPURL_Type` already behaved this way; the other five did not, so each
11+
was one backend addition away from emptying a response the same way issue #78
12+
and the unknown `generic` purl type did.
13+
- Fallbacks are deliberate rather than convenient. `SocketIssueSeverity` and
14+
`DiffType` gained an explicit `UNKNOWN` member because guessing an existing
15+
level would either hide a real finding or invent one, and `SecurityAction`
16+
falls back to `DEFER` because that already means "use the configured
17+
default". Every fallback logs a warning naming the unrecognized value.
18+
- Added the 10 purl types the API defines that this SDK was missing: `alpm`,
19+
`chrome`, `clawhub`, `edge-extension`, `firefox-extension`, `qpkg`, `socket`,
20+
`swid`, `vscode` and `vscode-extension`. Artifacts with those types were
21+
being flattened to `unknown`.
22+
23+
### Added: enum forward-compatibility is now an enforced invariant
24+
25+
- `tests/unit/test_enum_forward_compat.py` discovers every enum in the package,
26+
including ones added later, and fails if any raises on an unrecognized value.
27+
The two prior incidents were each fixed with a bespoke test on the single
28+
enum that happened to fire; this replaces that pattern.
29+
30+
### Added: scheduled check for enum drift against the live API
31+
32+
- `scripts/check_api_enum_drift.py` compares the SDK's enums against
33+
`https://api.socket.dev/v0/openapi`. The spec is public, so the check needs no
34+
token, org or fixture data. Run by `.github/workflows/api-drift-check.yml`,
35+
which is manual-dispatch only for now and is not a pull request check --- it
36+
tests the API rather than the diff.
37+
338
## 3.5.0
439

540
### Changed: bound runtime dependency ranges and pin build backend

‎scripts/check_api_enum_drift.py‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
#!/usr/bin/env python3
2+
"""Compare this SDK's enums against the live Socket OpenAPI specification.
3+
4+
The SDK's enums are hand-maintained copies of value sets the API owns, and
5+
nothing has ever told us when the API adds to one. Both prior incidents were
6+
both found by a customer, after the fact, via an empty report.
7+
8+
The spec at ``https://api.socket.dev/v0/openapi`` is public and unauthenticated,
9+
so this needs no token, no org and no fixture data -- it is a plain GET plus a
10+
set comparison. It catches schema drift only; it deliberately says nothing about
11+
runtime behaviour, response shapes or auth, which need the authenticated
12+
integration checks.
13+
14+
Exit codes:
15+
0 no missing values (extras and unmapped enums are reported, not fatal)
16+
1 the API defines values this SDK does not know about
17+
2 the spec could not be fetched or parsed
18+
"""
19+
20+
import argparse
21+
import json
22+
import sys
23+
import urllib.error
24+
import urllib.request
25+
26+
from socketdev.fullscans import (
27+
DiffType,
28+
ScanType,
29+
SocketCategory,
30+
SocketIssueSeverity,
31+
SocketPURL_Type,
32+
)
33+
from socketdev.settings import SecurityAction
34+
35+
DEFAULT_SPEC_URL = "https://api.socket.dev/v0/openapi"
36+
37+
# SDK enum -> the schema in components/schemas that defines the same value set.
38+
# None means the API does not expose the value set as a named schema, so this
39+
# check cannot cover it; those are reported so the gap stays visible rather than
40+
# looking like a pass.
41+
ENUM_TO_SCHEMA = {
42+
SocketPURL_Type: "SocketPURL_Type",
43+
SocketIssueSeverity: "SocketIssueSeverity",
44+
SocketCategory: "SocketCategory",
45+
DiffType: "SocketDiffArtifactType",
46+
ScanType: None,
47+
SecurityAction: None,
48+
}
49+
50+
# Members this SDK adds deliberately, which the API will never send. They are
51+
# the documented _missing_ fallbacks (see socketdev/core/enums.py), so their
52+
# absence from the spec is expected rather than drift.
53+
SDK_ONLY_VALUES = {
54+
"SocketPURL_Type": {"unknown"},
55+
"SocketIssueSeverity": {"unknown"},
56+
"SocketCategory": {"miscellaneous"},
57+
"DiffType": {"unknown"},
58+
}
59+
60+
61+
def fetch_spec(url):
62+
with urllib.request.urlopen(url, timeout=60) as response:
63+
if response.status != 200:
64+
raise RuntimeError(f"{url} returned HTTP {response.status}")
65+
return json.load(response)
66+
67+
68+
def main():
69+
parser = argparse.ArgumentParser(description=__doc__)
70+
parser.add_argument("--spec-url", default=DEFAULT_SPEC_URL)
71+
args = parser.parse_args()
72+
73+
try:
74+
spec = fetch_spec(args.spec_url)
75+
schemas = spec["components"]["schemas"]
76+
except (urllib.error.URLError, KeyError, ValueError, RuntimeError) as exc:
77+
print(f"::error::could not read the OpenAPI spec: {exc}")
78+
return 2
79+
80+
drifted = False
81+
unmapped = []
82+
83+
for enum_cls, schema_name in ENUM_TO_SCHEMA.items():
84+
if schema_name is None:
85+
unmapped.append(enum_cls.__name__)
86+
continue
87+
schema = schemas.get(schema_name)
88+
if not schema or "enum" not in schema:
89+
print(
90+
f"::warning::schema {schema_name!r} for {enum_cls.__name__} is gone "
91+
f"or no longer an enum -- the API may have restructured it"
92+
)
93+
continue
94+
95+
api_values = set(schema["enum"])
96+
sdk_values = {member.value for member in enum_cls}
97+
sdk_only = SDK_ONLY_VALUES.get(enum_cls.__name__, set())
98+
99+
missing = sorted(api_values - sdk_values)
100+
extra = sorted(sdk_values - api_values - sdk_only)
101+
102+
if missing:
103+
drifted = True
104+
print(
105+
f"::error::{enum_cls.__name__} is missing {len(missing)} value(s) "
106+
f"the API defines: {', '.join(missing)}"
107+
)
108+
if extra:
109+
# Not fatal: the spec omitting a value the SDK accepts is usually a
110+
# spec gap, and dropping a member would be a breaking change.
111+
print(
112+
f"::warning::{enum_cls.__name__} defines {len(extra)} value(s) "
113+
f"absent from the spec: {', '.join(extra)}"
114+
)
115+
if not missing and not extra:
116+
print(f"ok: {enum_cls.__name__} matches {schema_name} "
117+
f"({len(api_values)} values)")
118+
119+
if unmapped:
120+
print(
121+
f"::warning::not covered by this check, because the API exposes no "
122+
f"named schema for them: {', '.join(sorted(unmapped))}"
123+
)
124+
125+
if drifted:
126+
print(
127+
"\nAdd the missing members to the SDK enum. Existing values are "
128+
"still parsed correctly in the meantime -- _missing_ maps unknown "
129+
"values to a fallback -- so this is a loss of fidelity, not an "
130+
"outage."
131+
)
132+
return 1
133+
134+
print("\nno missing enum values")
135+
return 0
136+
137+
138+
if __name__ == "__main__":
139+
sys.exit(main())

‎socketdev/core/enums.py‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
"""Forward-compatibility helpers for enums sourced from the Socket API.
2+
3+
The Socket API adds values to its enums (purl types, alert categories, policy
4+
actions) without a corresponding SDK release. When a strict ``Enum`` coercion
5+
meets one of those values it raises ``ValueError``, and because coercion happens
6+
inside ``from_dict`` that error takes down the whole response parse rather than
7+
the single field it applies to. That is how issue #78 (an unknown
8+
``SocketCategory``) and the unknown ``generic`` purl type each produced
9+
empty reports from otherwise-successful scans.
10+
11+
Every enum in this package that is populated from an API response therefore
12+
defines ``_missing_`` and falls back to a documented sentinel instead of
13+
raising. ``tests/unit/test_enum_forward_compat.py`` enforces that as an
14+
invariant across the package, including for enums added later.
15+
"""
16+
17+
import logging
18+
19+
log = logging.getLogger("socketdev")
20+
21+
22+
def unknown_enum_value(enum_name: str, value: object, fallback):
23+
"""Log an unrecognized API enum value and return the enum's fallback member.
24+
25+
Callers are ``_missing_`` implementations, so returning ``fallback`` is what
26+
turns the would-be ``ValueError`` into a usable member.
27+
"""
28+
log.warning(
29+
"Unknown %s %r; falling back to %s. "
30+
"Upgrade socketdev to pick up newer values.",
31+
enum_name,
32+
value,
33+
fallback.name,
34+
)
35+
return fallback

‎socketdev/fullscans/__init__.py‎

Lines changed: 40 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,29 @@
55
from dataclasses import dataclass, asdict, field
66
import urllib.parse
77
from ..core.dedupe import Dedupe
8+
from ..core.enums import unknown_enum_value
89
from ..utils import IntegrationType, Utils
910

1011
log = logging.getLogger("socketdev")
1112

1213

1314
class SocketPURL_Type(str, Enum):
1415
UNKNOWN = "unknown"
16+
ALPM = "alpm"
1517
APK = "apk"
1618
BITBUCKET = "bitbucket"
1719
CARGO = "cargo"
20+
CHROME = "chrome"
21+
CLAWHUB = "clawhub"
1822
COCOAPODS = "cocoapods"
1923
COMPOSER = "composer"
2024
CONAN = "conan"
2125
CONDA = "conda"
2226
CRAN = "cran"
2327
DEB = "deb"
2428
DOCKER = "docker"
29+
EDGE_EXTENSION = "edge-extension"
30+
FIREFOX_EXTENSION = "firefox-extension"
2531
GEM = "gem"
2632
GENERIC = "generic"
2733
GITHUB = "github"
@@ -37,28 +43,33 @@ class SocketPURL_Type(str, Enum):
3743
OCI = "oci"
3844
PUB = "pub"
3945
PYPI = "pypi"
46+
QPKG = "qpkg"
4047
RPM = "rpm"
48+
SOCKET = "socket"
49+
SWID = "swid"
4150
SWIFT = "swift"
51+
VSCODE = "vscode"
52+
VSCODE_EXTENSION = "vscode-extension"
4253

4354
@classmethod
4455
def _missing_(cls, value):
45-
# The API can emit purl types this SDK does not know about yet. Fall
46-
# back to UNKNOWN instead of raising so one artifact cannot fail an
47-
# entire response parse (same forward-compat approach as
48-
# SocketCategory, https://github.com/SocketDev/socket-sdk-python/issues/78).
49-
log.warning(
50-
"Unknown SocketPURL_Type %r; falling back to UNKNOWN. "
51-
"Upgrade socketdev to pick up newer purl types.",
52-
value,
53-
)
54-
return cls.UNKNOWN
56+
return unknown_enum_value(cls.__name__, value, cls.UNKNOWN)
5557

5658

5759
class SocketIssueSeverity(str, Enum):
5860
LOW = "low"
5961
MIDDLE = "middle"
6062
HIGH = "high"
6163
CRITICAL = "critical"
64+
# Sentinel for severities the API adds later. Deliberately not an existing
65+
# level: falling back to LOW would hide a serious finding and CRITICAL
66+
# would manufacture one, so consumers get an explicit "not understood"
67+
# value to branch on instead of a guess.
68+
UNKNOWN = "unknown"
69+
70+
@classmethod
71+
def _missing_(cls, value):
72+
return unknown_enum_value(cls.__name__, value, cls.UNKNOWN)
6273

6374

6475
class SocketCategory(str, Enum):
@@ -70,19 +81,35 @@ class SocketCategory(str, Enum):
7081
MISCELLANEOUS = "miscellaneous"
7182
OTHER = "other" # Added to match backend API responses
7283

84+
@classmethod
85+
def _missing_(cls, value):
86+
return unknown_enum_value(cls.__name__, value, cls.MISCELLANEOUS)
87+
7388

7489
class DiffType(str, Enum):
7590
ADDED = "added"
7691
REMOVED = "removed"
7792
UNCHANGED = "unchanged"
7893
REPLACED = "replaced"
7994
UPDATED = "updated"
95+
# Not UNCHANGED: treating an unrecognized change as "nothing happened"
96+
# would drop a real diff entry out of a comparison silently.
97+
UNKNOWN = "unknown"
98+
99+
@classmethod
100+
def _missing_(cls, value):
101+
return unknown_enum_value(cls.__name__, value, cls.UNKNOWN)
80102

81103

82104
class ScanType(str, Enum):
83105
SOCKET = "socket"
84106
SOCKET_TIER1 = "socket_tier1"
85107
SOCKET_BASICS = "socket_basics"
108+
UNKNOWN = "unknown"
109+
110+
@classmethod
111+
def _missing_(cls, value):
112+
return unknown_enum_value(cls.__name__, value, cls.UNKNOWN)
86113

87114

88115
@dataclass(kw_only=True)
@@ -481,15 +508,9 @@ def to_dict(self):
481508

482509
@classmethod
483510
def from_dict(cls, data: dict) -> "SocketAlert":
484-
try:
485-
category = SocketCategory(data["category"])
486-
except ValueError:
487-
log.warning(
488-
"Unknown SocketCategory %r; falling back to MISCELLANEOUS. "
489-
"Upgrade socketdev to pick up newer categories.",
490-
data["category"],
491-
)
492-
category = SocketCategory.MISCELLANEOUS
511+
# SocketCategory._missing_ handles unrecognized values; see
512+
# socketdev/core/enums.py.
513+
category = SocketCategory(data["category"])
493514
return cls(
494515
key=data["key"],
495516
type=data["type"],

0 commit comments

Comments
 (0)