CloudGuard External Findings API

openapi: 3.2.0
info:
  title: Events External Findings API
  version: v2
servers:
- url: https://api.dome9.com/
  description: US region
- url: https://api.{region}.dome9.com/
  description: Other regions
  variables:
    region:
      enum:
      - eu1
      - ap1
      - ap2
      - ap3
      - cace1
      default: eu1
security:
- basic: []
tags:
- name: External Findings
paths:
  /v2/ExternalFindings/{id}/Archive:
    post:
      tags:
      - External Findings
      summary: Archive External Finding
      operationId: ExternalFindings_ArchiveExternalFinding_post_/v2/ExternalFindings/{id}/Archive
      parameters:
      - name: id
        in: path
        description: the id of the alert (in Dome9)
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content
      description: Archive a specific external finding. The finding in Dome9 will be marked as 'archived', but not deleted. It will be searchable.
  /v2/ExternalFindings/Archive:
    post:
      tags:
      - External Findings
      summary: Archive External Findings
      operationId: ExternalFindings_ArchiveExternalFindings_post_/v2/ExternalFindings/Archive
      responses:
        '204':
          description: No Content
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingsOperationRequestViewModel'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingsOperationRequestViewModel'
        description: filter block, selecting external system, resource, cloud account id, and finding id
        required: true
      description: Archive selected external findings according filter settings. The findings will be marked as 'archived', but not deleted. They will be searchable.
  /v2/ExternalFindings/search:
    post:
      tags:
      - External Findings
      operationId: ExternalFindings_Search_post_/v2/ExternalFindings/search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dome9.Web.Api.ExternalFindings.ExternalFindingPaginationViewModel'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.SearchRequestViewModel'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.SearchRequestViewModel'
        required: true
      description: ''
      summary: Search
  /v2/ExternalFindings:
    post:
      tags:
      - External Findings
      summary: Post
      operationId: ExternalFindings_Post_post_/v2/ExternalFindings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingsResponseViewModel'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingUpsertRequestViewModel'
          application/x-www-form-urlencoded:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingUpsertRequestViewModel'
        description: list of findings
        required: true
      description: 'Add a list of findings to Dome9, from an external source. The findings will be labelled as external, but will be searchable as any other finding.

        Findings much have a unique findingId (per source).'
    delete:
      tags:
      - External Findings
      summary: Delete External Findings
      operationId: ExternalFindings_DeleteExternalFindings_delete_/v2/ExternalFindings
      responses:
        '204':
          description: No Content
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingsOperationRequestViewModel'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingsOperationRequestViewModel'
        description: '>filter block, selecting external system, resource, cloud account id, and finding id'
        required: true
      description: Delete selected external findings in Dome9. The findings will be permanently removed from Dome9 and will not be searchable.
  /v2/ExternalFindings/{id}:
    delete:
      tags:
      - External Findings
      summary: Delete External Finding
      operationId: ExternalFindings_DeleteExternalFinding_delete_/v2/ExternalFindings/{id}
      parameters:
      - name: id
        in: path
        description: the  id of the alert (in Dome9)
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content
      description: Delete a specific finding in Dome9. The finding will be permanently deleted, and will not be searchable.
