Abnormal AI Messages API

openapi: 3.2.0
info:
  title: Abnormal Security Client Messages API
  version: 1.4.3
  description: 'This is the specification for Abnormal Security Client API which can be used for managing security threats detected by Abnormal Security.

    <h2>Who is this API for?</h2>

    This API is for managing threats to an organization identified by Abnormal Security. The organization should be integrated with Abnormal Security and enabled for real-time detection of malicious emails.

    <h2> Integration Steps </h2>

    Go to `https://portal.abnormalsecurity.com/home/settings/integrations` & click on `Abnormal REST API`

    <h3> Step 1: Generating the authentication token </h3>


    Retrieve your authentication token via the <a href="https://portal.abnormalsecurity.com/home/settings/integrations">Abnormal portal</a>. You will use this token to view and modify your Abnormal-detected threats and cases.


    Keep the token safe, as it grants access to sensitive threat data related to your organization. Store it in a secure place, such as an encrypted password vault, and do not share it unless absolutely necessary. If you feel that the token has been compromised, please contact your Account Manager immediately.


    Once obtained, the token can be used in a request from any HTTP client, such as cURL:

    <pre> curl -H "Authorization: Bearer  << ACCESS_TOKEN >>" https://api.abnormalplatform.com/v1/threats </pre>


    <h3> Step 2: IP allowlisting </h3>


    IP allowlisting ensures that API access is only possible from IP addresses explicitly belonging to your organization. It prevents users from unauthorized networks to access your Abnormal SOAR data. This second layer of security helps keep your data safe from unauthorized users, and protects you in the event of a token compromise.


    To allowlist your organization''s IPs, please provide enter into the <a href="https://portal.abnormalsecurity.com/home/settings/integrations">Abnormal portal</a> specific IPv4 / IPv6 addresses, or a range of addresses using a <a href="https://www.ipaddressguide.com/cidr"> CIDR block</a>.


    <h3> Step 3: Try it out with Test Data </h3>


    To confirm that <b>Steps 1 & 2</b> have been configured properly, send a request to the server with the following header set:


    <pre> curl -H "Authorization: Bearer  << ACCESS_TOKEN >>" <b>-H "Mock-Data: True"</b> https://api.abnormalplatform.com/v1/threats </pre>


    The server should respond with a body payload similar to the examples specified in this documentation.


    <h3> Note for EU Customers </h3>


    If you''re a customer in the EU, you''ll need to make API requests to our EU host `https://eu.rest.abnormalsecurity.com`. If you''d like to test the API through SwaggerHub, you''ll find both the default host and the EU host in the Servers dropdown menu below.

    '
  termsOfService: https://legal.abnormalsecurity.com/legal-hub/abnormal-security-api-terms-of-service-6feee5e3
  contact:
    name: Abnormal Security Support
    email: support@abnormalsecurity.com
servers:
- url: https://api.abnormalplatform.com/v1
  description: Production Server for managing threats
- url: https://eu.rest.abnormalsecurity.com/v1
  description: EU Production Server for managing threats.
security:
- BearerAuth: []
tags:
- name: Messages
  description: API to manage message details
