openapi: 3.0.3
info:
  contact:
    email: cwe@mitre.org
    name: CWE-CAPEC team
    url: https://github.com/CWE-CAPEC/REST-API-wg
  description: >
    The CWE-CAPEC API specification defines the RESTful semantics for querying
    the

    CWE and CAPEC data sets from MITRE hosted servers. The goals of this

    API are to provide access to the RAW CWE dataset in JSON form, and to

    perform common search, and filter queries
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
  termsOfService: TODO
  title: CWE-CAPEC API 0.1
  version: '0.1'
servers:
  - url: /api/v1
paths:
  /cwe/version:
    get:
      tags: [CWE]
      description: |
        This API endpoint returns content version data of CWE.
      operationId: getCWE
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CWEVersion'
          description: success
        '404':
          description: CWE version not found
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: CWE content version
  /cwe/{id(s)}:
    get:
      tags: [CWE]
      description: >
        This API endpoint returns metadata on specified CWE IDs.
      operationId: getCWEInfo
      parameters:
        - description: ''
          explode: false
          in: path
          name: id(s)
          required: true
          schema:
            items:
              type: string
            maxItems: 1000
            minItems: 0
            type: array
            uniqueItems: true
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CWEInfo'
          description: success
        '404':
          description: CWE ID not found
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: CWE ID type
  /cwe/weakness/{id(s)}:
    get:
      tags: [CWE]
      description: >
        This API endpoint returns a given set of CWE weaknesses by identifier.
        Multiple identifiers are separated by a comma. If the keyword "all" is given, all CWE weaknesses are returned.
      operationId: getCWEWeakness
      parameters:
        - description: CWE Weakness ID(s)
          explode: false
          in: path
          name: id(s)
          required: true
          schema:
            items:
              type: string
            maxItems: 1000
            minItems: 0
            type: array
            uniqueItems: true
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Weakness'
                type: array
          description: success
        '404':
          description: CWE ID not found
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: CWE weaknesses
  /cwe/category/{id(s)}:
    get:
      tags: [CWE]
      description: >+
        This API endpoint returns a given set of CWE categories by identifier.
        Multiple identifiers are separated by a comma. If keyword "all" is given, all CWE categories are returned.

      operationId: getCWECategory
      parameters:
        - description: CWE Category ID(s)
          explode: false
          in: path
          name: id(s)
          required: true
          schema:
            items:
              type: string
            maxItems: 1000
            minItems: 0
            type: array
            uniqueItems: true
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Category'
                type: array
          description: success
        '404':
          description: CWE ID not found
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: CWE categories
  /cwe/view/{id(s)}:
    get:
      tags: [CWE]
      description: >
        This API endpoint returns a given set of CWE views by identifier. 
        Multiple identifiers are separated by a comma. If keyword "all" is given, all CWE views are returned.
      operationId: getCWEView
      parameters:
        - description: CWE View ID(s)
          explode: false
          in: path
          name: id(s)
          required: true
          schema:
            items:
              type: string
            maxItems: 1000
            minItems: 0
            type: array
            uniqueItems: true
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/View'
                type: array
          description: success
        '404':
          description: CWE ID not found
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: CWE views
  /cwe/{id}/parents:
      get:
        tags: [CWE]
        operationId: getCWEParent
        parameters:
          - description: >-
              the View_ID field to follow in the Has_Member entries and ChildOf
              relationships to determine the appropriate parent. If there is none
              the reponse will be empty
            explode: true
            in: query
            name: view
            required: false
            schema:
              type: string
            style: form
          - description: CWE ID
            explode: false
            in: path
            name: id
            required: true
            schema:
              type: string
            style: simple
        responses:
          '200':
            content:
              application/json:
                schema:
                  items:
                    $ref: '#/components/schemas/Parent'
                  type: array
            description: success
          '404':
            description: CWE relationship data not found
          '500':
            $ref: '#/components/responses/InternalServerError'
        summary: The parent of a specified weakness, sampling by the view
  /cwe/{id}/descendants:
    get:
      tags: [CWE]
      operationId: getCWEDescendants
      parameters:
        - description: >-
            the View_ID field to follow in the Has_Member entries and ChildOf
            relationships
          explode: true
          in: query
          name: view
          required: false
          schema:
            type: string
          style: form
        - description: CWE ID
          explode: false
          in: path
          name: id
          required: true
          schema:
            type: string
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Decendants'
                type: array
          description: success
        '404':
          description: CWE relationship data not found
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: All descendants of a specified weakness, sampling by the view
components:
  schemas:
    CWEVersion:
      type: object
      properties:
        ContentVersion:
          description: CWE Content Version
          type: string
          format: integer
        ContentDate:
          description: Release Date of CWE Content Version
          type: string
        TotalWeaknesses:
          description: Total count of Weaknesses in this release
          type: integer
        TotalCategories:
          description: Total count of Categories in this release
          type: integer
        TotalViews:
          description: Total count of Views in this release
          type: integer
      example:
          ContentVersion: "4.12"
          ContentDate: "2023-06-29"
          TotalWeaknesses: 958
          TotalCategories: 409
          TotalViews: 53
    CWEInfo:
      type: array
      items:
        type: object
        properties:
          id:
            description: CWE ID
            type: string
            format: integer
          type:
            description: Type of CWE object
            type: string
            enum:
              - Weakness
              - Category
              - View
        required:
          - id
          - type
      example:
        - id: "79"
          type: Weakness
        - id: "1000"
          type: View
    Weakness:
      type: object
      additionalProperties: false
      properties:
        ID:
          type: string
          format: integer
          example: "79"
        Name:
          type: string
          example: Weakness Title
        Abstraction:
          type: string
          example: Base
        Structure:
          type: string
          example: Simple
        Status:
          type: string
          example: Stable
        Description:
          type: string
          example: A short description of the weakness
        ExtendedDescription:
          type: string
          example: A long description of the weakness
        LikelihoodOfExploit:
          type: string
          example: High
        RelatedWeaknesses:
          $ref: '#/components/schemas/RelatedWeaknesses'
        WeaknessOrdinalities:
          $ref: '#/components/schemas/WeaknessOrdinalities'
        ApplicablePlatforms:
          $ref: '#/components/schemas/ApplicablePlatforms'
        BackgroundDetails:
          type: array
          items:
            type: string
          title: BackgroundDetails
          example: [A short detail text, Another detail]
        AlternateTerms:
          $ref: '#/components/schemas/AlternateTerms'
        ModesOfIntroduction:
          $ref: '#/components/schemas/ModesOfIntroduction'
        CommonConsequences:
          $ref: '#/components/schemas/Consequences'
        DetectionMethods:
          $ref: '#/components/schemas/DetectionMethods'
        PotentialMitigations:
          $ref: '#/components/schemas/Mitigations'
        DemonstrativeExamples:
          $ref: '#/components/schemas/DemonstrativeExamples'
        ObservedExamples:
          $ref: '#/components/schemas/ObservedExamples'
        FunctionalAreas:
          type: array
          items:
            type: string
          title: FunctionalAreas
          example:
          - Cryptography
          - Logging
          - String Processing
        AffectedResources:
          type: array
          items:
            type: string
          title: AffectedResources
          example: 
          - System Process
          - File or Directory
        TaxonomyMappings:
          $ref: '#/components/schemas/TaxonomyMappings'
        RelatedAttackPatterns:
          type: array
          items:
            type: string
            format: integer
          title: RelatedAttackPatterns
          example: 
          - "103"
          - "23"
        References:
          $ref: '#/components/schemas/References'
        MappingNotes:
          $ref: '#/components/schemas/MappingNotes'
        Notes:
          $ref: '#/components/schemas/Notes'
        ContentHistory:
          $ref: '#/components/schemas/ContentHistory'
      required:
        - Abstraction
        - ContentHistory
        - Description
        - ID
        - Name
        - Status
        - Structure
    Category:
      description: CWE Category
      properties:
        ID:
          type: integer
          example: "12"
        Name:
          type: string
          example: Category Name
        Status:
          type: string
          example: Draft
        Summary:
          type: string
          example: A brief summary of the category
        Taxonomy_Mappings:
          $ref: '#/components/schemas/TaxonomyMappings'
        Relationships:
          $ref: '#/components/schemas/Relationships'
        References:
          $ref: '#/components/schemas/References'
        Notes:
          $ref: '#/components/schemas/Notes'
        Content_History:
          $ref: '#/components/schemas/ContentHistory'
      type: object
    View:
      description: CWE View
      properties:
        ID:
          type: string
          format: integer
          example: "12"
        Name:
          type: string
          example: View Name
        Type:
          type: string
          example: Implicit
        Status:
          type: string
          example: Stable
        Objective:
          type: string
          example: A brief description of the objective of the view
        Audience:
          $ref: '#/components/schemas/Stakeholders'
        Members:
          $ref: '#/components/schemas/Relationships'
        References:
          $ref: '#/components/schemas/References'
        Notes:
          $ref: '#/components/schemas/Notes'
        Content_History:
          $ref: '#/components/schemas/ContentHistory'
      type: object
    AlternateTerms:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Term:
            type: string
            example: Another name for the weakness
          Description:
            type: string
            example: A description of the term
        required:
          - Term
    ApplicablePlatforms:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Type:
            type: string
            example: Language
          Name:
            type: string
            example: Javascript
          Class:
            type: string
            example: Language-Independent
          Prevalence:
            type: string
            example: Often
        required:
          - Prevalence
          - Type
    Consequences:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Scope:
            type: array
            items:
              type: string
            example:
            - Integrity
            - Confidentiality
          Impact:
            type: array
            items:
              type: string
            example:
            - Read Application Data
            - Modify Application Data
          Likelihood:
            type: array
            items:
              type: string
              example: High
          Note:
            type: string
            example: A brief note on the consequence
        required:
          - Scope
    ContentHistory:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Type:
            type: string
          SubmissionName:
            type: string
          SubmissionOrganization:
            type: string
          SubmissionDate:
            type: string
            format: date
          ModificationName:
            type: string
          ModificationOrganization:
            type: string
          ModificationDate:
            type: string
            format: date
          ModificationComment:
            type: string
          
          ContributionName:
            type: string
          ContributionOrganization:
            type: string
          ContributionDate:
            type: string
            format: date
          ContributionComment:
            type: string
          ContributionType:
            type: string
          PreviousEntryName:
            type: string
          Date:
            type: string
            format: date
      example:
        - Type: Submission
          SubmissionName: PLOVER
          SubmissionDate: "2006-07-19"
        - Type: Modification
          ModificationName: John Doe
          ModificationOrganization: ACME Corp
          ModificationDate: "2008-07-01"
          ModificationComment: Updated Description
        - Type: Rename
          PreviousEntryName: Old name
          Date: "2000-01-04"
      required:
        - Type
    Decendants:
      type: object
      properties:
        Type:
          type: string
          format: integer
        ID:
          items:
            type: string
            format: integer
          type: array
      required:
        - ID
        - Type
      example:
        Type: category
        ID: "1009"
    DemonstrativeExamples:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          ID:
            type: string
            example: DX-60
          Entries:
            type: array
            items:
              type: object
              additionalProperties: false
              properties:
                IntroText:
                  type: string
                BodyText:
                  type: string
                Nature:
                  type: string
                Language:
                  type: string
                ExampleCode:
                  type: string
                Reference:
                  type: string
            example:
            - IntroText: Short text at begining of example
            - Nature: bad
              Language: PHP
              ExampleCode: A markdown representation of the code
            - BodyText: Example text
            - Nature: good
              ExampleCode: A markdown representation of the code
            - BodyText: Example text
            - Reference: REF-1990
        required:
          - Entries
    DetectionMethods:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          DetectionMethodID:
            type: string
            example: DM-1
          Method:
            type: string
            example: Automated Static Analysis
          Description:
            type: string
            example: A brief description of the detection
          Effectiveness:
            type: string
            example: Moderate
          EffectivenessNotes:
            type: string
            example: A brief note on the detection effectiveness
        required:
          - Description
          - Method
    MappingNotes:
      type: object
      items:
        type: object
        additionalProperties: false
        properties:
          Usage:
            type: string
            example: allowed
          Rationale:
            type: string
            example: A brief explanation on mapping rationale
          Comments:
            type: string
            example: Comments on the mapping
          Reasons:
            type: array
            items:
              type: string
            example: 
              - Acceptable-Use
              - Other
          Suggestions:
            type: string
            example: High
        required:
          - Description
    Mitigations:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          MitigationID:
            type: string
            example: MIT-5
          Phase:
            type: array
            items:
              type: string
            example:
            - Architecture and Design
            - Implementation
          Strategy:
            type: string
            example: Parameterization
          Description:
            type: string
            example: A brief description on the mitigation
          Effectiveness:
            type: string
            example: High
          EffectivenessNotes:
            type: string
            example: A brief example on the effectiveness of the mitigation
        required:
          - Description
    ModesOfIntroduction:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Phase:
            type: string
            example: Architecture and Design
          Note:
            type: string
            example: A brief note on the phase
    Notes:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Type:
            type: string
          Note:
            type: string
        example:
          Type: Relationship
          Note: A note on the relationship
        required:
          - Note
          - Type
    ObservedExamples:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Reference:
            type: string
            example: CVE-2021-1879
          Description:
            type: string
            example: A short description of the example
          Link:
            type: string
            format: uri
            example: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-1879
        required:
          - Description
          - Link
          - Reference
    Parent:
      type: object
      properties:
        Type:
          type: string
          format: integer
        ID:
          type: string
          format: integer
      required:
        - ID
        - Type
      example:
        Type: category
        ID: "74"
    References:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          ExternalReferenceID:
            type: string
          Section:
            type: string
          Authors:
            type: array
            items:
              type: string
          Title:
            type: string
          PublicationYear:
            type: string
            format: integer
          PublicationMonth:
            type: string
            format: integer
          PublicationDay:
            type: string
            format: integer
          Publisher:
            type: string
          URL:
            type: string
            format: uri
          URLDate:
            type: string
            format: date
          Edition:
            type: string
          Publication:
            type: string
        example:
          ExternalReferenceID: REF-2
          Section: Chapter 11, Page 384
          Authors: 
          - John Doe
          - Jane Doe
          Title: An Analysis of All That is Wrong With Software Development
          Edition: 2nd Edition
          PublicationYear: "2000"
          PublicationMonth: "01"
          PublicationDay: "01"
          Publisher: "Perfect Publishing"
          URL: "https://example.com"
          URLDate: "2021-10-24"
        required:
          - ExternalReferenceID
    RelatedWeaknesses:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Nature:
            type: string
          CweID:
            type: string
            format: integer
          ViewID:
            type: string
            format: integer
          Ordinal:
            type: string
        required:
          - CweID
          - Nature
          - ViewID
      example:
        - Nature: ChildOf
          CweID: "74"
          ViewID: "1000"
          Ordinal: Primary
        - Nature: PeerOf
          CweID: "352"
          ViewID: "1000"
    Relationships:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          CWE_ID:
            type: string
          View_ID:
            type: string
      example:
        - CWE_ID: "123"
          View_ID: "321"
    Stakeholders:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Type:
            type: string
          Description:
            type: string
      example:
        - Type: Software Developers
          Description: A brief description of the audience
    TaxonomyMappings:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          TaxonomyName:
            type: string
          EntryName:
            type: string
          EntryID:
            type: string
          MappingFit:
            type: string
        required:
          - TaxonomyName
      example:
        - TaxonomyName: OWASP Top Ten
          EntryID: A1
          EntryName: Cross Site Scription (XSS)
          MappingFit: Exact
    WeaknessOrdinalities:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          Ordinality:
            type: string
            example: Resultant
          Description:
            type: string
            example: A short description of ordinality
  responses:
      InternalServerError:
        description: An Internal Server Error occurred