Spyderbat Spyctl API

openapi: 3.2.0
info:
  title: Spyderbat API UI & Public Spyctl API
  description: Restful APIs for use by UI & customers.
  termsOfService: https://www.spyderbat.com/terms-of-use/
  contact:
    name: API Support
    url: https://api.prod.spyderbat.com/openapi
    email: support@spyderbat.com
  license:
    name: MIT
    url: https://mit-license.org/
  version: 1.0.0
  x-logo:
    url: /static/sb-logo.svg
    backgroundColor: '#161A21'
    altText: Spyderbat Logo
servers:
- url: https://api.prod.spyderbat.com/
  description: Spyderbat API Server
security:
- apiToken: []
tags:
- name: Spyctl
  description: A way to execute specific Spyctl logic via the API.
paths:
  /api/v1/org/{orgUID}/spyctl/diff/:
    post:
      tags:
      - Spyctl
      summary: Diff spyderbat documents
      description: This will diff one or more spyderbat documents with a primary document and return the diff output.
      operationId: SpyctlDiff
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpyctlDiffInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlDiffOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/guardianpolicy/build/:
    post:
      tags:
      - Spyctl
      summary: Build a new Guardian Policy document
      description: 'This will build and return a new Guardian Policy document which can then be applied via the AnalyticsPolicy API.

        * Requires the user have the action *spyctl:GuardianPolicyBuild'
      operationId: GuardianPolicyBuild
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuardianPolicyBuildInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlGuardianPolicyBuildOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/merge/:
    post:
      tags:
      - Spyctl
      summary: Merge spyderbat documents
      description: This will merge one or more spyderbat documents into a primary document and return the merged document.
      operationId: SpyctlMerge
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpyctlMergeInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlMergeOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/report:
    post:
      tags:
      - Spyctl
      summary: Generate a spyderbat report
      description: This will schedule a report to be generated based on provided input report type and arguments.
      operationId: SpyctlReportGenerate
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpyctlReportGenerateInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlReportOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/report/:
    get:
      tags:
      - Spyctl
      summary: Get list of spyderbat reports for an org
      description: This will return the list of reports generated for an organization.
      operationId: SpyctlReportList
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlReportListOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
    post:
      tags:
      - Spyctl
      summary: Get list of spyderbat reports for an org, paginated
      description: This will return the list of reports generated for an organization, paginated with 1000 reports per page.
      operationId: SpyctlReportListPager
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpyctlReportListPagerInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlReportListPagerOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/report/download/{id.format}:
    get:
      tags:
      - Spyctl
      summary: Download a spyderbat report
      description: This will download a published report.
      operationId: SpyctlReportDownload
      parameters:
      - name: id.format
        in: path
        description: identifier and format, delimited by a dot for the report and format to download
        required: true
        schema:
          type: string
          description: identifier and format, delimited by a dot for the report and format to download
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/report/inventory:
    get:
      tags:
      - Spyctl
      summary: Report inventory of spyderbat reports
      description: This will return a report of the inventory of available spyderbat reports to generate and their metadata.
      operationId: SpyctlReportInventory
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlReportInventoryOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/report/status/{id}:
    get:
      tags:
      - Spyctl
      summary: Check status of spyderbat report
      description: This will check for the generation status of a report and return all the report metadata.
      operationId: SpyctlReportStatus
      parameters:
      - name: id
        in: path
        description: identifier for the report to check status for
        required: true
        schema:
          type: string
          description: identifier for the report to check status for
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlReportOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/report/{id}:
    delete:
      tags:
      - Spyctl
      summary: Delete a spyderbat report
      description: This will delete a report.
      operationId: SpyctlReportDelete
      parameters:
      - name: id
        in: path
        description: identifier for the report to check status for
        required: true
        schema:
          type: string
          description: identifier for the report to check status for
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlReportDeleteOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/suppressionpolicy/build/:
    post:
      tags:
      - Spyctl
      summary: Build a new Suppression Policy document
      description: 'This will build and return a new Suppression Policy document which can then be applied via the AnalyticsPolicy API.

        * Requires the user have the action *spyctl:SuppressionPolicyBuild'
      operationId: SuppressionPolicyBuild
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuppressionPolicyBuildInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlSuppressionPolicyBuildOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
  /api/v1/org/{orgUID}/spyctl/validate/:
    post:
      tags:
      - Spyctl
      summary: Validate a spyderbat document
      description: This will verify that a spyderbat document matches a validation schema. If the document is not valid, this will return a message detailing the error.
      operationId: SpyctlValidate
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpyctlValidateInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSpyctlValidateOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
components:
  schemas:
    SessionSpyctlReportSpec:
      type: object
      properties:
        args:
          type: array
          items:
            $ref: '#/components/schemas/SessionSpyctlReportSpecArgument'
          description: List of arguments for the report
        description:
          type: string
          description: Long form description of the report
        id:
          type: string
          description: Name of the report
        short:
          type: string
          description: Short form description of the report
        supported_formats:
          type: array
          items:
            type: string
          description: List of output formats available for the report
    SessionSpyctlSuppressionPolicyBuildOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        policy:
          $ref: '#/components/schemas/DaoPolicyObject'
    GuardianPolicyBuildInput:
      type: object
      properties:
        input_objects:
          type: array
          items:
            $ref: '#/components/schemas/DaoAnalyticResourceObject'
          description: Fingerprints, FingerprintGroup, or Baseline to create a Guardian Policy from.
        mode:
          type: string
          description: The enforcement mode of the policy.
        name:
          type: string
          description: Custom name for the suppression policy
          maxLength: 64
      required:
      - input_objects
      - mode
    SessionSpyctlReportDeleteOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
    SessionSpyctlGuardianPolicyBuildOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        policy:
          $ref: '#/components/schemas/DaoPolicyObject'
    SessionSpyctlMergeOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        merged_object:
          $ref: '#/components/schemas/DaoAnalyticResourceObject'
    DaoAnalyticResourceObject:
      type: object
      properties:
        apiVersion:
          type: string
          description: API Version
        data:
          type: object
          additionalProperties: {}
          description: Data
        kind:
          type: string
          description: Kind
        metadata:
          type: object
          additionalProperties: {}
          description: Metadata
        spec:
          type: object
          additionalProperties: {}
          description: Spec
      description: The object to validate.
      required:
      - apiVersion
      - kind
      - metadata
    SessionSpyctlReportListPagerOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        continuation_token:
          type: string
          description: Continuation token for the next page of reports
        reports:
          type: array
          items:
            $ref: '#/components/schemas/SessionSpyctlReportOutput'
          description: List of reports
    SuppressionPolicyBuildInput:
      type: object
      properties:
        name:
          type: string
          description: Custom name for the suppression policy
          maxLength: 64
        object_uid:
          type: string
          description: The uid of the object to suppress
          maxLength: 64
        scope_to_users:
          type: boolean
          description: If set to true, the policy will automatically be scoped to the users associated with the object referenced by ObjUID; unless overwritten by the selectors.
          default: false
        selectors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: 'The way to define a custom scope for the policy. Possible keys are: trigger-class, trigger-ancestors, users, interactive-users, non-interactive-users. Values may be wildcarded with ''*''.'
          maxProperties: 5
        type:
          type: string
          maxLength: 64
      required:
      - type
    SessionSpyctlReportSpecArgument:
      type: object
      properties:
        default:
          type: string
          description: Suggested default value for the argument
        description:
          type: string
          description: Long form description of the argument
        name:
          type: string
          description: Name of the argument
        required:
          type: boolean
          description: Is the argument required
        short:
          type: string
          description: Short form description of the argument
        type:
          type: string
          description: Type of the argument
    SpyctlMergeInput:
      type: object
      properties:
        merge_objects:
          type: array
          items:
            $ref: '#/components/schemas/DaoAnalyticResourceObject'
          description: The object(s) to merge into the primary object.
        object:
          $ref: '#/components/schemas/DaoAnalyticResourceObject'
      required:
      - merge_objects
      - object
    SpyctlDiffInput:
      type: object
      properties:
        content_type:
          type: string
          description: 'The content type of the diff output. Possible values are: text, json.'
        diff_objects:
          type: array
          items:
            $ref: '#/components/schemas/DaoAnalyticResourceObject'
          description: The object(s) to diff the primary object with.
        full_diff:
          type: boolean
          description: When content_type is omitted or set to text this returns the full diff text instead of a summary.
        include_irrelevant:
          type: boolean
          description: When set to true, the output of this API will return lists of objects, by kind, that had no impact on the diff. This option may increase compute time.
        object:
          $ref: '#/components/schemas/DaoAnalyticResourceObject'
      required:
      - diff_objects
      - object
    SpyctlReportGenerateInput:
      type: object
      properties:
        report_args:
          type: object
          additionalProperties: {}
          description: name value pair arguments for the report to generate
        report_id:
          type: string
          description: identifier for the type of report to generate
        report_tags:
          type: object
          additionalProperties: {}
          description: name value pairs to tag the report to generate
      required:
      - report_args
      - report_id
    SpyctlReportListPagerInput:
      type: object
      properties:
        continuation_token:
          type: string
          description: token to continue the list of reports
        scheduled_time_from:
          type: number
          description: Get only reports that were scheduled after this timestamp. If omitted, defaulted to 1 week ago.
          format: float
        scheduled_time_to:
          type: number
          description: Get only reports that were scheduled before this timestamp. If omitted, defaults to current time.
          format: float
    ValidationError:
      type: object
      properties:
        err_msg:
          type: string
          description: Message regarding the validation failure
        field:
          type: string
          description: Field name which failed validation
        property:
          type: string
          description: JSON property name of the field which failed validation
        tags:
          type: string
          description: Validation tag which failed
    SessionSpyctlReportInventoryOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        inventory:
          type: array
          items:
            $ref: '#/components/schemas/SessionSpyctlReportSpec'
          description: The inventory of reports available to generate for the org
    SessionSpyctlReportListOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        reports:
          type: array
          items:
            $ref: '#/components/schemas/SessionSpyctlReportOutput'
          description: List of reports
    SpyctlValidateInput:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/DaoAnalyticResourceObject'
      required:
      - object
    SessionSpyctlReportOutput:
      type: object
      properties:
        change_log:
          type: array
          items:
            type: array
            items: {}
          description: Change log of the report generation process
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        error:
          type: string
          description: Error message if the report generation failed
        formats:
          type: array
          items:
            type: string
          description: List of formats available for the report
        id:
          type: string
          description: Identifier for the generated report, to use in subsequent status update requests
        input:
          type: object
          additionalProperties: {}
          description: Input arguments for the report
        status:
          type: string
          description: Status of the report generation
    DaoPolicyObject:
      type: object
      properties:
        apiVersion:
          type: string
          description: API Version
        kind:
          type: string
          description: Kind
        metadata:
          type: object
          additionalProperties: {}
          description: Metadata
        spec:
          type: object
          additionalProperties: {}
          description: Spec
      description: Policy
      required:
      - apiVersion
      - kind
      - metadata
      - spec
    SessionSpyctlDiffOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        diff_data:
          type: string
        irrelevant:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Includes any objects that were irrelevant to the diff. The include_irrelevant option must be set to true to return this data.
    SessionSpyctlValidateOutput:
      type: object
      properties:
        context_uid:
          type: string
          description: Context UID for this query, it's used to track the query as it flows through the system
        invalid_message:
          type: string
          description: If the input object is invalid, InvalidMessage will be populated with descriptions of the detected syntax errors
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      bearerFormat: JWT