openapi: 3.0.0
info:
  title: Ubuntu Security CVE API
  description: >-
    The Ubuntu Security CVE API provides programmatic access to Ubuntu's CVE
    (Common Vulnerabilities and Exposures) database. It enables querying security
    notices, CVE details, affected packages, and patch status across Ubuntu releases.
  version: "1.0.0"
  contact:
    name: Ubuntu Security Team
    url: https://ubuntu.com/security
servers:
  - url: https://ubuntu.com/security
    description: Ubuntu Security API
tags:
  - name: CVEs
    description: CVE security vulnerabilities
  - name: Notices
    description: Ubuntu Security Notices
paths:
  /cves.json:
    get:
      operationId: listCves
      summary: List CVEs
      description: Returns a paginated list of CVEs affecting Ubuntu packages.
      tags:
        - CVEs
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Search query for CVE IDs or descriptions.
        - name: package
          in: query
          required: false
          schema:
            type: string
          description: Filter CVEs by affected package name.
        - name: priority
          in: query
          required: false
          schema:
            type: string
            enum:
              - critical
              - high
              - medium
              - low
              - negligible
          description: Filter by CVE priority level.
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: Filter by fix status.
        - name: codename
          in: query
          required: false
          schema:
            type: string
          description: Filter by Ubuntu release codename (e.g., jammy, noble).
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Pagination offset.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: Number of CVEs to return per page.
      responses:
        '200':
          description: Paginated list of CVEs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CveListResponse'

  /cves/{cve_id}.json:
    get:
      operationId: getCve
      summary: Get CVE
      description: Returns detailed information about a specific CVE.
      tags:
        - CVEs
      parameters:
        - name: cve_id
          in: path
          required: true
          schema:
            type: string
            pattern: '^CVE-\d{4}-\d{4,}$'
          description: CVE identifier (e.g., CVE-2024-1234).
      responses:
        '200':
          description: CVE details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cve'
        '404':
          description: CVE not found.

  /notices.json:
    get:
      operationId: listNotices
      summary: List Security Notices
      description: Returns Ubuntu Security Notices (USN) for published vulnerabilities.
      tags:
        - Notices
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Pagination offset.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: Number of notices to return.
        - name: release
          in: query
          required: false
          schema:
            type: string
          description: Filter notices by Ubuntu release codename.
      responses:
        '200':
          description: List of security notices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeListResponse'

  /notices/{notice_id}.json:
    get:
      operationId: getNotice
      summary: Get Security Notice
      description: Returns details for a specific Ubuntu Security Notice.
      tags:
        - Notices
      parameters:
        - name: notice_id
          in: path
          required: true
          schema:
            type: string
          description: Ubuntu Security Notice ID (e.g., USN-6789-1).
      responses:
        '200':
          description: Security notice details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notice'
        '404':
          description: Notice not found.

components:
  schemas:
    CveListResponse:
      type: object
      properties:
        cves:
          type: array
          items:
            $ref: '#/components/schemas/Cve'
        offset:
          type: integer
        limit:
          type: integer
        total_results:
          type: integer

    Cve:
      type: object
      properties:
        id:
          type: string
          description: CVE identifier.
        published:
          type: string
          format: date-time
          description: Date the CVE was published.
        updated_at:
          type: string
          format: date-time
          description: Date the CVE was last updated.
        description:
          type: string
          description: Official CVE description.
        ubuntu_description:
          type: string
          description: Ubuntu-specific description.
        notes:
          type: string
          description: Additional notes about the CVE.
        priority:
          type: string
          enum:
            - critical
            - high
            - medium
            - low
            - negligible
          description: Ubuntu priority level for this CVE.
        cvss3:
          type: number
          description: CVSS v3 score.
        status:
          type: string
          description: Current fix status.
        mitigation:
          type: string
          description: Available mitigation steps.
        references:
          type: array
          items:
            type: string
          description: External references and links.
        packages:
          type: array
          items:
            $ref: '#/components/schemas/AffectedPackage'

    AffectedPackage:
      type: object
      properties:
        name:
          type: string
          description: Package name.
        source:
          type: string
          description: Source package name.
        statuses:
          type: array
          items:
            type: object
            properties:
              release_codename:
                type: string
              status:
                type: string
              description:
                type: string

    NoticeListResponse:
      type: object
      properties:
        notices:
          type: array
          items:
            $ref: '#/components/schemas/Notice'
        offset:
          type: integer
        limit:
          type: integer
        total_results:
          type: integer

    Notice:
      type: object
      properties:
        id:
          type: string
          description: Ubuntu Security Notice identifier.
        title:
          type: string
          description: Notice title.
        summary:
          type: string
          description: Summary of the vulnerability.
        description:
          type: string
          description: Full description.
        published:
          type: string
          format: date-time
          description: Publication date.
        cves:
          type: array
          items:
            type: string
          description: List of CVE IDs addressed by this notice.
        packages:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              version:
                type: string
              release:
                type: string