Synack Hosts API

openapi: 3.2.0
info:
  title: Asset Service Hosts API
  version: 2.1.020
  contact:
    name: Synack Engineering
    email: engineering@synack.com
  description: Host assets.
servers:
- url: https://client.synack.com/api/asset
  description: Commercial
- url: https://client.synack.us/api/asset
  description: FedRAMP (Medium)
tags:
- name: Hosts
  description: Host assets.
paths:
  /v2/assets/{assetUid}/ports/{portNumber}/{portProtocol}:
    parameters:
    - $ref: '#/components/parameters/AssetUIDPath'
    - $ref: '#/components/parameters/PortNumberPath'
    - $ref: '#/components/parameters/PortProtocolPath'
    put:
      x-excluded: true
      operationId: putHostPort
      tags:
      - Hosts
      description: 'Upsert a port to a host asset. Will return 409 status if the asset is not a single host (i.e. a CIDR).

        '
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        description: Port properties to upsert.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Port'
      responses:
        '200':
          $ref: '#/components/responses/SinglePort'
        '201':
          $ref: '#/components/responses/SinglePort'
        '204':
          $ref: '#/components/responses/204NoContent'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        '422':
          $ref: '#/components/responses/422EntityNotProcessable'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gw
        - asset_client_ow
        - asset_boss_ow
        - asset_client_lw
        - asset_boss_lw
    patch:
      x-excluded: true
      operationId: patchHostPort
      tags:
      - Hosts
      description: 'Update properties of a port belonging a single-IP host asset.

        '
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        description: Asset properties to patch.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortUpdate'
      responses:
        '200':
          $ref: '#/components/responses/SinglePort'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '412':
          $ref: '#/components/responses/412PreconditionFailed'
        '422':
          $ref: '#/components/responses/422EntityNotProcessable'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gw
        - asset_client_ow
        - asset_boss_ow
        - asset_client_lw
        - asset_boss_lw
    delete:
      x-excluded: true
      operationId: deleteHostPort
      tags:
      - Hosts
      description: 'Delete a port from a host asset. Will return 409 status if the asset is not a single host (i.e. a CIDR).

        '
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gw
        - asset_client_ow
        - asset_boss_ow
        - asset_client_lw
        - asset_boss_lw
  /v2/assets/{assetUid}/scope-rules:
    parameters:
    - $ref: '#/components/parameters/AssetUIDPath'
    get:
      x-excluded: true
      operationId: getScopeRules
      tags:
      - Hosts
      description: Gets a list of all scope rules for a host or web application asset.
      parameters:
      - $ref: '#/components/parameters/PerPageQuery'
      - $ref: '#/components/parameters/PageQuery'
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - rule
          - appliesTo
          - createdAt
          - updatedAt
        description: Optional property to sort results by.
        required: false
      - $ref: '#/components/parameters/SortDirQuery'
      responses:
        '200':
          $ref: '#/components/responses/PaginatedArrayOfScopeRules'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gr
        - asset_or
        - asset_srt_lr
    post:
      x-excluded: true
      operationId: postScopeRule
      tags:
      - Hosts
      description: Adds a scope rule to a web application or host asset. Returns a 409 status code if the asset is not one of these expected types.
      requestBody:
        description: Host or web application scope rule to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopeRule'
      responses:
        '201':
          $ref: '#/components/responses/SingleScopeRuleResponse'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '422':
          $ref: '#/components/responses/422EntityNotProcessable'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gw
        - asset_client_ow
        - asset_boss_ow
        - asset_client_lw
        - asset_boss_lw
  /v2/scope-rules/{scopeRuleUid}:
    parameters:
    - $ref: '#/components/parameters/ScopeRuleUIDPath'
    get:
      x-excluded: true
      operationId: getScopeRule
      tags:
      - Hosts
      description: Retrieve a scope rule.
      responses:
        '200':
          $ref: '#/components/responses/SingleScopeRuleResponse'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gr
        - asset_or
        - asset_lr
    patch:
      x-excluded: true
      operationId: patchScopeRule
      tags:
      - Hosts
      description: Patch properties of a scope rule for a host asset with CIDRs or web application asset. Will return a 409 status code if the type is not one of these expected types.
      requestBody:
        description: Scope rule to patch.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopeRuleUpdate'
      responses:
        '200':
          $ref: '#/components/responses/SingleScopeRuleResponse'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '422':
          $ref: '#/components/responses/422EntityNotProcessable'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gw
        - asset_client_ow
        - asset_boss_ow
        - asset_client_lw
        - asset_boss_lw
    delete:
      x-excluded: true
      operationId: deleteScopeRule
      tags:
      - Hosts
      description: Delete a scope rule from a host or web application asset. Will return a 409 status code if the type is not one of these expected types.
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gw
        - asset_client_ow
        - asset_boss_ow
        - asset_client_lw
        - asset_boss_lw
