jvs

README

Justification Verification Service (JVS)

JVS is not an official Google product.

This repository contains components related to a justification verification service

Use Case

Audit logs are special logs that record when and who called which application and accessed what data. And why the access was necessary (aka. the justification of the data access). JVS is a solution to produce verified justifications, and in combination with abcxyz/lumberjack, the justifications could be audit logged.

Architecture

JVS consists of the following components:

• Justification API service: Verify justifications and mint short-lived justification tokens. Find more about the API here.

• jvsctl CLI: This is the primary interface into the JVS and server components. Find more about the CLI here.

• Web UI: Support requesting justification tokens from web pages. Find more about the web UI and flow here.

• Public Key service: JWKs endpoint for retrieving public keys to validate justification tokens.

• Cert Rotator service: Rotate signing keys stored in Cloud KMS. Triggered by Cloud Scheduler.

End User Workflows

CLI flow: Calling REST or gRPC APIs from command line with justification.

1. The requester uses jvsctl to request a justification token by giving a reason.
2. The justification API will authenticate the requester, verify the provided reason and return a justification token after verification.
3. The requester then can use the justification token in REST or gRPC requests header (HTTP header or gRPC metadata).
4. The REST or gRPC service server is responsible to validate the justification token in the requests header and audit log it down. abcxyz/lumberjack client SDK provides this functionality.

Web flow: Accessing web pages with justification.

1. The web page(s) must redirect the requester to the JVS web UI when the access happens. See example.
2. The JVS web UI will authenticate the requester and ask the requester to provide a reason.
3. The JVS web UI will verify the provided reason and after verification redirect back to the original web page(s) along with the justification token.
4. The original web app will then be able to cache and use the justification token to call its backend.
5. The web app's backend is responsible to validate the justification token in the requests header and audit log it down. abcxyz/lumberjack client SDK provides this functionality.

Installation

Via abc CLI

You can leverage abc CLI to set up the basic infrastructure needed for this service. You will need to install abc CLI by following docs here.

abc templates render \
 -input="<YOUR_PROJECT_ID>" \
 -input="jvs_release_version=<JVS_RELEASE_VERSION>" \
 -input="jvs_api_domain=<YOUR_JVS_API_DOMAIN>" \
 -input="jvs_ui_domain=<YOUR_JVS_UI_DOMAIN>" \
 -input="iap_support_email=<YOUR_IAP_SUPPORT_EMAIL>" \
 -input="notification_channel_email=<YOUR_NOTIFICATION_CHANNEL_EMAIL>" \
 -input="jvs_invoker_members=<YOUR_JVS_INVOKE_MEMBERS>" \
 -input="prober_audience=<YOUR_CLOUD_RUN_URL_FOR_JVS_API_SERVICE_OR_APP_ADDRESS>" \
 -input="terraform_state_bucket=<YOUR_TERRAFORM_STATE_BUCKET>" \
 -input="terraform_state_prefix=<YOUR_TERRAFORM_STATE_PREFIX>" \
 github.com/abcxyz/jvs.git//templates/jvs-e2e

Via Terraform Module

You can use the provided Terraform module to setup the basic infrastructure needed for this service. Otherwise you can refer to the provided module to see how to build your own Terraform from scratch.

module "jvs" {
  source     = "git::https://github.com/abcxyz/jvs.git//terraform/e2e?ref=main" # this should be pinned to the SHA desired
  project_id = "YOUR_PROJECT_ID"

  # Specify who can access JVS.
  jvs_invoker_members = ["user:foo@example.com"]

  # Use your own domain.
  jvs_api_domain = "api.jvs.example.com"
  jvs_ui_domain  = "web.jvs.example.com"

  iap_support_email = "support@example.com"

  jvs_container_image = "us-docker.pkg.dev/abcxyz-artifacts/docker-images/jvsctl:0.0.5-amd64"


  # Specify the Email address where alert notifications send to.
  notification_channel_email = "foo@example.com"

  jvs_prober_image = "us-docker.pkg.dev/abcxyz-artifacts/docker-images/jvs-prober:0.0.5-amd64"

  # The cloud run url for jvs api service or app address.
  prober_audience = "https://example-api-jvs-cloud-run.run.app"
}

External Verifier

JVS itself only supports two types of reasons:

• Manual explanantion
• Breakglass

We plan to introduce a plug-in model for external verifiers as JVS extensions. E.g. The ability to verify if a Github issue exists.