swagger: "2.0"
schemes:
  - https
host: api.cisco.com
info:
  contact:
    email: os@cisco.com
    name: Omar Santos
  description: |
    The Cisco Product Security Incident Response Team (PSIRT) openVuln API is a RESTful API that allows customers to obtain Cisco Security Vulnerability information in different machine-consumable formats. APIs are important for customers because they allow their technical staff and programmers to build tools that help them do their job more effectively (in this case, to keep up with security vulnerability information).
    For more information about the Cisco PSIRT openVuln API visit https://developer.cisco.com/site/PSIRT/discover/overview

    For detail steps on how to use the API go to:https://developer.cisco.com/site/PSIRT/get-started/getting-started.gsp

    This is a beta release of a swagger YAML for the Cisco PSIRT openVuln API

    To access the API sign in with your Cisco CCO account at http://apiconsole.cisco.com and register an application
    to recieve a client_id and a client_secret

    You can then get your token using curl or any other method you prefer.

    'curl -s -k -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "client_id=<your_client_id>" -d "client_secret=<your_client_secret>" -d "grant_type=client_credentials" https://cloudsso.cisco.com/as/token.oauth2'

    You will receive an access token as demonstrated in the following example:
     '{"access_token":"I7omWtBDAieSiUX3shOxNJfuy4J6","token_type":"Bearer","expires_in":3599}'

    In Swagger, click on Change Authentication

    enter the text "I7omWtBDAieSiUX3shOxNJfuy4J6" (which is the token you received)

    then click on "Try this operation"
  title: Cisco PSIRT openVuln API
  version: 0.0.3
  x-apisguru-categories:
    - security
  x-logo:
    url: https://logo-core.clearbit.com/cisco.com
  x-origin:
    - format: swagger
      url: https://raw.githubusercontent.com/CiscoPSIRT/openVulnAPI/master/swagger/openVulnAPISwagger0_0_3.yaml
      version: "2.0"
  x-providerName: cisco.com
produces:
  - application/json
securityDefinitions:
  psirt_openvuln_api_auth:
    authorizationUrl: https://cloudsso.cisco.com/as/token.oauth2
    flow: implicit
    scopes:
      read:cvrf: read cvrf files
      read:oval: read oval files
    type: oauth2
