|
| 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()) |
0 commit comments