overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Dome9 / CloudGuard v2 API
  version: 1.0.0
x-provenance:
  generated: '2026-09-07'
  method: generated
  provider: Dome9
  providerId: dome9
  extends: openapi/dome9-api-openapi.json
  source: >-
    Enhancements derived from the CloudGuard developer hub
    (docs.cgn.portal.checkpoint.com/reference/introduction and
    /reference/authentication, read 2026-09-07) and from this repo's derived
    artifacts. The upstream Swagger 2.0 document at
    https://api.dome9.com/swagger/docs/v2 is NEVER mutated — this overlay is the
    only place our additions live.
  note: >-
    Every action below adds context the first-party contract omits: a real
    title/description, contact and licence, the regional host families the docs
    publish but the spec does not, external docs, and machine-readable warnings
    about the absent error, idempotency and pagination conventions.
actions:
- target: $.info
  description: Replace the bare "Dome9.API" title with a document a consumer can read.
  update:
    title: CloudGuard (Dome9) API
    description: >-
      Check Point CloudGuard posture management REST API, formerly Dome9.
      601 paths / 722 operations covering cloud-account onboarding (AWS, Azure,
      Google, Alibaba, Kubernetes, container registries), compliance rulesets and
      assessments, findings and alerts, security groups and firewall policy,
      access leases, users, roles and service accounts. HTTP Basic auth with a
      V2 API key id and secret. The API is region-pinned — see x-regions.
    termsOfService: https://www.checkpoint.com/about-us/legal-notice/
    contact:
      name: Check Point CloudGuard
      url: https://docs.cgn.portal.checkpoint.com/
    license:
      name: Proprietary
      url: https://www.checkpoint.com/about-us/legal-notice/
- target: $
  description: >-
    Record the six regional API hosts the developer hub publishes. The upstream
    spec declares only host api.dome9.com, which is the US deployment.
  update:
    externalDocs:
      description: CloudGuard developer hub
      url: https://docs.cgn.portal.checkpoint.com/reference/introduction
    x-regions:
    - region: US
      dome9: https://api.dome9.com
      infinity: https://api.us1.cgn.portal.checkpoint.com
    - region: EU
      dome9: https://api.eu1.dome9.com
      infinity: https://api.eu1.cgn.portal.checkpoint.com
    - region: AU
      dome9: https://api.ap2.dome9.com
      infinity: https://api.ap2.cgn.portal.checkpoint.com
    - region: CA
      dome9: https://api.cace1.dome9.com
      infinity: https://api.cace1.cgn.portal.checkpoint.com
    - region: IN
      dome9: https://api.ap3.dome9.com
      infinity: https://api.ap3.cgn.portal.checkpoint.com
    - region: SG
      dome9: https://api.ap1.dome9.com
      infinity: https://api.ap1.cgn.portal.checkpoint.com
    x-agent-readiness:
      idempotency: none
      error_schema: undeclared
      pagination: none-standard
      reversibility: documented
      rate_limits: undocumented
      note: >-
        See conventions/dome9-conventions.yml and errors/dome9-problem-types.yml
        in the API Evangelist record for the evidence behind each verdict.
- target: $.securityDefinitions['API key V2']
  description: Document how the Basic credential is actually minted.
  update:
    description: >-
      HTTP Basic. Username = V2 API key id, password = API key secret, both
      created in the CloudGuard portal under Settings > Credentials
      (https://secure.dome9.com). The key inherits the permissions of the user
      who created it; there is no scope narrowing.
      Docs: https://docs.cgn.portal.checkpoint.com/reference/authentication
- target: $.paths['/v2/Compliance/Finding/selectAll/close'].post
  description: Flag the highest blast-radius operation in the contract.
  update:
    x-blast-radius: high
    x-human-in-the-loop: required
    x-reversible: false
    x-note: >-
      Closes every finding matching the supplied filter. No idempotency key, no
      undo. Preview the same filter through Finding_Search before calling.
- target: $.paths['/v2/cloudaccounts/{id}/DeleteForce'].delete
  description: Flag irreversible cloud-account deletion.
  update:
    x-blast-radius: high
    x-human-in-the-loop: required
    x-reversible: false
    x-note: >-
      Deletes the AWS cloud account and every linked entity in CloudGuard. No
      restore operation exists and no grace period is documented.