{
  "openapi": "3.0.1",
  "info": {
    "contact": {
      "name": "Chkk",
      "url": "https://www.chkk.io"
    },
    "description": "A REST API that exposes the Chkk data model.",
    "title": "Chkk API",
    "version": "v1.0"
  },
  "externalDocs": {
    "description": "Detailed documentation of the Chkk data model and product features",
    "url": "https://docs.chkk.io"
  },
  "servers": [
    {
      "url": "https://api.us.chkk.io/v1"
    }
  ],
  "tags": [
    {
      "description": "Operations that authenticate users and return scoped access tokens.",
      "name": "Login"
    },
    {
      "description": "Operations for retrieving Guardrails, Misconfigurations, and API-Deprecation Risks detected in your clusters.",
      "name": "Risk"
    }
  ],
  "paths": {
    "/login": {
      "post": {
        "summary": "Get Access Token",
        "description": "Authenticate and obtain access credentials for authorized operations.",
        "operationId": "login",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            },
            "description": "Returns organization metadata for authenticated users."
          }
        },
        "security": [
          {
            "bearer_token": []
          }
        ],
        "tags": [
          "Login"
        ]
      }
    },
    "/risks": {
      "get": {
        "summary": "List Risks",
        "description": "List Risks matching one or more filter parameters.",
        "operationId": "risk-list",
        "parameters": [
          {
            "description": "List Risks matching one or more filter parameters.\n1. cluster_id:k8scl_<uuid> (required) \n2. tag:category:guardrail \n3. show_ignored:true",
            "explode": true,
            "in": "query",
            "name": "filter",
            "required": false,
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "style": "form"
          },
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/Continuation"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListRisksResponse"
                }
              }
            },
            "description": "Returns an array of `RiskSummary` objects."
          }
        },
        "security": [
          {
            "bearer_token": []
          }
        ],
        "tags": [
          "Risk"
        ]
      }
    },
    "/risks/{riskId}": {
      "parameters": [
        {
          "description": "Unique identifier for the Risk",
          "explode": false,
          "in": "path",
          "name": "riskId",
          "required": true,
          "schema": {
            "type": "string"
          },
          "style": "simple"
        }
      ],
      "get": {
        "summary": "Get a specific Risk",
        "description": "Returns the full details of a single Risk.",
        "operationId": "risk-get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Risk"
                }
              }
            },
            "description": "Returns the requested Risk."
          }
        },
        "security": [
          {
            "bearer_token": []
          }
        ],
        "tags": [
          "Risk"
        ]
      }
    },
    "/risks/{riskId}/resources": {
      "parameters": [
        {
          "explode": false,
          "in": "path",
          "name": "riskId",
          "required": true,
          "schema": {
            "type": "string"
          },
          "style": "simple",
          "description": "Unique identifier of the Risk whose affected resources you want to list."
        }
      ],
      "get": {
        "summary": "List resources for a specific Risk",
        "description": "Returns a paginated list of resources that are associated with the specified Operational Risk.",
        "operationId": "risk-list-affected-resources",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageSize"
          },
          {
            "$ref": "#/components/parameters/Continuation"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListRiskResourcesResponse"
                }
              }
            },
            "description": "Returns an array of `RiskAffectedResource` objects."
          }
        },
        "security": [
          {
            "bearer_token": []
          }
        ],
        "tags": [
          "Risk"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "LoginResponse": {
        "properties": {
          "access_tokens": {
            "additionalProperties": {
              "additionalProperties": {
                "$ref": "#/components/schemas/AccessToken"
              },
              "description": "Mapping from account slug to its access token bundle.",
              "type": "object"
            },
            "description": "Map keyed by **org ID**. Each entry is an object keyed by account slug that contains the bearer AccessToken for that account.",
            "type": "object"
          },
          "user": {
            "$ref": "#/components/schemas/LoginResponseUser",
            "description": "Details of the logged in user"
          }
        },
        "required": [
          "continuation_token",
          "orgs"
        ],
        "type": "object"
      },
      "AccessToken": {
        "description": "An access token as used by the Chkk API for authentication",
        "properties": {
          "access_token": {
            "description": "The actual token to be used in Authorization header",
            "type": "string"
          },
          "user_id": {
            "description": "The ID of the user represented by the access token",
            "type": "string"
          },
          "aws_identity_arn": {
            "description": "The ARN of the AWS Identity represented by the access token",
            "type": "string"
          },
          "org_id": {
            "description": "The ID of the organization represented by the access token",
            "type": "string"
          },
          "account_id": {
            "description": "The ID of the account represented by the access token",
            "type": "string"
          },
          "created": {
            "description": "Time at which the access token was created. Measured in seconds since the Unix epoch",
            "type": "integer"
          }
        },
        "required": [
          "access_token",
          "created"
        ],
        "type": "object"
      },
      "LoginResponseUser": {
        "description": "Details of the logged in user",
        "properties": {
          "user_id": {
            "description": "The ID of the user of the current identity",
            "type": "string"
          },
          "email": {
            "description": "The email address of the user of the current identity",
            "type": "string"
          },
          "name": {
            "description": "the name of the user of the current identity",
            "type": "string"
          },
          "profile_picture": {
            "description": "The profile picture for the user",
            "type": "string"
          }
        },
        "required": [
          "email",
          "user_id"
        ],
        "title": "LoginResponseUser",
        "type": "object"
      },
      "ListRisksResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/RiskSummary"
            },
            "type": "array"
          },
          "continuation_token": {
            "description": "Opaque token for pagination",
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "Risk": {
        "properties": {
          "id": {
            "description": "Unique identifier for the Risk.",
            "type": "string"
          },
          "signature": {
            "$ref": "#/components/schemas/RiskSignature"
          },
          "remediation": {
            "description": "Guidance on how to remediate and permanently fix the Risk from your environment.",
            "type": "string"
          },
          "mitigation": {
            "description": "Guidance on how to temporarily resolve the Risk from your environment.",
            "type": "string"
          },
          "root_cause": {
            "description": "Underlying condition that causes the Risk to manifest.",
            "type": "string"
          },
          "severity": {
            "$ref": "#/components/schemas/RiskSeverity"
          },
          "location": {
            "$ref": "#/components/schemas/RiskLocation"
          },
          "status": {
            "$ref": "#/components/schemas/RiskStatus"
          },
          "last_detected": {
            "description": "Time when the Risk was most recently identified.",
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "last_detected",
          "location",
          "signature"
        ],
        "type": "object"
      },
      "ListRiskResourcesResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/RiskAffectedResource"
            },
            "type": "array"
          },
          "continuation_token": {
            "description": "Opaque token for pagination",
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "RiskSummary": {
        "description": "A condensed version of a Risk.",
        "properties": {
          "id": {
            "description": "Stable identifier for this Risk within Chkk.",
            "type": "string"
          },
          "signature": {
            "$ref": "#/components/schemas/RiskSignatureSummary"
          },
          "severity": {
            "$ref": "#/components/schemas/RiskSeverity"
          },
          "location": {
            "$ref": "#/components/schemas/RiskLocation"
          },
          "last_detected": {
            "description": "Unix epoch timestamp of when the Risk was most recently identified.",
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "last_detected",
          "location",
          "signature"
        ],
        "type": "object"
      },
      "RiskSeverity": {
        "description": "The severity of a Risk. It is a measure of the combination of probability and impact of a Risk materializing",
        "enum": [
          "low",
          "medium",
          "high",
          "critical"
        ],
        "type": "string"
      },
      "RiskLocationCluster": {
        "type": "object",
        "description": "The Cluster where the Risk was detected",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the Cluster"
          },
          "name": {
            "type": "string",
            "description": "The name of the Cluster"
          },
          "namespace": {
            "type": "string",
            "description": "Namespace in the cluster if relevant"
          }
        },
        "required": [
          "id"
        ]
      },
      "RiskLocation": {
        "properties": {
          "cluster": {
            "description": "ID of the cluster where the Risk was detected.",
            "$ref": "#/components/schemas/RiskLocationCluster"
          }
        },
        "type": "object"
      },
      "RiskStatus": {
        "description": "Details about the status of the Risk including its lifecycle state.",
        "properties": {
          "lifecycle": {
            "$ref": "#/components/schemas/RiskStatusLifecycle"
          },
          "reason": {
            "$ref": "#/components/schemas/RiskStatusReason"
          },
          "comment": {
            "description": "A comment further describing the reason behind the Risk's status change",
            "type": "string"
          },
          "identity": {
            "$ref": "#/components/schemas/Identity"
          },
          "updated": {
            "description": "The time the Risk's status was updated",
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "lifecycle"
        ],
        "type": "object"
      },
      "RiskAffectedResource": {
        "description": "A resource impacted by an Operational Risk.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/RiskAffectedK8sResource"
          }
        ],
        "properties": {
          "type": {
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "RiskSignature": {
        "description": "RiskSignature is the source of Operational Risk for a customer.",
        "properties": {
          "id": {
            "description": "Unique identifier for this RiskSignature.",
            "type": "string"
          },
          "title": {
            "description": "Human-readable RiskSignature title.",
            "type": "string"
          },
          "description": {
            "description": "Description of the Risk detected by the signature, i.e. what happens when it materializes",
            "type": "string"
          },
          "tags": {
            "description": "The tags associated with the Risk signature",
            "items": {
              "$ref": "#/components/schemas/RiskTag"
            },
            "type": "array"
          },
          "links": {
            "$ref": "#/components/schemas/Links"
          }
        },
        "required": [
          "description",
          "id",
          "title"
        ],
        "type": "object"
      },
      "RiskSignatureSummary": {
        "properties": {
          "id": {
            "description": "Unique identifier of the Risk signature",
            "type": "string"
          },
          "title": {
            "description": "Title of the Risk signature",
            "type": "string"
          },
          "description": {
            "description": "Description of what happens when the Risk signature materializes.",
            "type": "string"
          },
          "tags": {
            "description": "The tags associated with the Risk signature",
            "items": {
              "$ref": "#/components/schemas/RiskTag"
            },
            "type": "array"
          }
        },
        "required": [
          "description",
          "id",
          "title"
        ],
        "title": "RiskSignatureSummary",
        "type": "object"
      },
      "RiskStatusLifecycle": {
        "description": "The lifecycle state of a Risk",
        "enum": [
          "ignored",
          "active",
          "resolved"
        ],
        "type": "string"
      },
      "RiskStatusReason": {
        "description": "Reason why a Risk was set to its current lifecycle state.",
        "enum": [
          "FalsePositive",
          "ByDesign",
          "DevTestCluster",
          "FollowedProcedure",
          "Other"
        ],
        "type": "string"
      },
      "Identity": {
        "description": "Actor that changed the lifecycle of a Risk. Can be a machine principal or a human user.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/MachineAwsIdentity"
          },
          {
            "$ref": "#/components/schemas/UserIdentity"
          }
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Discriminator that indicates which identity object is present."
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "RiskAffectedK8sResource": {
        "description": "A object affected by an Operational Risk.",
        "properties": {
          "type": {
            "enum": [
              "k8s"
            ],
            "type": "string"
          },
          "kind": {
            "type": "string",
            "description": "API Kind (e.g., `Deployment`, `StatefulSet`)."
          },
          "name": {
            "type": "string",
            "description": "Resource name."
          },
          "namespace": {
            "type": "string",
            "description": "namespace where the resource is located."
          }
        },
        "required": [
          "kind",
          "name",
          "type"
        ],
        "type": "object"
      },
      "RiskTag": {
        "description": "A tag that can be applied to a Risk or Risk Signature.",
        "enum": [
          "category:guardrail",
          "category:api-deprecation",
          "category:misconfiguration"
        ],
        "type": "string"
      },
      "Links": {
        "items": {
          "$ref": "#/components/schemas/Link"
        },
        "type": "array"
      },
      "Link": {
        "properties": {
          "url": {
            "description": "URL of the reference link",
            "type": "string"
          },
          "type": {
            "description": "The type of linked resource",
            "enum": [
              "generic",
              "github.releases",
              "github.release",
              "github.issues",
              "github.issue",
              "gitlab.releases",
              "gitlab.release",
              "gitlab.issues",
              "gitlab.issue",
              "bitbucket.releases",
              "bitbucket.release",
              "bitbucket.issues",
              "bitbucket.issue",
              "documentation",
              "project.website",
              "project.releasenotes",
              "project.upgradeguide",
              "project.versioning",
              "project.support",
              "project.source",
              "project.component.source",
              "package.source"
            ],
            "type": "string"
          },
          "description": {
            "description": "A description of the related resource",
            "type": "string"
          }
        },
        "required": [
          "type",
          "url"
        ],
        "type": "object"
      },
      "MachineAwsIdentity": {
        "description": "An AWS-based machine identity",
        "properties": {
          "type": {
            "enum": [
              "aws"
            ],
            "type": "string"
          },
          "aws_identity_arn": {
            "description": "ARN of the AWS identity that took the action.",
            "type": "string"
          }
        },
        "required": [
          "aws_identity_arn",
          "type"
        ],
        "type": "object"
      },
      "UserIdentity": {
        "description": "A human user in the Chkk platform",
        "properties": {
          "type": {
            "enum": [
              "user"
            ],
            "type": "string"
          },
          "id": {
            "description": "Internal Chkk user identifier.",
            "type": "string"
          },
          "name": {
            "description": "User's full name",
            "type": "string"
          },
          "email": {
            "description": "User's email address.",
            "format": "email",
            "type": "string"
          },
          "picture": {
            "description": "A URL for the  user's picture",
            "type": "string"
          }
        },
        "required": [
          "email",
          "id",
          "name",
          "type"
        ],
        "type": "object"
      }
    },
    "parameters": {
      "PageSize": {
        "explode": true,
        "in": "query",
        "name": "page_size",
        "required": false,
        "schema": {
          "default": 100,
          "description": "Number of resources to return per page",
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "style": "form"
      },
      "Continuation": {
        "explode": true,
        "in": "query",
        "name": "continuation_token",
        "required": false,
        "schema": {
          "description": "Opaque token for pagination",
          "type": "string"
        },
        "style": "form"
      }
    },
    "securitySchemes": {
      "bearer_token": {
        "in": "header",
        "name": "Authorization",
        "type": "apiKey",
        "description": "Authorization credentials supplied in the Authorization header."
      }
    }
  }
}