openapi: 3.2.0
info:
  version: 0.1.0
  title: References Credential watchlist 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: Credential watchlist
  description: Credentials incident reports and credentials
paths:
  /v1/reports_credentials/count:
    get:
      tags:
      - Credential watchlist
      summary: Get Number of Credentials Reports
      description: 'Return the number of credentials reports matching the specified filters.


        ⚠️ **Account Takeover Prevention module is required.**'
      operationId: get-reports-credentials-count
      parameters:
      - name: query
        in: query
        description: A text to look up in the credentials reports.
        schema:
          type: string
      - name: start
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: end
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: email
        in: query
        schema:
          type: string
      - name: severity
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  all:
                    type: integer
                    description: Total number of reports matching these criteria (without `draft` one)
                    examples:
                    - 1
                  discarded:
                    type: integer
                    description: Total number of *discarded* reports matching these criteria
                    examples:
                    - 1
                  draft:
                    type: integer
                    description: Total number of *draft* reports matching these criteria if user has permission to see them
                    examples:
                    - 1
                  in_progress:
                    type: integer
                    description: Total number of *in_progress* reports matching these criteria
                    examples:
                    - 1
                  open:
                    type: integer
                    description: Total number of *open* reports matching these criteria
                    examples:
                    - 1
                  resolved:
                    type: integer
                    description: Total number of *resolved* reports matching these criteria
                    examples:
                    - 1
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token: []
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/credentials:
    get:
      tags:
      - Credential watchlist
      summary: Get credential watchlist
      description: 'Return the list of monitored credentials matching the specified filters.


        ⚠️ **Account Takeover Protection module is required.**

        '
      operationId: get-credential-watchlist
      parameters:
      - name: status
        in: query
        style: form
        explode: false
        schema:
          type: array
          default:
          - compromised
          - addressed
          items:
            $ref: '#/components/schemas/CredentialStatus'
      - name: start
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: end
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: email
        in: query
        schema:
          type: string
      - name: skip
        in: query
        description: The number of results that are skipped.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: The number of results that are returned.
        schema:
          type: integer
          default: 10
      - name: sort_by
        in: query
        description: The field on which we sort the results.
        schema:
          type: string
          default: last_detection_date
      - name: order
        in: query
        description: The sort order.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Credential'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - credentials.read
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/credentials/count:
    get:
      tags:
      - Credential watchlist
      summary: Get volume of credentials
      description: 'Return the number of credentials matching the specified filters.


        ⚠️ **Account Takeover Protection module is required.**

        '
      operationId: get-volume-of-credentials
      parameters:
      - name: start
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: end
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: email
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  addressed:
                    type: integer
                  all:
                    type: integer
                  compromised:
                    type: integer
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token: []
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/credentials/export:
    get:
      tags:
      - Credential watchlist
      summary: Get export credential watchlist (CSV file)
      description: 'Export a CSV that contains the list of Account Takeover Protection reports matching the specified filters.


        ⚠️ **Account Takeover Protection module is required.**

        '
      operationId: get-export-credential-watchlist
      parameters:
      - name: email
        in: query
        schema:
          type: string
          examples:
          - john.doe@acme.fr
      - name: end
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: start
        in: query
        schema:
          $ref: '#/components/schemas/Date'
      - name: status
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ReportStatus'
      responses:
        '200':
          description: OK
          content:
            text/csv:
              schema:
                type: string
                examples:
                - 'Email,Password,Incident id,Source,Category,Severity,Published date,Keywords

                  john.doe@acme.fr,MZIzNDU2,333e67ff-2aef-4367-8b62-8fb2c74efe3e,Gist.githubusercontent.com,paste,4,14/12/2020,[''test.com'']

                  jane.doe@acme.fr,DZlJDK34,333e67ff-2aef-4367-8b62-8fb2c74efe3e,Gist.githubusercontent.com,paste,4,14/12/2020,[''test.com'']

                  '
              examples:
                default:
                  value: 'Email,Password,Incident id,Source,Category,Severity,Published date,Keywords

                    john.doe@acme.fr,MZIzNDU2,333e67ff-2aef-4367-8b62-8fb2c74efe3e,Gist.githubusercontent.com,paste,4,14/12/2020,[''test.com'']

                    jane.doe@acme.fr,DZlJDK34,333e67ff-2aef-4367-8b62-8fb2c74efe3e,Gist.githubusercontent.com,paste,4,14/12/2020,[''test.com'']

                    '
          headers:
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename=credentials.csv
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - credentials.export
      servers:
      - url: https://platform.cybelangel.com/api
  /v1/credentials/status:
    post:
      tags:
      - Credential watchlist
      summary: Update status of credential
      description: 'Update status of the specified credentials


        ⚠️ **Account Takeover Protection module is required.**

        '
      operationId: update-status-of-credential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  description: The ids of the credentials to update
                  items:
                    type: string
                    format: uuid
                    examples:
                    - 670e7227-74c9-4579-b6e3-f91ad0169a08
                status:
                  $ref: '#/components/schemas/CredentialStatus'
              required:
              - ids
              - status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: integer
                description: Number of updated credentials
                examples:
                - 27
              examples:
                default:
                  value: 27
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
      - bearer_token:
        - credentials.move
      servers:
      - url: https://platform.cybelangel.com/api
      x-codegen-request-body-name: body
