openapi: 3.0.1
info:
  title: PCM Qualys ELT Clouds API Services
  description: |
    This service isa RESTful API service that provides access to Qualys Vulnerability Data. The data will cover all Clouds and on On Premise assets.
    The REST API is a collection of HTTP methods that are used to interact with the Qualys Vulnerability Data. The backend is Athena that is used to query the data and lambdas to deliver the data.
    All the data is stored in S3 buckets.

    ## Query Pattern
    1. Authorization: This is a POST method that will return an authorization token. This token is used to access the API.
    2. Query Execution: This is a POST method that will execute the query and return a query id to get the results.
    3. Query Finder: This is a POST method that will return the query data based on the query id.
  version: 1.0.4
servers:
  - url: https://api-dev.pearsoncloudmanagement.com/{basePath}
    variables:
      basePath:
        default: qualys_vulnerabilities
  - url: https://api.pearsoncloudmanagement.com/{basePath}
    variables:
      basePath:
        default: qualys_vulnerabilities
tags:
  - name: authorization
    description: Authorization
  - name: vpd
    description: |
      Information about  VPD including t_AppID, number of instances, number of vulnerabilities, VPD, and report date.
      Each row of the results CSV represents a t_AppID in a specific account, with the VPD information corresponding to that t_AppID
      These endpoints have access to AWS instance vulnerability information in any Pearson account.
  - name: vulnerabilities
    description: |
      Information about Qualys vulnerabilities including t_AppID, number of instances, number of vulnerabilities, and report date.
      Each row of the results CSV represents a t_AppID in a specific account, with the VPD information corresponding to that t_AppID
      These endpoints have access to AWS instance vulnerability information in any Pearson account.
  - name: finder
    description: |
      Finder creates a pre-signed url to download the CSV file with the results of the query.