components:
  schemas:
    Updatable:
      allOf:
      - $ref: '#/components/schemas/Creatable'
      - type: object
        properties:
          updatedAt:
            type: string
            format: date-time
            readOnly: true
            description: Automatically set by the server to the time the request was processed whenever the resource is updated.
          updatedBy:
            $ref: '#/components/schemas/OperationUserUID'
    PortUpdate:
      type: object
      properties:
        scope:
          $ref: '#/components/schemas/Scope'
        service:
          type: string
          description: 'Name of service running on port. Will use the [Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml) for well-known ports.

            '
        observedState:
          $ref: '#/components/schemas/PortObservedState'
    FailedValidation:
      type: object
      required:
      - message
      properties:
        property:
          type: string
          readOnly: true
        value:
          type: string
          readOnly: true
        message:
          type: string
          readOnly: true
    PortNumber:
      type: integer
      format: int32
      minimum: 0
      maximum: 65535
    PortProtocol:
      type: string
      enum:
      - tcp
      - udp
    ScopeRuleApplicability:
      type: string
      enum:
      - scanners
      - srt
      - both
    WebRULE:
      type: string
      pattern: ^(/([a-zA-Z0-9_-~!$&'()+,;=:@.]|%[0-9a-fA-F]{2})+/)*(/?((([A-z]|[0-9]|[-_~])|%[0-9a-fA-F]{2}|[!$&'()*+,;=]|[:@])|[/?])*){0,1}//(#((([A-z]|[0-9]|[-_~.])|%[0-9a-fA-F]{2}|[!$&'()*+,;=]|[:@])|[/?])*){0,1}/?$
      description: Rule for web asset validation
    Port:
      allOf:
      - type: object
        required:
        - scope
        - observedState
        properties:
          number:
            $ref: '#/components/schemas/PortNumber'
          protocol:
            $ref: '#/components/schemas/PortProtocol'
          scope:
            $ref: '#/components/schemas/Scope'
          service:
            type: string
            description: 'Name of (expected) service running on port. Will use the [Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml) for well-known ports.

              '
          observedState:
            $ref: '#/components/schemas/PortObservedState'
          detectedService:
            type: string
            description: 'Name of detected service running on port according to fingerprinting.

              '
            readOnly: true
          detectedProductName:
            type: string
            description: 'Name of software product running on port according to fingerprinting.

              '
            readOnly: true
          detectedProductVersion:
            type: string
            description: Version of software product running on port according to fingerprinting.
            readOnly: true
          detectedProductConfidenceLevel:
            type: integer
            format: int
            minimum: 1
            maximum: 10
            description: Confidence level of detected product on port according to fingerprinting.
            readOnly: true
          detectedProductCPE:
            type: string
            description: 'CPE for detected product according to fingerprinting.

              '
            readOnly: true
          serviceBanner:
            type: string
            description: Port banner according to fingerprinting.
            readOnly: true
      - $ref: '#/components/schemas/Updatable'
    ScopeRuleInclusion:
      type: string
      enum:
      - in
      - out
    ArrayOfScopeRules:
      type: array
      items:
        $ref: '#/components/schemas/ScopeRule'
    IndexedFailedValidations:
      type: object
      properties:
        index:
          type: integer
          description: Zero-based index indicating the which item in request containing an array of items has failed validation.
          readOnly: true
        failedValidation:
          type: array
          description: Array of failed validation rules.
          readOnly: true
          items:
            $ref: '#/components/schemas/FailedValidation'
    ScopeRule:
      allOf:
      - $ref: '#/components/schemas/ScopeRuleSummary'
      - $ref: '#/components/schemas/Updatable'
    Scope:
      description: 'Set to _in_-scope means automated and manual testing _should_ occur; _out_-of-scope means automated and manual testing _must not_ occur; _discovered_ means observed through automated discovery and may be automatically removed if not observed again during subseqent discovery activities.

        '
      type: string
      enum:
      - in
      - out
      - discovered
      - blocked
    ProblemDetails:
      type: object
      description: 'See [RFC 7807: Problem Details for HTTP APIs](https://tools.ietf.org/html/rfc7807)'
      properties:
        type:
          type: string
          readOnly: true
        title:
          type: string
          readOnly: true
        status:
          type: integer
          format: int32
          minimum: 100
          maximum: 511
          description: HTTP Status code.
          readOnly: true
        detail:
          type: string
          description: Message detailing the problem.
          readOnly: true
        instance:
          type: string
          description: generated problem instance number to correlate with logs
          readOnly: true
        failedValidation:
          type: array
          description: Array of failed validation rules.
          readOnly: true
          items:
            $ref: '#/components/schemas/FailedValidation'
        failedValidations:
          type: array
          description: Array of indexed failed validation rules.
          readOnly: true
          items:
            $ref: '#/components/schemas/IndexedFailedValidations'
        maxBatchSize:
          type: integer
          description: Maximum processable batch size.
          readOnly: true
        batchSize:
          type: integer
          description: Batch size sent when batch is too large.
          readOnly: true
    OperationUserUID:
      type: string
      pattern: ^[0-9a-f]{12}
      readOnly: true
      description: Automatically set by the server to the requesting user whenever the resource is updated. May be a user account or a service account if the action is performed by an automated.
    ScopeRuleUpdate:
      type: object
      description: Updatable properties of a Scope Rule.
      properties:
        rule:
          type: string
          description: A textual definition of the scope rule. Format will vary by assetType.
        scope:
          $ref: '#/components/schemas/ScopeRuleInclusion'
        appliesTo:
          $ref: '#/components/schemas/ScopeRuleApplicability'
    UID:
      type: string
      pattern: ^[0-9a-f]{12}
      readOnly: true
      description: Unique Identifier.
    Creatable:
      type: object
      required:
      - createdAt
      - createdBy
      properties:
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Automatically set by the server to the time the request was processed whenever the resource was created.
        createdBy:
          $ref: '#/components/schemas/OperationUserUID'
    PortObservedState:
      type: string
      enum:
      - open
      - closed
      - filtered
      description: Observed state reported by automated scanning.
    AssetUID:
      type: string
      pattern: ^[0-9a-f]{24}
      description: Unique identifier for an asset.
    ScopeRuleSummary:
      type: object
      description: Part of the scope of an asset that is included/excluded from a specific activity.
      required:
      - uid
      - rule
      - scope
      - appliesTo
      properties:
        uid:
          $ref: '#/components/schemas/UID'
        rule:
          $ref: '#/components/schemas/WebRULE'
          description: A textual definition of the scope rule. Format will vary by assetType.
        scope:
          $ref: '#/components/schemas/ScopeRuleInclusion'
        appliesTo:
          $ref: '#/components/schemas/ScopeRuleApplicability'
  responses:
    404NotFound:
      description: Not found.
    412PreconditionFailed:
      description: Precondition Failed.
    401Unauthorized:
      description: Unauthorized.
    PaginatedArrayOfScopeRules:
      description: Paginated scope rules of a host with CIDRs or web application asset.
      headers:
        Pagination-Limit:
          $ref: '#/components/headers/PaginationLimit'
        Pagination-Current-Page:
          $ref: '#/components/headers/PaginationCurrentPage'
        Pagination-Total-Pages:
          $ref: '#/components/headers/PaginationTotalPages'
        Pagination-Total-Count:
          $ref: '#/components/headers/PaginationTotalCount'
        Link:
          $ref: '#/components/headers/Link'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ArrayOfScopeRules'
    SinglePort:
      description: The current state of a host port.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Port'
    SingleScopeRuleResponse:
      description: The current state of a scope rule.
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScopeRule'
    503ServiceUnavailable:
      description: Service Unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    500InternalServerError:
      description: Internal Server Error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    204NoContent:
      description: No content.
    403Forbidden:
      description: Forbidden
    409Conflict:
      description: Conflict.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    422EntityNotProcessable:
      description: Entity Not Processable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
  parameters:
    PortNumberPath:
      name: portNumber
      in: path
      schema:
        $ref: '#/components/schemas/PortNumber'
      required: true
      description: Port number.
    PerPageQuery:
      name: perPage
      in: query
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 5000
      required: false
      description: 'Requested page size for pagination. A server-selected default of 100 will be used when no perPage is requested via query parameter.

        '
    SortDirQuery:
      name: sortDir
      in: query
      schema:
        type: string
        enum:
        - asc
        - desc
        default: asc
      required: false
      description: Direction of sort-order for items in the response.
    PageQuery:
      name: page
      in: query
      schema:
        type: integer
        format: int32
        minimum: 1
      required: false
      description: 'Page to retrieve in paginated response. A server-selected default of 1 will be used when no page is requested via query parameter.

        '
    AssetUIDPath:
      name: assetUid
      in: path
      schema:
        $ref: '#/components/schemas/AssetUID'
      required: true
      description: Unique identifier for an asset.
    PortProtocolPath:
      name: portProtocol
      in: path
      schema:
        $ref: '#/components/schemas/PortProtocol'
      required: true
      description: Port protocol.
    IfMatch:
      name: If-Match
      in: header
      required: true
      description: 'Used to prevent the lost-update problem. The operation will only

        continue if the ETag of the resource matches the supplied value;

        other was a 412 status will be returned. Provide a returned

        ETag value or * to force the operation.

        '
      schema:
        type: string
        pattern: ^(?:\".*\"|\*)$
    ScopeRuleUIDPath:
      name: scopeRuleUid
      in: path
      schema:
        $ref: '#/components/schemas/UID'
      required: true
      description: Unique identifier for a scope rule.
  headers:
    Link:
      description: Standard link header.
      schema:
        type: string
    PaginationTotalPages:
      description: Total number of pages in a paginated response.
      schema:
        type: integer
        format: int32
        minimum: 1
    PaginationTotalCount:
      description: Total number of items in all pages of a paginated response.
      schema:
        format: int32
        minimum: 1
    PaginationLimit:
      description: Maximum number of items returned in a paginated response.
      schema:
        type: integer
        format: int32
        minimum: 1
    ETag:
      description: An identifier for a specific version of a resource
      schema:
        type: string
        pattern: ^(?:W\/)?\".*\"$
    PaginationCurrentPage:
      description: Current page in a paginated response.
      schema:
        type: integer
        format: int32
        minimum: 1
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: login.synack.com
          scopes:
            asset_lr: Grants per-listing read access for all types of assets.
            asset_srt_lr: Grants per-listing read access to assets that may be read by SRTs.
            asset_or: Grants organization-level read access for all types of assets owned by a particular organization.
            asset_boss_ow: Grants organization-level access to assets owned by a particular organization that may be modified by BOSS users.
            asset_boss_lw: Grants per-listing write access to assets that may be modified by BOSS users.
            asset_client_ow: Grants organization-level access to assets owned by a particular organization that may be modified by Client users.
            asset_client_lw: Grants per-listing write access to assets that may be modified by Client users.
            asset_user_or: Grants user-level read access to asset stats that owned by a particular organization.
            asset_gr: Grants unrestricted read access to all assets. Except for credential data of cloud accout assets.
            asset_gw: Grants unrestricted write access to all assets.
            asset_scan_gr: Grants unrestricted read access to all assets. Including credential data of cloud account assets.