gulag/gulag-openapi-2.0.yaml

swagger: '2.0'
info:
  description: https://app.swaggerhub.com/apis/DC-IT-Consulting/Gulag/1.0.0#/
  version: "1.0.0"
  title: Gulag quarantine REST API
  contact:
    email: info@dc-it-con.de
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
host: gulag.example.com
basePath: "/api/v1"
schemes:
  - https
paths:
  /quarmails:
    get:
      summary: retrieves quarantined emails
      operationId: get_quarmails
      description: |
        By passing in the appropriate parameters, you can search for
        available quarantined emails        
      produces:
      - application/json
      parameters:
      - in: query
        name: query_limit
        description: number of records to retrieve
        type: integer
        format: int32
        minimum: 0
        required: false
      - in: query
        name: query_offset
        description: number of records to skip for pagination
        required: false
        type: string
      - in: query
        name: sort_index
        description: field used to sort results
        type: string
        required: false
      - in: query
        name: sort_order
        description: order used to sort results
        type: string
        required: false
      - in: query
        name: rfc822_message
        type: string
        required: false
        description: get full RFC822 email message for each QuarMail object
      - in: query
        name: headers
        description: get all email headers for each QuarMail object
        required: false
      - in: query
        name: filters
        type: string
        required: false
        description: 'jqgrid-style filters, e.g. {"groupOp":"AND","rules":[{"field":"uri_count","op":"eq","data":"3"}]}'
      responses:
        200:
          description: search results matching criteria
          schema:
            type: array
            items:
              $ref: '#/definitions/QuarMail'
        400:
          description: bad input parameter
        500:
          description: server error

  /quarmails/{quarmail_id}:
    get:
      summary: retrieves a quarantined email
      operationId: get_quarmail
      produces:
      - application/json
      parameters:
      - in: path
        name: quarmail_id
        description: unique id of quarantined email
        required: true
        type: integer
      - in: query
        name: rfc822_message
        description: if set to a (random) value, full RFC822 email message will be returned
        type: string
        required: false
      - in: query
        name: headers
        description: if set to a (random) value, all email headers will be returned
        required: false
      responses:
        200:
          description: quarantined email object
          schema:
            $ref: '#/definitions/QuarMail'
        400:
          description: bad input parameter
        404:
          description: not found
        500:
          description: server error
    patch:
      summary: modifies a quarantined email
      operationId: modify_quarmail
      produces:
      - application/json
      parameters:
      - in: path
        name: quarmail_id
        description: unique id of quarantined email
        required: true
        type: integer
      - in: body
        name: quarmail
        description: quarmail fields to modify.
          schema:
            $ref: "#/definitions/QuarMail"
      responses:
        202:
          description: quarantined email deleted
        404:
          description: not found
        500:
          description: server error
    delete:
      summary: deletes a quarantined email
      operationId: delete_quarmail
      produces:
      - application/json
      parameters:
      - in: path
        name: quarmail_id
        description: unique id of quarantined email
        required: true
        type: integer
      responses:
        202:
          description: quarantined email deleted
        404:
          description: not found
        500:
          description: server error
  /quarmails/{quarmail_id}/attachments:
    get:
      summary: retrieves meta data of all attachments of a quarantined email by quarmail_id
      operationId: get_quarmail_attachments
      produces:
      - application/json
      parameters:
      - in: path
        name: quarmail_id
        description: unique id of quarantined email
        required: true
        type: string
      responses:
        200:
          description: quarantined email object
          schema:
            type: array
            items:
              $ref: '#/definitions/Attachment'
        400:
          description: bad input parameter
        404:
          description: not found
        500:
          description: server error

  /quarmails/{quarmail_id}/attachments/{attachment_id}:
    get:
      summary: retrieves a quarantined email
      operationId: get_quarmail_attachment
      produces:
      - application/json
      parameters:
      - in: path
        name: quarmail_id
        description: unique id of quarantined email
        required: true
        type: integer
      - in: path
        name: attachment_id
        description: unique id of attachment
        required: true
        type: integer
      - in: query
        name: data
        description: if set to a (random) value, full attachment will be returned as well
        type: string
        required: false
      responses:
        200:
          description: attachment object
          schema:
            $ref: '#/definitions/Attachment'
        404:
          description: not found
        500:
          description: server error

  /quarmails/{quarmail_id}/uris:
    get:
      summary: "retrieves all URIS from any main MIME part (text/plain,text/html)"
      operationId: get_quarmail_uris
      produces:
      - application/json
      parameters:
      - in: path
        name: quarmail_id
        description: unique id of quarantined email
        required: true
        type: string
      - in: query
        name: from_rfc822_message
        description: fetch all URIs from RFC822 message not from database
        required: false
        type: string
      responses:
        200:
          description: array of URIs
          schema:
            type: array
            items:
              $ref: '#/definitions/URI'
        400:
          description: bad input parameter
        404:
          description: not found
        500:
          description: server error

  /quarmails/{quarmail_id}/uris/{uri_id}:
    get:
      summary: "returns an URI by ID"
      operationId: get_quarmail_uri
      produces:
      - application/json
      parameters:
      - in: path
        name: quarmail_id
        description: unique id of quarantined email
        required: true
        type: string
      - in: path
        name: uri_id
        description: id of URI to fetch
        required: true
        type: string
      responses:
        200:
          description: URI object
          schema:
            $ref: '#/definitions/URI'
        404:
          description: not found
        500:
          description: server error
  /quarmails/{quarmail_id}/bounce:
    post:
      summary: bounces a quarantined email by quarmail_id
      operationId: bounce_quarmail
      produces:
      - application/json
      parameters:
      - in: path
        name: quarmail_id
        description: unique id of quarantined email
        required: true
        type: string
      responses:
        200:
          description: null
        400:
          description: bad input parameter
        404:
          description: not found
        500:
          description: server error

