openapi: 3.0.0
info:
  description: Socket threat feed API endpoints.
  title: Socket Threat Feed API
  version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
  /orgs/{org_slug}/threat-feed:
    get:
      tags:
      - threat-feed
      summary: Get Threat Feed Items (Beta)
      operationId: getOrgThreatFeedItems
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: per_page
        in: query
        required: false
        description: Number of threats per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
      - name: page_cursor
        in: query
        required: false
        description: Page cursor token. Pass the returned nextPageCursor to this query string to fetch the next page of the threat feed.
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Set the sort order for the threat feed items. Default is descending order by updated_at, which includes all new and updated threat feed items.
        schema:
          type: string
          enum:
          - id
          - created_at
          - updated_at
          default: updated_at
      - name: updated_after
        in: query
        required: false
        description: A Unix timestamp in seconds that filters results to items only updated after the timestamp.
        schema:
          type: string
      - name: created_after
        in: query
        required: false
        description: A Unix timestamp in seconds that filters results to items only created after the date.
        schema:
          type: string
      - name: direction
        in: query
        required: false
        description: Order direction of the provided sort field.
        schema:
          type: string
          enum:
          - desc
          - asc
          default: desc
      - name: filter
        in: query
        required: false
        description: 'Filter by threat classification. Supported values: `mal` (malware, including possible malware), `vuln` (vulnerability), `typo` (typosquat, including possible typosquat), `anom` (anomaly),
          `spy` (telemetry), `obf` (obfuscated code), `dual` (dual-use tool), `joke` (protestware or joke package), `tp` (all confirmed true positives), `fp` (false positive), `u` (unreviewed), `c` (classified,
          i.e. anything except unreviewed).'
        schema:
          type: string
          enum:
          - u
          - c
          - fp
          - tp
          - mal
          - vuln
          - anom
          - joke
          - spy
          - typo
          - obf
          - dual
          default: mal
      - name: name
        in: query
        required: false
        description: Filter threats by package name
        schema:
          type: string
          default: ''
      - name: version
        in: query
        required: false
        description: Filter threats by package version.
        schema:
          type: string
          default: ''
      - name: is_human_reviewed
        in: query
        required: false
        description: Only return threats which have been human-reviewed
        schema:
          type: boolean
          default: false
      - name: ecosystem
        in: query
        required: false
        description: Filter threats by package ecosystem.
        schema:
          type: string
          enum:
          - github
          - cargo
          - clawhub
          - composer
          - chrome
          - golang
          - huggingface
          - maven
          - npm
          - nuget
          - vscode
          - pypi
          - gem
          - swift
      security:
      - bearerAuth:
        - threat-feed:list
      - basicAuth:
        - threat-feed:list
      description: 'Paginated list of threats, sorted by updated_at by default. Set updated_after to the unix timestamp of your last sync while sorting by updated_at to synchronize all new or updated threats
        in the feed.


        This endpoint requires an Enterprise Plan with Threat Feed add-on. [Contact](https://socket.dev/demo?utm_source=api-docs&utm_medium=referral&utm_campaign=tracking) our sales team for more details.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - threat-feed:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        createdAt:
                          type: string
                          description: ISO 8601 timestamp of when the threat in the package artifact was first discovered
                          default: ''
                          format: date-time
                        updatedAt:
                          type: string
                          description: ISO 8601 timestamp of when the threat record for the package artifact was last updated (e.g., classification changed, package removed from registry, etc.)
                          default: ''
                          format: date-time
                        publishedAt:
                          type: string
                          description: ISO 8601 timestamp of when the package artifact was published to the respective registry
                          default: ''
                          format: date-time
                          nullable: true
                        description:
                          type: string
                          description: Detailed description of the underlying threat
                          default: ''
                        id:
                          type: integer
                          description: Unique identifier of the threat feed entry
                          default: 0
                        locationHtmlUrl:
                          type: string
                          description: URL to the threat details page on Socket
                          default: ''
                          format: uri
                        packageHtmlUrl:
                          type: string
                          description: URL to the affected package page on Socket
                          default: ''
                          format: uri
                        purl:
                          type: string
                          description: Package URL (PURL) of the affected package artifact
                          default: ''
                        removedAt:
                          type: string
                          description: ISO 8601 timestamp of when the package artifact was removed from the respective registry, or null if the package is still available on the registry
                          default: ''
                          format: date-time
                          nullable: true
                        threatType:
                          type: string
                          description: 'Threat classification. Possible values: `malware` (known malware), `possible_malware` (AI-detected potential malware), `vulnerability` (potential vulnerability),
                            `typosquat` (human-reviewed typosquat), `possible_typosquat` (AI-detected potential typosquat), `anomaly` (anomalous behavior), `telemetry` (telemetry), `obfuscated` (obfuscated
                            code), `dual_use` (dual-use tool), `troll` (protestware or joke package), `unreviewed` (not yet reviewed), `false_positive` (confirmed false positive).'
                          default: ''
                        needsHumanReview:
                          type: boolean
                          default: false
                          description: Whether the threat still is in need of human review by the threat research team
                        threatInstanceId:
                          type: integer
                          description: Unique threat instance identifier across artifacts
                          default: 0
                      description: ''
                    description: ''
                  nextPageCursor:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                required:
                - nextPageCursor
                - results
          description: The paginated list of items in the threat feed and the next page cursor.
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
components:
  requestBodies: {}
  responses:
    SocketBadRequest:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Bad request
    SocketUnauthorized:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Unauthorized
    SocketForbidden:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Insufficient max_quota for API method
    SocketNotFoundResponse:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource not found
    SocketTooManyRequestsResponse:
      description: Insufficient quota for API route
      headers:
        Retry-After:
          description: 'Retry contacting the endpoint *at least* after seconds.

            See https://tools.ietf.org/html/rfc7231#section-7.1.3'
          schema:
            format: int32
            type: integer
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
    SocketInternalServerError:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Internal server error
    SocketConflict:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource already exists
    SocketGone:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Gone
  schemas: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization Tokens can be passed as a Bearer token
    basicAuth:
      type: http
      scheme: basic
      description: Organization Tokens can be passed as the user field in basic auth