openapi: 3.1.0
info:
  title: Cybereason API
  version: 23.x
  description: |
    Cybereason EDR/XDR REST API. Exposes Malop investigation, hunting
    via Visual Search, sensor management, isolation rules, custom
    detection rules, reputation lists, threat-intel lookups, malware
    queries, and remediation actions against a Cybereason tenant.

    Best-effort spec derived from publicly indexed Cybereason API
    documentation references (api-doc.cybereason.com URI/endpoints
    pages, docs.cybereason.com 23.2 docs, Cortex XSOAR / Demisto
    Cybereason integration, and the open-source CybereasonAPI
    PowerShell module). Cybereason's primary API documentation is
    customer/partner-gated; the operational surface modelled here
    matches the publicly described endpoints.

    Authentication is performed via a POST to /login.html which
    returns a JSESSIONID cookie used on subsequent calls. JWT
    authentication is also supported on version 20.1+ deployments.
  contact:
    name: Cybereason Nest
    url: https://nest.cybereason.com/documentation/api-documentation
  license:
    name: Proprietary
externalDocs:
  description: Cybereason API documentation
  url: https://nest.cybereason.com/documentation/api-documentation
servers:
  - url: https://{tenant}.cybereason.net
    description: Cybereason tenant
    variables:
      tenant:
        default: example
        description: Your Cybereason tenant hostname prefix.
security:
  - SessionCookie: []
tags:
  - name: Authentication
  - name: Malops
  - name: VisualSearch
  - name: Sensors
  - name: Remediation
  - name: Reputation
  - name: ThreatIntel
  - name: IsolationRules
  - name: CustomDetectionRules
paths:
  /login.html:
    post:
      tags: [Authentication]
      summary: Log in and obtain a JSESSIONID cookie
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [username, password]
              properties:
                username: { type: string }
                password: { type: string }
      responses:
        '200':
          description: 'Login successful (Set-Cookie: JSESSIONID)'
          headers:
            Set-Cookie:
              schema: { type: string }
        '302':
          description: Redirect on successful login
        '401':
          description: Invalid credentials
  /logout:
    get:
      tags: [Authentication]
      summary: Log out the current session
      responses:
        '200': { description: Logged out }
  /rest/detection/inbox:
    post:
      tags: [Malops]
      summary: Query the Malop inbox
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/MalopInboxRequest' }
      responses:
        '200':
          description: Malop inbox results
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MalopInboxResponse' }
  /rest/crimes/unified:
    post:
      tags: [Malops]
      summary: Query unified Malops
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        '200':
          description: Malop list
          content:
            application/json:
              schema: { type: object }
  /rest/visualsearch/query/simple:
    post:
      tags: [VisualSearch]
      summary: Hunt with a Visual Search query
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/VisualSearchRequest' }
      responses:
        '200':
          description: Visual Search response
          content:
            application/json:
              schema: { $ref: '#/components/schemas/VisualSearchResponse' }
  /rest/sensors/query:
    post:
      tags: [Sensors]
      summary: Query sensors
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SensorQueryRequest' }
      responses:
        '200':
          description: Matching sensors
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SensorQueryResponse' }
  /rest/sensors/action/archive:
    post:
      tags: [Sensors]
      summary: Archive sensors
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SensorActionRequest' }
      responses:
        '200':
          description: Archive action accepted
  /rest/sensors/action/unarchive:
    post:
      tags: [Sensors]
      summary: Unarchive sensors
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SensorActionRequest' }
      responses:
        '200':
          description: Unarchive action accepted
  /rest/sensors/action/delete:
    post:
      tags: [Sensors]
      summary: Delete sensors
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SensorActionRequest' }
      responses:
        '200':
          description: Delete action accepted
  /rest/monitor/global/commands/isolate:
    post:
      tags: [Sensors]
      summary: Isolate machines from the network
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PylumIdRequest' }
      responses:
        '200':
          description: Isolation triggered
  /rest/monitor/global/commands/un-isolate:
    post:
      tags: [Sensors]
      summary: Un-isolate machines
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PylumIdRequest' }
      responses:
        '200':
          description: Un-isolation triggered
  /rest/remediate:
    post:
      tags: [Remediation]
      summary: Trigger remediation actions on a Malop
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RemediationRequest' }
      responses:
        '200':
          description: Remediation accepted
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RemediationResponse' }
  /rest/remediate/status/{malopId}:
    parameters:
      - in: path
        name: malopId
        required: true
        schema: { type: string }
    get:
      tags: [Remediation]
      summary: Get remediation status for a Malop
      responses:
        '200':
          description: Remediation status
          content:
            application/json:
              schema: { type: object }
  /rest/remediate/abort:
    post:
      tags: [Remediation]
      summary: Abort remediation
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        '200':
          description: Aborted
  /rest/classification:
    get:
      tags: [Reputation]
      summary: List reputation entries
      responses:
        '200':
          description: Reputations
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Reputation' }
    post:
      tags: [Reputation]
      summary: Add or update reputation entries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: { $ref: '#/components/schemas/Reputation' }
      responses:
        '200':
          description: Reputations updated
  /rest/classification_v1/file:
    get:
      tags: [ThreatIntel]
      summary: Lookup file reputation
      parameters:
        - in: query
          name: hash
          required: true
          schema: { type: string }
      responses:
        '200':
          description: File reputation
          content:
            application/json:
              schema: { type: object }
  /rest/classification_v1/domain:
    get:
      tags: [ThreatIntel]
      summary: Lookup domain reputation
      parameters:
        - in: query
          name: domain
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Domain reputation
          content:
            application/json:
              schema: { type: object }
  /rest/classification_v1/ip:
    get:
      tags: [ThreatIntel]
      summary: Lookup IP reputation
      parameters:
        - in: query
          name: ip
          required: true
          schema: { type: string }
      responses:
        '200':
          description: IP reputation
          content:
            application/json:
              schema: { type: object }
  /rest/settings/isolation-rule:
    get:
      tags: [IsolationRules]
      summary: List isolation rules
      responses:
        '200':
          description: Isolation rules
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/IsolationRule' }
    post:
      tags: [IsolationRules]
      summary: Create isolation rule
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/IsolationRule' }
      responses:
        '200':
          description: Rule created
    put:
      tags: [IsolationRules]
      summary: Update isolation rule
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/IsolationRule' }
      responses:
        '200':
          description: Rule updated
  /rest/settings/isolation-rule/delete:
    post:
      tags: [IsolationRules]
      summary: Delete isolation rule
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/IsolationRule' }
      responses:
        '200':
          description: Rule deleted
  /rest/customRules/decisionFeature/live:
    get:
      tags: [CustomDetectionRules]
      summary: List active custom detection rules
      responses:
        '200':
          description: Active rules
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/CustomDetectionRule' }
  /rest/customRules/decisionFeature/create:
    post:
      tags: [CustomDetectionRules]
      summary: Create a custom detection rule
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CustomDetectionRule' }
      responses:
        '200':
          description: Rule created
  /rest/customRules/decisionFeature/update:
    post:
      tags: [CustomDetectionRules]
      summary: Update a custom detection rule
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CustomDetectionRule' }
      responses:
        '200':
          description: Rule updated
