openapi: 3.0.3
info:
  title: ThreatSpot Security API
  description: |
    ## Overview
    The ThreatSpot Security API provides programmatic access to WordPress plugin vulnerability data, 
    EPSS scores, CISA KEV catalog, and security scanning capabilities.
    
    ## Authentication
    API key authentication is required for most endpoints. Provide your API key via:
    - **Header**: `X-API-Key: your-api-key`
    - **Query Parameter**: `?api_key=your-api-key`
    
    ## Rate Limiting
    Rate limits are enforced per API key or IP address:
    - **Freemium**: 100 requests/hour
    - **Professional**: 1,000 requests/hour  
    - **Enterprise**: 10,000 requests/hour
    
    When rate limited, responses include `retry_after` seconds.
    
    ## Subscription Tiers
    Some endpoints require specific subscription levels:
    - `none` - Freemium (basic access)
    - `read_only` - Pro/Agency (premium read endpoints)
    - `read_write` - Enterprise (all features)
    
  version: 1.0.0
  contact:
    name: ThreatSpot Support
    email: support@threatspot.ai
    url: https://threatspot.ai/support
  license:
    name: Proprietary
    url: https://threatspot.ai/terms

servers:
  - url: https://dashboard-webapp-c10t.onrender.com
    description: Production Server
  - url: http://localhost:5000
    description: Local Development

tags:
  - name: Vulnerabilities
    description: WordPress plugin vulnerability intelligence
  - name: Plugins
    description: WordPress plugin metadata and version information
  - name: Scanning
    description: Security scanning operations
  - name: Webhooks
    description: Webhook notifications for security events

security:
  - ApiKeyHeader: []
  - ApiKeyQuery: []

