openapi: 3.0.1
info:
  title: Check Point Reputation Service API
  description: |
    ## Introduction
    Leverage the Check Point’s threat intelligence to enrich your SIEM and SOAR solutions and secure your business applications and websites using simple RESTful APIs.  

    | **Input** | **Output** |
    |-------|--------|
    | **URL, IP, File digest (md5/sha1/sha256)**   | Reputation, Risk and Context     |

    ## Getting Started with the Reputation Service API
    ### 1. Get your API Key 
    [Contact us](mailto:TCAPI_SUPPORT@checkpoint.com) to get an API key
    
    <br>
    ### 2. Request a session token
    * Use the provided client key to get a session token
    * The session token is <ins>**valid for 30min**<ins>.  
    
    <ins>Request example:<ins>  
    ```linux
    curl -X GET "https://rep.checkpoint.com/rep-auth/service/v1.0/request" -H "Client-Key: XXXXXXXXXXXXX"
    ```
    <ins> Response example: <ins> 
    ```
    exp=XXXXXXX~acl=XXXX/*~hmac=XXXXXXXXX
    ```
    <br>
  
    ### 3. Reputation Service Query
    * With your API Key and the generated session token you can query Reputation Service
    * Fill in the required service [url-rep / file-rep / ip-rep]
    * Fill in the requested resource
    * **Important**: The resource should be inserted in 2 places:
      * **Paylod** [Json / Request Body] 
      * **Request parameter** [after ?resource=].  

    <ins>Request example:<ins>  
    ```linux
    curl -X POST "https://rep.checkpoint.com/url-rep/service/v2.0/query?resource=ynet.co.il" -H "accept: application/json" -H "Client-Key: XXXXXXX" -H "token: exp=XXXXXXX~acl=XXXX/*~hmac=XXXXXXXXX -H "Content-Type: application/json" -d "{\"request\":[{\"resource\":\"ynet.co.il\"}]}"
    ```

    <ins> Response example: <ins> 
    ```json
    {
      "response": [
          {
              "status": {
                  "code": 2001,
                  "label": "SUCCESS",
                  "message": "Succeeded to generate reputation"
              },
              "resource": "ynet.co.il",
              "reputation": {
                  "classification": "Benign",
                  "confidence": "High",
                  "severity": "N/A"
              },
              "risk": 0,
              "context": {
                  "categories": [
                      {
                          "id": 24,
                          "name": "News / Media"
                      }
                  ],
                  "indications": [
                      "The URL is known benign by Check Point's Threat Cloud",
                      "The domain is popular in the world",
                      "Domain is classified as News / Media"
                  ],
                  "safe": true
              }
          }
      ]
    }
    ```
  version: 1.0.0
servers:
  - url: 'https://rep.checkpoint.com'
paths:
  /rep-auth/service/v1.0/request:
    get:
      summary: Request a session token
      tags:
        - Authentication
      parameters:
        - name: Client-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Sucess - the response is a token valild for 30 minutes
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  '/{service}-rep/service/v2.0/query':
    post:
      summary: Query your resource
      tags:
        - Query
      parameters:
        - name: Client-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
        - name: token
          in: header
          required: true
          schema:
            type: string
        - name: service
          in: path
          description: The service you want to query
          required: true
          schema:
            type: string
            enum:
              - url
              - ip
              - file
        - name: resource
          in: query
          description: The resource you want to query
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReputationRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReputationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Unauthorized:
      description: Invalid Client-Key header
    BadRequest:
      description: Bad Request - Check the request paremters
    Forbidden:
      description: Invalid token header
    TooManyRequests:
      description: Quota exceeded
    NotFound:
      description: The requested URL was not found
  schemas:
    ReputationSingleRequest:
      properties:
        resource:
          type: string
    ReputationRequest:
      properties:
        request:
          type: array
          items:
            $ref: '#/components/schemas/ReputationSingleRequest'
      required:
        - request
    ReputationResponse:
      properties:
        risk:
          type: number
          example: 0
        resource:
          type: string
          example: 'http://google.com'
        reputation:
          $ref: '#/components/schemas/ReputationClassification'
        status:
          $ref: '#/components/schemas/ReputationStatus'
        context:
          $ref: '#/components/schemas/ReputationResponseContext'
    ReputationClassification:
      properties:
        classification:
          type: string
          example: Benign
        severity:
          type: string
          enum:
            - N/A
            - Low
            - Medium
            - High
            - Critical
        Confidence:
          type: string
          enum:
            - Low
            - Medium
            - High
    ReputationStatus:
      properties:
        code:
          type: integer
          enum:
            - 2001
            - 2002
        label:
          type: string
          enum:
            - SUCCESS
            - PARTIAL_SUCCESS
        message:
          type: string
          enum:
            - Succeeded to generate reputation
            - Some vendors are unavailable
    ReputationResponseContext:
      type: object
      properties:
        asn:
          type: number
          description: ASN of the IP (IP)
        as_owner:
          type: string
          description: ASN owner of the IP (IP)
        safe:
          type: boolean
          description: exists and true if certified safe (URL)
        malware_family:
          type: string
          description: the malware family associated with the resource  (URL/FILE/IP)
        protection_name:
          type: string
          description: The protection name returned from Malware Service / AntiVirus
            (URL/FILE)
        redirections:
          type: array
          description: The redirections of the resource (URL)
          items:
            type: string
        malware_types:
          type: array
          description: The malware types based on VT scans (FILE)
          items:
            type: string
        categories:
          type: array
          description: URLF categories (URL)
          items:
            type: string
        location:
          type: object
          description: geo location information (IP)
          properties:
            region:
              type: string
            city:
              type: string
            postalCode:
              type: string
            latitude:
              type: number
            longitude:
              type: number
            dma_code:
              type: integer
            area_code:
              type: integer
            metro_code:
              type: integer
        related_resources:
          type: object
          description: (FILE)
          properties:
            similar_files_found:
              description: How many similar files found
              type: number
            similar_files_details:
              description: Information about the similar file
              type: object
              properties:
                md5:
                  type: string
                ssdeep:
                  type: string
                ssdeep_similarity:
                  type: string
                file_type:
                  type: string
                classification:
                  type: string
                malware_family:
                  type: string
                confidence:
                  type: string