openapi: 3.2.0
info:
  title: Spyderbat Agent Action API
  version: 1.0.0
  contact:
    name: API Support
    url: https://api.prod.spyderbat.com/openapi
    email: support@spyderbat.com
  license:
    name: MIT
    url: https://mit-license.org/
  termsOfService: https://www.spyderbat.com/terms-of-use/
  x-logo:
    url: /static/sb-logo.svg
    backgroundColor: '#161A21'
    altText: Spyderbat Logo
  description: 'Operations tagged Agent Action across 2 of this provider''s published API definitions: spyderbat-openapi-original.json, spyderbat-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.prod.spyderbat.com/
  description: Spyderbat API Server
security:
- apiToken: []
tags:
- name: Agent Action
  description: '

    Agent Action defines actions that can be executed on remote agents in response to events.'
paths:
  /api/v1/agent_action/enqueue/{agentUID}:
    post:
      tags:
      - Agent Action
      summary: Enqueue an agent action
      description: "\n\tEnqueue an agent action. The action will be executed by the agent at the next opportunity.\n\n\t * Requires action agent_action:Enqueue"
      operationId: AgentActionEnqueue
      parameters:
      - name: agentUID
        in: path
        description: Agent UID
        required: true
        schema:
          type: string
          description: Agent UID
          maxLength: 20
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentActionEnqueueInput'
      responses:
        '200':
          description: OK
        '403':
          description: permission denied
    servers:
    - url: https://api.prod.spyderbat.com/
      description: Spyderbat API Server
  /api/v1/org/{orgUID}/agent_action_status:
    get:
      tags:
      - Agent Action
      summary: List agent actions.
      description: "\nThis will list agent action statuses.\n* Requires the action *agent:ListActionStatus* on the organization\n\t\t\t"
      operationId: AgentActionStatusList
      parameters:
      - name: orgUID
        in: path
        description: Organization UID
        required: true
        schema:
          type: string
          description: Organization UID
      - name: action_taken_by
        in: query
        description: Filter actions by the principal that created the action or the agent that executed the action
        schema:
          type: string
          description: Filter actions by the principal that created the action or the agent that executed the action
      - name: action_type_equals
        in: query
        description: Return actions with a type equal to this value.
        schema:
          type: string
          description: Return actions with a type equal to this value.
      - name: action_uid_equals
        in: query
        description: The auto-generated uid for the action
        schema:
          type: string
          description: The auto-generated uid for the action
      - name: agent_uid_equals
        in: query
        description: Return actions for this agent
        schema:
          type: string
          description: Return actions for this agent
      - name: analytic_uid_equals
        in: query
        description: Analytic UID -- the uid that starts with 'action:'
        schema:
          type: string
          description: Analytic UID -- the uid that starts with 'action:'
      - name: object_uid_equals
        in: query
        description: Filter actions by one or more object UIDs
        schema:
          type: array
          items:
            type: string
          description: Filter actions by one or more object UIDs
        style: form
        explode: true
      - name: page
        in: query
        description: Page number to return
        schema:
          type: integer
          description: Page number to return
          format: int32
          minimum: 1
      - name: page_size
        in: query
        description: Number of results to return (10 by default). If you specify -1, all results are returned
        schema:
          type: integer
          description: Number of results to return (10 by default). If you specify -1, all results are returned
          format: int32
          maximum: 100
      - name: reason_contains
        in: query
        description: Filter actions by the reason
        schema:
          type: string
          description: Filter actions by the reason
      - name: reason_equals
        in: query
        description: Filter actions by the reason
        schema:
          type: string
          description: Filter actions by the reason
      - name: result_code_equals
        in: query
        description: Return actions with a result code equal to this value
        schema:
          type: integer
          description: Return actions with a result code equal to this value
          format: int32
      - name: result_code_not_equals
        in: query
        description: Return actions with a result code not equal to this value
        schema:
          type: integer
          description: Return actions with a result code not equal to this value
          format: int32
      - name: reversed
        in: query
        description: Sort in descending order
        allowEmptyValue: true
        schema:
          type: boolean
          description: Sort in descending order
      - name: sort_by
        in: query
        description: Sort by field. Valid values are 'state', 'resultcode', 'completed', 'validfrom', and 'validto'
        schema:
          type: string
          description: Sort by field. Valid values are 'state', 'resultcode', 'completed', 'validfrom', and 'validto'
      - name: state_equals
        in: query
        description: Return actions with a state equal to this value. Valid values are 'queued', 'delivered', 'expired', and 'completed'
        schema:
          type: string
          description: Return actions with a state equal to this value. Valid values are 'queued', 'delivered', 'expired', and 'completed'
      - name: state_not_equals
        in: query
        description: Return actions with a state not equal to this value. Valid values are 'queued', 'delivered', 'expired', and 'completed'
        schema:
          type: string
          description: Return actions with a state not equal to this value. Valid values are 'queued', 'delivered', 'expired', and 'completed'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListActionStatusOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
    servers:
    - url: https://api.prod.spyderbat.com/
      description: Spyderbat API Server
  /api/v1/org/{orgUID}/agent_action_status/{actionUID}:
    get:
      tags:
      - Agent Action
      summary: Load agent action.
      description: "\nThis will load an agent action status.\n* Requires the action *agent:LoadActionStatus* on the organization\n\t\t\t"
      operationId: AgentActionStatusLoad
      parameters:
      - name: actionUID
        in: path
        description: The uid of the action record
        required: true
        schema:
          type: string
          description: The uid of the action record
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionLoadActionStatusOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
        '404':
          description: agent action not found
    servers:
    - url: https://api.prod.spyderbat.com/
      description: Spyderbat API Server
  /api/v1/org/{orgUID}/response/agent/killpod/{podUID}:
    post:
      tags:
      - Agent Action
      summary: Kill a pod on an agent.
      description: "\nThis will attempt to kill a pod on an kubernetes cluster.\n* Requires the action *agent:KillPod* on the organization\n\t\t\t"
      operationId: AgentKillPod
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      - name: podUID
        in: path
        description: The Spyderbat uid of the pod to kill
        required: true
        schema:
          type: string
          description: The Spyderbat uid of the pod to kill
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentKillPodInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAgentKillPodOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
        '429':
          description: too many requests
    servers:
    - url: https://api.prod.spyderbat.com/
      description: Spyderbat API Server
  /api/v1/org/{orgUID}/response/agent/killprocess/{processUID}:
    post:
      tags:
      - Agent Action
      summary: Kill a process on an agent.
      description: "\nThis will attempt to kill a process on a node that an agent monitors.\n* Requires the action *agent:KillProcess* on the organization\n\t\t\t"
      operationId: AgentKillProcess
      parameters:
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      - name: processUID
        in: path
        description: The Spyderbat uid of the process to kill
        required: true
        schema:
          type: string
          description: The Spyderbat uid of the process to kill
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentKillProcessInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAgentKillProcessOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
        '429':
          description: too many requests
    servers:
    - url: https://api.prod.spyderbat.com/
      description: Spyderbat API Server
  /api/v1/org/{orgUID}/response/agent/scancontainer/{containerUID}:
    post:
      tags:
      - Agent Action
      summary: Scan a container.
      description: "\nThis will run a scan of a container on a cluster that an agent monitors.\n* Requires the action *agent:ScanContainer* on the organization\n\t\t\t"
      operationId: AgentScanContainer
      parameters:
      - name: containerUID
        in: path
        description: The Spyderbat uid of the container to scan
        required: true
        schema:
          type: string
          description: The Spyderbat uid of the container to scan
      - name: orgUID
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentScanContainerInput'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionAgentScanContainerOutput'
        '400':
          description: invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '403':
          description: permission denied
        '429':
          description: too many requests
    servers:
    - url: https://api.prod.spyderbat.com/
      description: Spyderbat API Server