components:
  securitySchemes:
    SessionCookie:
      type: apiKey
      in: cookie
      name: JSESSIONID
      description: Session cookie returned by POST /login.html.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Available on Cybereason 20.1+ for token-based access.
  schemas:
    MalopInboxRequest:
      type: object
      properties:
        startTime: { type: integer, format: int64 }
        endTime: { type: integer, format: int64 }
        statusFilter:
          type: array
          items: { type: string, enum: [Active, ToReview, Closed, Reopened, FalsePositive, UnderInvestigation] }
    MalopInboxResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            malops:
              type: array
              items:
                type: object
                properties:
                  guid: { type: string }
                  displayName: { type: string }
                  severity: { type: string }
                  status: { type: string }
                  creationTime: { type: integer, format: int64 }
                  lastUpdateTime: { type: integer, format: int64 }
    VisualSearchRequest:
      type: object
      properties:
        queryPath:
          type: array
          items:
            type: object
            properties:
              requestedType: { type: string }
              filters:
                type: array
                items: { type: object }
        customFields:
          type: array
          items: { type: string }
        totalResultLimit: { type: integer, default: 1000 }
        perGroupLimit: { type: integer }
        templateContext: { type: string, example: SPECIFIC }
    VisualSearchResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
        status: { type: string }
    SensorQueryRequest:
      type: object
      properties:
        limit: { type: integer, default: 100 }
        offset: { type: integer, default: 0 }
        filters:
          type: array
          items: { type: object }
    SensorQueryResponse:
      type: object
      properties:
        sensors:
          type: array
          items: { $ref: '#/components/schemas/Sensor' }
        totalResults: { type: integer }
    Sensor:
      type: object
      properties:
        sensorId: { type: string }
        pylumId: { type: string }
        machineName: { type: string }
        internalIpAddress: { type: string }
        externalIpAddress: { type: string }
        osType: { type: string }
        status: { type: string }
        version: { type: string }
        lastPylumInfoMsgUpdateTime: { type: integer, format: int64 }
    SensorActionRequest:
      type: object
      properties:
        sensorsIds:
          type: array
          items: { type: string }
        argument: { type: string }
    PylumIdRequest:
      type: object
      properties:
        pylumIds:
          type: array
          items: { type: string }
    RemediationRequest:
      type: object
      properties:
        initiatorUserName: { type: string }
        malopId: { type: string }
        actionsByMachine:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                targetId: { type: string }
                actionType: { type: string, enum: [KILL_PROCESS, QUARANTINE_FILE, DELETE_REGISTRY_KEY, UNQUARANTINE_FILE, BLOCK_FILE] }
    RemediationResponse:
      type: object
      properties:
        remediationId: { type: string }
        initiatingUser: { type: string }
        start: { type: integer, format: int64 }
        statusLog:
          type: array
          items: { type: object }
    Reputation:
      type: object
      properties:
        keys:
          type: array
          items: { type: string }
        maliciousType:
          type: string
          enum: [blacklist, whitelist, remove]
        prevent: { type: boolean }
        remove: { type: boolean }
    IsolationRule:
      type: object
      properties:
        ruleId: { type: string }
        ipAddress: { type: string }
        ipAddressString: { type: string }
        port: { type: integer }
        portRangeStart: { type: integer }
        portRangeEnd: { type: integer }
        direction: { type: string, enum: [INCOMING, OUTGOING, ALL] }
        blocking: { type: boolean }
    CustomDetectionRule:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        rootCause: { type: string }
        malopDetectionType: { type: string }
        severity: { type: string }
        enabled: { type: boolean }