paths:
  /api/vulnerabilities/check:
    get:
      tags:
        - Vulnerabilities
      summary: Check Plugin Vulnerability
      description: |
        Check if a specific WordPress plugin version has known vulnerabilities.
        Returns detailed findings including CVE IDs, severity, CVSS scores, and remediation guidance.
      operationId: checkVulnerability
      parameters:
        - name: plugin_slug
          in: query
          required: true
          description: WordPress plugin slug (e.g., 'contact-form-7', 'akismet')
          schema:
            type: string
          example: contact-form-7
        - name: version
          in: query
          required: true
          description: Installed plugin version to check
          schema:
            type: string
          example: "5.5.0"
      responses:
        '200':
          description: Plugin vulnerability check completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VulnerabilityCheckResponse'
              examples:
                vulnerable:
                  summary: Vulnerable plugin found
                  value:
                    vulnerable: true
                    plugin_slug: "contact-form-7"
                    plugin_name: "Contact Form 7"
                    version: "5.5.0"
                    findings_count: 2
                    findings:
                      - cve_id: "CVE-2023-1234"
                        severity: "HIGH"
                        cvss_score: 7.5
                        affected_range: "<5.6.0"
                        fixed_in: "5.6.0"
                        risk_score: 85.5
                        risk_badge: "CRITICAL"
                        summary: "Cross-site scripting vulnerability..."
                        published: "2023-05-15T00:00:00"
                        epss_percentile: 0.95
                        in_cisa_kev: true
                not_vulnerable:
                  summary: No vulnerabilities found
                  value:
                    vulnerable: false
                    plugin_slug: "akismet"
                    plugin_name: "Akismet Anti-Spam"
                    version: "5.3.0"
                    findings_count: 0
                    findings: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Plugin not found in database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                vulnerable: false
                message: "Plugin 'unknown-plugin' not found in database"
                findings: []
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/vulnerabilities/search:
    get:
      tags:
        - Vulnerabilities
      summary: Search Vulnerabilities
      description: |
        Search for vulnerabilities with flexible filtering options.
        Supports filtering by CVE ID, severity, plugin, CVSS score, and KEV status.
      operationId: searchVulnerabilities
      parameters:
        - name: cve_id
          in: query
          description: CVE ID (partial match supported)
          schema:
            type: string
          example: "CVE-2024"
        - name: severity
          in: query
          description: Severity level filter
          schema:
            type: string
            enum: [CRITICAL, HIGH, MEDIUM, LOW]
        - name: plugin_slug
          in: query
          description: Filter by WordPress plugin slug
          schema:
            type: string
          example: "woocommerce"
        - name: min_cvss
          in: query
          description: Minimum CVSS score (0.0-10.0)
          schema:
            type: number
            format: float
            minimum: 0
            maximum: 10
          example: 7.0
        - name: in_kev
          in: query
          description: Only include CISA KEV vulnerabilities (requires read_only access)
          schema:
            type: boolean
          example: true
        - name: limit
          in: query
          description: Maximum results to return (max 500)
          schema:
            type: integer
            default: 100
            maximum: 500
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VulnerabilitySearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/SubscriptionRequired'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/vulnerabilities/cve/{cve_id}:
    get:
      tags:
        - Vulnerabilities
      summary: Get CVE Details
      description: Get comprehensive information about a specific CVE including EPSS scores, KEV status, and affected plugins.
      operationId: getCveDetails
      parameters:
        - name: cve_id
          in: path
          required: true
          description: CVE identifier
          schema:
            type: string
          example: "CVE-2024-1234"
      responses:
        '200':
          description: CVE details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CveDetailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: CVE not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "CVE CVE-2024-9999 not found"
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/vulnerabilities/kev:
    get:
      tags:
        - Vulnerabilities
      summary: Get CISA KEV Catalog
      description: |
        Retrieve the CISA Known Exploited Vulnerabilities catalog.
        **Requires**: `read_only` API access level (Pro/Agency/Enterprise subscription)
      operationId: getKevCatalog
      parameters:
        - name: limit
          in: query
          description: Maximum results (max 500)
          schema:
            type: integer
            default: 100
            maximum: 500
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            default: 0
        - name: sort
          in: query
          description: Sort field
          schema:
            type: string
            enum: [added, due]
            default: added
        - name: order
          in: query
          description: Sort order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: KEV catalog entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KevCatalogResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/SubscriptionRequired'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/vulnerabilities/stats:
    get:
      tags:
        - Vulnerabilities
      summary: Get Database Statistics
      description: Get vulnerability database statistics including totals, severity breakdown, and top vulnerable plugins.
      operationId: getStats
      responses:
        '200':
          description: Database statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/plugins/{slug}:
    get:
      tags:
        - Plugins
      summary: Get Plugin Metadata
      description: Get detailed metadata for a WordPress plugin including version history and install counts.
      operationId: getPlugin
      parameters:
        - name: slug
          in: path
          required: true
          description: WordPress plugin slug
          schema:
            type: string
          example: "akismet"
      responses:
        '200':
          description: Plugin metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PluginResponse'
        '404':
          description: Plugin not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/plugins/{slug}/vulnerabilities:
    get:
      tags:
        - Plugins
      summary: Get Plugin Vulnerabilities
      description: Get all known vulnerabilities for a specific WordPress plugin.
      operationId: getPluginVulnerabilities
      parameters:
        - name: slug
          in: path
          required: true
          description: WordPress plugin slug
          schema:
            type: string
          example: "contact-form-7"
      responses:
        '200':
          description: Plugin vulnerabilities
          content:
            application/json:
              schema:
                type: object
                properties:
                  plugin_slug:
                    type: string
                  plugin_name:
                    type: string
                  vulnerability_count:
                    type: integer
                  vulnerabilities:
                    type: array
                    items:
                      $ref: '#/components/schemas/VulnerabilityFinding'
        '404':
          description: Plugin not found

  /api/plugins/search:
    get:
      tags:
        - Plugins
      summary: Search Plugins
      description: Search for WordPress plugins by name or slug.
      operationId: searchPlugins
      parameters:
        - name: q
          in: query
          required: true
          description: Search query
          schema:
            type: string
          example: "security"
        - name: limit
          in: query
          description: Maximum results
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/PluginSummary'

  /api/plugins/popular:
    get:
      tags:
        - Plugins
      summary: Get Popular Plugins
      description: Get list of most popular WordPress plugins by install count.
      operationId: getPopularPlugins
      parameters:
        - name: limit
          in: query
          description: Number of plugins to return
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Popular plugins list
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  plugins:
                    type: array
                    items:
                      $ref: '#/components/schemas/PluginSummary'

components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key passed in X-API-Key header
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as query parameter

  schemas:
    VulnerabilityCheckResponse:
      type: object
      properties:
        vulnerable:
          type: boolean
          description: Whether the plugin version is vulnerable
        plugin_slug:
          type: string
        plugin_name:
          type: string
        version:
          type: string
        findings_count:
          type: integer
        findings:
          type: array
          items:
            $ref: '#/components/schemas/VulnerabilityFinding'

    VulnerabilityFinding:
      type: object
      properties:
        cve_id:
          type: string
          example: "CVE-2024-1234"
        severity:
          type: string
          enum: [CRITICAL, HIGH, MEDIUM, LOW]
        cvss_score:
          type: number
          format: float
          example: 7.5
        affected_range:
          type: string
          example: "<5.6.0"
        fixed_in:
          type: string
          example: "5.6.0"
        risk_score:
          type: number
          format: float
          description: Composite risk score (0-100)
        risk_badge:
          type: string
          enum: [CRITICAL, HIGH, MEDIUM, LOW]
        summary:
          type: string
        published:
          type: string
          format: date-time
        references:
          type: array
          items:
            type: string
        epss_percentile:
          type: number
          format: float
          description: EPSS exploit prediction percentile (0-1)
        in_cisa_kev:
          type: boolean
          description: Whether CVE is in CISA KEV catalog
        confidence:
          type: string
          enum: [HIGH, MEDIUM, LOW]
        mapping_method:
          type: string
          example: "NVD_CPE"
        remediation:
          type: object
          properties:
            action:
              type: string
            priority:
              type: string
            steps:
              type: array
              items:
                type: string

    VulnerabilitySearchResponse:
      type: object
      properties:
        count:
          type: integer
          description: Number of results in this response
        total:
          type: integer
          description: Total matching results
        offset:
          type: integer
        limit:
          type: integer
        has_more:
          type: boolean
        results:
          type: array
          items:
            type: object
            properties:
              cve_id:
                type: string
              severity:
                type: string
              cvss_score:
                type: number
              summary:
                type: string
              published:
                type: string
                format: date-time
              affected_plugins:
                type: array
                items:
                  type: object
                  properties:
                    slug:
                      type: string
                    name:
                      type: string
                    affected_range:
                      type: string
                    fixed_in:
                      type: string

    CveDetailResponse:
      type: object
      properties:
        cve_id:
          type: string
        severity:
          type: string
        cvss_score:
          type: number
        cvss_vector:
          type: string
        summary:
          type: string
        published:
          type: string
          format: date-time
        last_modified:
          type: string
          format: date-time
        risk_score:
          type: number
        risk_badge:
          type: string
        epss:
          type: object
          properties:
            score:
              type: number
            percentile:
              type: number
            as_of:
              type: string
              format: date
        cisa_kev:
          type: object
          nullable: true
          properties:
            added:
              type: string
              format: date-time
            due:
              type: string
              format: date-time
            notes:
              type: string
        affected_plugins:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
              name:
                type: string
              affected_range:
                type: string
              fixed_in:
                type: string
              confidence:
                type: string
              mapping_method:
                type: string
              active_installs:
                type: integer
        references:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              source:
                type: string
              title:
                type: string

    KevCatalogResponse:
      type: object
      properties:
        count:
          type: integer
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        has_more:
          type: boolean
        results:
          type: array
          items:
            type: object
            properties:
              cve_id:
                type: string
              added_to_kev:
                type: string
                format: date-time
              due_date:
                type: string
                format: date-time
              notes:
                type: string
              vulnerability:
                type: object
                properties:
                  severity:
                    type: string
                  cvss_score:
                    type: number
                  summary:
                    type: string
                  published:
                    type: string
                    format: date-time
              epss:
                type: object
                properties:
                  score:
                    type: number
                  percentile:
                    type: number
              affected_plugins:
                type: array
                items:
                  type: object
                  properties:
                    slug:
                      type: string
                    name:
                      type: string
                    affected_range:
                      type: string
                    fixed_in:
                      type: string

    StatsResponse:
      type: object
      properties:
        total_vulnerabilities:
          type: integer
        total_plugins:
          type: integer
        total_mappings:
          type: integer
        cisa_kev_count:
          type: integer
        severity_breakdown:
          type: object
          properties:
            CRITICAL:
              type: integer
            HIGH:
              type: integer
            MEDIUM:
              type: integer
            LOW:
              type: integer
        top_vulnerable_plugins:
          type: array
          items:
            type: object
            properties:
              slug:
                type: string
              name:
                type: string
              vulnerability_count:
                type: integer

    PluginResponse:
      type: object
      properties:
        slug:
          type: string
        name:
          type: string
        version:
          type: string
        author:
          type: string
        active_installs:
          type: integer
        tested_up_to:
          type: string
        requires_php:
          type: string
        last_updated:
          type: string
          format: date-time
        vulnerability_count:
          type: integer

    PluginSummary:
      type: object
      properties:
        slug:
          type: string
        name:
          type: string
        active_installs:
          type: integer
        vulnerability_count:
          type: integer

    Error:
      type: object
      properties:
        error:
          type: string
        error_code:
          type: string
        message:
          type: string
        status_code:
          type: integer
        request_id:
          type: string
        details:
          type: object

    RateLimitError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            retry_after:
              type: integer
              description: Seconds to wait before retrying
            upgrade_url:
              type: string
            upgrade_message:
              type: string

  responses:
    BadRequest:
      description: Bad request - missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Bad request"
            message: "Missing required parameters: plugin_slug and version"

    Unauthorized:
      description: API key missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "API key required"
            message: "Provide API key via X-API-Key header or api_key query parameter"

    SubscriptionRequired:
      description: Subscription upgrade required for this endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "subscription_required"
            message: "This endpoint requires API access level 'read_only'. Your current access level is 'none'."
            required_access_level: "read_only"
            current_access_level: "none"

    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: "Rate limit exceeded"
            error_code: "rate_limit_exceeded"
            message: "Maximum 100 requests per 3600 seconds"
            retry_after: 1234
            upgrade_url: "/pricing"
            upgrade_message: "You've reached the Free plan request limit. Upgrade for higher throughput."
