Synack Suspected Vulnerabilities API

openapi: 3.1.0
info:
  title: Assessment Service Assessment Groups Suspected Vulnerabilities API
  version: 1.0.0
  description: 'APIs for managing Assessment and related operations on the Synack.

    '
  contact:
    name: Synack Engineering
    email: engineering@synack.com
servers:
- url: https://client.synack.com/api/assessment
  description: Commercial
- url: https://client.synack.us/api/assessment
  description: FedRAMP (Medium)
security:
- bearerAuth: []
tags:
- name: Suspected Vulnerabilities
  description: Operations related to suspected vulnerabilities
paths:
  /v1/suspected_vulnerabilities/{id}:
    patch:
      operationId: updateSuspectedVulnerability
      summary: Update a suspected vulnerability
      description: Update a specific suspected vulnerability's status
      tags:
      - Suspected Vulnerabilities
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Suspected vulnerability ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - vulnerability_status_id
              properties:
                vulnerability_status_id:
                  type: integer
                  description: New vulnerability status ID
      responses:
        '200':
          description: Suspected vulnerability updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuspectedVulnerability'
        '400':
          description: Bad request
        '404':
          description: Suspected vulnerability not found
  /v1/{org_uid}/assets/{asset_uid}/suspected_vulns:
    get:
      x-mint:
        metadata:
          title: Get Suspected Vulnerabilities for an Asset
      summary: Returns list of suspected vulnerabilities on a given organization and asset uid
      description: Get asset suspected vulnerabilities by organization and assets uid
      operationId: getAssetSuspectedVulnerabilities
      tags:
      - Suspected Vulnerabilities
      parameters:
      - name: org_uid
        in: path
        description: Organization UID
        required: true
        schema:
          type: string
      - name: asset_uid
        in: path
        description: Asset UID
        required: true
        schema:
          type: string
      - name: statuses[]
        in: query
        description: Suspected vulnerability status
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - in_triage
            - vulnerable
            - not_vulnerable
            - qualified
            - info_low
      - name: vuln_cvss[]
        in: query
        description: Suspected vulnerability CVSS range [0.0-0.0, 0.1-3.9, 4.0-6.9, 7.0-8.9, 9.0-10.0]
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: include_expired
        in: query
        description: Include expired suspected vulnerabilities
        schema:
          type: boolean
      - name: listing_uids[]
        in: query
        description: Listing uids
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: order_by
        in: query
        description: Order by [title, severity, location, created_at, status, listing_codename]
        schema:
          type: string
          default: severity
          enum:
          - title
          - severity
          - location
          - created_at
          - status
          - listing_codename
      - name: order_direction
        in: query
        description: Order direction [asc desc]
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - name: per_page
        in: query
        description: Maximum number of results to be returned
        schema:
          type: integer
      - name: page
        in: query
        description: If provided, show the provided page
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Bearer token is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/organizations/{organizationUid}/suspected-vulnerabilities:
    get:
      summary: Retrieve suspected vulnerabilities for an organization
      description: 'Fetches a paginated list of suspected vulnerabilities associated with a specific organization.

        Supports comprehensive filtering by status, source, listings, categories, and search queries.

        '
      operationId: getSuspectedVulnerabilities
      tags:
      - Suspected Vulnerabilities
      parameters:
      - name: organizationUid
        in: path
        description: Unique identifier for the organization whose vulnerabilities are being retrieved
        required: true
        schema:
          type: string
      - name: status[]
        in: query
        description: 'Filter vulnerabilities by their current status (e.g, qualified, in_triage, vulnerable, not_vulnerable, qualified)

          '
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: automatedTriageStatus[]
        in: query
        description: 'Filter by automated triage status. Indicates whether the vulnerability has been processed

          through automated triage workflows and its current automated assessment state. (e.g., eligible, ineligible, agent_review, ops_review, vulnerable, not_vulnerable, target_unreachable, out_of_scope, not_applicable)

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: source[]
        in: query
        description: 'Filter by vulnerability detection source (e.g., ''synack'', ''tenable'', ''qualys'', ''tenablewas'').

          Identifies the tool or method that originally discovered the vulnerability.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sourceId[]
        in: query
        description: 'Filter by vulnerability detection source ID/job ID. This represents the specific

          batch or job identifier from external scanning tools that discovered the vulnerability.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: listingUid[]
        in: query
        description: 'Filter vulnerabilities by specific listing UIDs. Listings represent individual penetration

          testing engagements.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: categoryId[]
        in: query
        description: 'Filter by vulnerability category ID. Categories classify vulnerabilities by type

          (e.g., authorization_permissions/cross_origin_resource_sharing_cors, cross_site_scripting_xss/) to organize findings.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: listingCategoryId[]
        in: query
        description: 'Filter by the specific category of listings (penetration testing scopes).

          Helps narrow results to particular types of security assessments. (e.g., web application, mobile)

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: severity[]
        in: query
        description: 'Filter by the specific severity of vulnerabilities.

          Helps narrow results to particular types of security. (e.g., low, medium, high, critical, none)

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: exportFormat
        in: query
        description: 'Specify the format for data export: ''csv'' for spreadsheet analysis. When provided, returns downloadable file instead of JSON.

          '
        schema:
          type: string
      - name: exportData[]
        in: query
        description: 'Specify which fields to include in exported files. Allows customization of export

          content to include only relevant fields for specific reporting or analysis needs.

          Will return all fields by default.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: exportColumnNames[]
        in: query
        description: 'Specify the column headers for the exported file. Returns all custom names for headers in the file, it will be the same as SuspectedVulnerabilityResponse by default.

          '
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: query
        in: query
        description: 'Free-text search query to filter vulnerabilities. Searches across vulnerability titles,

          descriptions, asset information, and other relevant text fields for matching content.

          '
        style: form
        schema:
          type: string
      - name: perPage
        in: query
        description: 'Maximum number of vulnerability records to return per page. Controls pagination size

          for better performance and manageable result sets. Typical values range from 10-100.

          '
        schema:
          type: integer
      - name: page
        in: query
        description: 'Page number for paginated results. Used in conjunction with perPage to navigate

          through large result sets. Page numbering starts from 1.

          '
        schema:
          type: integer
      - name: sort
        in: query
        schema:
          type: string
          default: lastDetectedAt
        description: 'Field to sort results by: ''createdAt'' for chronological discovery, ''lastDetectedAt''

          for most recent activity, or ''cvssBase'' for severity-based ordering.

          '
      - name: sortDir
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: 'Sort direction: ''asc'' for ascending or ''desc'' for descending order.

          '
      responses:
        '200':
          $ref: '#/components/responses/SuspectedVulnerabilitiesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - OAuth2:
        - asset_gr
        - asset_or
        - asset_lr
    post:
      summary: Add suspected vulnerabilities for an organization
      description: Add suspected vulnerabilities for an organization, creating corresponding assets if needed. On success returns list of numeric IDs of the newly created suspected vulnerabilities
      operationId: postSuspectedVulnerabilities
      tags:
      - Suspected Vulnerabilities
      parameters:
      - name: organizationUid
        in: path
        description: Unique identifier for the organization
        required: true
        schema:
          type: string
        x-go-name: orgUID
      requestBody:
        description: Request body containing the list of objects, describing the properties of suspected vulnerabilities to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuspectedVulnerabilitiesCreateRequest'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/SuspectedVulnerabilitiesCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - OAuth2:
        - asset_gr
        - asset_gw
  /v1/organizations/{organizationUid}/suspected-vulnerabilities/{id}:
    get:
      tags:
      - Suspected Vulnerabilities
      summary: Retrieve a specific suspected vulnerability
      description: 'Fetches detailed information for a single suspected vulnerability by its unique identifier.

        Returns comprehensive vulnerability data including metadata, triage information, and related assets.

        '
      operationId: getSuspectedVulnerability
      parameters:
      - name: organizationUid
        in: path
        required: true
        description: 'Unique identifier for the organization that owns the vulnerability being retrieved

          '
        schema:
          type: string
      - name: id
        in: path
        description: 'Unique identifier for the specific suspected vulnerability to retrieve

          '
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          $ref: '#/components/responses/SuspectedVulnerabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
      - OAuth2:
        - asset_gr
        - asset_or
        - asset_lr