paths:
  /historicvpd:
    post:
      tags:
        - vpd
      summary: historicvpd
      description: |
        ## Historic VPD
        Intiate a query for the Historic VPD. Must use a valid authorization. The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url.  
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /currentvpd:
    post:
      tags:
        - vpd
      summary: currentvpd
      description: |
        ## Current VPD
        Intiate the query for the Current VPD. Must use a valid authorization. The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url.
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /healthcheck:
    get:
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /authtoken:
    post:
      tags:
        - authorization
      summary: Retrieve Authorization Token
      description: |
        Retrieve an authorization token using a user_group_name and user_group_token.
        Include a valid user_group_name and user_group_token pair on the post body.
        The user_group_name and user_group_token must be base64 encoded.
        Please note that a valid api access token may not work for all endpoints in this API, depending on the scope of access for your user group.
      requestBody:
        description: Required JSON body including the base64 encoded user_group_name and user_group_token.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_group_name:
                  description: url base64 encoded user_group_name. Required.
                  type: string
                  nullable: false
                user_group_token:
                  description: url base64 encoded user_group_token. Required
                  type: string
                  nullable: false
      responses:
        '201':
          description: |
            The user_group_name and user_group_token are valid.
            Response contains an api_access_token for use as a Bearer token with subsequent API calls.
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_access_token:
                    description: api_access_token for use as a Bearer token with subsequent API calls
                    type: string
                    nullable: false
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
        '400':
          description: Bad Request
        '401':
          description: Invalid user_group_name or user_group_token
        '403':
          description: Forbidden
        '500':
          description: Server error. Try again.
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${AuthToken.Arn}/invocations
        passthroughBehavior: when_no_match
  /currentvuln:
    post:
      tags:
        - vulnerabilities
      summary: currentvuln
      description: |
        ## Current Vulnerabilities
        Intiate the query for the Current Vulnerabilities. Must use a valid authorization. The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url.  
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /historicvuln:
    post:
      tags:
        - vulnerabilities
      summary: historicvuln
      description: |
        ## Historic Vulnerabilities
        Intiate the query for the Historic Vulnerabilities. Must use a valid authorization. The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url. 
      parameters:
        - in: query
          name: account_id
          schema:
            type: array
            items:
              type: string
          description: The account id of the cloud. This can be singular or in a list. ?account_id=12345
        - in: query
          name: instance_id
          schema:
            type: array
            items:
              type: string
          description: The instance id of the cloud server instance. This can be singular or in a list.
        - in: query
          name: ami_id
          schema:
            type: array
            items:
              type: string
          description: The ami id of the EC2 instances. This can be singular or in a list.
        - in: query
          name: t_appid
          schema:
            type: array
            items:
              type: string
          description: The t_AppID of the product. This can be singular or in a list.
        - in: query
          name: report_date
          schema:
            type: array
            items:
              type: string
          description: The report_date of the product. This be a singular date or a list of dates. Dates must be in yyyy-m-d format.
        - in: query
          name: start_report_date
          schema:
            type: string
          description: Starting date in a range of dates. This must be used with `end_report_date`.  Dates must be in yyyy-m-d format.
        - in: query
          name: end_report_date
          schema:
            type: string
          description: Ending date in a range of dates. This must be used with `start_report_date`.  Dates must be in yyyy-m-d format.
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /missingagents:
    post:
      tags:
        - vulnerabilities
      summary: missingagents
      description: |
        ## Missing Agents
        Intiate the query for the SRE X Vulnerabilities. Must use a valid authorization. The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url.  
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
            - user/ciso_reader
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /endoflifeosvuln:
    post:
      tags:
        - vulnerabilities
      summary: Current End of Life Operating Systems
      description: |
        ## Missing Agents
        Initiate the query for the Vulnerabilities Current End of Life Operating Systems. Must use a valid authorization. 
        The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url.
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
            - user/ciso_reader
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /instanceassetaccount:
    post:
      tags:
        - vpd
      summary: Instances Asset Account
      description: |
        ## Instances Asset Account
        Intiate the query for the Instances with assets. Must use a valid authorization. The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url.
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
            - user/ciso_reader
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /srexvuln:
    post:
      tags:
        - vulnerabilities
      summary: SRE X currentvuln
      description: |
        ## Current Vulnerabilities
        Intiate the query for the SRE X Vulnerabilities. Must use a valid authorization. The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url.  
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
            - user/sre_x_reader
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysExecutorLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /findquery:
    get:
      tags:
        - finder
      summary: Query Finder
      description: |
        ## Query Finder
        Intiate the query for the Current Vulnerabilities. Must use a valid authorization. The query will return a query execution id and a query execution status.
        The status will let you know if the query is "QUEUED", "RUNNING", "SUCCEEDED", or "FAILED". 
        --The results of the query will not be included on the response body directly.--
        Instead, the response body will contain a 'query_execution_id' from which you may poll the results from the 'findquery' endpoint. 
        The 'findquery' endpoint will return the results of the query in a CSV format. The endpoint is a pre-signed S3 url that will allow you to download the CSV file.
        This pre-signed url is available for a limited time. Re-run this endpoint with the same query execution id to retrieve a new pre-signed S3 url.
      responses:
        '204':
          description: 204 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Vary:
              schema:
                type: string
            Access-Control-Max-Age:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      security:
        - QualysETLCloudsUserPool:
            - user/full
            - user/sre_x_reader
            - user/ciso_reader
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri:
          Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${QualysFinderLambdaApi.Arn}/invocations
        passthroughBehavior: when_no_match
  /:
    get:
      summary: API landing page
      operationId: APILandingPage
      responses:
        '200':
          description: Default 200 response
          headers:
            Content-Type:
              schema:
                type: string
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
        '404':
          description: API landing page not found
          headers:
            Content-Type:
              schema:
                type: string
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content: {}
      x-amazon-apigateway-integration:
        responses:
          default:
            statusCode: '200'
            responseParameters:
              method.response.header.Content-Type: '''text/html'''
              method.response.header.Access-Control-Allow-Headers: '''Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,Api-Auth-Token'''
              method.response.header.Access-Control-Allow-Methods: '''*'''
              method.response.header.Access-Control-Allow-Origin: '''*'''
            responseTemplates:
              text/html: |
                <!DOCTYPE html> <html lang="en">
                  <head>
                    <meta charset="utf-8"> <!-- Important: rapi-doc uses utf8 charecters -->
                    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
                  </head>
                  <body>
                    <!-- Swagger build propagates info.version. Change the version in openapi.yaml, not here. v0.0.0 is a placeholder. -->
                    <rapi-doc spec-url = "https://downloads.pearsoncloudmanagement.com/qualys_vulnerabilities/$context.stage/api/openapi_bundled_v1.0.4.yaml"> </rapi-doc>
                  </body>
                </html>
        requestTemplates:
          application/json: '{ statusCode: 200 }'
        passthroughBehavior: when_no_match
        type: mock
components:
  securitySchemes:
    QualysETLCloudsUserPool:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools
      x-amazon-apigateway-authorizer:
        type: cognito_user_pools
        providerARNs:
          - Fn::Sub: ${QualysUserPool.Arn}
