From 28e78d76904234eeb33413dd18ec70f4d722e7a6 Mon Sep 17 00:00:00 2001 From: lelia <2418071+lelia@users.noreply.github.com> Date: Fri, 13 Nov 2026 20:57:00 -0500 Subject: [PATCH 1/5] Document the API token scopes each SDK method needs Add an "API token scopes" section to the README that maps every SDK method to the endpoint it calls and the scopes that endpoint checks, matching the per-endpoint scopes in the public API reference. It also explains how a 401 or 403 surfaces: a missing scope raises APIAccessDenied with status_code 403 and the server's "Insufficient permissions" message, and 403s with more specific messages raise APIInsufficientPermissions, APIOrganizationNotAllowed or APIInsufficientQuota, all subclasses of APIFailure. Methods whose endpoint the reference does not list are marked as such rather than given a guessed scope. --- README.rst | 350 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 349 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 0ac5262..cbc4a77 100644 --- a/README.rst +++ b/README.rst @@ -24,7 +24,7 @@ Initializing the module **PARAMETERS:** -- **token (str)** - The Socket API Key for your Organization +- **token (str)** - The Socket API Key for your Organization. Each method needs the token to carry particular scopes; see `API token scopes`_ - **timeout (int)** - The number of seconds to wait before failing the connection - **allow_unverified (bool)** - Whether to skip SSL certificate verification (default: False). Set to True for testing with self-signed certificates. - **user_agent (str, optional)** - Custom User-Agent string to use in API requests. If not provided, defaults to "SocketSDKPython/{version}" @@ -1498,3 +1498,351 @@ List historical snapshots for an organization. - **org_slug (str)** - The organization slug - **query_params (dict, optional)** - Optional query parameters for filtering + + +API token scopes +---------------- + +The SDK authenticates every call with one organization API token, and each Socket API +endpoint checks that the token carries particular scopes. The table below lists, for each +SDK method, the endpoint it calls and the scopes that endpoint checks. Where an endpoint +lists more than one scope, the token needs all of them. "none" means any valid token for +the organization works. Paths are relative to ``https://api.socket.dev/v0/``; query strings +are omitted. + +The scopes each endpoint checks are also listed in the +`API reference `_. For a least-privilege token, grant +only the scopes of the methods your integration calls. + +Missing scopes and other 403 responses +"""""""""""""""""""""""""""""""""""""" + +Methods do not return an empty result on a 401 or 403. ``API.do_request()`` raises +before the method sees the response, so the exception reaches the caller, including when +``use_types=True``. + +A missing scope raises ``APIAccessDenied`` with ``status_code`` 403. Its message starts +with the server's ``Insufficient permissions``, followed by the request URL and the +response headers. A 401, from a bad or revoked token, also raises ``APIAccessDenied``, +with ``Unauthorized`` in the message. + +Recent API responses name the required scopes in the 403 body under +``error.details.requiredScopes``, but the SDK does not include them in the exception +message; to see them, look up the endpoint in the table below or the API reference. + +A 403 whose ``error.message`` contains one of these texts raises a more specific class +instead, and logs the server's message at ``ERROR`` on the ``socketdev`` logger: + +- ``Insufficient permissions for API method``: ``APIInsufficientPermissions`` +- ``Organization not allowed``: ``APIOrganizationNotAllowed`` +- ``Insufficient max quota``: ``APIInsufficientQuota`` (a 429 also raises this class) + +All of these classes live in ``socketdev.exceptions``, carry the HTTP status in +``status_code`` and subclass ``APIFailure``, so catching ``APIFailure`` covers every +case. + +.. code-block:: python + + from socketdev import socketdev + from socketdev.exceptions import APIAccessDenied + + socket = socketdev(token="REPLACE_ME") + try: + socket.diffscans.list("org_slug") + except APIAccessDenied as error: + if error.status_code == 403: + print("Access denied; check the token's scopes for this method:", error) + raise + +Scopes by method +"""""""""""""""" + +A few rows need a note: + +- ``fullscans.finalize_tier1()`` and ``uploadmanifests.upload_manifest_files()`` call + endpoints the API reference does not list. Both check ``full-scans:create``. +- Rows marked "not in the API reference" call an endpoint the current reference does not + list, so no scope is documented for it. ``repositories.list()`` and ``sbom.view()`` + belong to the deprecated report-era API. ``settings.integration_events()`` calls + ``settings/integrations/{integration_id}``; the reference lists the integration events + endpoint as ``settings/integrations/{integration_id}/events``, which checks + ``integration:list``. +- Some scopes differ from what the method name suggests: ``analytics.get_org()`` and + ``analytics.get_repo()`` check ``report:write``; ``apitokens.update()`` checks + ``api-tokens:create``; ``labels.setting.delete()`` checks ``repo-label:update``; and + the ``export`` methods check ``report:read`` rather than a full-scans scope. + +.. list-table:: + :header-rows: 1 + :widths: 30 45 25 + + * - Method + - Endpoint + - Scopes + * - ``alertfullscansearch.search()`` + - ``GET orgs/{org_slug}/alert-full-scan-search`` + - ``alerts:list`` + * - ``alerts.get()`` + - ``GET orgs/{org_slug}/alerts`` + - ``alerts:list`` + * - ``alerttypes.get()`` + - ``POST alert-types`` + - none + * - ``analytics.get_org()`` + - ``GET analytics/org/{filter}`` + - ``report:write`` + * - ``analytics.get_repo()`` + - ``GET analytics/repo/{name}/{filter}`` + - ``report:write`` + * - ``apitokens.create()`` + - ``POST orgs/{org_slug}/api-tokens`` + - ``api-tokens:create`` + * - ``apitokens.list()`` + - ``GET orgs/{org_slug}/api-tokens`` + - ``api-tokens:list`` + * - ``apitokens.update()`` + - ``POST orgs/{org_slug}/api-tokens/update`` + - ``api-tokens:create`` + * - ``apitokens.update(token_id=...)`` + - ``PUT orgs/{org_slug}/api-tokens/{token_id}`` + - not in the API reference + * - ``apitokens.rotate()`` + - ``POST orgs/{org_slug}/api-tokens/rotate`` + - ``api-tokens:rotate`` + * - ``apitokens.revoke()`` + - ``POST orgs/{org_slug}/api-tokens/revoke`` + - ``api-tokens:revoke`` + * - ``auditlog.get()`` + - ``GET orgs/{org_slug}/audit-log`` + - ``audit-log:list`` + * - ``basics.get_config()`` + - ``GET orgs/{org_slug}/settings/socket-basics`` + - ``socket-basics:read`` + * - ``dependencies.post()`` + - ``POST dependencies/upload`` + - ``report:write`` + * - ``dependencies.get()`` + - ``POST dependencies/search`` + - none + * - ``dependencies.get(org_slug, ecosystem, package, version)`` + - ``GET orgs/{org_slug}/dependencies/{ecosystem}/{package}/{version}`` + - not in the API reference + * - ``diffscans.list()`` + - ``GET orgs/{org_slug}/diff-scans`` + - ``diff-scans:list`` + * - ``diffscans.get()`` + - ``GET orgs/{org_slug}/diff-scans/{diff_scan_id}`` + - ``diff-scans:list`` + * - ``diffscans.create_from_repo()`` + - ``POST orgs/{org_slug}/diff-scans/from-repo/{repo_slug}`` + - ``diff-scans:create``, ``full-scans:create`` and ``repo:list`` + * - ``diffscans.create_from_ids()`` + - ``POST orgs/{org_slug}/diff-scans/from-ids`` + - ``diff-scans:create`` and ``full-scans:list`` + * - ``diffscans.gfm()`` + - ``GET orgs/{org_slug}/diff-scans/{diff_scan_id}/gfm`` + - ``diff-scans:list`` + * - ``diffscans.delete()`` + - ``DELETE orgs/{org_slug}/diff-scans/{diff_scan_id}`` + - ``diff-scans:delete`` + * - ``export.cdx_bom()`` + - ``GET orgs/{org_slug}/export/cdx/{id}`` + - ``report:read`` + * - ``export.spdx_bom()`` + - ``GET orgs/{org_slug}/export/spdx/{id}`` + - ``report:read`` + * - ``export.openvex_bom()`` + - ``GET orgs/{org_slug}/export/openvex/{id}`` + - ``report:read`` + * - ``fixes.get()`` + - ``GET orgs/{org_slug}/fixes`` + - ``fixes:list`` + * - ``fullscans.get()`` + - ``GET orgs/{org_slug}/full-scans``, or ``GET orgs/{org_slug}/full-scans/{full_scan_id}`` when ``params`` holds only ``id`` + - ``full-scans:list`` + * - ``fullscans.post()`` + - ``POST orgs/{org_slug}/full-scans`` + - ``full-scans:create`` + * - ``fullscans.delete()`` + - ``DELETE orgs/{org_slug}/full-scans/{full_scan_id}`` + - ``full-scans:delete`` + * - ``fullscans.stream_diff()`` + - ``GET orgs/{org_slug}/full-scans/diff`` + - ``full-scans:list`` + * - ``fullscans.stream()`` + - ``GET orgs/{org_slug}/full-scans/{full_scan_id}`` + - ``full-scans:list`` + * - ``fullscans.metadata()`` + - ``GET orgs/{org_slug}/full-scans/{full_scan_id}/metadata`` + - ``full-scans:list`` + * - ``fullscans.gfm()`` + - ``GET orgs/{org_slug}/full-scans/diff/gfm`` + - ``full-scans:list`` + * - ``fullscans.finalize_tier1()`` + - ``POST tier1-reachability-scan/finalize`` + - ``full-scans:create`` (not in the API reference) + * - ``fullscans.archive()`` + - ``POST orgs/{org_slug}/full-scans/archive`` + - ``full-scans:create`` + * - ``fullscans.rescan()`` + - ``POST orgs/{org_slug}/full-scans/{full_scan_id}/rescan`` + - ``full-scans:create`` + * - ``fullscans.get_tar_files()`` + - ``GET orgs/{org_slug}/full-scans/{full_scan_id}/files/tar`` + - ``full-scans:list`` + * - ``historical.list()`` + - ``GET orgs/{org_slug}/historical/alerts`` + - ``historical:alerts-list`` + * - ``historical.trend()`` + - ``GET orgs/{org_slug}/historical/alerts/trend`` + - ``historical:alerts-trend`` + * - ``historical.dependencies_trend()`` + - ``GET orgs/{org_slug}/historical/dependencies/trend`` + - ``historical:dependencies-trend`` + * - ``historical.snapshots.create()`` + - ``POST orgs/{org_slug}/historical/snapshots`` + - ``historical:snapshots-start`` + * - ``historical.snapshots.list()`` + - ``GET orgs/{org_slug}/historical/snapshots`` + - ``historical:snapshots-list`` + * - ``labels.list()`` + - ``GET orgs/{org_slug}/repos/labels`` + - ``repo-label:list`` + * - ``labels.post()`` + - ``POST orgs/{org_slug}/repos/labels`` + - ``repo-label:create`` + * - ``labels.get()`` + - ``GET orgs/{org_slug}/repos/labels/{label_id}`` + - ``repo-label:list`` + * - ``labels.delete()`` + - ``DELETE orgs/{org_slug}/repos/labels/{label_id}`` + - ``repo-label:delete`` + * - ``labels.associate()`` + - ``POST orgs/{org_slug}/repos/labels/{label_id}/associate`` + - ``repo-label:update`` + * - ``labels.disassociate()`` + - ``POST orgs/{org_slug}/repos/labels/{label_id}/disassociate`` + - ``repo-label:update`` + * - ``labels.setting.get()`` + - ``GET orgs/{org_slug}/repos/labels/{label_id}/label-setting`` + - ``repo-label:list`` + * - ``labels.setting.put()`` + - ``PUT orgs/{org_slug}/repos/labels/{label_id}/label-setting`` + - ``repo-label:update`` + * - ``labels.setting.delete()`` + - ``DELETE orgs/{org_slug}/repos/labels/{label_id}/label-setting`` + - ``repo-label:update`` + * - ``licensemetadata.post()`` + - ``POST license-metadata`` + - none + * - ``npm.issues()`` + - ``GET npm/{package}/{version}/issues`` + - none + * - ``npm.score()`` + - ``GET npm/{package}/{version}/score`` + - none + * - ``openapi.get()`` + - ``GET openapi`` + - none + * - ``org.get()`` + - ``GET organizations`` + - none + * - ``purl.post(org_slug=...)`` + - ``POST orgs/{org_slug}/purl`` + - ``packages:list`` + * - ``purl.post()`` + - ``POST purl`` + - ``packages:list`` + * - ``quota.get()`` + - ``GET quota`` + - none + * - ``report.list()`` + - ``GET report/list`` + - ``report:list`` + * - ``report.delete()`` + - ``DELETE report/delete/{id}`` + - ``report:write`` + * - ``report.view()`` + - ``GET report/view/{id}`` + - ``report:read`` + * - ``report.supported()`` + - ``GET report/supported`` + - none + * - ``report.create()`` + - ``PUT report/upload`` + - ``report:write`` + * - ``repos.get()`` + - ``GET orgs/{org_slug}/repos`` + - ``repo:list`` + * - ``repos.repo()`` + - ``GET orgs/{org_slug}/repos/{repo_slug}`` + - ``repo:list`` + * - ``repos.post()`` + - ``POST orgs/{org_slug}/repos`` + - ``repo:create`` + * - ``repos.update()`` + - ``POST orgs/{org_slug}/repos/{repo_slug}`` + - ``repo:update`` + * - ``repos.delete()`` + - ``DELETE orgs/{org_slug}/repos/{repo_slug}`` + - ``repo:delete`` + * - ``repositories.list()`` + - ``GET repos`` + - not in the API reference + * - ``sbom.view()`` + - ``GET sbom/view/{id}`` + - not in the API reference + * - ``settings.get()`` + - ``GET orgs/{org_slug}/settings/security-policy`` + - ``security-policy:read`` + * - ``settings.update_security_policy()`` + - ``POST orgs/{org_slug}/settings/security-policy`` + - ``security-policy:update`` + * - ``settings.get_license_policy()`` + - ``GET orgs/{org_slug}/settings/license-policy`` + - ``license-policy:read`` + * - ``settings.update_license_policy()`` + - ``POST orgs/{org_slug}/settings/license-policy`` + - ``license-policy:update`` + * - ``settings.integration_events()`` + - ``GET orgs/{org_slug}/settings/integrations/{integration_id}`` + - not in the API reference + * - ``supportedfiles.get()`` + - ``GET orgs/{org_slug}/supported-files`` + - none + * - ``telemetry.get_config()`` + - ``GET orgs/{org_slug}/telemetry/config`` + - none + * - ``telemetry.update_config()`` + - ``PUT orgs/{org_slug}/telemetry/config`` + - ``telemetry-policy:update`` + * - ``threatfeed.get(org_slug)`` + - ``GET orgs/{org_slug}/threat-feed`` + - ``threat-feed:list`` + * - ``threatfeed.get()`` + - ``GET threat-feed`` + - ``threat-feed:list`` + * - ``triage.list_alert_triage()`` + - ``GET orgs/{org_slug}/triage/alerts`` + - ``triage:alerts-list`` + * - ``triage.update_alert_triage()`` + - ``POST orgs/{org_slug}/triage/alerts`` + - ``triage:alerts-update`` + * - ``uploadmanifests.upload_manifest_files()`` + - ``POST orgs/{org_slug}/upload-manifest-files`` + - ``full-scans:create`` (not in the API reference) + * - ``webhooks.list()`` + - ``GET orgs/{org_slug}/webhooks`` + - ``webhooks:list`` + * - ``webhooks.create()`` + - ``POST orgs/{org_slug}/webhooks`` + - ``webhooks:create`` + * - ``webhooks.get()`` + - ``GET orgs/{org_slug}/webhooks/{webhook_id}`` + - ``webhooks:list`` + * - ``webhooks.update()`` + - ``PUT orgs/{org_slug}/webhooks/{webhook_id}`` + - ``webhooks:update`` + * - ``webhooks.delete()`` + - ``DELETE orgs/{org_slug}/webhooks/{webhook_id}`` + - ``webhooks:delete`` From 94df69d3a37236a5524935bf9607c7afc9bf2041 Mon Sep 17 00:00:00 2001 From: lelia <2418071+lelia@users.noreply.github.com> Date: Fri, 13 Nov 2026 21:40:08 -0500 Subject: [PATCH 2/5] Request the events path in settings.integration_events() The method requested orgs/{org}/settings/integrations/{id}, which has no GET route, so it always failed. The events listing lives under /events and checks integration:list. --- CHANGELOG.md | 9 +++++++++ socketdev/settings/__init__.py | 2 +- socketdev/version.py | 2 +- tests/unit/test_all_endpoints_unit.py | 14 ++++++++++++++ 4 files changed, 25 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 11bc25b..cfe4b08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 3.6.3 + +### Fixed: `settings.integration_events()` requested the wrong path + +- `settings.integration_events()` now calls + `GET orgs/{org_slug}/settings/integrations/{integration_id}/events`. It + previously requested the integration's own path, which has no `GET` route, + so the method always failed. It needs the `integration:list` scope. + ## 3.6.2 ### Fixed: reject retired API credentials before use diff --git a/socketdev/settings/__init__.py b/socketdev/settings/__init__.py index 1ba8724..cfc4514 100644 --- a/socketdev/settings/__init__.py +++ b/socketdev/settings/__init__.py @@ -115,7 +115,7 @@ def integration_events(self, org_slug: str, integration_id: str) -> dict: org_slug: Organization slug integration_id: Integration ID """ - path = f"orgs/{org_slug}/settings/integrations/{integration_id}" + path = f"orgs/{org_slug}/settings/integrations/{integration_id}/events" response = self.api.do_request(path=path) if response.status_code == 200: diff --git a/socketdev/version.py b/socketdev/version.py index 4f82193..6a45bf5 100644 --- a/socketdev/version.py +++ b/socketdev/version.py @@ -1 +1 @@ -__version__ = "3.6.2" +__version__ = "3.6.3" diff --git a/tests/unit/test_all_endpoints_unit.py b/tests/unit/test_all_endpoints_unit.py index 7e0d36b..fc79a25 100644 --- a/tests/unit/test_all_endpoints_unit.py +++ b/tests/unit/test_all_endpoints_unit.py @@ -736,6 +736,20 @@ def test_settings_get_unit(self): self.assertEqual(call_args[0][0], "GET") self.assertIn("/orgs/test-org/settings", call_args[0][1]) + def test_settings_integration_events_unit(self): + """Test integration events retrieval.""" + expected_data = {"results": [{"id": "event-1"}]} + self._mock_response(expected_data) + + result = self.sdk.settings.integration_events("test-org", "integration-1") + + self.assertEqual(result, expected_data) + call_args = self.mock_requests.request.call_args + self.assertEqual(call_args[0][0], "GET") + self.assertTrue( + call_args[0][1].endswith("/orgs/test-org/settings/integrations/integration-1/events") + ) + # Triage endpoints def test_triage_list_alert_triage_unit(self): """Test alert triage listing.""" From 5007b6f118da9069412b8c80ec5a56d80fa14aa4 Mon Sep 17 00:00:00 2001 From: lelia <2418071+lelia@users.noreply.github.com> Date: Wed, 18 Nov 2026 14:53:48 -0500 Subject: [PATCH 3/5] Type integration_events() as the list the endpoint returns GET .../integrations/{integration_id}/events answers with a bare JSON array of events. The method was annotated -> dict and fell back to {}, and its test mocked a {"results": [...]} wrapper the API never sends. The annotation and fallback are now a list, and the fixture has the shape of a real event. --- CHANGELOG.md | 2 ++ socketdev/settings/__init__.py | 7 +++++-- tests/unit/test_all_endpoints_unit.py | 15 ++++++++++++++- 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cfe4b08..d8bb72a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ `GET orgs/{org_slug}/settings/integrations/{integration_id}/events`. It previously requested the integration's own path, which has no `GET` route, so the method always failed. It needs the `integration:list` scope. +- Its return annotation is now `list`, matching the JSON array the endpoint + returns. ## 3.6.2 diff --git a/socketdev/settings/__init__.py b/socketdev/settings/__init__.py index cfc4514..86541ae 100644 --- a/socketdev/settings/__init__.py +++ b/socketdev/settings/__init__.py @@ -108,12 +108,15 @@ def get( ) return {} - def integration_events(self, org_slug: str, integration_id: str) -> dict: + def integration_events(self, org_slug: str, integration_id: str) -> list: """Get integration events for a specific integration. Args: org_slug: Organization slug integration_id: Integration ID + + Returns: + The integration's events, as the list the API returns. """ path = f"orgs/{org_slug}/settings/integrations/{integration_id}/events" response = self.api.do_request(path=path) @@ -123,7 +126,7 @@ def integration_events(self, org_slug: str, integration_id: str) -> dict: error_message = response.json().get("error", {}).get("message", "Unknown error") log.error(f"Error getting integration events: {response.status_code}, message: {error_message}") - return {} + return [] def get_license_policy(self, org_slug: str) -> dict: """Get license policy settings for an organization. diff --git a/tests/unit/test_all_endpoints_unit.py b/tests/unit/test_all_endpoints_unit.py index fc79a25..ae264ef 100644 --- a/tests/unit/test_all_endpoints_unit.py +++ b/tests/unit/test_all_endpoints_unit.py @@ -738,7 +738,20 @@ def test_settings_get_unit(self): def test_settings_integration_events_unit(self): """Test integration events retrieval.""" - expected_data = {"results": [{"id": "event-1"}]} + expected_data = [ + { + "id": "event-1", + "integration_id": "integration-1", + "type": "alert", + "payload": {}, + "status_code": 200, + "error": "", + "sent_at": "2026-01-01T00:00:00.000Z", + "retry_info": [], + "created_at": "2026-01-01T00:00:00.000Z", + "updated_at": "2026-01-01T00:00:00.000Z", + } + ] self._mock_response(expected_data) result = self.sdk.settings.integration_events("test-org", "integration-1") From be87415bf7bbbc6879f009be3de23d2c61dd6b09 Mon Sep 17 00:00:00 2001 From: lelia <2418071+lelia@users.noreply.github.com> Date: Wed, 18 Nov 2026 14:55:29 -0500 Subject: [PATCH 4/5] Correct the rows and exceptions the API contradicts Checked against the API's route handlers: - Three calls request a path with no route and always fail with a 404: apitokens.update(token_id=...), dependencies.get() with all four arguments, and repositories.list(). They were marked "not in the API reference", which read as working but undocumented. - sbom.view() checks report:read. - settings.integration_events() is listed with the /events path and integration:list. - POST dependencies/search checks no scope at the route but filters results by dependencies:list repository access. - The API sends neither "Insufficient permissions for API method" nor "Organization not allowed", so APIInsufficientPermissions and APIOrganizationNotAllowed are not raised today. A missing scope is APIAccessDenied. Also marks the endpoints the API reference lists as deprecated, and explains scope groups and tokens restricted to specific repositories. --- README.rst | 112 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 69 insertions(+), 43 deletions(-) diff --git a/README.rst b/README.rst index cbc4a77..83cb589 100644 --- a/README.rst +++ b/README.rst @@ -1506,14 +1506,24 @@ API token scopes The SDK authenticates every call with one organization API token, and each Socket API endpoint checks that the token carries particular scopes. The table below lists, for each SDK method, the endpoint it calls and the scopes that endpoint checks. Where an endpoint -lists more than one scope, the token needs all of them. "none" means any valid token for -the organization works. Paths are relative to ``https://api.socket.dev/v0/``; query strings -are omitted. +lists more than one scope, the token needs all of them. "none" means the endpoint checks +no scope, so any valid token for the organization works. Paths are relative to +``https://api.socket.dev/v0/``; query strings are omitted. The scopes each endpoint checks are also listed in the `API reference `_. For a least-privilege token, grant only the scopes of the methods your integration calls. +Scopes are grouped by their prefix, and a token that holds a group holds every scope in +it: ``full-scans`` covers ``full-scans:list``, ``full-scans:create`` and +``full-scans:delete``. When a token is given every scope of a group, the API stores and +reports the group name instead, so a token created with ``packages:list``, the only +scope in its group, is listed with ``packages``. + +Scopes are not the only check. A token restricted to specific repositories is rejected +by some endpoints whatever scopes it holds, and organizations that restrict repository +access apply per-repository checks on top of the scopes listed here. + Missing scopes and other 403 responses """""""""""""""""""""""""""""""""""""" @@ -1530,16 +1540,22 @@ Recent API responses name the required scopes in the 403 body under ``error.details.requiredScopes``, but the SDK does not include them in the exception message; to see them, look up the endpoint in the table below or the API reference. -A 403 whose ``error.message`` contains one of these texts raises a more specific class -instead, and logs the server's message at ``ERROR`` on the ``socketdev`` logger: +A token restricted to specific repositories gets the same exception from an endpoint +that does not accept such tokens. Its message starts with ``This endpoint does not +support repository-scoped tokens``. -- ``Insufficient permissions for API method``: ``APIInsufficientPermissions`` -- ``Organization not allowed``: ``APIOrganizationNotAllowed`` -- ``Insufficient max quota``: ``APIInsufficientQuota`` (a 429 also raises this class) +A 403 whose message contains ``Insufficient max quota`` raises ``APIInsufficientQuota`` +instead, as does a 429, and logs the server's message at ``ERROR`` on the ``socketdev`` +logger. -All of these classes live in ``socketdev.exceptions``, carry the HTTP status in -``status_code`` and subclass ``APIFailure``, so catching ``APIFailure`` covers every -case. +``socketdev.exceptions`` also defines ``APIInsufficientPermissions`` and +``APIOrganizationNotAllowed``. The SDK raises them for 403 messages containing +``Insufficient permissions for API method`` and ``Organization not allowed``, which the +API does not currently send. Do not rely on either to detect a missing scope: catch +``APIAccessDenied``. + +All of these classes carry the HTTP status in ``status_code`` and subclass +``APIFailure``, so catching ``APIFailure`` covers every case. .. code-block:: python @@ -1559,14 +1575,24 @@ Scopes by method A few rows need a note: -- ``fullscans.finalize_tier1()`` and ``uploadmanifests.upload_manifest_files()`` call - endpoints the API reference does not list. Both check ``full-scans:create``. -- Rows marked "not in the API reference" call an endpoint the current reference does not - list, so no scope is documented for it. ``repositories.list()`` and ``sbom.view()`` - belong to the deprecated report-era API. ``settings.integration_events()`` calls - ``settings/integrations/{integration_id}``; the reference lists the integration events - endpoint as ``settings/integrations/{integration_id}/events``, which checks - ``integration:list``. +- "Deprecated" marks an endpoint the API reference lists as deprecated. Prefer the + method the reference names as its successor. ``report.view()`` calls + ``GET report/view/{id}``, which the reference says will be removed on 2026-11-20; + use ``fullscans`` instead. +- ``fullscans.finalize_tier1()``, ``uploadmanifests.upload_manifest_files()`` and + ``sbom.view()`` call endpoints the API reference does not list. Their scopes are + given in the table. +- Three calls request a path the API has no route for, so they fail with a 404 + (``APIResourceNotFound``) whatever the token: ``apitokens.update()`` when + ``token_id`` is passed, ``dependencies.get()`` when ``org_slug``, ``ecosystem``, + ``package`` and ``version`` are all passed, and ``repositories.list()``. Call + ``apitokens.update()`` without ``token_id``, and use ``repos.get()`` to list + repositories. +- ``dependencies.get()`` otherwise calls ``POST dependencies/search``. That endpoint + accepts any valid token, but it returns only results from repositories the token can + read under ``dependencies:list``. Depending on how the organization restricts + repository access, a token without that scope gets an empty result instead of a 403, + so grant ``dependencies:list``. - Some scopes differ from what the method name suggests: ``analytics.get_org()`` and ``analytics.get_repo()`` check ``report:write``; ``apitokens.update()`` checks ``api-tokens:create``; ``labels.setting.delete()`` checks ``repo-label:update``; and @@ -1589,10 +1615,10 @@ A few rows need a note: - ``POST alert-types`` - none * - ``analytics.get_org()`` - - ``GET analytics/org/{filter}`` + - ``GET analytics/org/{filter}``. Deprecated - ``report:write`` * - ``analytics.get_repo()`` - - ``GET analytics/repo/{name}/{filter}`` + - ``GET analytics/repo/{name}/{filter}``. Deprecated - ``report:write`` * - ``apitokens.create()`` - ``POST orgs/{org_slug}/api-tokens`` @@ -1605,7 +1631,7 @@ A few rows need a note: - ``api-tokens:create`` * - ``apitokens.update(token_id=...)`` - ``PUT orgs/{org_slug}/api-tokens/{token_id}`` - - not in the API reference + - no such route; the call fails * - ``apitokens.rotate()`` - ``POST orgs/{org_slug}/api-tokens/rotate`` - ``api-tokens:rotate`` @@ -1619,14 +1645,14 @@ A few rows need a note: - ``GET orgs/{org_slug}/settings/socket-basics`` - ``socket-basics:read`` * - ``dependencies.post()`` - - ``POST dependencies/upload`` + - ``POST dependencies/upload``. Deprecated - ``report:write`` * - ``dependencies.get()`` - ``POST dependencies/search`` - - none + - none; ``dependencies:list`` to get results (see the note above) * - ``dependencies.get(org_slug, ecosystem, package, version)`` - ``GET orgs/{org_slug}/dependencies/{ecosystem}/{package}/{version}`` - - not in the API reference + - no such route; the call fails * - ``diffscans.list()`` - ``GET orgs/{org_slug}/diff-scans`` - ``diff-scans:list`` @@ -1640,7 +1666,7 @@ A few rows need a note: - ``POST orgs/{org_slug}/diff-scans/from-ids`` - ``diff-scans:create`` and ``full-scans:list`` * - ``diffscans.gfm()`` - - ``GET orgs/{org_slug}/diff-scans/{diff_scan_id}/gfm`` + - ``GET orgs/{org_slug}/diff-scans/{diff_scan_id}/gfm``. Deprecated - ``diff-scans:list`` * - ``diffscans.delete()`` - ``DELETE orgs/{org_slug}/diff-scans/{diff_scan_id}`` @@ -1655,7 +1681,7 @@ A few rows need a note: - ``GET orgs/{org_slug}/export/openvex/{id}`` - ``report:read`` * - ``fixes.get()`` - - ``GET orgs/{org_slug}/fixes`` + - ``GET orgs/{org_slug}/fixes``. Deprecated - ``fixes:list`` * - ``fullscans.get()`` - ``GET orgs/{org_slug}/full-scans``, or ``GET orgs/{org_slug}/full-scans/{full_scan_id}`` when ``params`` holds only ``id`` @@ -1667,7 +1693,7 @@ A few rows need a note: - ``DELETE orgs/{org_slug}/full-scans/{full_scan_id}`` - ``full-scans:delete`` * - ``fullscans.stream_diff()`` - - ``GET orgs/{org_slug}/full-scans/diff`` + - ``GET orgs/{org_slug}/full-scans/diff``. Deprecated - ``full-scans:list`` * - ``fullscans.stream()`` - ``GET orgs/{org_slug}/full-scans/{full_scan_id}`` @@ -1676,7 +1702,7 @@ A few rows need a note: - ``GET orgs/{org_slug}/full-scans/{full_scan_id}/metadata`` - ``full-scans:list`` * - ``fullscans.gfm()`` - - ``GET orgs/{org_slug}/full-scans/diff/gfm`` + - ``GET orgs/{org_slug}/full-scans/diff/gfm``. Deprecated - ``full-scans:list`` * - ``fullscans.finalize_tier1()`` - ``POST tier1-reachability-scan/finalize`` @@ -1736,10 +1762,10 @@ A few rows need a note: - ``POST license-metadata`` - none * - ``npm.issues()`` - - ``GET npm/{package}/{version}/issues`` + - ``GET npm/{package}/{version}/issues``. Deprecated - none * - ``npm.score()`` - - ``GET npm/{package}/{version}/score`` + - ``GET npm/{package}/{version}/score``. Deprecated - none * - ``openapi.get()`` - ``GET openapi`` @@ -1751,25 +1777,25 @@ A few rows need a note: - ``POST orgs/{org_slug}/purl`` - ``packages:list`` * - ``purl.post()`` - - ``POST purl`` + - ``POST purl``. Deprecated - ``packages:list`` * - ``quota.get()`` - ``GET quota`` - none * - ``report.list()`` - - ``GET report/list`` + - ``GET report/list``. Deprecated - ``report:list`` * - ``report.delete()`` - - ``DELETE report/delete/{id}`` + - ``DELETE report/delete/{id}``. Deprecated - ``report:write`` * - ``report.view()`` - - ``GET report/view/{id}`` + - ``GET report/view/{id}``. Deprecated - ``report:read`` * - ``report.supported()`` - - ``GET report/supported`` + - ``GET report/supported``. Deprecated - none * - ``report.create()`` - - ``PUT report/upload`` + - ``PUT report/upload``. Deprecated - ``report:write`` * - ``repos.get()`` - ``GET orgs/{org_slug}/repos`` @@ -1788,10 +1814,10 @@ A few rows need a note: - ``repo:delete`` * - ``repositories.list()`` - ``GET repos`` - - not in the API reference + - no such route; the call fails * - ``sbom.view()`` - ``GET sbom/view/{id}`` - - not in the API reference + - ``report:read`` (not in the API reference) * - ``settings.get()`` - ``GET orgs/{org_slug}/settings/security-policy`` - ``security-policy:read`` @@ -1799,14 +1825,14 @@ A few rows need a note: - ``POST orgs/{org_slug}/settings/security-policy`` - ``security-policy:update`` * - ``settings.get_license_policy()`` - - ``GET orgs/{org_slug}/settings/license-policy`` + - ``GET orgs/{org_slug}/settings/license-policy``. Deprecated - ``license-policy:read`` * - ``settings.update_license_policy()`` - ``POST orgs/{org_slug}/settings/license-policy`` - ``license-policy:update`` * - ``settings.integration_events()`` - - ``GET orgs/{org_slug}/settings/integrations/{integration_id}`` - - not in the API reference + - ``GET orgs/{org_slug}/settings/integrations/{integration_id}/events`` + - ``integration:list`` * - ``supportedfiles.get()`` - ``GET orgs/{org_slug}/supported-files`` - none @@ -1820,7 +1846,7 @@ A few rows need a note: - ``GET orgs/{org_slug}/threat-feed`` - ``threat-feed:list`` * - ``threatfeed.get()`` - - ``GET threat-feed`` + - ``GET threat-feed``. Deprecated - ``threat-feed:list`` * - ``triage.list_alert_triage()`` - ``GET orgs/{org_slug}/triage/alerts`` From 6602fb22b50a52d608025cd7720015f7c7a701de Mon Sep 17 00:00:00 2001 From: lelia <2418071+lelia@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:47:25 -0500 Subject: [PATCH 5/5] Remove SDK calls that request paths the API does not route Three calls could not succeed, because the API has no route for the path they requested: - apitokens.update(token_id=...) sent PUT orgs/{org}/api-tokens/{id}. The method now always posts to api-tokens/update, which reads the token from the request body. - dependencies.get() with org_slug, ecosystem, package and version sent GET orgs/{org}/dependencies/... The method now only searches, with the get(limit, offset) signature the README documents. Positional arguments used to bind to the removed parameters and were ignored. - repositories.list() sent GET repos. The module is removed; repos.get(org_slug) lists repositories. The README scope table drops the three rows and their note, and its apitokens.update example names the token with uuid instead of token_id. --- CHANGELOG.md | 18 +++++++++ README.rst | 37 +++---------------- socketdev/__init__.py | 2 - socketdev/apitokens/__init__.py | 25 ++++--------- socketdev/dependencies/__init__.py | 25 ++++++------- socketdev/repositories/__init__.py | 31 ---------------- socketdev/version.py | 2 +- tests/integration/test_all_endpoints.py | 9 ++--- .../test_comprehensive_integration.py | 2 +- tests/integration/test_new_endpoints.py | 8 ++-- tests/unit/test_all_endpoints_unit.py | 28 +++++++++----- tests/unit/test_socket_sdk_unit.py | 2 +- 12 files changed, 71 insertions(+), 118 deletions(-) delete mode 100644 socketdev/repositories/__init__.py diff --git a/CHANGELOG.md b/CHANGELOG.md index d8bb72a..40c88b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## 3.6.4 + +### Removed: SDK calls that requested paths the API does not route + +These calls failed with a 404 on every request, whatever the token. + +- `apitokens.update()` no longer takes `token_id`. It always calls + `POST orgs/{org_slug}/api-tokens/update`, which reads the token to update from + the request body. Pass exactly one of `uuid`, `id`, `token` or `hash` in the + keyword arguments. +- `dependencies.get()` no longer takes `org_slug`, `ecosystem`, `package` and + `version`. Its signature is `get(limit=50, offset=0)`, as the README documents, + and it always searches. Positional arguments now set `limit` and `offset`; + they used to be bound to the removed parameters and ignored. +- The `repositories` module and `socketdev(...).repositories` are removed. Its + only method, `list()`, requested `GET repos`. Use `repos.get(org_slug)` to list + repositories. + ## 3.6.3 ### Fixed: `settings.integration_events()` requested the wrong path diff --git a/README.rst b/README.rst index 83cb589..2a81525 100644 --- a/README.rst +++ b/README.rst @@ -681,18 +681,6 @@ Create a new project health report with the provided files - **files (list)** - List of file paths of manifest files -Deprecated: repositories.get() -"""""""""""""""""""""""""""""" -Get a list of information about the tracked repositories - -**Usage:** - -.. code-block:: python - - from socketdev import socketdev - socket = socketdev(token="REPLACE_ME") - print(socket.repositories.get()) - Deprecated: sbom.view(report_id) """""""""""""""""""""""""""""""" Retrieve the information for a SBOM Report @@ -1107,16 +1095,18 @@ Update an existing API token. from socketdev import socketdev socket = socketdev(token="REPLACE_ME") update_params = { - "token_id": "token_123", + "uuid": "token_uuid", "name": "Updated Token Name", - "permissions": ["read"] + "scopes": ["full-scans:create"] } print(socket.apitokens.update("org_slug", **update_params)) **PARAMETERS:** - **org_slug (str)** – The organization name -- **kwargs** – Token update parameters +- **kwargs** – Token update parameters, sent as the request body. Identify the token + with exactly one of ``uuid``, ``id``, ``token`` or ``hash``. See the + `API reference `_ for the other fields. auditlog.get(org_slug, \*\*kwargs) """""""""""""""""""""""""""""""""""" @@ -1582,13 +1572,7 @@ A few rows need a note: - ``fullscans.finalize_tier1()``, ``uploadmanifests.upload_manifest_files()`` and ``sbom.view()`` call endpoints the API reference does not list. Their scopes are given in the table. -- Three calls request a path the API has no route for, so they fail with a 404 - (``APIResourceNotFound``) whatever the token: ``apitokens.update()`` when - ``token_id`` is passed, ``dependencies.get()`` when ``org_slug``, ``ecosystem``, - ``package`` and ``version`` are all passed, and ``repositories.list()``. Call - ``apitokens.update()`` without ``token_id``, and use ``repos.get()`` to list - repositories. -- ``dependencies.get()`` otherwise calls ``POST dependencies/search``. That endpoint +- ``dependencies.get()`` calls ``POST dependencies/search``. That endpoint accepts any valid token, but it returns only results from repositories the token can read under ``dependencies:list``. Depending on how the organization restricts repository access, a token without that scope gets an empty result instead of a 403, @@ -1629,9 +1613,6 @@ A few rows need a note: * - ``apitokens.update()`` - ``POST orgs/{org_slug}/api-tokens/update`` - ``api-tokens:create`` - * - ``apitokens.update(token_id=...)`` - - ``PUT orgs/{org_slug}/api-tokens/{token_id}`` - - no such route; the call fails * - ``apitokens.rotate()`` - ``POST orgs/{org_slug}/api-tokens/rotate`` - ``api-tokens:rotate`` @@ -1650,9 +1631,6 @@ A few rows need a note: * - ``dependencies.get()`` - ``POST dependencies/search`` - none; ``dependencies:list`` to get results (see the note above) - * - ``dependencies.get(org_slug, ecosystem, package, version)`` - - ``GET orgs/{org_slug}/dependencies/{ecosystem}/{package}/{version}`` - - no such route; the call fails * - ``diffscans.list()`` - ``GET orgs/{org_slug}/diff-scans`` - ``diff-scans:list`` @@ -1812,9 +1790,6 @@ A few rows need a note: * - ``repos.delete()`` - ``DELETE orgs/{org_slug}/repos/{repo_slug}`` - ``repo:delete`` - * - ``repositories.list()`` - - ``GET repos`` - - no such route; the call fails * - ``sbom.view()`` - ``GET sbom/view/{id}`` - ``report:read`` (not in the API reference) diff --git a/socketdev/__init__.py b/socketdev/__init__.py index 2be291f..da0d144 100644 --- a/socketdev/__init__.py +++ b/socketdev/__init__.py @@ -14,7 +14,6 @@ from socketdev.quota import Quota from socketdev.report import Report from socketdev.repos import Repos -from socketdev.repositories import Repositories from socketdev.sbom import Sbom from socketdev.settings import Settings from socketdev.triage import Triage @@ -83,7 +82,6 @@ def __init__(self, token: Optional[str] = None, timeout: int = 1200, allow_unver self.quota = Quota(self.api) self.report = Report(self.api) self.repos = Repos(self.api) - self.repositories = Repositories(self.api) self.sbom = Sbom(self.api) self.settings = Settings(self.api) self.triage = Triage(self.api) diff --git a/socketdev/apitokens/__init__.py b/socketdev/apitokens/__init__.py index 03dc41c..3545da0 100644 --- a/socketdev/apitokens/__init__.py +++ b/socketdev/apitokens/__init__.py @@ -54,31 +54,22 @@ def list(self, org_slug: str, **kwargs) -> dict: log.error(response.text) return {} - def update(self, org_slug: str, token_id: str = None, **kwargs) -> dict: + def update(self, org_slug: str, **kwargs) -> dict: """ Update an API token. - + Args: org_slug: Organization slug - token_id: Token ID to update (optional, can be in kwargs) - **kwargs: Token update parameters - + **kwargs: Token update parameters. The API reads the token to update + from the request body, so include exactly one of ``uuid``, ``id``, + ``token`` or ``hash``. + Returns: dict: API response containing the updated token details """ - # Extract token_id from kwargs if not provided as parameter - if token_id is None and 'token_id' in kwargs: - token_id = kwargs.pop('token_id') - - if token_id: - path = f"orgs/{org_slug}/api-tokens/{token_id}" - method = "PUT" - else: - path = f"orgs/{org_slug}/api-tokens/update" - method = "POST" - + path = f"orgs/{org_slug}/api-tokens/update" payload = json.dumps(kwargs) if kwargs else "{}" - response = self.api.do_request(path=path, method=method, payload=payload) + response = self.api.do_request(path=path, method="POST", payload=payload) if response.status_code == 200: return response.json() log.error(f"Error updating API token: {response.status_code}") diff --git a/socketdev/dependencies/__init__.py b/socketdev/dependencies/__init__.py index dbe4fd7..138bcb2 100644 --- a/socketdev/dependencies/__init__.py +++ b/socketdev/dependencies/__init__.py @@ -30,20 +30,17 @@ def post(self, files: list, params: dict, use_lazy_loading: bool = True, workspa log.error(response.text) return result - def get(self, org_slug: str = None, ecosystem: str = None, package: str = None, version: str = None, **kwargs) -> dict: - # If all specific parameters are provided, use the specific dependency endpoint - if org_slug and ecosystem and package and version: - path = f"orgs/{org_slug}/dependencies/{ecosystem}/{package}/{version}" - response = self.api.do_request(path=path, method="GET") - else: - # Otherwise use the search endpoint - limit = kwargs.get('limit', 50) - offset = kwargs.get('offset', 0) - path = "dependencies/search" - payload = {"limit": limit, "offset": offset} - payload_str = json.dumps(payload) - response = self.api.do_request(path=path, method="POST", payload=payload_str) - + def get(self, limit: int = 50, offset: int = 0) -> dict: + """Search the dependencies of the token's organization. + + Args: + limit: Maximum number of dependencies to return + offset: Number of dependencies to skip + """ + path = "dependencies/search" + payload = json.dumps({"limit": limit, "offset": offset}) + response = self.api.do_request(path=path, method="POST", payload=payload) + if response.status_code == 200: result = response.json() else: diff --git a/socketdev/repositories/__init__.py b/socketdev/repositories/__init__.py deleted file mode 100644 index e63faf9..0000000 --- a/socketdev/repositories/__init__.py +++ /dev/null @@ -1,31 +0,0 @@ -from typing import TypedDict, Union -import logging - -log = logging.getLogger("socketdev") - - -class Repo(TypedDict): - name: str - description: str - homepage: str - visibility: str - archived: bool - default_branch: str - - -class Repositories: - def __init__(self, api): - self.api = api - - def list(self, use_types: bool = False) -> Union[dict, list[Repo]]: - path = "repos" - response = self.api.do_request(path=path) - if response.status_code == 200: - result = response.json() - if use_types: - return [Repo(repo) for repo in result] - return result - - log.error(f"Error listing repositories: {response.status_code}") - log.error(response.text) - return [] diff --git a/socketdev/version.py b/socketdev/version.py index 6a45bf5..be798a7 100644 --- a/socketdev/version.py +++ b/socketdev/version.py @@ -1 +1 @@ -__version__ = "3.6.3" +__version__ = "3.6.4" diff --git a/tests/integration/test_all_endpoints.py b/tests/integration/test_all_endpoints.py index e36f074..3ac4241 100644 --- a/tests/integration/test_all_endpoints.py +++ b/tests/integration/test_all_endpoints.py @@ -68,7 +68,7 @@ def test_dependencies_post_mocked(self): def test_dependencies_get_mocked(self): """Test dependencies get endpoint.""" self._mock_success_response({"dependencies": []}) - result = self.sdk.dependencies.get("test-org", "npm", "test-package", "1.0.0") + result = self.sdk.dependencies.get(limit=10, offset=0) self.assertIn("dependencies", result) # DiffScans endpoints @@ -307,7 +307,7 @@ def test_apitokens_create_mocked(self): def test_apitokens_update_mocked(self): """Test apitokens update endpoint.""" self._mock_success_response({"id": "token-123", "name": "updated-token"}) - result = self.sdk.apitokens.update("test-org", token_id="token-123", name="updated-token") + result = self.sdk.apitokens.update("test-org", uuid="token-123", name="updated-token") self.assertEqual(result["name"], "updated-token") def test_apitokens_list_mocked(self): @@ -517,10 +517,7 @@ def test_auditlog_get_integration(self): # Dependencies endpoint def test_dependencies_get_integration(self): """Test dependencies get endpoint.""" - result = self._try_endpoint( - self.sdk.dependencies.get, - self.org_slug, "npm", "lodash", "4.18.1" - ) + result = self._try_endpoint(self.sdk.dependencies.get) if result: self.assertIsInstance(result, dict) diff --git a/tests/integration/test_comprehensive_integration.py b/tests/integration/test_comprehensive_integration.py index 4259b6b..442171e 100644 --- a/tests/integration/test_comprehensive_integration.py +++ b/tests/integration/test_comprehensive_integration.py @@ -348,7 +348,7 @@ def test_new_endpoints_basic(self): def test_dependencies_endpoint(self): """Test dependencies endpoint.""" try: - deps = self.sdk.dependencies.get(self.org_slug) + deps = self.sdk.dependencies.get() self.assertIsInstance(deps, dict) except Exception as e: print(f"Dependencies endpoint not available: {e}") diff --git a/tests/integration/test_new_endpoints.py b/tests/integration/test_new_endpoints.py index 6bac7f9..24377e9 100644 --- a/tests/integration/test_new_endpoints.py +++ b/tests/integration/test_new_endpoints.py @@ -227,7 +227,7 @@ def test_apitokens_update_mocked(self): result = self.sdk.apitokens.update( org_slug="test-org", - token_id="token123", + uuid="token123", name="updated-token" ) @@ -235,7 +235,7 @@ def test_apitokens_update_mocked(self): self.mock_api.do_request.assert_called_once_with( path="orgs/test-org/api-tokens/update", method="POST", - payload='{"token_id": "token123", "name": "updated-token"}' + payload='{"uuid": "token123", "name": "updated-token"}' ) def test_analytics_deprecation_warning(self): @@ -282,7 +282,7 @@ def test_all_endpoints_have_api_reference(self): endpoints = [ 'dependencies', 'export', 'fullscans', 'historical', 'npm', 'openapi', 'org', 'purl', 'quota', 'report', 'repos', - 'repositories', 'sbom', 'settings', 'triage', 'labels', + 'sbom', 'settings', 'triage', 'labels', 'licensemetadata', 'diffscans', 'threatfeed', 'apitokens', 'auditlog', 'analytics', 'alerttypes' ] @@ -302,7 +302,7 @@ def test_sdk_components_initialization(self): components = [ sdk.dependencies, sdk.export, sdk.fullscans, sdk.historical, sdk.npm, sdk.openapi, sdk.org, sdk.purl, sdk.quota, - sdk.report, sdk.repos, sdk.repositories, sdk.sbom, + sdk.report, sdk.repos, sdk.sbom, sdk.settings, sdk.triage, sdk.utils, sdk.labels, sdk.licensemetadata, sdk.diffscans, sdk.threatfeed, sdk.apitokens, sdk.auditlog, sdk.analytics, sdk.alerttypes diff --git a/tests/unit/test_all_endpoints_unit.py b/tests/unit/test_all_endpoints_unit.py index ae264ef..ed7406f 100644 --- a/tests/unit/test_all_endpoints_unit.py +++ b/tests/unit/test_all_endpoints_unit.py @@ -68,16 +68,23 @@ def test_dependencies_post_unit(self): os.unlink(f.name) def test_dependencies_get_unit(self): - """Test dependencies get with all parameters.""" + """Test dependencies get sends limit and offset to the search endpoint.""" expected_data = {"dependencies": [{"name": "sub-dependency", "version": "1.0.0"}]} self._mock_response(expected_data) - - result = self.sdk.dependencies.get("test-org", "npm", "lodash", "4.18.1") - + + result = self.sdk.dependencies.get(10, 20) + self.assertEqual(result, expected_data) call_args = self.mock_requests.request.call_args - self.assertEqual(call_args[0][0], "GET") - self.assertIn("/orgs/test-org/dependencies/npm/lodash/4.18.1", call_args[0][1]) + self.assertEqual(call_args[0][0], "POST") + self.assertTrue(call_args[0][1].endswith("/dependencies/search")) + self.assertEqual(json.loads(call_args[1]["data"]), {"limit": 10, "offset": 20}) + + def test_dependencies_get_rejects_package_arguments(self): + """The API has no per-package dependency route, so get() takes no package.""" + with self.assertRaises(TypeError): + self.sdk.dependencies.get(org_slug="test-org", ecosystem="npm", package="lodash", version="4.18.1") + self.mock_requests.request.assert_not_called() # DiffScans endpoints def test_diffscans_list_unit(self): @@ -843,12 +850,13 @@ def test_apitokens_update_unit(self): expected_data = {"id": "token-123", "name": "updated-token"} self._mock_response(expected_data) - result = self.sdk.apitokens.update("test-org", token_id="token-123", name="updated-token") - + result = self.sdk.apitokens.update("test-org", uuid="token-123", name="updated-token") + self.assertEqual(result, expected_data) call_args = self.mock_requests.request.call_args - self.assertEqual(call_args[0][0], "PUT") - self.assertIn("/orgs/test-org/api-tokens/token-123", call_args[0][1]) + self.assertEqual(call_args[0][0], "POST") + self.assertTrue(call_args[0][1].endswith("/orgs/test-org/api-tokens/update")) + self.assertEqual(json.loads(call_args[1]["data"]), {"uuid": "token-123", "name": "updated-token"}) def test_apitokens_list_unit(self): """Test API token listing.""" diff --git a/tests/unit/test_socket_sdk_unit.py b/tests/unit/test_socket_sdk_unit.py index 973c046..1735aab 100644 --- a/tests/unit/test_socket_sdk_unit.py +++ b/tests/unit/test_socket_sdk_unit.py @@ -28,7 +28,7 @@ def test_sdk_initialization(self): expected_components = [ 'api', 'dependencies', 'export', 'fullscans', 'historical', 'npm', 'openapi', 'org', 'purl', 'quota', 'report', 'repos', - 'repositories', 'sbom', 'settings', 'triage', 'utils', 'labels', + 'sbom', 'settings', 'triage', 'utils', 'labels', 'licensemetadata', 'diffscans', 'threatfeed', 'apitokens', 'auditlog', 'analytics', 'alerttypes' ]