components:
  responses:
    Forbidden:
      description: 'Forbidden - Access denied. The authenticated user lacks permission to access

        the requested resource or perform the specified operation.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    SuspectedVulnerabilitiesResponse:
      description: 'Successfully retrieved a paginated list of suspected vulnerabilities matching the

        specified filter criteria, including metadata for pagination and summary statistics.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              suspectedVulnerabilities:
                type: array
                description: List of suspected vulnerabilities matching the filter criteria
                items:
                  $ref: '#/components/schemas/SuspectedVulnerability_2'
              metadata:
                type: object
                description: Response metadata including pagination and summary information
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  summaries:
                    $ref: '#/components/schemas/SuspectedVulnerabilitiesSummaries'
                  actions:
                    type: object
                    description: Available actions for the suspected vulnerabilities collection
        text/csv:
          schema:
            type: string
            description: CSV data of the suspected vulnerabilities
            example: 'Asset UID,Reason Title,Reason Description,Severity,CVSS Base,Automated Triage Status,Confidence,False Positive,Source

              ah28034gsjdf98eqwgbjufj,Test Reason Title,Test Reason Description,Low,5.4,srt_review,firm,true,synack

              ah28034gsjdf98eqwgbjufj,Test Reason Title,Test Reason Description,Medium,6.4,srt_review,tentative,false,synack

              '
    UnprocessableEntity:
      description: 'Unprocessable Entity - The request is well-formed but contains semantic errors

        or business logic violations that prevent processing (e.g., invalid status transitions).

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    SuspectedVulnerabilityResponse:
      description: 'Successfully retrieved detailed information for a single suspected vulnerability,

        including associated triage data and related metadata.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              suspectedVulnerability:
                $ref: '#/components/schemas/SuspectedVulnerabilityWithTriages'
              metadata:
                $ref: '#/components/schemas/Metadata'
    NotFound:
      description: 'Not Found - The requested resource does not exist. This may occur when

        referencing invalid organization UIDs or non-existent vulnerability IDs.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    Unauthorized:
      description: 'Unauthorized - Authentication failed. The bearer token is missing, expired,

        invalid, or lacks sufficient permissions to access this resource.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    BadRequest:
      description: 'Bad Request - The request is malformed, contains invalid parameters, or missing

        required fields. Check request syntax and parameter values.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    SuspectedVulnerabilitiesCreateResponse:
      description: Response to a POST request, inserting new suspected vulnerabilities for the organization
      content:
        application/json:
          schema:
            type: array
            description: List of numeric identifiers of newly created suspected vulnerabilities
            items:
              type: integer
    InternalServerError:
      description: 'Internal Server Error - An unexpected server-side error occurred. This indicates

        a system issue that should be reported to the engineering team for investigation.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    UnexpectedError:
      description: 'Unexpected Error - An unhandled error condition occurred. This represents

        an edge case scenario that requires technical support intervention.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
  schemas:
    StringMap:
      type: object
      additionalProperties:
        type: string
    ExternalJobTriageAgentToolExecution:
      type: object
      description: Tool execution data for a vulnerability triage, including analysis and reporting
      properties:
        name:
          type: string
          description: Name of the tool
        input:
          type: string
          description: Input to the tool
        output:
          type: string
          description: Output of the tool
        error:
          type: string
          description: Error of the tool
    ExternalJobTriageAgentBlock:
      type: object
      description: Block data for a vulnerability triage, including analysis and reporting
      properties:
        parentThoughtId:
          type: string
          description: Unique identifier for the parent thought
        predecessorThoughtId:
          type: string
          description: Unique identifier for the predecessor thought
    SuspectedVulnerabilitiesCreateRequest:
      description: List of objects, describing the properties of suspected vulnerabilities to create
      type: array
      items:
        $ref: '#/components/schemas/NewSuspectedVulnerability'
    SuspectedVulnerabilitiesSummaries_SummarySeverity:
      type: object
      description: Summary severity of the vulnerabilities
      properties:
        critical:
          type: integer
          description: Number of critical severity vulnerabilities
        high:
          type: integer
          description: Number of high severity vulnerabilities
        medium:
          type: integer
          description: Number of medium severity vulnerabilities
        low:
          type: integer
          description: Number of low severity vulnerabilities
        none:
          type: integer
          description: Number of vulnerabilities with no assigned severity
          example: 0
        total:
          type: integer
          description: Total number of vulnerabilities across all severity levels
          example: 100
    Relationship:
      type: object
      properties:
        data: {}
        links:
          $ref: '#/components/schemas/Links'
    Data:
      type: object
      properties:
        attributes: {}
        id:
          type: string
        links:
          $ref: '#/components/schemas/Links'
        meta: {}
        relationships:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Relationship'
        type:
          $ref: '#/components/schemas/ResourceType'
    ExternalJobTriageAgentThought:
      type: object
      description: Thought data for a vulnerability triage, including analysis and reporting
      properties:
        triageId:
          type: string
          description: Unique identifier for this triage assessment
        targetId:
          type: string
          description: Unique identifier for the target of this triage assessment
        thoughtId:
          type: string
          description: Unique identifier for this thought
        thoughtType:
          type: string
          description: Type of thought
        thoughtContent:
          type: string
          description: Content of the thought
        toolExecution:
          $ref: '#/components/schemas/ExternalJobTriageAgentToolExecution'
        block:
          $ref: '#/components/schemas/ExternalJobTriageAgentBlock'
        addedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the thought was added
    SuspectedVulnerabilitiesSummaries_Counts:
      type: object
      description: Numerical counts of vulnerabilities grouped by various attributes
      properties:
        severity:
          $ref: '#/components/schemas/SuspectedVulnerabilitiesSummaries_SummarySeverity'
        status:
          $ref: '#/components/schemas/SuspectedVulnerabilitiesSummaries_SummaryStatus'
    Pagination:
      type: object
      description: Pagination metadata for navigating through large result sets
      required:
      - total
      - page
      - perPage
      - totalPages
      properties:
        total:
          type: integer
          description: Total number of items across all pages
        page:
          type: integer
          description: Current page number (1-based)
        perPage:
          type: integer
          description: Number of items per page
        totalPages:
          type: integer
          description: Total number of pages available
        prev:
          type: string
          description: URL for the previous page (null if on first page)
        next:
          type: string
          description: URL for the next page (null if on last page)
        first:
          type: string
          description: URL for the first page
        last:
          type: string
          description: URL for the last page
        self:
          type: string
          description: URL for the current page
    Error:
      type: object
      properties:
        detail:
          type: string
        id:
          type: string
        source:
          type: string
        status:
          type: integer
        title:
          type: string
    SuspectedVulnerability:
      type: object
      properties:
        id:
          type: integer
        asset_uid:
          type: string
        category_in_scope:
          type: boolean
        confidence:
          type: number
          format: float
        cvss_base:
          type: number
          format: float
        exploitable_locations:
          type: array
          items:
            type: string
        false_positive:
          type: boolean
        created_at:
          type: string
          format: date-time
        last_detected_at:
          type: string
          format: date-time
        payload:
          type: object
        reference_urls:
          type: array
          items:
            type: string
        severity:
          type: string
        source:
          type: string
        status:
          type: string
        vulnerability_status_id:
          type: integer
        reason_title:
          type: string
        reason_description:
          type: string
        organization_profile_id:
          type: integer
        automated_triage_status:
          type: string
        automated_triage_status_updated_at:
          type: string
          format: date-time
    Metadata:
      type: object
      description: Additional metadata accompanying API responses
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        actions:
          type: object
          description: Available actions that can be performed on the returned data
    ResourceType:
      type: string
      enum:
      - asset_list
      - assets_counts
      - asset_details
      - asset_whois
      - asset_ports
      - asset_providers
      - asset_seed_groups
      - health_check
      - org_asset_ports
      - org_asset_suspected_vulns
      - org_asset_vulns
      - org_asset_listings_tests_latest
      - top_vulnerable_ports
      - top_unique_ports
      - most_recently_added_assets
      - top_cisa_cves
      - top_vulnerable_ips
      - asset_gateways
      - tags
      - last_tested_counts
      - last_assets_scan
    SuspectedVulnerabilityWithTriages:
      description: 'Extended suspected vulnerability schema that includes embedded triage assessments.

        Used specifically for single vulnerability responses where triage data is included.

        '
      allOf:
      - $ref: '#/components/schemas/SuspectedVulnerability_2'
      - type: object
        properties:
          triages:
            type: array
            description: Associated triage assessments for this vulnerability
            items:
              $ref: '#/components/schemas/SuspectedVulnerabilityTriage'
    SuspectedVulnerabilitiesSummaries:
      type: object
      description: Statistical summary information about the vulnerabilities in the result set
      properties:
        counts:
          $ref: '#/components/schemas/SuspectedVulnerabilitiesSummaries_Counts'
    SuspectedVulnerabilitiesSummaries_SummaryStatus:
      type: object
      description: Summary status of the vulnerabilities
      properties:
        eligible:
          type: integer
          description: Number of eligible vulnerabilities
          example: 10
        ineligible:
          type: integer
          description: Number of ineligible vulnerabilities
          example: 10
        agent_review:
          type: integer
          description: Number of vulnerabilities awaiting agent review
          example: 10
        ops_review:
          type: integer
          description: Number of vulnerabilities awaiting operations team review
          example: 10
        srt_review:
          type: integer
          description: Number of vulnerabilities awaiting security research team review
          example: 10
        vulnerable:
          type: integer
          description: Number of confirmed vulnerable findings
          example: 10
        not_vulnerable:
          type: integer
          description: Number of findings determined to be not vulnerable
          example: 10
        out_of_scope:
          type: integer
          description: Number of findings determined to be out of scope
          example: 10
        target_unreachable:
          type: integer
          description: Number of findings determined to be target unreachable
          example: 10
        not_applicable:
          type: integer
          description: Number of findings determined to be not applicable
          example: 10
        total:
          type: integer
          description: Total number of vulnerabilities across all status categories
          example: 100
    Error_2:
      type: object
      description: Standard error response format following RFC 7807 Problem Details specification
      required:
      - status
      - title
      properties:
        type:
          type: string
          description: URI reference that identifies the problem type
        status:
          type: integer
          description: HTTP status code for this occurrence of the problem
        title:
          type: string
          description: Human-readable summary of the problem type
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
        instance:
          type: string
          description: URI reference identifying the specific occurrence of the problem
    Links:
      type: object
      properties:
        next:
          type: string
        prev:
          type: string
    SuspectedVulnerability_2:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique numeric identifier for the suspected vulnerability
          example: 2000
        assetUid:
          type: string
          description: Unique identifier for the asset where the vulnerability was discovered
          example: ah28034gsjdf98eqwgbjufj
        listingUid:
          type: string
          description: Unique identifier for the penetration testing listing/engagement scope
          example: ah28034gsjdf
        listingCodename:
          type: string
          description: Human-readable codename for the penetration testing engagement
          example: ACME-H001
        organizationUid:
          type: string
          description: Unique identifier for the organization that owns this vulnerability
          example: ah28034gsjdf
        categoryInScope:
          type: boolean
          description: Indicates whether this vulnerability category is within the current testing scope
        confidence:
          type: string
          description: Confidence level of the vulnerability assessment (e.g., 'firm', 'tentative', 'certain')
          example: firm
        cvssBase:
          type: number
          format: double
          description: CVSS (Common Vulnerability Scoring System) base score indicating severity (0-10 scale)
          example: 5.4
        exploitableLocations:
          type: array
          description: List of key-value maps describing exploitable locations
          items:
            $ref: '#/components/schemas/StringMap'
        falsePositive:
          type: boolean
          description: Flag indicating whether this vulnerability has been determined to be a false positive
        payload:
          type: object
          description: Additional vulnerability data and metadata from the detection source
          $ref: '#/components/schemas/StringMap'
        referenceUrls:
          type: array
          items:
            type: string
          description: External reference URLs providing additional context about the vulnerability
          example:
          - https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring_ec2.html
          - https://docs.aws.amazon.com/AWSEC2/latest/APIRef

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/synack/refs/heads/main/openapi/synack-suspected-vulnerabilities-api-openapi.yml