openapi: 3.0.0
info:
  title: GreyNoise Callback CVE API
  version: 3.0.0
  description: GreyNoise is a cybersecurity company that collects and analyzes Internet-wide scan and attack traffic. Use GreyNoise to contextualize existing alerts, filter false-positives, identify compromised devices, and track emerging threats.
  contact:
    email: hello@greynoise.io
  license:
    name: Proprietary
    url: https://www.greynoise.io/terms
servers:
- url: https://api.greynoise.io
  description: Production
security:
- APIKeyHeaderAuth: []
tags:
- name: CVE
  description: 'Endpoints that are used for retrieving information about Common Vulnerabilities and Exposures (CVEs).

    '
paths:
  /v1/cve/{cve_id}:
    get:
      operationId: getCVE
      tags:
      - CVE
      summary: Retrieve CVE Information
      description: Retrieve details about a specific Common Vulnerabilities and Exposures (CVE).
      parameters:
      - name: cve_id
        in: path
        description: The CVE ID to query (e.g., CVE-2024-12345)
        required: true
        schema:
          type: string
          pattern: ^CVE-\d{4}-\d+$
      responses:
        '200':
          description: Successful response with CVE details based on entitlements.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CVEAdvancedResponse'
                - $ref: '#/components/schemas/CVEBasicResponse'
                - $ref: '#/components/schemas/CVEMinimalResponse'
              examples:
                GetCVE200Example:
                  summary: Default getCVE 200 response
                  x-microcks-default: true
                  value:
                    id: CVE-2024-12345
                    details:
                      vulnerability_name: Sample Vulnerability
                      vulnerability_description: This vulnerability allows remote attackers to execute arbitrary code.
                      cve_cvss_score: 7.5
                      product: Sample Product
                      vendor: Sample Vendor
                      published_to_nist_nvd: true
                    timeline:
                      cve_published_date: '2024-01-01'
                      cve_last_updated_date: '2024-01-02'
                      first_known_published_date: '2024-01-01'
                      cisa_kev_date_added: '2024-01-03'
                    exploitation_details:
                      attack_vector: Network
                      exploit_found: true
                      exploitation_registered_in_kev: true
                      epss_score: 0.8
                    exploitation_stats:
                      number_of_available_exploits: 5
                      number_of_threat_actors_exploiting_vulnerability: 3
                      number_of_botnets_exploiting_vulnerability: 2
                    exploitation_activity:
                      activity_seen: true
                      benign_ip_count_1d: 100
                      benign_ip_count_10d: 500
                      benign_ip_count_30d: 1000
                      threat_ip_count_1d: 10
                      threat_ip_count_10d: 50
                      threat_ip_count_30d: 100
        '400':
          description: Invalid CVE ID format or missing CVE ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'bad query: invalid CVE format'
        '404':
          description: CVE not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: CVE not found
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: internal server error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/cves:
    post:
      operationId: bulkCVELookup
      tags:
      - CVE
      summary: Bulk CVE Lookup
      description: 'Retrieve information about multiple CVEs in a single request. Supports up to 10,000 CVEs per request.


        This endpoint requires a business email address and appropriate entitlements.

        Response type depends on user entitlements (minimal, basic, or advanced).

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cves
              properties:
                cves:
                  type: array
                  items:
                    type: string
                    pattern: ^CVE-\d{4}-\d+$
                  description: Array of CVE IDs to lookup
                  example: &id001
                  - CVE-2024-12345
                  - CVE-2023-45678
                  maxItems: 10000
            examples:
              BulkCVELookupRequestExample:
                summary: Default bulkCVELookup request
                x-microcks-default: true
                value:
                  cves: *id001
      responses:
        '200':
          description: OK - request successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/CVEAdvancedResponse'
                  - $ref: '#/components/schemas/CVEBasicResponse'
                  - $ref: '#/components/schemas/CVEMinimalResponse'
              examples:
                BulkCVELookup200Example:
                  summary: Default bulkCVELookup 200 response
                  x-microcks-default: true
                  value:
                  - id: CVE-2024-12345
                    details:
                      vulnerability_name: Sample Vulnerability
                      vulnerability_description: This vulnerability allows remote attackers to execute arbitrary code.
                      cve_cvss_score: 7.5
                      product: Sample Product
                      vendor: Sample Vendor
                      published_to_nist_nvd: true
                    timeline:
                      cve_published_date: '2024-01-01'
                      cve_last_updated_date: '2024-01-02'
                      first_known_published_date: '2024-01-01'
                      cisa_kev_date_added: '2024-01-03'
                    exploitation_details:
                      attack_vector: Network
                      exploit_found: true
                      exploitation_registered_in_kev: true
                      epss_score: 0.8
                    exploitation_stats:
                      number_of_available_exploits: 5
                      number_of_threat_actors_exploiting_vulnerability: 3
                      number_of_botnets_exploiting_vulnerability: 2
                    exploitation_activity:
                      activity_seen: true
                      benign_ip_count_1d: 100
                      benign_ip_count_10d: 500
                      benign_ip_count_30d: 1000
                      threat_ip_count_1d: 10
                      threat_ip_count_10d: 50
                      threat_ip_count_30d: 100
        '400':
          description: 'Bad request - invalid CVE format or too many CVEs requested.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Maximum number of CVEs per request is 10000
        '403':
          description: 'Forbidden - bulk CVE search requires a business email address.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Bulk CVE search is only available to users with a business email address. Sign up with your work email (e.g., you@company.com) to continue.
        '429':
          description: Too many requests. You've hit the rate-limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BulkCVELookup429Example:
                  summary: Default bulkCVELookup 429 response
                  x-microcks-default: true
                  value:
                    message: Success
        '500':
          $ref: '#/components/responses/UnexpectedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    UnexpectedError:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Encountered error while performing request
  schemas:
    CVEExploitationDetails:
      type: object
      properties:
        attack_vector:
          type: string
          description: The attack vector for the CVE.
          example: Network
        exploit_found:
          type: boolean
          description: Whether an exploit has been found for this CVE.
          example: true
        exploitation_registered_in_kev:
          type: boolean
          description: Whether the exploitation is registered in KEV.
          example: true
        epss_score:
          type: number
          description: The EPSS score for the CVE.
          example: 0.8
    CVEExploitationStats:
      type: object
      properties:
        number_of_available_exploits:
          type: integer
          description: The number of available exploits for the CVE.
          example: 5
        number_of_threat_actors_exploiting_vulnerability:
          type: integer
          description: The number of threat actors exploiting the vulnerability.
          example: 3
        number_of_botnets_exploiting_vulnerability:
          type: integer
          description: The number of botnets exploiting the vulnerability.
          example: 2
    CVETimeline:
      type: object
      properties:
        cve_published_date:
          type: string
          format: date
          description: The date the CVE was published.
          example: '2024-01-01'
        cve_last_updated_date:
          type: string
          format: date
          description: The date the CVE was last updated.
          example: '2024-01-02'
        first_known_published_date:
          type: string
          format: date
          description: The first known published date of the CVE.
          example: '2024-01-01'
        cisa_kev_date_added:
          type: string
          format: date
          description: The date the CVE was added to the CISA KEV list.
          example: '2024-01-03'
    CVEBasicResponse:
      type: object
      properties:
        id:
          type: string
          description: The CVE identifier.
          example: CVE-2024-12345
        details:
          $ref: '#/components/schemas/CVEDetails'
        timeline:
          $ref: '#/components/schemas/CVETimeline'
        exploitation_details:
          $ref: '#/components/schemas/CVEExploitationDetails'
    CVEMinimalResponse:
      type: object
      properties:
        id:
          type: string
          description: The CVE identifier.
          example: CVE-2024-12345
        details:
          $ref: '#/components/schemas/CVEDetails'
    CVEExploitationActivity:
      type: object
      properties:
        activity_seen:
          type: boolean
          description: Whether exploitation activity has been observed.
          example: true
        benign_ip_count_1d:
          type: integer
          description: The count of benign IPs in the last day.
          example: 100
        benign_ip_count_10d:
          type: integer
          description: The count of benign IPs in the last 10 days.
          example: 500
        benign_ip_count_30d:
          type: integer
          description: The count of benign IPs in the last 30 days.
          example: 1000
        threat_ip_count_1d:
          type: integer
          description: The count of threat IPs in the last day.
          example: 10
        threat_ip_count_10d:
          type: integer
          description: The count of threat IPs in the last 10 days.
          example: 50
        threat_ip_count_30d:
          type: integer
          description: The count of threat IPs in the last 30 days.
          example: 100
    CVEAdvancedResponse:
      type: object
      properties:
        id:
          type: string
          description: The CVE identifier.
          example: CVE-2024-12345
        details:
          $ref: '#/components/schemas/CVEDetails'
        timeline:
          $ref: '#/components/schemas/CVETimeline'
        exploitation_details:
          $ref: '#/components/schemas/CVEExploitationDetails'
        exploitation_stats:
          $ref: '#/components/schemas/CVEExploitationStats'
        exploitation_activity:
          $ref: '#/components/schemas/CVEExploitationActivity'
    CVEDetails:
      type: object
      properties:
        vulnerability_name:
          type: string
          description: The name of the vulnerability.
          example: Sample Vulnerability
        vulnerability_description:
          type: string
          description: Description of the vulnerability.
          example: This vulnerability allows remote attackers to execute arbitrary code.
        cve_cvss_score:
          type: number
          description: The CVSS score of the CVE.
          example: 7.5
        product:
          type: string
          description: The product affected by the vulnerability.
          example: Sample Product
        vendor:
          type: string
          description: The vendor of the affected product.
          example: Sample Vendor
        published_to_nist_nvd:
          type: boolean
          description: Whether the CVE is published to the NIST National Vulnerability Database.
          example: true
    Error:
      type: object
      properties:
        message:
          type: string
          example: Success
      required:
      - message
  securitySchemes:
    APIKeyHeaderAuth:
      type: apiKey
      in: header
      name: key
      description: GreyNoise API key passed via the 'key' HTTP header.