paths:
  "/security/advisories/cvrf/advisory/{advisory_id}":
    get:
      description: |
        Used to obtain an advisory in CVRF format for a given advisory ID `advisory_id` (i.e., cisco-sa-20150819-pcp)
      parameters:
        - description: advisory ID
          format: cisco-sa-XXX
          in: path
          name: advisory_id
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  /security/advisories/cvrf/all:
    get:
      description: |
        Used to obtain all advisories in Common Vulnerability Reporting Format (CVRF). For more information about CVRF go to https://communities.cisco.com/docs/DOC-63156 . By default the output is in JSON. To obtain the output in XML use the .xml extension. For example, /advisories/cvrf/all.xml
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/cvrf/cve/{cve_id}":
    get:
      description: |
        Used to obtain an advisory in CVRF format for a given Common Vulnerability Enumerator (CVE). The `cve_id` format is CVE-YYYY-NNNN. For more information about CVE visit http://cve.mitre.org/
      parameters:
        - description: CVE Identifier (i.e., CVE-YYYY-NNNN)
          format: CVE-YYYY-NNNN
          in: path
          name: cve_id
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/cvrf/latest/{number}":
    get:
      description: |
        Used to obtain all the latest security advisories in CVRF format given an absolute number. For instance, the latest 10 or latest 5.
      parameters:
        - description: An absolute number to obtain the latest security advisories.
          format: number
          in: path
          name: number
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  /security/advisories/cvrf/product:
    get:
      description: |
        Used to obtain all the advisories that affects the given product name.
      parameters:
        - description: An product name to obtain security advisories that matches given product name.
          format: string
          in: query
          name: product
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/cvrf/severity/{severity}":
    get:
      description: |
        Used to obtain all security advisories for a given security impact rating (critical, high, medium, or low) in CVRF format.
      parameters:
        - description: Critical, High, Medium, Low
          enum:
            - critical
            - high
            - medium
            - low
          format: enum
          in: path
          name: severity
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/cvrf/severity/{severity}/firstpublished":
    get:
      description: |
        Used to obtain all security advisories for a given security impact rating (critical, high, medium, or low) in CVRF format and additionally filter based of firstpublished start date and enddate
      parameters:
        - description: Used to obtain all advisories that have a security impact rating of critical
          enum:
            - critical
            - high
            - medium
            - low
          format: enum
          in: path
          name: severity
          required: true
          type: string
        - format: date
          in: query
          name: startDate
          required: true
          type: string
        - format: date
          in: query
          name: endDate
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/cvrf/severity/{severity}/lastpublished":
    get:
      description: |
        Used to obtain all security advisories for a given security impact rating (critical, high, medium, or low) in CVRF format.
      parameters:
        - description: Used to obtain all advisories that have a security impact rating of critical
          enum:
            - critical
            - high
            - medium
            - low
          format: enum
          in: path
          name: severity
          required: true
          type: string
        - format: date
          in: query
          name: startDate
          required: true
          type: string
        - format: date
          in: query
          name: endDate
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/cvrf/year/{year}":
    get:
      description: |
        Used to obtain all security advisories that have were orginally published in a specific year `YYYY`.
      parameters:
        - description: The four digit year.
          format: YYYY
          in: path
          name: year
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  /security/advisories/ios:
    get:
      description: |
        Used to obtain all advisories that affects the given ios version
      parameters:
        - description: IOS version to obtain security advisories
          format: string
          in: query
          name: version
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  /security/advisories/iosxe:
    get:
      description: |
        Used to obtain all advisories that affects the given ios version
      parameters:
        - description: IOS version to obtain security advisories
          format: string
          in: query
          name: version
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/oval/advisory/{advisory_id}":
    get:
      description: |
        Used to obtain OVAL definitions for a given advisory ID `advisory_id` (i.e., cisco-sa-20150819-pcp)
      parameters:
        - description: advisory ID
          format: cisco-sa-XXX
          in: path
          name: advisory_id
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  /security/advisories/oval/all:
    get:
      description: |
        Used to obtain all Open Vulnerability and Assessment Language (OVAL) definitions available for Cisco security vulnerabilities. For more information about OVAL go to https://communities.cisco.com/docs/DOC-63158 . By default the output is in JSON. To obtain the output in XML use the .xml extension. For example, /advisories/oval/all.xml
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/oval/cve/{cve_id}":
    get:
      description: |
        Used to obtain OVAL definitions for a given CVE Identifier. The `cve_id` format is CVE-YYYY-NNNN.
      parameters:
        - description: CVE Identifier (i.e., CVE-YYYY-NNNN)
          format: CVE-YYYY-NNNN
          in: path
          name: cve_id
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/oval/latest/{number}":
    get:
      description: |
        Used to obtain all the latest OVAL definitions given an absolute number. For instance, the latest 10 or latest 5.
      parameters:
        - description: The latest OVAL definitions (absolute number).
          format: number
          in: path
          name: number
          required: true
          type: integer
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  /security/advisories/oval/product:
    get:
      description: |
        Used to obtain all the oval advisories that affects the given product name.
      parameters:
        - description: An product name to obtain security advisories that matches given product name.
          format: string
          in: query
          name: product
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/oval/severity/{severity}":
    get:
      description: |
        Used to obtain all OVAL definitions for a given security impact rating (critical, high, medium, or low).
      parameters:
        - description: Used to obtain all OVAL definitions for advisories that have a security impact rating of critical
          enum:
            - critical
            - high
            - medium
            - low
          format: enum
          in: path
          name: severity
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/oval/severity/{severity}/firstpublished":
    get:
      description: |
        Used to obtain all security advisories for a given security impact rating (critical, high, medium, or low) in OVAL format.
      parameters:
        - description: Critical, High, Medium, Low
          enum:
            - critical
            - high
            - medium
            - low
          format: enum
          in: path
          name: severity
          required: true
          type: string
        - format: date
          in: query
          name: startDate
          required: true
          type: string
        - format: date
          in: query
          name: endDate
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
  "/security/advisories/oval/severity/{severity}/lastpublished":
    get:
      description: |
        Used to obtain all security advisories for a given security impact rating (critical, high, medium, or low) in OVAL format.
      parameters:
        - description: Critical, High, Medium, Low
          enum:
            - critical
            - high
            - medium
            - low
          format: enum
          in: path
          name: severity
          required: true
          type: string
        - format: date
          in: query
          name: startDate
          required: true
          type: string
        - format: date
          in: query
          name: endDate
          required: true
          type: string
      responses:
        "200":
          description: Successful response
      security:
        - psirt_openvuln_api_auth:
            - read:cvrf
            - read:oval
