CybelAngel Incident reports API

openapi: 3.2.0
info:
  version: 0.1.0
  title: References Incident reports API
  description: 'API for CybelAngel''s Platform.

    Authentication uses standard [OAuth2 Bearer Tokens](https://tools.ietf.org/html/rfc6750).

    [Activate your API access](docs/Activate-API-service.md) to obtain your credentials.

    You will be communicated a client `client_id` and a `client_secret` that will allow you to fetch tokens for our API.

    These tokens expire 24 hours.


    Here is a simple example of how to fetch such a token with curl:


    ```shell

    curl -XPOST https://auth.cybelangel.com/oauth/token -H ''content-type: application/json'' -d ''{"client_id": "client_id", "client_secret": "client_secret", "audience": "https://platform.cybelangel.com/", "grant_type": "client_credentials"}''

    ```


    The received access token can then be used as a Bearer token to request our API.

    '
  contact:
    email: support@cybelangel.com
  license:
    url: https://cybelangel.com/
    name: Proprietary
servers:
- url: https://platform.cybelangel.com/api
security:
- bearer_token: []
tags:
- name: Incident reports
  description: Manipulate incident reports.
paths:
  /v2/reports:
    get:
      tags:
      - Incident reports
      summary: Get reports (V2)
      description: Return the list of reports between the specified dates. The range between start-date and end-date must be less than or equal to 1 year The reports are returned in ascending order by date.
      operationId: get-v2-reports
      parameters:
      - name: start-date
        in: query
        description: Filter the reports that have been sent before this date
        required: true
        schema:
          type: string
          format: date-time
          examples:
          - '2021-10-15T13:45:30'
      - name: end-date
        in: query
        description: Filter the reports that have been sent after this date
        required: true
        schema:
          type: string
          format: date-time
          examples:
          - '2009-06-18T13:45:30'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  reports:
                    type: array
                    items:
                      $ref: '#/components/schemas/Report-v2'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.read
      servers:
      - url: https://platform.cybelangel.com/api
      x-internal: false
  /v2/reports/{report-id}:
    get:
      tags:
      - Incident reports
      summary: Get reports by ID (V2)
      description: Return a report with a particular ID.
      operationId: get-v2-reports-by-id
      parameters:
      - name: report-id
        in: path
        description: UUID of the report
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report-v2'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          description: Report can't be found
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.read
      servers:
      - url: https://platform.cybelangel.com/api
      x-internal: false
  /v1/reports/{report-id}/mirror:
    get:
      tags:
      - Incident reports
      summary: Get mirror details of a report (by ID)
      description: "Get mirror details information about the report identified by `report-id`.\nYour teams can leverage this API endpoint to retrieve:\n  - **Russian Market incident report attachments**, as part of our Dark Web Monitoring module\n  - **Sensitive documents downloaded through the Access to Cache** feature of our Data Breach Prevention module\n\n**Recommendation**: Upgrade your connector to query both the \"attachments\" endpoint and this one to ensure you are always receiving all available data.\n"
      operationId: get-mirror-by-report-id
      parameters:
      - name: report-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportMirror'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.read
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/reports/{report-id}/mirror/csv:
    get:
      tags:
      - Incident reports
      summary: Get mirror details in CSV of a report (by ID)
      description: "Get a csv containing information about files related to report identified by `report-id`.\nYour teams can leverage this API endpoint to retrieve:\n  - **Russian Market incident report attachments**, as part of our Dark Web Monitoring module\n  - **Sensitive documents downloaded through the Access to Cache** feature of our Data Breach Prevention module\n\n**Recommendation**: Upgrade your connector to query both the \"attachments\" endpoint and this one to ensure you are always receiving all available data.\n"
      operationId: get-mirror-csv-by-report-id
      parameters:
      - name: report-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '302':
          description: Redirect to the csv file
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.read
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/reports/{report-id}/mirror/archive:
    get:
      tags:
      - Incident reports
      summary: Get archive from report (by ID)
      description: "Get the archive containing files related to report identified by `report-id`.\nYour teams can leverage this API endpoint to retrieve:\n  - **Russian Market incident report attachments**, as part of our Dark Web Monitoring module\n  - **Sensitive documents downloaded through the Access to Cache** feature of our Data Breach Prevention module\n\n**Recommendation**: Upgrade your connector to query both the \"attachments\" endpoint and this one to ensure you are always receiving all available data.\n"
      operationId: get-mirror-archive-by-report-id
      parameters:
      - name: report-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '302':
          description: Redirect to the archive file
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.read
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/reports/{report-id}/status:
    put:
      tags:
      - Incident reports
      summary: Update status of a report
      description: Update status of a specific report identified by `report-id`
      operationId: update-report-status-by-report-id
      parameters:
      - name: report-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/ReportStatus'
              required:
              - status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    examples:
                    - updated
                  id:
                    type: string
                    description: The id of the report
                    format: uuid
                    examples:
                    - 670e7227-74c9-4579-b6e3-f91ad0169a08
                  status:
                    $ref: '#/components/schemas/ReportStatus'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.move
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/reports/status:
    post:
      tags:
      - Incident reports
      summary: Update multiple statuses (bulk)
      description: Update multiple reports statuses
      operationId: update-multiple-reports-statuses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/ReportStatus'
                ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                    examples:
                    - 670e7227-74c9-4579-b6e3-f91ad0169a08
              required:
              - status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  updated:
                    type: integer
                    examples:
                    - 1
                  total:
                    type: integer
                    description: Number of updated reports
                    examples:
                    - 1
                required:
                - updated
                - total
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.move
      servers:
      - url: https://platform.cybelangel.com/api
      x-codegen-request-body-name: body
  /v1/reports/{report-id}/comments:
    get:
      tags:
      - Incident reports
      summary: Get comments of a report
      description: Get the list of comments on a specific report
      operationId: get-report-comments
      parameters:
      - name: report-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of comments returned
                    examples:
                    - 1
                  new:
                    type: integer
                    description: Number of comments which are new to current user
                    examples:
                    - 0
                  comments:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportComment'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports_global_comments.read
      servers:
      - url: https://platform.cybelangel.com/api
    post:
      tags:
      - Incident reports
      summary: Post a comment on a report
      description: Create a new comments attached to a specific report
      operationId: post-report-comments
      parameters:
      - name: report-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  examples:
                  - This is a comment message
                discussion_id:
                  type: string
                  description: Deprecated property. The discussion_id will be ignored. The discussion_id is computed automatically.
                parent_id:
                  type:
                  - string
                  - 'null'
                  description: Defining the id of the previous comment if it's a reply, null for top-level comments
                  format: uuid
                  examples:
                  - 3500bb64-6081-4cf5-8e6f-dca82dab4983
                assigned:
                  type: boolean
                  description: boolean describing if this message was assigned to the analysts
              required:
              - content
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddReportCommentResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports_global_comments.write
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/reports/{report-id}/attachments/{attachment-id}:
    get:
      tags:
      - Incident reports
      summary: Get Attachments
      description: Get an attachment on a specific report
      operationId: get-attachments-by-report-id
      parameters:
      - name: report-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: attachment-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                contentMediaType: application/octet-stream
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.read
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/reports/{report-id}/pdf:
    get:
      tags:
      - Incident reports
      summary: Get PDF version of a report (by ID)
      description: Return a specified report as a PDF file
      operationId: get-pdf-by-report-id
      parameters:
      - name: report-id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/pdf:
              schema:
                type: string
                contentMediaType: application/octet-stream
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.read
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/reports/remediation-request:
    post:
      tags:
      - Incident reports
      summary: Create a Remediation Request
      description: Create a remediation request
      operationId: create-remediation-request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                report_id:
                  type: string
                  format: uuid
                  examples:
                  - d334220f-0f41-48e5-b01a-129d2b0a73f5
                requester_email:
                  type: string
                  format: email
                  examples:
                  - john.doe@corp.com
                requester_fullname:
                  type: string
                  examples:
                  - John Doe
              required:
              - report_id
              - requester_email
              - requester_fullname
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  report_id:
                    type: string
                    format: uuid
                    examples:
                    - d334220f-0f41-48e5-b01a-129d2b0a73f5
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - reports.read
      servers:
      - url: https://platform.cybelangel.com/api
      x-codegen-request-body-name: body
components:
  schemas:
    ReportComment:
      type: object
      properties:
        author:
          type: object
          properties:
            firstname:
              type: string
              examples:
              - John
            lastname:
              type: string
              examples:
              - Doe
            id:
              type: string
              examples:
              - google-oauth2|112361861605444479803
            notFound:
              type: boolean
              description: true if the user doesn't exist anymore
        content:
          type: string
          description: Body of the comment
          examples:
          - Body of the comment
        created_at:
          type: string
          description: Creation date
          format: date-time
        discussion_id:
          type: string
          description: 'discussion id: made of report id and tenant id like uuid:uuid'
          examples:
          - 3500bb64-6081-4cf5-8e6f-dca82dab4982:41ce4e85-9bd0-4a4f-bab9-c3cf3d0d97da
        id:
          type: string
          description: Id of comment
          format: uuid
          examples:
          - 3500bb64-6081-4cf5-8e6f-dca82dab4982
        isNew:
          type: boolean
          description: true if comment is a new one to the current user
        last_updated_at:
          type: string
          description: Date of comment last update by its author
          format: date-time
        parent_id:
          type:
          - string
          - 'null'
          description: id of parent comment if this comment is a reply to another comment, null if this is a top-level comment
          format: uuid
          examples:
          - 3500bb64-6081-4cf5-8e6f-dca82dab4982
        assigned:
          type: boolean
          description: boolean describing if this message was assigned to the analysts
    ReportMirrorStatus:
      type: string
      enum:
      - error
      - expired
      - pending
      - ready
      examples:
      - ready
    Report-v2:
      type: object
      title: Report (V2)
      description: Report schema response
      properties:
        id:
          type: string
          format: uuid
          examples:
          - 92f7baa2-59f7-436e-86fc-d0ee153bc51e
        report_content:
          type: string
          description: Report content in markdown format
          format: text
          examples:
          - Report content\nWritten by an analyst.
        url:
          type: string
          format: url
          examples:
          - https://platform.cybelangel.com/reports/4abf0132-194e-47dd-9584-3270a456cd37
        abstract:
          type: string
          description: Report abstract in markdown format
          format: text
          examples:
          - Report abstract\nWritten by an analyst.
        category:
          $ref: '#/components/schemas/ReportCategoryResponse'
        created_at:
          type: string
          format: date-time
          readOnly: true
          examples:
          - '2021-10-30T18:00:00.000Z'
        detected_at:
          type: string
          format: date-time
          readOnly: true
          examples:
          - '2021-10-30T18:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          readOnly: true
          examples:
          - '2021-10-30T18:00:00.000Z'
        incident_id:
          type: string
          examples:
          - ABC123
        incident_type:
          $ref: '#/components/schemas/ReportIncidentType'
        investigation_id:
          type: string
          readOnly: true
          examples:
          - a3b8cc8c-bc7d-4a33-a32a-93b0336a20fe:9a4c1e53-4864-4e3c-aca7-736109e0d5cb
        ip:
          type: string
          format: ip
          examples:
          - 254.181.32.18
        keywords:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                examples:
                - 43ar92d1-1fdd-4e7b-9628-e30t7a2ce5ea
              name:
                type: string
                examples:
                - my-keyword
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ReportAttachment'
        liveness:
          type:
          - object
          - 'null'
          properties:
            online:
              type: boolean
            last_checked_at:
              type:
              - string
              - 'null'
              format: date-time
              examples:
              - '2018-01-30T18:00:00.000Z'
        machine_name:
          type: string
          description: Machine name
          examples:
          - Office-28
        malware_location:
          type: string
          description: Malware location
          examples:
          - Drive C
        malware_name:
          type: string
          description: Malware name
          examples:
          - Raccoon
        origins:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              value:
                type: string
        port:
          type:
          - integer
          - 'null'
          examples:
          - 80
        registrant_email:
          type: string
          format: email
          examples:
          - best.hacker@malicious.com
        registrar_name:
          type: string
          examples:
          - OVH
        report_type:
          $ref: '#/components/schemas/ReportType'
        risks:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              message:
                type: string
        samples:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              sample:
                type: string
        sender:
          type: string
          format: email
          examples:
          - john.doe@cybelangel.com
        sender_tenant_id:
          type: string
          examples:
          - 43ath2d1-1fdd-4e7b-9628-e30t7a2ce5rd
        sent_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2018-01-30T18:00:00.000Z'
        severity:
          type: integer
          format: int32
          minimum: 0
          maximum: 4
          examples:
          - 4
        source:
          type:
          - string
          - 'null'
          examples:
          - www.doma1n.com
        status:
          $ref: '#/components/schemas/ReportStatus'
        suggestions:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              message:
                type: string
        threat:
          type:
          - string
          - 'null'
          examples:
          - malicious.co
        title:
          type: string
          examples:
          - Inaccessible sensitive website on malicious.co
        city:
          type: string
          examples:
          - Paris
        country_code:
          type: string
          examples:
          - FR
        location:
          type: string
          examples:
          - France
        user_session:
          type: string
          description: User session
          examples:
          - john.doe
        volume:
          type:
          - object
          - 'null'
          properties:
            bins:
              type:
              - integer
              - 'null'
            documents:
              type:
              - integer
              - 'null'
              examples:
              - 6
            domain:
              type:
              - integer
              - 'null'
            email:
              type:
              - integer
              - 'null'
            passwords:
              type:
              - integer
              - 'null'
            ips:
              type:
              - integer
              - 'null'
        usergroups:
          type: array
          items:
            type: string
            examples:
            - '[UG1, UG2, UG3]'
        workspaces:
          type: array
          description: Only available for migrated organizations. The workspaces the report is shared with.
          items:
            $ref: '#/components/schemas/ReportWorkspace'
        screenshots:
          type: array
          examples:
          - - https://platform.cybelangel.com/api/v1/assets/report_image/f3851f63-f27c-4b0e-xxxx-7d2cd3d5ffc
            - https://platform.cybelangel.com/api/v1/assets/report_image/2e8908d3-f109-42d5-xxxx-79c6719dd12
          items:
            type: string
            format: url
        abuse_email:
          type: string
          examples:
          - abuse@acme.com
        analysis:
          type: string
          description: Report analysis in markdown format
          format: text
          examples:
          - Here's my analysis
        domain_registered_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2023-02-16T16:03:24Z'
        hostnames:
          type: array
          examples:
          - - www.acme.com
            - www.emca.com
          items:
            type: string
            examples:
            - www.doma1n.co
        mx_servers:
          type: array
          examples:
          - - value: mx1.acme.com
              priority: 10
            - value: mx2.acme.com
              priority: 5
          items:
            type: object
            properties:
              priority:
                type: integer
              value:
                type: string
        ns_servers:
          type: array
          examples:
          - - ns1.acme.com
            - ns2.acme.com
          items:
            type: string
        tags:
          type: array
          examples:
          - - tag1
            - tag2
          items:
            type: string
        asset_urls:
          type: array
          examples:
          - - http://www.org.com/asset1
            - http://www.org.com/asset2
          items:
            type: string
        board:
          type: string
          examples:
          - tor
        whois:
          type: string
          format: text
          examples:
          - Info whois here
        stream:
          type: string
          format: uuid
          readOnly: true
          examples:
          - b2196357-dd51-4c9b-8e97-2c62xxxxx24f
        module:
          $ref: '#/components/schemas/ReportModule'
    ReportCategoryResponse:
      type: string
      enum:
      - ''
      - board
      - paste
      - social
      - codeshare
      - docshare
      - leak
      - database
      - iot
      - dns
      - fileserver
      - rss
      - openserver
      description: The category of the report (can be empty)
      examples:
      - dns
    ReportType:
      type: string
      enum:
      - incident_report
      - incident_detection
      - preliminary_report
      - reminder
      - communication
      examples:
      - incident_report
    ReportStatus:
      type: string
      enum:
      - draft
      - open
      - in_progress
      - resolved
      - discarded
      examples:
      - resolved
    ReportMirror:
      type: object
      properties:
        available_files_count:
          type: integer
          description: The number of downloadable files in the mirror
          examples:
          - 1
        created_at:
          type: string
          description: The mirror's creation date
          format: date-time
          examples:
          - '2022-03-10T13:52:48Z'
        files_count:
          type: integer
          description: The number of files that matched on the server
          examples:
          - 155
        files_volume:
          type: integer
          description: The total volume of files in bytes
          examples:
          - 88726
        report_id:
          type: string
          description: The id of the report to which this mirror is linked
          format: uuid
          examples:
          - 2fa68ccc-005d-4033-8fcd-7d38a2370b44
        status:
          $ref: '#/components/schemas/ReportMirrorStatus'
          description: The mirror status
        stream_id:
          type: string
          description: The id of the mirror's stream
          format: uuid
          examples:
          - c683aa1a-a029-4bcf-9333-a029f2963d2b
        updated_at:
          type: string
          description: The mirror's last update date
          format: date-time
          examples:
          - '2022-03-10T13:52:48Z'
    ReportAttachment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          examples:
          - fe3ar92d1-1fdd-4d7b-9628-e30t7a2ce5ea
        name:
          type: string
          examples:
          - cybelangel-attachment.png
        attached_to:
          type: string
          enum:
          - investigation_id
          - report_id
    ReportWorkspace:
      type: object
      properties:
        id:
          type: string
          format: uuid
          examples:
          - e7b5ea39-a627-4e7d-a836-abcfd4f11f01
        name:
          type: string
          examples:
          - Workspace 1
    AddReportCommentResponse:
      type: object
      properties:
        author:
          type: string
          description: User ID of the author
          examples:
          - 78006d2b-1563-4a08-9567-97879df3d2b0
        content:
          type: string
    

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybelangel/refs/heads/main/openapi/cybelangel-incident-reports-api-openapi.yml