diff --git a/README.rst b/README.rst index 0ac5262..83cb589 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,377 @@ 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 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 +"""""""""""""""""""""""""""""""""""""" + +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 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``. + +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. + +``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 + + 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: + +- "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 + 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}``. Deprecated + - ``report:write`` + * - ``analytics.get_repo()`` + - ``GET analytics/repo/{name}/{filter}``. Deprecated + - ``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}`` + - no such route; the call fails + * - ``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``. Deprecated + - ``report:write`` + * - ``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`` + * - ``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``. Deprecated + - ``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``. 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`` + - ``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``. Deprecated + - ``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``. Deprecated + - ``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``. Deprecated + - none + * - ``npm.score()`` + - ``GET npm/{package}/{version}/score``. Deprecated + - 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``. Deprecated + - ``packages:list`` + * - ``quota.get()`` + - ``GET quota`` + - none + * - ``report.list()`` + - ``GET report/list``. Deprecated + - ``report:list`` + * - ``report.delete()`` + - ``DELETE report/delete/{id}``. Deprecated + - ``report:write`` + * - ``report.view()`` + - ``GET report/view/{id}``. Deprecated + - ``report:read`` + * - ``report.supported()`` + - ``GET report/supported``. Deprecated + - none + * - ``report.create()`` + - ``PUT report/upload``. Deprecated + - ``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`` + - no such route; the call fails + * - ``sbom.view()`` + - ``GET sbom/view/{id}`` + - ``report:read`` (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``. 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}/events`` + - ``integration:list`` + * - ``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``. Deprecated + - ``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``