definitions:
  QuarMail:
    type: object
    required:
    - id
    - ctime
    - mx_queueid
    - env_from
    - env_rcpt
    - hdr_cf
    - hdr_from
    - hdr_subject
    - hdr_msgid
    - hdr_date
    - cf_meta
    - mailbox_id
    - imap_uid
    - msg_size
    - ssdeep
    - href
    properties:
      id:
        type: integer
        description: unique id of a quarantined email
      ctime:
        type: string
        example: "2018-12-09 11:14:18"
      mx_queueid:
        type: string
        example: "43CNrL6pK2zSV"
      env_from:
        type: string
        description: RFC5321 envelope sender
        example: alice@example.org
      env_rcpt:
        type: string
        description: RFC5321 envelope recipient
        example: bob@example.com
      hdr_cf:
        type: string
        description: content filter header
        example: '[{"group":"ungrouped","name":"GTUBE","score":0}]'
      hdr_from:
        type: string
        description: RFC5322 From header
      hdr_subject:
        type: string
        description: RFC5322 Subject header
      hdr_msgid:
        type: string
        description: RFC5322 Message-ID header
      hdr_date:
        type: string
        description: RFC5322 Date header
      cf_meta:
        type: string
        description: content filter meta infos
      mailbox_id:
        type: string
        description: IMAP mailbox name, that holds the quarantined email
        example: quarantine@example.com
      imap_uid:
        type: integer
        description: IMAP unique id of the quarantined email
      href:
        type: string
        description: hypermedia
        example: "https://gulag.example.org/api/v1/quarmails/123"
      attach_count:
        type: integer
        description: number of attachments
      uri_count:
        type: integer
        description: number of uris
      ssdeep:
        type: string
        description: Context triggered piecewise hash (CTPH)
        example: '6:lWRUFiWwx5QHD2Q2/NNsj90YzrWPpsj7v:lWiEQHD2Q+sj90aKsjr'
      rfc822_message:
        type: string
        description: full RFC822 email message
      headers:
        type: string
        description: email headers
  Attachment:
    type: object
    required:
    - id
    - filename
    - content_encoding
    - content_type
    - magic
    - mailbox_id
    - imap_uid
    - ssdeep
    - sha256
    - href
    properties:
      id:
        type: integer
        description: unique id of an attachment
      filename:
        type: string
        description: filename extracted from Content-Type header
      comment:
        type: string
      content_encoding:
        type: string
        example: base64
        description: method used to encode attachment (Content-Transfer-Encoding header)
      content_type:
        type: string
        example: image/jpeg
      magic:
        type: string
        example: "PDF document, version 1.2"
      href:
        type: string
        description: hypermedia
        example: "https://gulag.example.org/api/v1/quarmails/123/attachment/2"
      mailbox_id:
        type: string
        description: IMAP mailbox name, that holds the quarantined email
        example: quarantine@example.com
      imap_uid:
        type: integer
        description: IMAP unique id of the quarantined email
        example: 12345
      data:
        type: string
        description: raw/encoded (see content_encoding) attachment payload
      ssdeep:
        type: string
        description: Context Triggered Piecewise Hash (CTPH)
        example: '6:lWRUFiWwx5QHD2Q2/NNsj90YzrWPpsj7v:lWiEQHD2Q+sj90aKsjr'
      sha256:
        type: string
        description: SHA256 digest
        example: '658cb334f4ab3d747e77fdfceaa1ff3c2477ccc8500c4d8f4552ac0471089b60'
  URI:
    type: object
    required:
    - id
    - uri
    - fqdn
    properties:
      id:
        type: integer
      uri:
        type: string
      fqdn:
        type: string
      href:
        type: string