components:
  schemas:
    Falconetix.Model.ExternalFindings.ExternalFindingsOperationRequestViewModel:
      required:
      - findingSource
      - externalCloudAccountId
      type: object
      properties:
        findingSource:
          description: the external system sending the finding (e.g, Qualys)
          maxLength: 30
          minLength: 0
          type: string
        resourceId:
          description: The id of the cloud entity related to the finding, as identified by the cloud provider (e.g., an instanceId for AWS)
          maxLength: 250
          minLength: 0
          type: string
        findingId:
          description: a unique id for the finding, set by the external source. This must be unique for all findings from this source.
          maxLength: 250
          minLength: 0
          type: string
        externalCloudAccountId:
          description: the cloud id of the entity, as identified by the cloud provider (e.g., the AWS account number, or Azure subscription id)
          maxLength: 250
          minLength: 0
          type: string
    Falconetix.Model.ExternalFindings.FailedExternalFindingsResponse:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingUpsertRequestViewModel'
        reason:
          type: string
    Dome9.Web.Api.Compliance.Finding.FindingCommentViewModel:
      description: comments for a finding (listed by user)
      type: object
      properties:
        text:
          type: string
        timestamp:
          format: date-time
          type: string
        userName:
          type: string
    Dome9.Web.Api.Compliance.Finding.SearchFilterViewModel:
      type: object
      properties:
        freeTextPhrase:
          description: free text
          type: string
        fields:
          description: fields
          type: array
          items:
            $ref: '#/components/schemas/CGN.OpenSearch.Model.CommonViewModels.FieldFilterViewModel'
        onlyCIEM:
          type: boolean
        onlyCustomPolicy:
          description: Filtering all findings created by custom policy
          type: boolean
        creationTime:
          $ref: '#/components/schemas/Dome9.Web.Api.Shared.SharedViewModels.DateRangeViewModel'
        updatedTime:
          $ref: '#/components/schemas/Dome9.Web.Api.Shared.SharedViewModels.DateRangeViewModel'
        hasRemediation:
          type: boolean
    Falconetix.Model.RuleEngine.Entities.FindingAdditionalFieldViewModel:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    Falconetix.Model.ExternalFindings.ExternalFindingsResponseViewModel:
      type: object
      properties:
        failedRecords:
          type: array
          items:
            $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.FailedExternalFindingsResponse'
        totalFailedRecords:
          format: int32
          type: integer
          readOnly: true
        totalSuccessfulRecords:
          format: int32
          type: integer
    Falconetix.Model.ExternalFindings.ExternalFindingsFieldViewModel:
      type: object
      properties:
        name:
          maxLength: 30
          minLength: 0
          type: string
        value:
          maxLength: 100
          minLength: 0
          type: string
        comment:
          maxLength: 100
          minLength: 0
          type: string
    Dome9.Web.Api.Compliance.Finding.FieldAggregationViewModel:
      type: object
      properties:
        value:
          type: object
        count:
          format: int64
          type: integer
    Dome9.Web.Api.Shared.SharedViewModels.DateRangeViewModel:
      type: object
      properties:
        from:
          format: date-time
          type: string
        to:
          format: date-time
          type: string
    Falconetix.Model.RuleEngine.Entities.Compliance.AssessmentFinding.MagellanData:
      type: object
      properties:
        alertWindowStartTime:
          format: date-time
          type: string
        alertWindowEndTime:
          format: date-time
          type: string
    Dome9.Web.Api.Compliance.Finding.FindingViewModel:
      type: object
      properties:
        entityObject:
          description: details for the entity in the cloud provider
          type: object
        id:
          format: uuid
          description: finding id
          type: string
          example: 00000000-0000-0000-0000-000000000000
        findingKey:
          description: finding key
          type: string
        createdTime:
          format: date-time
          description: date finding was first found
          type: string
        updatedTime:
          format: date-time
          description: date of last update for the finding
          type: string
        cloudAccountType:
          description: cloud account provider (AWS/Azure/GCP)
          enum:
          - Aws
          - Azure
          - Google
          - Kubernetes
          - Terraform
          - Generic
          - KubernetesRuntimeAssurance
          - ShiftLeft
          - SourceCodeAssurance
          - ImageAssurance
          - Alibaba
          - Cft
          - ContainerRegistry
          - Oci
          - CIEM
          type: string
        comments:
          type: array
          items:
            $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.FindingCommentViewModel'
        cloudAccountId:
          format: uuid
          description: cloud account id (on AWS/Azure/GCP)
          type: string
          example: 00000000-0000-0000-0000-000000000000
        cloudAccountExternalId:
          description: cloud account id on the cloud provider
          type: string
        organizationalUnitId:
          format: uuid
          description: the Organizational Unit id
          type: string
          example: 00000000-0000-0000-0000-000000000000
        organizationalUnitPath:
          description: the Organizational Unit path
          type: string
        bundleId:
          format: int64
          description: the bundle id
          type: integer
        bundleVersion:
          type: string
        alertType:
          description: the bundle id
          enum:
          - SecurityEvent
          - Task
          type: string
        ruleId:
          description: id of the specific rule that failed
          type: string
        ruleName:
          description: name of the specific rule that failed (text string)
          type: string
        ruleLogic:
          description: the GSL logic for the rule
          type: string
        entityDome9Id:
          description: the Dome9 entity id (representing a cloud entity) that was tested by the rule
          type: string
        entityExternalId:
          description: the cloud provider entity id for the entity tested by the rule
          type: string
        entityType:
          description: the type of entity tested (e.g. S3, or EC2)
          type: string
        entityTypeByEnvironmentType:
          description: the type of entity tested by the environment type in format of {EnvironmentType}|{EntityType}
          type: string
        entityName:
          description: the entity name (on the cloud provider), as a text string, in the specific cloud provider format
          type: string
        entityNetwork:
          type: string
        entityTags:
          type: array
          items:
            $ref: '#/components/schemas/Falconetix.Model.RuleEngine.Entities.TagRuleEntity'
        severity:
          description: the severity of the finding (H/M/L)
          type: string
        description:
          description: text description of the finding (the failure reason)
          type: string
        remediation:
          description: the recommended remediation (if any) for the failure
          type: string
        tag:
          description: tags assigned to the finding (list string)
          type: string
        region:
          description: the region in which the entity was located
          type: string
        bundleName:
          description: the name of the bundle with the rule
          type: string
        acknowledged:
          description: indicates the finding was acknowledged
          type: boolean
        origin:
          description: Dome9 source of the finding (Compliance or Magellan)
          enum:
          - ComplianceEngine
          - Magellan
          - MagellanAwsGuardDuty
          - Serverless
          - Agentless
          - AwsInspector
          - ServerlessSecurityAnalyzer
          - ExternalFindingSource
          - Qualys
          - Tenable
          - AwsGuardDuty
          - KubernetesImageScanning
          - KubernetesRuntimeAssurance
          - ContainersRuntimeProtection
          - WorkloadChangeMonitoring
          - ImageAssurance
          - SourceCodeAssurance
          - InfrastructureAsCode
          - CIEM
          - Incident
          type: string
        lastSeenTime:
          format: date-time
          description: Date when the finding was last seen
          type: string
        ownerUserName:
          description: Dome9 user assigned to the finding
          type: string
        magellan:
          $ref: '#/components/schemas/Falconetix.Model.RuleEngine.Entities.Compliance.AssessmentFinding.MagellanData'
          description: Extra data for Magellan findings
        isExcluded:
          description: Indicates the finding was excluded from the assessment
          type: boolean
        webhookResponses:
          description: Consists of Webhook type and the response of that webhook, if response defined
          type: object
          properties:
            none:
              $ref: '#/components/schemas/Falconetix.Model.ElasticSearch.WebhookResponse.WebhookResponseMessage'
            serviceNow:
              $ref: '#/components/schemas/Falconetix.Model.ElasticSearch.WebhookResponse.WebhookResponseMessage'
            jira:
              $ref: '#/components/schemas/Falconetix.Model.ElasticSearch.WebhookResponse.WebhookResponseMessage'
        remediationActions:
          type: array
          items:
            type: string
        additionalFields:
          type: array
          items:
            $ref: '#/components/schemas/Falconetix.Model.RuleEngine.Entities.FindingAdditionalFieldViewModel'
        occurrences:
          type: array
          items:
            type: string
        scanId:
          type: string
        status:
          enum:
          - Active
          - Archived
          type: string
        statusReason:
          enum:
          - Unspecified
          - RuleViolation
          - ConfigurationFixed
          - AssetDeleted
          - RulesetDeleted
          - RuleDeleted
          - PolicyDeleted
          - UserClosed
          - CloudAccountDeleted
          type: string
        category:
          type: string
        action:
          enum:
          - Detect
          - Prevent
          type: string
        labels:
          type: array
          items:
            type: string
    Falconetix.Model.ExternalFindings.ExternalFindingUpsertRequestViewModel:
      required:
      - resourceId
      - resourceType
      - externalCloudAccountId
      - vendor
      - findingSource
      - findingSeverity
      - findingId
      - findingCreatedAt
      - findingTitle
      type: object
      properties:
        resourceId:
          description: cloud entity resource Id such as AWS ec2 instance id, or  Azure vm id etc
          maxLength: 250
          minLength: 0
          type: string
        resourceName:
          description: '[optional] cloud entity resource name such as AWS lambda name'
          maxLength: 250
          minLength: 0
          type: string
        resourceType:
          description: the entityType, as used by the Dome9 Rule engine.
          type: string
        externalCloudAccountId:
          description: the cloud account id, i.e., Aws account id, Azure subscriptionId, or GCP projectId
          maxLength: 100
          minLength: 0
          type: string
        vendor:
          description: the cloud vendor, Aws, Azure, or Gcp
          enum:
          - aws
          - hp
          - mellanox
          - awsgov
          - azure
          - google
          - awschina
          - azuregov
          - kubernetes
          - azurechina
          - terraform
          - generic
          - kubernetesruntimeassurance
          - shiftleft
          - sourcecodeassurance
          - imageassurance
          - alibaba
          - cft
          - containerregistry
          - oci
          - ocigov
          - ocigovuk
          - CIEM
          type: string
        findingSource:
          description: the name of the external source, e.g., qualys , tenable etc
          maxLength: 30
          minLength: 0
          type: string
        findingSourceDescription:
          description: '[optional] additional description of external source'
          maxLength: 250
          minLength: 0
          type: string
        findingSourceUrl:
          description: external URL describing the finding
          maxLength: 250
          minLength: 0
          type: string
        findingSeverity:
          description: the Dome9 Severity level for the finding, Low, Medium, or High
          enum:
          - Low
          - Medium
          - High
          - Critical
          - Informational
          type: string
        originalFindingSeverity:
          description: original external source  severity for the finding
          maxLength: 30
          minLength: 0
          type: string
        findingId:
          description: unique identifier for the finding. This must be unique for all findings from this source.
          maxLength: 250
          minLength: 0
          type: string
        scanId:
          description: '[optional] refering scan id'
          maxLength: 250
          minLength: 0
          type: string
        findingCreatedAt:
          format: date-time
          description: date finding was created, in ISO8601 Date String format
          type: string
        findingTitle:
          description: short description of the finding
          maxLength: 250
          minLength: 0
          type: string
        findingDescription:
          description: description of the finding
          maxLength: 500
          minLength: 0
          type: string
        findingStatus:
          description: Finding status text
          maxLength: 30
          minLength: 0
          type: string
        findingCategory:
          description: Finding Category text
          maxLength: 50
          minLength: 0
          type: string
        findingRecommendation:
          description: Finding Recommendation/remediation  text
          maxLength: 500
          minLength: 0
          type: string
        relatedFindingsRef:
          description: FindingIds that are related to this finding
          type: array
          items:
            type: string
        ruleId:
          description: '[optional] Rule id or Plugin id that is used to generate the finding'
          maxLength: 250
          minLength: 0
          type: string
        findingRulesPackage:
          $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingsRulesPackageViewModel'
          description: ''
        additionalFields:
          description: Additional fields that can be added as part of the finding object, as  (name, value) pairs
          type: array
          items:
            $ref: '#/components/schemas/Falconetix.Model.ExternalFindings.ExternalFindingsFieldViewModel'
        findingAlertType:
          description: Alert Type for Events page possible values SecurityEvent, Task(POSTURE FINDINGS) if no value provided using default SecurityEvent
          maxLength: 50
          minLength: 0
          type: string
    Falconetix.Model.ExternalFindings.ExternalFindingsRulesPackageViewModel:
      type: object
      properties:
        id:
          maxLength: 30
          minLength: 0
          type: string
        name:
          maxLength: 100
          minLength: 0
          type: string
        provider:
          maxLength: 30
          minLength: 0
          type: string
        version:
          maxLength: 30
          minLength: 0
          type: string
    Falconetix.Model.ElasticSearch.WebhookResponse.WebhookResponseMessage:
      type: object
      properties:
        requestTime:
          format: date-time
          type: string
        responseContent:
          type: object
    Dome9.Web.Api.ExternalFindings.ExternalFindingPaginationViewModel:
      type: object
      properties:
        searchRequest:
          $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.SearchRequestViewModel'
          description: search request for findings
        findings:
          description: current page of findings
          type: array
          items:
            $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.FindingViewModel'
        totalFindingsCount:
          format: int64
          description: total number of findings
          type: integer
        aggregations:
          description: aggregate findings per search or filter entity (facet)
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.FieldAggregationViewModel'
        searchAfter:
          description: token for next page of results
          type: array
          items:
            type: string
    CGN.OpenSearch.Model.CommonViewModels.FieldFilterViewModel:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    Dome9.Web.Api.Compliance.Finding.SearchRequestViewModel:
      type: object
      properties:
        searchAfter:
          description: token for the page of findings (first page if not specified)
          type: array
          items:
            type: string
        pageSize:
          format: int32
          description: 'page size (number of findings returned per page). default: 10.'
          maximum: 10000
          minimum: 0
          type: integer
        skipAggregations:
          type: boolean
        lowAggregationsSize:
          type: boolean
        sorting:
          $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.SortingViewModel'
          description: sort data
        multiSorting:
          type: array
          items:
            $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.SortingViewModel'
        filter:
          $ref: '#/components/schemas/Dome9.Web.Api.Compliance.Finding.SearchFilterViewModel'
          description: filter
        dataSource:
          enum:
          - Finding
          - Archive
          type: string
    Falconetix.Model.RuleEngine.Entities.TagRuleEntity:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
    Dome9.Web.Api.Compliance.Finding.SortingViewModel:
      type: object
      properties:
        fieldName:
          description: Field name
          type: string
        direction:
          format: int32
          description: direction. 1 is asc, -1 desc
          type: integer
  securitySchemes:
    basic:
      type: http
      scheme: basic
x-readme:
  explorer-enabled: true
  proxy-enabled: true