components:
  responses:
    Error403:
      description: '**Forbidden**


        Access to requested resource is forbidden with current credentials.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: number
                description: internal error code
              msg:
                type: string
                description: internal error message
              type:
                description: internal error type
                examples:
                - error
    Error401:
      description: '**Unauthorized**


        Authentication is required

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: number
                description: internal error code
              msg:
                type: string
                description: internal error message
              type:
                description: internal error type
                examples:
                - error
    Error400:
      description: '**Bad request**


        Check query parameters

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: number
                description: internal error code
              msg:
                type: string
                description: internal error message
              type:
                description: internal error type
                examples:
                - error
    Error500:
      description: '**Internal server error**


        An unexpected error occurred during request

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: number
                description: internal error code
              msg:
                type: string
                description: internal error message
              type:
                description: internal error type
                examples:
                - error
  schemas:
    ReportStatus:
      type: string
      enum:
      - draft
      - open
      - in_progress
      - resolved
      - discarded
      examples:
      - resolved
    CredentialStatus:
      type: string
      enum:
      - compromised
      - addressed
      examples:
      - addressed
    Credential:
      type: object
      properties:
        alert_ids:
          type: array
          items:
            type: string
            description: Ids of alerts in data processing
            format: uuid
            examples:
            - 739d79f6-b18b-4819-9444-bb52d42af2ff
        cred_ids:
          type: array
          items:
            type: string
            description: Credential identifiers in database
            format: uuid
            examples:
            - af2774a2-6f2d-4395-a9cf-768c99dc4849
        domain:
          type: string
          description: 'For Infostealer Credentials only: domain on which the credential can be used'
          examples:
          - http://www.example.com
        email:
          type: string
          description: The email
          format: email
          examples:
          - john.doe@acme.com
        extracted_at:
          type: string
          description: 'For Infostealer Credentials only: date on which the credential has been extracted from the victim computer'
          examples:
          - '2021-01-21T14:03:07Z'
        ip_address:
          type: string
          description: 'For Infostealer Credentials only: IP address of the victim'
          examples:
          - 123.123.123.123
        malware_name:
          type: string
          description: 'For Infostealer Credentials only: Detected malware name'
        malware_location:
          type: string
          description: 'For Infostealer Credentials only: Path of malware on victim''s machine'
        user_machine_name:
          type: string
          description: 'For Infostealer Credentials only: Victim''s machine name'
        user_session:
          type: string
          description: 'For Infostealer Credentials only: Victim''s session identifier'
        is_new_to_user:
          type: boolean
          description: Whether the current user has already seen this credential or not
          examples:
          - true
        last_detection_date:
          type: string
          description: The last date at which this credential has been detected
          format: date
          examples:
          - '2020-12-16T13:27:49Z'
        password:
          type: string
          description: The obfuscated (or clear if permitted) password
          examples:
          - 315bea••••••••••••••••••••cc5ed3
        report_ids:
          type: array
          items:
            type: string
            description: Ids of the related reports
            format: uuid
            examples:
            - 333e67ff-2aef-4367-8b62-8fb2c74efe3e
        reports_count:
          type: integer
          description: Number of related reports
          examples:
          - 1
        status:
          $ref: '#/components/schemas/CredentialStatus'
        stream_id:
          type: string
          description: Ids of the stream
          format: uuid
          examples:
          - caa4eb9e-2741-4e9a-8b1c-4eeceb490e2a
    Date:
      type: string
      format: date
      examples:
      - '2021-07-05T22:00:00.000Z'
  securitySchemes:
    bearer_token:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            assets.download: Downloading an asset
            reports.move: Resolve or reopen an incident report
            reports.read: Read incident reports
            reports_global_comments.read: Read comments of a incident report
            reports_global_comments.write: Write comments on a incident report (Endpoint not accessible, yet)
            usergroups.admin: Read and manage usergroups
            usergroups.read: Read subscribed usergroups
            credentials.read: Read list of leaked monitored credentials
            credentials.move: Resolve or reopen a credential
            credentials.export: Export list of credentials
          tokenUrl: https://auth.cybelangel.com/oauth/token