openapi: 3.0.3
info:
  title: Aqua Security REST API
  description: >-
    The Aqua Security REST API provides programmatic access to manage images, containers, policies, users,
    registries, and runtime security configurations for the Aqua Cloud Native Security Platform.
  version: '2022.4'
  x-generated-from: documentation
  contact:
    name: Aqua Security Support
    url: https://support.aquasec.com/
  license:
    name: Commercial
    url: https://www.aquasec.com/aqua-cloud/terms-of-service/
servers:
  - url: https://{tenant}.cloud.aquasec.com/api
    description: Aqua Cloud SaaS
    variables:
      tenant:
        description: Your Aqua tenant identifier
        default: your-tenant
  - url: https://{host}:8080/api
    description: Aqua self-hosted deployment
    variables:
      host:
        description: Hostname or IP of your Aqua server
        default: aqua-server
tags:
  - name: Authentication
    description: User authentication and token management
  - name: Images
    description: Container image scanning and vulnerability management
  - name: Containers
    description: Running container monitoring and enforcement
  - name: Policies
    description: Security policy management
  - name: Registries
    description: Container registry configuration
  - name: Users
    description: User and role management
  - name: Integrations
    description: Third-party integration configurations
paths:
  /v1/login:
    post:
      operationId: login
      summary: Aqua Security Authenticate User
      description: Authenticate a user and obtain an access token for subsequent API calls.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              LoginRequestExample:
                summary: Default login request
                x-microcks-default: true
                value:
                  id: admin
                  password: s3cur3P@ssw0rd
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
              examples:
                Login200Example:
                  summary: Default login 200 response
                  x-microcks-default: true
                  value:
                    token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.abc123
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/images:
    get:
      operationId: listImages
      summary: Aqua Security List Images
      description: List all container images registered in the Aqua platform.
      tags:
        - Images
      parameters:
        - name: registry
          in: query
          description: Filter images by registry name
          schema:
            type: string
          example: docker-hub
        - name: repository
          in: query
          description: Filter images by repository name
          schema:
            type: string
          example: nginx
        - name: tag
          in: query
          description: Filter images by tag
          schema:
            type: string
          example: latest
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            default: 1
          example: 1
        - name: pagesize
          in: query
          description: Number of results per page
          schema:
            type: integer
            default: 50
            maximum: 1000
          example: 50
      responses:
        '200':
          description: List of images
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageList'
              examples:
                ListImages200Example:
                  summary: Default listImages 200 response
                  x-microcks-default: true
                  value:
                    count: 2
                    result:
                      - registry: docker-hub
                        name: nginx:latest
                        vulnerabilities:
                          critical: 0
                          high: 3
                          medium: 12
                          low: 24
                        scan_status: completed
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: registerImage
      summary: Aqua Security Register Image
      description: Register a container image for scanning and policy enforcement.
      tags:
        - Images
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageRequest'
            examples:
              RegisterImageRequestExample:
                summary: Default registerImage request
                x-microcks-default: true
                value:
                  registry: docker-hub
                  image: nginx:latest
      responses:
        '200':
          description: Image registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/images/{registry}/{image_name}/{image_tag}:
    get:
      operationId: getImage
      summary: Aqua Security Get Image Details
      description: Get detailed information and vulnerability data for a specific container image.
      tags:
        - Images
      parameters:
        - name: registry
          in: path
          required: true
          description: Registry name
          schema:
            type: string
          example: docker-hub
        - name: image_name
          in: path
          required: true
          description: Image repository name
          schema:
            type: string
          example: nginx
        - name: image_tag
          in: path
          required: true
          description: Image tag
          schema:
            type: string
          example: latest
      responses:
        '200':
          description: Image details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageDetail'
              examples:
                GetImage200Example:
                  summary: Default getImage 200 response
                  x-microcks-default: true
                  value:
                    registry: docker-hub
                    name: nginx
                    tag: latest
                    digest: sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
                    scan_status: completed
                    vulnerabilities:
                      critical: 0
                      high: 3
                      medium: 12
                      low: 24
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Image not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteImage
      summary: Aqua Security Delete Image
      description: Remove a container image from the Aqua platform.
      tags:
        - Images
      parameters:
        - name: registry
          in: path
          required: true
          description: Registry name
          schema:
            type: string
          example: docker-hub
        - name: image_name
          in: path
          required: true
          description: Image repository name
          schema:
            type: string
          example: nginx
        - name: image_tag
          in: path
          required: true
          description: Image tag
          schema:
            type: string
          example: latest
      responses:
        '204':
          description: Image deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Image not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/containers:
    get:
      operationId: listContainers
      summary: Aqua Security List Containers
      description: List all running containers monitored by the Aqua enforcement agent.
      tags:
        - Containers
      parameters:
        - name: status
          in: query
          description: Filter by container status
          schema:
            type: string
            enum: [running, stopped, all]
          example: running
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            default: 1
          example: 1
        - name: pagesize
          in: query
          description: Number of results per page
          schema:
            type: integer
            default: 50
          example: 50
      responses:
        '200':
          description: List of containers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerList'
              examples:
                ListContainers200Example:
                  summary: Default listContainers 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    result:
                      - container_id: abc123def456
                        image: nginx:latest
                        status: running
                        policy: default
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/securitypolicies:
    get:
      operationId: listPolicies
      summary: Aqua Security List Security Policies
      description: List all configured security image assurance policies.
      tags:
        - Policies
      responses:
        '200':
          description: List of security policies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyList'
              examples:
                ListPolicies200Example:
                  summary: Default listPolicies 200 response
                  x-microcks-default: true
                  value:
                    count: 2
                    result:
                      - name: default
                        description: Default security policy
                        block_failed: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPolicy
      summary: Aqua Security Create Security Policy
      description: Create a new image assurance security policy.
      tags:
        - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyRequest'
            examples:
              CreatePolicyRequestExample:
                summary: Default createPolicy request
                x-microcks-default: true
                value:
                  name: high-security
                  description: Policy blocking high severity vulnerabilities
                  block_failed: true
                  maximum_score: 7.0
      responses:
        '200':
          description: Policy created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/registries:
    get:
      operationId: listRegistries
      summary: Aqua Security List Registries
      description: List all configured container registries.
      tags:
        - Registries
      responses:
        '200':
          description: List of registries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryList'
              examples:
                ListRegistries200Example:
                  summary: Default listRegistries 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    result:
                      - name: docker-hub
                        type: HUB
                        url: https://index.docker.io
                        status: connected
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/users:
    get:
      operationId: listUsers
      summary: Aqua Security List Users
      description: List all users configured in the Aqua platform.
      tags:
        - Users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
              examples:
                ListUsers200Example:
                  summary: Default listUsers 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    result:
                      - id: admin
                        name: Administrator
                        role: administrator
                        email: admin@example.com
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the /v1/login endpoint
  schemas:
    LoginRequest:
      type: object
      required:
        - id
        - password
      properties:
        id:
          type: string
          description: Username or user ID
          example: admin
        password:
          type: string
          description: User password
          example: s3cur3P@ssw0rd
    LoginResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT bearer token for subsequent API calls
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.abc123
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error description
          example: Unauthorized access
        code:
          type: integer
          description: Error code
          example: 401
    VulnerabilityCounts:
      type: object
      properties:
        critical:
          type: integer
          description: Number of critical severity vulnerabilities
          example: 0
        high:
          type: integer
          description: Number of high severity vulnerabilities
          example: 3
        medium:
          type: integer
          description: Number of medium severity vulnerabilities
          example: 12
        low:
          type: integer
          description: Number of low severity vulnerabilities
          example: 24
        negligible:
          type: integer
          description: Number of negligible severity vulnerabilities
          example: 5
    Image:
      type: object
      properties:
        registry:
          type: string
          description: Name of the container registry
          example: docker-hub
        name:
          type: string
          description: Image repository name
          example: nginx
        tag:
          type: string
          description: Image tag
          example: latest
        digest:
          type: string
          description: Image content digest (SHA256)
          example: sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
        scan_status:
          type: string
          description: Current scan status
          enum: [pending, in-progress, completed, failed]
          example: completed
        vulnerabilities:
          $ref: '#/components/schemas/VulnerabilityCounts'
        disallowed:
          type: boolean
          description: Whether the image is blocked by policy
          example: false
    ImageList:
      type: object
      properties:
        count:
          type: integer
          description: Total number of images
          example: 100
        result:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    ImageDetail:
      allOf:
        - $ref: '#/components/schemas/Image'
        - type: object
          properties:
            os:
              type: string
              description: Operating system of the image
              example: debian:bullseye-slim
            size:
              type: integer
              description: Image size in bytes
              example: 142000000
            created:
              type: string
              format: date-time
              description: Image creation timestamp
              example: '2025-03-15T14:30:00Z'
            scan_date:
              type: string
              format: date-time
              description: Date the image was last scanned
              example: '2026-04-18T10:00:00Z'
    ImageRequest:
      type: object
      required:
        - registry
        - image
      properties:
        registry:
          type: string
          description: Name of the configured registry
          example: docker-hub
        image:
          type: string
          description: Full image name including tag
          example: nginx:latest
    Container:
      type: object
      properties:
        container_id:
          type: string
          description: Container ID
          example: abc123def456
        name:
          type: string
          description: Container name
          example: web-server-1
        image:
          type: string
          description: Image name and tag
          example: nginx:latest
        status:
          type: string
          description: Container runtime status
          enum: [running, stopped, paused]
          example: running
        policy:
          type: string
          description: Applied security policy name
          example: default
        host:
          type: string
          description: Host running the container
          example: kube-node-01
    ContainerList:
      type: object
      properties:
        count:
          type: integer
          description: Total number of containers
          example: 50
        result:
          type: array
          items:
            $ref: '#/components/schemas/Container'
    Policy:
      type: object
      properties:
        name:
          type: string
          description: Policy name
          example: default
        description:
          type: string
          description: Policy description
          example: Default security policy
        block_failed:
          type: boolean
          description: Whether to block containers that fail policy evaluation
          example: true
        maximum_score:
          type: number
          format: float
          description: Maximum CVSS score allowed (0-10)
          example: 7.0
    PolicyList:
      type: object
      properties:
        count:
          type: integer
          description: Total number of policies
          example: 5
        result:
          type: array
          items:
            $ref: '#/components/schemas/Policy'
    PolicyRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Policy name (unique)
          example: high-security
        description:
          type: string
          description: Policy description
          example: Policy blocking high severity vulnerabilities
        block_failed:
          type: boolean
          description: Block containers failing policy
          example: true
        maximum_score:
          type: number
          description: Maximum CVSS score threshold
          example: 7.0
    Registry:
      type: object
      properties:
        name:
          type: string
          description: Registry display name
          example: docker-hub
        type:
          type: string
          description: Registry type
          enum: [HUB, V2, ECR, ACR, GCR, JFrog, Harbor]
          example: HUB
        url:
          type: string
          description: Registry URL
          example: https://index.docker.io
        username:
          type: string
          description: Authentication username
          example: myuser
        status:
          type: string
          description: Connection status
          enum: [connected, disconnected, error]
          example: connected
    RegistryList:
      type: object
      properties:
        count:
          type: integer
          description: Total number of registries
          example: 3
        result:
          type: array
          items:
            $ref: '#/components/schemas/Registry'
    User:
      type: object
      properties:
        id:
          type: string
          description: User login ID
          example: admin
        name:
          type: string
          description: User display name
          example: Administrator
        role:
          type: string
          description: User role
          enum: [administrator, auditor, scanner, image_assurance, runtime_policy]
          example: administrator
        email:
          type: string
          format: email
          description: User email address
          example: admin@example.com
    UserList:
      type: object
      properties:
        count:
          type: integer
          description: Total number of users
          example: 10
        result:
          type: array
          items:
            $ref: '#/components/schemas/User'
security:
  - BearerAuth: []