paths:
  /messages/{message_id}/attachment/{attachment_name}:
    get:
      operationId: v1_messages_attachment_retrieve
      summary: Get details of an attachment in an email message
      parameters:
      - in: path
        name: message_id
        schema:
          type: number
        description: The ABX Message Id of a message.
        required: true
      - in: path
        name: attachment_name
        schema:
          type: string
        description: The attachment name of an attachment belonging to an email message.
        required: true
      - in: header
        name: mock-data
        schema:
          type: string
          default: 'False'
          enum:
          - 'False'
          - 'True'
        description: Returns test data if set to `True`
      tags:
      - Messages
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SoarAttachmentSignalsStruct'
          description: Attachment details of an attachment in an email message.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/ThreatDoesNotExistError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /messages/{message_id}/attachment/{attachment_name}/download:
    get:
      operationId: v1_messages_attachment_download_retrieve
      summary: Download the attachment in an email as a file
      parameters:
      - in: path
        name: message_id
        schema:
          type: number
        description: The ABX Message Id of a message.
        required: true
      - in: path
        name: attachment_name
        schema:
          type: string
        description: The attachment name of an attachment belonging to an email message.
        required: true
      - in: header
        name: mock-data
        schema:
          type: string
          default: 'False'
          enum:
          - 'False'
          - 'True'
        description: Returns test data if set to `True`
      tags:
      - Messages
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          description: The attachment file as an octet-stream. Will resolve into a file in the file system of the machine calling the request.
        '401':
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/responses/UnauthorizedError'
          description: ''
        '403':
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/responses/ForbiddenError'
          description: ''
        '404':
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/responses/NotFoundError'
          description: ''
        '429':
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/responses/TooManyRequestsError'
          description: ''
  /messages/{message_id}/download:
    get:
      operationId: v1_messages_download_retrieve
      description: Download the message contents in plaintext in the EML format. For security reasons, this API endpoint is disabled by default. Please talk to your customer specialist to get it enabled.
      summary: Download a message in EML format
      parameters:
      - in: path
        name: message_id
        schema:
          type: number
        description: The ABX Message Id of a message.
        required: true
      tags:
      - Messages
      responses:
        '200':
          content:
            message/rfc822:
              schema:
                type: string
                example: 'From: sender@example.com

                  To: recipient@example.com

                  Subject: Test Email

                  Date: Thu, 23 Aug 2024 12:00:00 +0000

                  Content-Type: text/plain; charset="UTF-8"


                  This is the email body

                  '
          description: The EML file in plain text
        '401':
          content:
            message/rfc822:
              schema:
                $ref: '#/components/responses/UnauthorizedError'
          description: ''
        '403':
          content:
            message/rfc822:
              schema:
                $ref: '#/components/responses/ForbiddenError'
          description: ''
        '404':
          content:
            message/rfc822:
              schema:
                $ref: '#/components/responses/NotFoundError'
          description: ''
        '429':
          content:
            message/rfc822:
              schema:
                $ref: '#/components/responses/TooManyRequestsError'
          description: ''
  /messages/{message_id}/remediation_history:
    get:
      operationId: v1_messages_remediation_history_retrieve
      summary: Get details of the remediation history for a threat log message
      parameters:
      - in: path
        name: message_id
        schema:
          type: number
        description: The ABX Message Id of a message.
        required: true
      tags:
      - Messages
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemediationHistory'
          description: Remediation history for a threat log message.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
components:
  responses:
    NotFoundError:
      description: Invalid user input when using the filter query parameter. Will return various error messages
    UnauthorizedError:
      description: Access token is missing or invalid
    TooManyRequestsError:
      description: Request count exceeds allowed number of concurrent requests for this resource type
    ForbiddenError:
      description: Access to the resource is forbidden (e.g. IP not in allowlist)
    ThreatDoesNotExistError:
      description: Threat does not exist
  schemas:
    RemediationHistory:
      type: object
      properties:
        remediation_history:
          type: object
          additionalProperties:
            type: string
            format: date-time
          description: Remediation history of a threat.
          example: '"Auto-Remediated": "2023-04-11T20:54:56.244716+00:00"'
        folder_locations:
          type: array
          items:
            type: string
          description: Folder locations.
          example:
          - Junk
      required:
      - folder_locations
      - remediation_history
    SoarAttachmentSignalsStruct:
      type: object
      description: Serializes a AttachmentSignalsPortalStruct object for Soar payload
      properties:
        attachmentName:
          type: string
          readOnly: true
          description: Name of the attachment file
          example: test_attachment.pdf
        type:
          type: string
          readOnly: true
          description: File type of the attachment
          example: JPEG
        details:
          type: array
          items:
            type: string
          readOnly: true
          description: Details of insights gained from analyzing the attachment
          example:
          - has Javascript
        md5:
          type:
          - string
          - 'null'
          readOnly: true
          description: MD5 algorithm hash of the attachment
          example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
        sha1:
          type:
          - string
          - 'null'
          readOnly: true
          description: SHA1 hash of the attachment
          example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
        sha256:
          type:
          - string
          - 'null'
          readOnly: true
          description: SHA256 hash of the attachment
          example: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
        size:
          type: string
          readOnly: true
          description: Size of the attachment file
          example: 1KB
        createdOn:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp attachment file was created on
          example: '2020-01-01T00:00:00Z'
        lastUpdated:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp attachment file was last updated
          example: '2020-01-01T00:00:00Z'
        url:
          type: array
          items:
            type: string
          readOnly: true
          description: URLs found in the attachment
          example:
          - http://malicious.lamronba.com
        keyPhrases:
          type: array
          items:
            type: string
          readOnly: true
          description: Key phrases flagging the attachment as potential malware
          example:
          - view
          - completed document
      required:
      - attachmentName
      - createdOn
      - details
      - keyPhrases
      - lastUpdated
      - md5
      - sha1
      - sha256
      - size
      - type
      - url
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer