definitions:
  caasmmodel.AssetStatus:
    enum:
    - active
    - inactive
    type: string
    x-enum-varnames:
    - AssetStatusActive
    - AssetStatusInactive
  caasmmodel.AssetType:
    enum:
    - compute
    - storage
    - database
    - network
    - application
    - identity
    - other
    type: string
    x-enum-varnames:
    - AssetTypeCompute
    - AssetTypeStorage
    - AssetTypeDatabase
    - AssetTypeNetwork
    - AssetTypeApplication
    - AssetTypeIdentity
    - AssetTypeOther
  caasmmodel.CircuitBreakerConfig:
    properties:
      cool_off_sec:
        type: integer
      threshold:
        type: integer
    type: object
  caasmmodel.CloudAccountStatus:
    enum:
    - active
    - inactive
    type: string
    x-enum-varnames:
    - CloudAccountStatusActive
    - CloudAccountStatusInactive
  caasmmodel.CloudProvider:
    enum:
    - aws
    - gcp
    - azure
    - alibaba
    - godaddy
    - other
    type: string
    x-enum-varnames:
    - CloudProviderAWS
    - CloudProviderGCP
    - CloudProviderAzure
    - CloudProviderAlibaba
    - CloudProviderGoDaddy
    - CloudProviderOther
  caasmmodel.ThrottlingServiceSpec:
    properties:
      max_concurrency:
        type: integer
      min_concurrency:
        type: integer
      token_capacity:
        type: integer
      token_refill_per_sec:
        type: number
    type: object
  handler.addCommentRequest:
    properties:
      content:
        type: string
    required:
    - content
    type: object
  handler.authorizedViewerCandidateDTO:
    properties:
      avatar_url:
        type: string
      department_id:
        type: string
      department_name:
        type: string
      email:
        type: string
      id:
        type: integer
      job_title:
        type: string
      name:
        type: string
    type: object
  handler.caasmAPIRouteConfigSummaryDTO:
    properties:
      activated_at:
        type: string
      created_at:
        type: string
      id:
        type: integer
      is_active:
        type: boolean
      name:
        type: string
      route_count:
        type: integer
      source_type:
        type: string
      status:
        type: string
      updated_at:
        type: string
      uploaded_by:
        type: integer
      yaml_sha256:
        type: string
    type: object
  handler.caasmAssetListItemDTO:
    properties:
      asset_type:
        $ref: '#/definitions/caasmmodel.AssetType'
      cloud_account:
        $ref: '#/definitions/handler.cloudAccountSummary'
      cloud_account_id:
        type: integer
      criticality:
        type: string
      department:
        $ref: '#/definitions/internal_modules_caasm_handler.departmentSummary'
      department_id:
        type: string
      environment:
        type: string
      id:
        type: integer
      ip_addresses:
        items:
          type: string
        type: array
      last_seen_at:
        type: string
      name:
        type: string
      native_id:
        type: string
      owner_employee:
        $ref: '#/definitions/internal_modules_caasm_handler.employeeSummary'
      owner_employee_id:
        type: integer
      provider:
        type: string
      region:
        type: string
      service:
        type: string
      status:
        $ref: '#/definitions/caasmmodel.AssetStatus'
    type: object
  handler.caasmEffectiveThrottlingDTO:
    properties:
      adaptive_threshold:
        type: integer
      adaptive_window_sec:
        type: integer
      circuit_breaker:
        $ref: '#/definitions/caasmmodel.CircuitBreakerConfig'
      cool_off_sec:
        type: integer
      enabled:
        type: boolean
      max_concurrency:
        type: integer
      min_concurrency:
        type: integer
      service_limits:
        additionalProperties:
          $ref: '#/definitions/caasmmodel.ThrottlingServiceSpec'
        type: object
      sources:
        additionalProperties:
          type: string
        type: object
      token_capacity:
        type: integer
      token_refill_per_sec:
        type: number
    type: object
  handler.caasmPortDetailDTO:
    properties:
      asset:
        $ref: '#/definitions/handler.caasmAssetListItemDTO'
      evidence:
        $ref: '#/definitions/handler.caasmPortEvidenceDTO'
      port:
        $ref: '#/definitions/handler.caasmPortListItemDTO'
    type: object
  handler.caasmPortEvidenceDTO:
    properties:
      confidence:
        type: string
      dns_records: {}
      evidence:
        items:
          type: string
        type: array
      exposure_reason:
        type: string
      ownership_status:
        type: string
      resolution_ips:
        items:
          type: string
        type: array
      resource_id:
        type: string
      route:
        $ref: '#/definitions/handler.caasmPortEvidenceSectionDTO'
      scanner_result:
        $ref: '#/definitions/handler.caasmPortScannerResultDTO'
      security_group:
        $ref: '#/definitions/handler.caasmPortEvidenceSectionDTO'
      source_service:
        type: string
      warnings:
        items:
          type: string
        type: array
    type: object
  handler.caasmPortEvidenceSectionDTO:
    properties:
      available:
        type: boolean
      confidence:
        type: string
      metadata:
        additionalProperties: true
        type: object
      source:
        type: string
      summary:
        type: string
      title:
        type: string
    type: object
  handler.caasmPortListItemDTO:
    properties:
      asset_id:
        type: integer
      asset_service:
        type: string
      confidence:
        type: string
      dns_records: {}
      endpoint:
        type: string
      endpoint_type:
        type: string
      evidence:
        items:
          type: string
        type: array
      evidence_source:
        type: string
      evidence_sources:
        items:
          type: string
        type: array
      exposure:
        type: string
      id:
        type: integer
      ip_address:
        type: string
      last_seen_at:
        type: string
      observation_source:
        type: string
      ownership_status:
        type: string
      port:
        type: integer
      product:
        type: string
      protocol:
        type: string
      resolution_ips:
        items:
          type: string
        type: array
      resource_id:
        type: string
      service_name:
        type: string
      source_service:
        type: string
      status:
        type: string
      version:
        type: string
    type: object
  handler.caasmPortScannerResultDTO:
    properties:
      batch_id:
        type: integer
      connect_ms:
        type: integer
      id:
        type: integer
      observed_at:
        type: string
      reason_code:
        type: string
      request_id:
        type: string
      result:
        type: string
      scanner_batch_id:
        type: string
      scanner_source_ip:
        type: string
    type: object
  handler.caasmThrottlingContractDTO:
    properties:
      coordination_mode:
        type: string
      defaults:
        $ref: '#/definitions/handler.caasmThrottlingLimitsDTO'
      hard_caps:
        $ref: '#/definitions/handler.caasmThrottlingLimitsDTO'
      override_policy:
        type: string
      presets:
        additionalProperties:
          $ref: '#/definitions/handler.caasmThrottlingPresetDTO'
        type: object
      reject_out_of_range:
        type: boolean
      supported_services:
        items:
          type: string
        type: array
    type: object
  handler.caasmThrottlingLimitsDTO:
    properties:
      adaptive_threshold:
        type: integer
      adaptive_window_sec:
        type: integer
      circuit_breaker:
        $ref: '#/definitions/caasmmodel.CircuitBreakerConfig'
      cool_off_sec:
        type: integer
      max_concurrency:
        type: integer
      min_concurrency:
        type: integer
      service_limits:
        additionalProperties:
          $ref: '#/definitions/caasmmodel.ThrottlingServiceSpec'
        type: object
      token_capacity:
        type: integer
      token_refill_per_sec:
        type: number
    type: object
  handler.caasmThrottlingPresetDTO:
    properties:
      config:
        $ref: '#/definitions/handler.caasmThrottlingLimitsDTO'
      description:
        type: string
      label:
        type: string
    type: object
  handler.cloudAccountDTO:
    properties:
      created_at:
        type: string
      effective_throttling:
        $ref: '#/definitions/handler.caasmEffectiveThrottlingDTO'
      error_message:
        type: string
      external_id:
        type: string
      id:
        type: integer
      last_sync_at:
        type: string
      metadata:
        additionalProperties: true
        type: object
      name:
        type: string
      provider:
        $ref: '#/definitions/caasmmodel.CloudProvider'
      status:
        $ref: '#/definitions/caasmmodel.CloudAccountStatus'
      throttling_contract:
        $ref: '#/definitions/handler.caasmThrottlingContractDTO'
      updated_at:
        type: string
    type: object
  handler.cloudAccountSummary:
    properties:
      id:
        type: integer
      name:
        type: string
      provider:
        $ref: '#/definitions/caasmmodel.CloudProvider'
      status:
        $ref: '#/definitions/caasmmodel.CloudAccountStatus'
    type: object
  handler.confirmAttachmentUploadRequest:
    properties:
      attachment_id:
        type: integer
    required:
    - attachment_id
    type: object
  handler.createVulnerabilityRequest:
    properties:
      affected_assets_count:
        type: integer
      application:
        type: string
      batch_group_id:
        type: integer
      code_repository:
        type: string
      department_id:
        type: string
      dependency_name:
        type: string
      dependency_version:
        type: string
      description:
        type: string
      discoverer_employee_id:
        type: integer
      discovery_channel:
        type: string
      discovery_phase:
        type: string
      fixer_employee_id:
        type: integer
      has_poc_verification:
        type: boolean
      interface_path:
        type: string
      is_third_party:
        type: boolean
      network_env:
        type: string
      owner_employee_id:
        type: integer
      poc_text:
        type: string
      severity_level:
        $ref: '#/definitions/vulnmodel.SeverityLevel'
      sla_deadline:
        type: string
      source:
        type: string
      status:
        $ref: '#/definitions/vulnmodel.VulnerabilityStatus'
      submitted_at:
        type: string
      submitter_user_id:
        type: integer
      tags:
        items:
          type: string
        type: array
      title:
        type: string
      verification_steps:
        type: string
      vulnerability_type:
        type: string
    required:
    - discoverer_employee_id
    - severity_level
    - status
    - title
    type: object
  handler.transitionStatusRequest:
    properties:
      message:
        type: string
      status:
        $ref: '#/definitions/vulnmodel.VulnerabilityStatus'
    required:
    - status
    type: object
  handler.updateVulnerabilityPayload:
    properties:
      affected_assets_count:
        type: integer
      application:
        type: string
      code_repository:
        type: string
      department_id:
        type: string
      dependency_name:
        type: string
      dependency_version:
        type: string
      description:
        type: string
      discoverer_employee_id:
        type: integer
      discovery_channel:
        type: string
      discovery_phase:
        type: string
      fixer_employee_id:
        type: integer
      has_poc_verification:
        type: boolean
      interface_path:
        type: string
      is_third_party:
        type: boolean
      network_env:
        type: string
      owner_employee_id:
        type: integer
      poc_text:
        type: string
      severity_level:
        type: string
      sla_deadline:
        type: string
      source:
        type: string
      submitted_at:
        type: string
      tags:
        items:
          type: string
        type: array
      title:
        type: string
      verification_steps:
        type: string
      vulnerability_type:
        type: string
    type: object
  handler.uploadAttachmentRequest:
    properties:
      content_type:
        type: string
      filename:
        type: string
    required:
    - filename
    type: object
  internal_modules_caasm_handler.departmentSummary:
    properties:
      id:
        type: integer
      lark_department_id:
        type: string
      name:
        type: string
    type: object
  internal_modules_caasm_handler.employeeSummary:
    properties:
      avatar_url:
        type: string
      department_id:
        type: string
      email:
        type: string
      id:
        type: integer
      name:
        type: string
    type: object
  repository.PortFrequency:
    properties:
      count:
        type: integer
      port:
        type: integer
    type: object
  response.APIResponse:
    properties:
      code:
        type: integer
      data: {}
      message:
        type: string
      timestamp:
        type: integer
    type: object
  response.PaginatedResponse:
    properties:
      items: {}
      page:
        type: integer
      page_size:
        type: integer
      total:
        type: integer
      total_pages:
        type: integer
    type: object
  service.DomainStatsResult:
    properties:
      expired:
        type: integer
      expiring_soon:
        type: integer
      total:
        type: integer
    type: object
  service.GraphEdge:
    properties:
      label:
        type: string
      source:
        type: string
      target:
        type: string
    type: object
  service.GraphNode:
    properties:
      id:
        type: string
      label:
        type: string
      type:
        type: string
    type: object
  service.PortStatsResult:
    properties:
      by_status:
        additionalProperties:
          format: int64
          type: integer
        type: object
      internal:
        type: integer
      last_updated:
        type: string
      public:
        type: integer
      top_open_ports:
        items:
          $ref: '#/definitions/repository.PortFrequency'
        type: array
      total:
        type: integer
    type: object
  service.RelationshipGraph:
    properties:
      edges:
        items:
          $ref: '#/definitions/service.GraphEdge'
        type: array
      nodes:
        items:
          $ref: '#/definitions/service.GraphNode'
        type: array
    type: object
  vulnmodel.SeverityLevel:
    enum:
    - low
    - medium
    - high
    - critical
    type: string
    x-enum-varnames:
    - SeverityLow
    - SeverityMedium
    - SeverityHigh
    - SeverityCritical
  vulnmodel.VulnerabilityComment:
    properties:
      author_id:
        type: integer
      author_name:
        type: string
      content:
        type: string
      created_at:
        type: string
      id:
        type: integer
      vulnerability_id:
        type: integer
    type: object
  vulnmodel.VulnerabilityStatus:
    enum:
    - active
    - retesting
    - fixed
    - false_positive
    - risk_accepted
    type: string
    x-enum-varnames:
    - StatusActive
    - StatusRetesting
    - StatusFixed
    - StatusFalsePositive
    - StatusRiskAccepted
info:
  contact: {}
  description: Read-only APIs for the Security Center CAASM (asset) and Vuln (vulnerability)
    modules. Both success and business errors return HTTP 200, distinguished via the
    APIResponse envelope (code/message/data/timestamp).
  title: Security Center Agent API
  version: "1.0"
paths:
  /api/v1/caasm/api-assets:
    get:
      description: List API route assets with filtering by keyword, environment, domain,
        namespace, service, plugin, and route kind; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20, max 100
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: Environment
        in: query
        name: environment
        type: string
      - description: Domain name
        in: query
        name: domain
        type: string
      - description: Namespace
        in: query
        name: namespace
        type: string
      - description: Service name
        in: query
        name: service_name
        type: string
      - description: Plugin name
        in: query
        name: plugin
        type: string
      - description: Route kind
        in: query
        name: route_kind
        type: string
      - description: Filter by external route flag
        in: query
        name: external
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are API
            route asset entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List API route assets
      tags:
      - caasm
  /api/v1/caasm/api-assets/config/active:
    get:
      description: Return the currently active API asset discovery config.
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the active API route config
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handler.caasmAPIRouteConfigSummaryDTO'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get the active API route config
      tags:
      - caasm
  /api/v1/caasm/assets:
    get:
      description: List assets of all kinds (IP/domain/service, etc.) with multi-dimensional
        filtering and ETag caching (If-None-Match -> 304).
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20, max 100
        in: query
        name: page_size
        type: integer
      - description: Asset type (AssetType)
        in: query
        name: type
        type: string
      - description: Owner email
        in: query
        name: owner
        type: string
      - description: Owner employee ID
        in: query
        name: owner_employee_id
        type: integer
      - description: Cloud account ID
        in: query
        name: cloud_account_id
        type: integer
      - description: Environment
        in: query
        name: environment
        type: string
      - description: Asset status (AssetStatus)
        in: query
        name: status
        type: string
      - description: Criticality
        in: query
        name: criticality
        type: string
      - description: Cloud provider (CloudProvider)
        in: query
        name: provider
        type: string
      - description: Service name
        in: query
        name: service
        type: string
      - description: Keyword search
        in: query
        name: q
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are asset
            list entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List assets
      tags:
      - caasm
  /api/v1/caasm/assets/{id}:
    get:
      description: Get details of a single asset by ID.
      parameters:
      - description: Asset ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the asset detail object (including asset,
            ip_addresses, domain_assets, relationships)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get asset detail
      tags:
      - caasm
  /api/v1/caasm/assets/{id}/tags:
    get:
      description: Get the tag key-value set of an asset by ID.
      parameters:
      - description: Asset ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the asset tag key-value set
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  additionalProperties:
                    type: string
                  type: object
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get asset tags
      tags:
      - caasm
  /api/v1/caasm/assets/environments:
    get:
      description: Return the set of asset environment values, for filter dropdowns.
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of environment names
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  items:
                    type: string
                  type: array
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List environments
      tags:
      - caasm
  /api/v1/caasm/assets/ports/search:
    get:
      description: Semantic alias of ListPorts; parameters and response are identical
        to GET /api/v1/caasm/ports.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Port number
        in: query
        name: port
        type: integer
      - description: Protocol (tcp/udp)
        in: query
        name: protocol
        type: string
      - description: Port status
        in: query
        name: status
        type: string
      - description: Exposure
        in: query
        name: exposure
        type: string
      - description: Service name
        in: query
        name: service
        type: string
      - description: Asset service name
        in: query
        name: asset_service
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are port
            entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Search asset ports
      tags:
      - caasm
  /api/v1/caasm/assets/services:
    get:
      description: Return the set of service names that assets belong to, for filter
        dropdowns.
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of service names
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  items:
                    type: string
                  type: array
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List asset services
      tags:
      - caasm
  /api/v1/caasm/cloud-accounts:
    get:
      description: List cloud accounts with filtering by keyword, provider, and status;
        paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: Cloud provider (CloudProvider)
        in: query
        name: provider
        type: string
      - description: Cloud account status (CloudAccountStatus)
        in: query
        name: status
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are cloud
            account entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List cloud accounts
      tags:
      - caasm
  /api/v1/caasm/cloud-accounts/{id}:
    get:
      description: Get a single cloud account by ID.
      parameters:
      - description: Cloud account ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the cloud account detail
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handler.cloudAccountDTO'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get cloud account detail
      tags:
      - caasm
  /api/v1/caasm/cloud-accounts/{id}/jobs:
    get:
      description: List sync jobs of a cloud account by ID, paginated.
      parameters:
      - description: Cloud account ID
        in: path
        name: id
        required: true
        type: integer
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are sync
            job entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List cloud account sync jobs
      tags:
      - caasm
  /api/v1/caasm/dns-records:
    get:
      description: List DNS records with filtering by keyword, record type, owner
        department, domain, record value, and alert presence; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: DNS record type (A/CNAME, etc.)
        in: query
        name: type
        type: string
      - description: Owner department ID
        in: query
        name: owner_department_id
        type: string
      - description: Domain ID
        in: query
        name: domain_id
        type: integer
      - description: Domain name
        in: query
        name: domain_name
        type: string
      - description: Record value fuzzy match
        in: query
        name: value
        type: string
      - description: Filter by alert presence
        in: query
        name: has_alert
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are DNS
            record entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List DNS records
      tags:
      - caasm
  /api/v1/caasm/dns-records/{id}/comments:
    get:
      description: Get comments of a DNS record by ID.
      parameters:
      - description: DNS record ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of comments (caasmmodel.DNSRecordComment)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get DNS record comments
      tags:
      - caasm
  /api/v1/caasm/domains:
    get:
      description: List domain assets with filtering by keyword, environment, status,
        registrar, etc.; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: Environment
        in: query
        name: environment
        type: string
      - description: Domain status
        in: query
        name: status
        type: string
      - description: Zone type
        in: query
        name: zone_type
        type: string
      - description: Domain class
        in: query
        name: domain_class
        type: string
      - description: Registrar
        in: query
        name: registrar
        type: string
      - description: Cloud provider (CloudProvider)
        in: query
        name: provider
        type: string
      - description: Filter by forwarding presence
        in: query
        name: forwarding
        type: boolean
      - description: Filter by peering presence
        in: query
        name: peering
        type: boolean
      - description: Filter by auto-renew flag
        in: query
        name: auto_renew
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are domain
            entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List domains
      tags:
      - caasm
  /api/v1/caasm/domains/registrars:
    get:
      description: Return the set of domain registrar names, for filter dropdowns.
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of registrar names
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  items:
                    type: string
                  type: array
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List domain registrars
      tags:
      - caasm
  /api/v1/caasm/domains/stats:
    get:
      description: Return domain statistics (total, expiring soon, expired).
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the domain statistics object
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/service.DomainStatsResult'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get domain statistics
      tags:
      - caasm
  /api/v1/caasm/ip-assets:
    get:
      description: List IP assets with filtering by keyword, cloud provider, region,
        and exposure; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20, max 100
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: Cloud provider (CloudProvider)
        in: query
        name: provider
        type: string
      - description: Cloud account ID
        in: query
        name: cloud_account_id
        type: integer
      - description: Asset service name
        in: query
        name: asset_service
        type: string
      - description: Region
        in: query
        name: region
        type: string
      - description: 'Exposure, enum: public / private (other values return 400)'
        in: query
        name: exposure
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are IP asset
            entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List IP assets
      tags:
      - caasm
  /api/v1/caasm/ports:
    get:
      description: List ports (IP/domain port index) with filtering by port number,
        protocol, status, exposure, and service; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Port number
        in: query
        name: port
        type: integer
      - description: Protocol (tcp/udp)
        in: query
        name: protocol
        type: string
      - description: Port status
        in: query
        name: status
        type: string
      - description: Exposure
        in: query
        name: exposure
        type: string
      - description: Service name
        in: query
        name: service
        type: string
      - description: Asset service name
        in: query
        name: asset_service
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are port
            entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List ports
      tags:
      - caasm
  /api/v1/caasm/ports/{id}:
    get:
      description: Get a single port by ID (including evidence).
      parameters:
      - description: Port ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the port detail
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/handler.caasmPortDetailDTO'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get port detail
      tags:
      - caasm
  /api/v1/caasm/ports/high-risk:
    get:
      description: Return high-risk ports.
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of high-risk ports
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.caasmPortListItemDTO'
                  type: array
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List high-risk ports
      tags:
      - caasm
  /api/v1/caasm/ports/stats:
    get:
      description: Return port statistics (total, public/private, status distribution,
        top open ports).
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the port statistics object
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/service.PortStatsResult'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get port statistics
      tags:
      - caasm
  /api/v1/caasm/relationships/graph:
    get:
      description: Return relationship graph data (nodes + edges) among assets, domains,
        IPs, and ports.
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the relationship graph (nodes + edges)
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/service.RelationshipGraph'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get asset relationship graph
      tags:
      - caasm
  /api/v1/caasm/sync-jobs:
    get:
      description: List sync jobs with filtering by job type, status, cloud account,
        and execution mode; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Job type
        in: query
        name: job_type
        type: string
      - description: Sync job status (SyncJobStatus)
        in: query
        name: status
        type: string
      - description: Cloud account ID
        in: query
        name: cloud_account_id
        type: integer
      - description: Execution mode
        in: query
        name: execution_mode
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are sync
            job entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List sync jobs
      tags:
      - caasm
  /api/v1/caasm/sync-jobs/{id}:
    get:
      description: Get a single sync job by ID.
      parameters:
      - description: Sync job ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the sync job detail (caasmmodel.SyncJob)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get sync job detail
      tags:
      - caasm
  /api/v1/caasm/sync-jobs/{id}/events:
    get:
      description: Get the event stream of a sync job by ID, supporting limit and
        before_id/after_id cursors.
      parameters:
      - description: Sync job ID
        in: path
        name: id
        required: true
        type: integer
      - description: Maximum number of events to return
        in: query
        name: limit
        type: integer
      - description: Return only events before this event ID (mutually exclusive with
          after_id)
        in: query
        name: before_id
        type: integer
      - description: Return only events after this event ID (mutually exclusive with
          before_id)
        in: query
        name: after_id
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of sync job events (caasmmodel.SyncJobEvent)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List sync job events
      tags:
      - caasm
  /api/v1/vulnerabilities:
    get:
      description: List vulnerabilities with filtering by multi-select status/severity,
        application, discovery phase, network environment, keyword, tags, etc.; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20, max 100
        in: query
        name: page_size
        type: integer
      - description: Status multi-select (comma-separated)
        in: query
        name: status
        type: string
      - description: Severity multi-select (comma-separated)
        in: query
        name: severity
        type: string
      - description: Application
        in: query
        name: application
        type: string
      - description: Discovery phase
        in: query
        name: discovery_phase
        type: string
      - description: Discovery channel
        in: query
        name: discovery_channel
        type: string
      - description: Network environment
        in: query
        name: network_env
        type: string
      - description: Keyword
        in: query
        name: search
        type: string
      - description: Tag multi-select (comma-separated)
        in: query
        name: tags
        type: string
      - description: Dependency name
        in: query
        name: dependency_name
        type: string
      - description: Dependency version
        in: query
        name: dependency_version
        type: string
      - description: Owner employee ID
        in: query
        name: owner_employee_id
        type: integer
      - description: Submitter user ID
        in: query
        name: submitter_user_id
        type: integer
      - description: Sort field
        in: query
        name: sort_by
        type: string
      - description: Sort order (asc/desc)
        in: query
        name: sort_order
        type: string
      - description: Batch group ID
        in: query
        name: batch_group_id
        type: integer
      - description: Batch scope (batched/single)
        in: query
        name: batch_scope
        type: string
      - description: Filter by PoC verification presence
        in: query
        name: has_poc
        type: boolean
      - description: Filter by overdue flag
        in: query
        name: is_overdue
        type: boolean
      - description: Filter by third-party vulnerability flag
        in: query
        name: is_third_party
        type: boolean
      - description: Submitted from (RFC3339)
        in: query
        name: submitted_from
        type: string
      - description: Submitted to (RFC3339)
        in: query
        name: submitted_to
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are vulnerability
            entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List vulnerabilities
      tags:
      - vuln
    post:
      consumes:
      - application/json
      description: 'Submit a new vulnerability. title, severity_level, status and
        discoverer_employee_id are always required; the configurable submission_required_fields
        (see GET /api/v1/vulnerabilities/config) may mark more fields as required.
        Agent (API Key) constraints: submitter_user_id is forced to the Key owner''s
        user ID (request value ignored), and submitted_at/sla_deadline are forced
        to server-side defaults (request values ignored). To embed images in description,
        upload them first via POST /api/v1/vulnerabilities/uploads + POST /api/v1/vulnerabilities/uploads/confirm,
        then reference each attachment in the HTML with data-sc-attachment-id="<attachment_id>".
        Requires the vuln:submit_findings permission (for agents: the Key scope must
        include it).'
      parameters:
      - description: Vulnerability submission
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handler.createVulnerabilityRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the created vulnerability (vulnmodel.Vulnerability)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Submit a vulnerability
      tags:
      - vuln
  /api/v1/vulnerabilities/{public_id}:
    get:
      description: Get a single vulnerability by public_id; sensitive fields are trimmed
        according to the actions available to the current user.
      parameters:
      - description: Vulnerability public ID
        in: path
        name: public_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data contains vulnerability (vulnmodel.Vulnerability)
            and actions ([]string)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get vulnerability detail
      tags:
      - vuln
    put:
      consumes:
      - application/json
      description: 'Partially update a vulnerability by public_id; only fields present
        in the body are changed (an explicit null clears a nullable field). Requires
        vuln:edit_details (for agents, the Key scope must include it). Agent (API
        Key) constraint: any change to poc_text, verification_steps, has_poc_verification,
        submitted_at or sla_deadline is rejected with 403 for the whole request. To
        embed new images in description, upload them first via POST /api/v1/vulnerabilities/uploads
        + POST /api/v1/vulnerabilities/uploads/confirm and reference them with data-sc-attachment-id.'
      parameters:
      - description: Vulnerability public ID
        in: path
        name: public_id
        required: true
        type: string
      - description: Fields to update
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handler.updateVulnerabilityPayload'
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the updated vulnerability (vulnmodel.Vulnerability)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Update vulnerability details
      tags:
      - vuln
  /api/v1/vulnerabilities/{public_id}/comments:
    get:
      description: Get comments of a vulnerability by public_id.
      parameters:
      - description: Vulnerability public ID
        in: path
        name: public_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of comments
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/vulnmodel.VulnerabilityComment'
                  type: array
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List vulnerability comments
      tags:
      - vuln
    post:
      consumes:
      - application/json
      description: Add a comment to a vulnerability by public_id. The operator must
        be the vulnerability's submitter, its fixer, or hold a security role; agent
        (API Key) comments are attributed to the Key name in the event stream.
      parameters:
      - description: Vulnerability public ID
        in: path
        name: public_id
        required: true
        type: string
      - description: Comment content
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handler.addCommentRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the created comment (vulnmodel.VulnerabilityComment)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Add a vulnerability comment
      tags:
      - vuln
  /api/v1/vulnerabilities/{public_id}/events:
    get:
      description: Get lifecycle events (status transitions, field changes, etc.)
        of a vulnerability by public_id.
      parameters:
      - description: Vulnerability public ID
        in: path
        name: public_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of vulnerability events (vulnmodel.VulnerabilityEvent)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get vulnerability change events
      tags:
      - vuln
  /api/v1/vulnerabilities/{public_id}/transition:
    post:
      consumes:
      - application/json
      description: 'Transition a vulnerability by public_id; the body field status
        is the target status and selects one of five actions: retesting (=request_retest,
        submit fix for retest: only from active, and the operator must be the vulnerability''s
        fixer; agent Keys additionally need the vuln:request_retest scope), fixed
        (=mark_fixed, verification passed: only from retesting), false_positive (=mark_false_positive)
        or risk_accepted (=mark_risk_accepted) (from active or retesting), active
        (=reopen: from fixed, false_positive or risk_accepted). mark_fixed/mark_false_positive/mark_risk_accepted/reopen
        require vuln:close_findings (for agents, the Key scope must include it). Every
        transition is reversible via reopen; message is recorded in the event stream.'
      parameters:
      - description: Vulnerability public ID
        in: path
        name: public_id
        required: true
        type: string
      - description: Target status and optional message
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handler.transitionStatusRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the transitioned vulnerability (vulnmodel.Vulnerability)
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Transition vulnerability status
      tags:
      - vuln
  /api/v1/vulnerabilities/{public_id}/viewers/candidates:
    get:
      description: Search employee candidates (name/email/department, etc.) that can
        be granted as authorized viewers of the vulnerability, by public_id.
      parameters:
      - description: Vulnerability public ID
        in: path
        name: public_id
        required: true
        type: string
      - description: Keyword (name/email)
        in: query
        name: q
        type: string
      - description: Employee ID list (comma-separated)
        in: query
        name: ids
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is an array of employee candidates
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  items:
                    $ref: '#/definitions/handler.authorizedViewerCandidateDTO'
                  type: array
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Search authorized viewer candidates
      tags:
      - vuln
  /api/v1/vulnerabilities/uploads:
    post:
      consumes:
      - application/json
      description: 'Step 1 of the image attachment flow: create a pending attachment
        and return its attachment_id plus a presigned upload_url. Step 2: PUT the
        file bytes directly to upload_url (no API Key needed; the presigned URL itself
        is the credential). Step 3: call POST /api/v1/vulnerabilities/uploads/confirm
        with the attachment_id. Images only (png/jpeg/webp/gif; SVG is not allowed),
        max 10MB — enforced at confirm time. Reference the confirmed attachment in
        vulnerability descriptions with data-sc-attachment-id.'
      parameters:
      - description: Filename and content type
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handler.uploadAttachmentRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Success; data contains attachment_id, upload_url, key, expires_in
            and optional view_url
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Presign an image attachment upload
      tags:
      - vuln
  /api/v1/vulnerabilities/uploads/confirm:
    post:
      consumes:
      - application/json
      description: 'Step 3 of the image attachment flow: validate the uploaded object
        and mark the attachment ready. Only the original uploader may confirm it.
        Images only (content type png/jpeg/webp/gif; SVG is not allowed) and size
        at most 10MB; a non-compliant object is deleted and the attachment is rejected.'
      parameters:
      - description: Attachment ID returned by the presign step
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/handler.confirmAttachmentUploadRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the confirmed attachment (vulnmodel.VulnerabilityAttachment)
            plus optional view_url
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Confirm an image attachment upload
      tags:
      - vuln
  /api/v1/vulnerability-discovery-channels:
    get:
      description: List vulnerability discovery channels with filtering by keyword
        and system-only flag; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: System channels only
        in: query
        name: system_only
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are vulnerability
            discovery channel entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List vulnerability discovery channels
      tags:
      - vuln
  /api/v1/vulnerability-sources:
    get:
      description: List vulnerability sources with filtering by keyword and system-only
        flag; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: System sources only
        in: query
        name: system_only
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are vulnerability
            source entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List vulnerability sources
      tags:
      - vuln
  /api/v1/vulnerability-tags:
    get:
      description: List vulnerability tags with filtering by keyword, category, and
        system-only flag; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: Tag category
        in: query
        name: category
        type: string
      - description: System tags only
        in: query
        name: system_only
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are vulnerability
            tag entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List vulnerability tags
      tags:
      - vuln
  /api/v1/vulnerability-tags/stats:
    get:
      description: Return tag statistics.
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is the tag statistics object
          schema:
            $ref: '#/definitions/response.APIResponse'
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: Get vulnerability tag statistics
      tags:
      - vuln
  /api/v1/vulnerability-types:
    get:
      description: List vulnerability types with filtering by keyword, category, severity,
        and system-only flag; paginated.
      parameters:
      - description: Page number, default 1
        in: query
        name: page
        type: integer
      - description: Page size, default 20
        in: query
        name: page_size
        type: integer
      - description: Keyword
        in: query
        name: q
        type: string
      - description: Type category
        in: query
        name: category
        type: string
      - description: Severity
        in: query
        name: severity
        type: string
      - description: System types only
        in: query
        name: system_only
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Success; data is a paginated structure whose items are vulnerability
            type entries
          schema:
            allOf:
            - $ref: '#/definitions/response.APIResponse'
            - properties:
                data:
                  $ref: '#/definitions/response.PaginatedResponse'
              type: object
      security:
      - agentApiKey: []
      - bearerAuth: []
      summary: List vulnerability types
      tags:
      - vuln
securityDefinitions:
  agentApiKey:
    description: Agent M2M authentication (X-API-Key).
    in: header
    name: X-API-Key
    type: apiKey
  bearerAuth:
    description: 'Human user JWT (Authorization: Bearer <access_token>).'
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"