components:
  schemas:
    RbacStatement:
      type: object
      properties:
        actions:
          type: array
          items:
            type: string
          description: The actions that may be performed
          maxItems: 50
          minItems: 1
        condition:
          $ref: '#/components/schemas/RbacConditionMap'
        effect:
          type: string
          description: The effect of the statement, i.e. allow or deny
          maxLength: 5
        resources:
          type: array
          items:
            type: string
          description: The resource the statement applies to
          maxItems: 25
          minItems: 1
        sid:
          type: string
          description: Statement ID, used to identify the statement in audit logs
          maxLength: 32
      required:
      - effect
      - sid
    SessionAgentScanContainerOutput:
      type: object
      properties:
        action_uid:
          type: string
          description: The uid of the action record
    AgentScanContainerInput:
      type: object
      properties:
        reason:
          type: string
          description: The reason for scanning the container
          maxLength: 500
        scan_type:
          type: string
          description: The type of scan to run
    SessionAgentKillProcessOutput:
      type: object
      properties:
        action_uid:
          type: string
          description: The uid of the action record
    SessionLoadActionStatusOutput:
      type: object
      properties:
        action_status:
          $ref: '#/components/schemas/DaoActionStatus'
    AgentActionEnqueueInput:
      type: object
      properties:
        analytic_uid:
          type: string
        env:
          type: object
          additionalProperties:
            type: string
        object_uid:
          type: string
        principal:
          type: string
          description: Principal that created this action
        reason:
          type: string
        resource_name:
          type: string
          description: Resource name used for RBAC
        resource_policy:
          $ref: '#/components/schemas/ResourcePolicy'
        script_hash:
          type: string
          maxLength: 64
        script_name:
          type: string
          maxLength: 64
        valid_from:
          type: string
          description: Valid from date, the first date this object was valid
          format: date-time
        valid_to:
          type: string
          description: Valid to date, the date this object is valid to
          format: date-time
      required:
      - script_hash
      - script_name
      - valid_to
    ResourcePolicy:
      type: object
      properties:
        name:
          type: string
          description: Name of the resource policy
          maxLength: 32
        statements:
          type: array
          items:
            $ref: '#/components/schemas/RbacStatement'
          description: List of statements to be examined by the resource policy
        version:
          type: string
          maxLength: 24
      description: Resource policy for RBAC
    Orc_apiAgentActionError:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message containing context about how or why the error occurred
          maxLength: 1024
        reason:
          type: string
          description: A short, predictable string that identifies the type of error
          maxLength: 128
    RbacConditionMap:
      type: object
      description: Additional conditions which may be applied
    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
    SessionListActionStatusOutput:
      type: object
      properties:
        action_statuses:
          type: array
          items:
            $ref: '#/components/schemas/DaoActionStatus'
          description: The list of action status records
        search_total:
          type: integer
          description: The total number of items
          format: int32
        total_pages:
          type: integer
          description: The total number of pages
          format: int32
    AgentKillProcessInput:
      type: object
      properties:
        kill_process_group:
          type: boolean
          description: Whether to kill the entire process group
        kill_process_tree:
          type: boolean
          description: Whether to kill the entire process tree with the processUID as the parent
        reason:
          type: string
          description: The reason for killing the process
          maxLength: 500
    SessionAgentKillPodOutput:
      type: object
      properties:
        action_uid:
          type: string
          description: The uid of the action record
    AgentKillPodInput:
      type: object
      properties:
        reason:
          type: string
          description: The reason for killing the pod
          maxLength: 500
    DaoActionStatus:
      type: object
      properties:
        action_taken_by:
          type: string
        action_type:
          type: string
        agent_uid:
          type: string
        analytic_uid:
          type: string
        completed:
          type:
          - string
          - 'null'
          format: date-time
        error:
          $ref: '#/components/schemas/Orc_apiAgentActionError'
        object_uid:
          type:
          - string
          - 'null'
        org_uid:
          type: string
        principal:
          type: string
        reason:
          type:
          - string
          - 'null'
        result_code:
          type:
          - integer
          - 'null'
          format: int32
        state:
          type: string
        uid:
          type: string
        valid_from:
          type: string
          format: date-time
        valid_to:
          type:
          - string
          - 'null'
          format: date-time
      description: The action status record
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- spyderbat-openapi-original.json
- spyderbat-openapi.json