From c93dde62bdf3aede023b02fc5f57a18b727b8be8 Mon Sep 17 00:00:00 2001 From: Rim Vilgalys Date: Mon, 8 Jun 2026 14:47:40 -0700 Subject: [PATCH] Internal documentation updates. PiperOrigin-RevId: 928781799 --- DEVELOPMENT.md | 58 +++++++++++++++++++++++++++++++++++++++++ MOSS_PLAYBOOK.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100644 DEVELOPMENT.md create mode 100644 MOSS_PLAYBOOK.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..bfa1105 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,58 @@ +# Web Risk Container App Development Guide + +This document explains the development workflow for the Web Risk Container App. + +## The Hybrid Workflow + +The Source of Truth (SoT) for this code is in Piper (`google3/third_party/webrisk/`), but the container app is mirrored to GitHub ([github.com/google/webrisk](https://github.com/google/webrisk)) and relies on standard Go modules for external users. + +Because the files in Piper use internal `google3/...` import paths, **standard Go toolchain commands (like `go get`, `go mod tidy`, and `go test`) cannot be run directly inside your google3 CitC workspace.** They will fail to resolve the internal imports. + +To make updates (including dependency updates), you must use a hybrid workflow: **develop externally, copy back internally.** + +--- + +## Step-by-Step Development Process + +### 1. Make Changes in a GitHub Clone +Do not edit the Go files or `go.mod` directly in CitC if you need to run Go tools. Instead: + +1. Clone the public GitHub repository to your local machine (outside of CitC): + ```bash + git clone https://github.com/google/webrisk + cd webrisk + ``` +2. Make your code changes or dependency updates in this clone. +3. If you are updating dependencies (e.g., to fix a vulnerability): + ```bash + # Update all packages: + go get -u ./... + # Or update a specific package: + go get -u golang.org/x/net@latest + + # Tidy the module: + go mod tidy + ``` +4. Verify the changes by running the Go tests in the clone: + ```bash + go test ./... + ``` + +### 2. Copy Changes Back to Piper +Once your changes are verified and working in the GitHub clone: + +1. Copy the modified files from your local GitHub clone back into your google3 CitC workspace under `google3/third_party/webrisk/`. + * *Make sure to copy `go.mod` and `go.sum` if you updated dependencies.* +2. In your CitC workspace, verify that the google3 build is still healthy by running Blaze tests: + ```bash + SKYBUILD=1 blaze test //third_party/webrisk:webrisk_test + ``` + +### 3. Submit the CL (with Attestation) +1. Create your CL. +2. **If you updated dependencies**, you must add the following tag to your CL description: + ``` + DEPS_CHECKED=true + ``` + *A presubmit check (configured in [METADATA](file:///google/src/cloud/interweb/prodx-fixit-share-260608150135/google3/third_party/webrisk/METADATA)) enforces this tag if `go.mod` or `go.sum` are modified. This confirms you followed this guide and verified the updates externally.* +3. Submit the CL. Copybara will automatically mirror your changes back to GitHub. diff --git a/MOSS_PLAYBOOK.md b/MOSS_PLAYBOOK.md new file mode 100644 index 0000000..b123464 --- /dev/null +++ b/MOSS_PLAYBOOK.md @@ -0,0 +1,68 @@ +# MOSS Playbook: Web Risk Container App Dependency Updates + +This playbook is part of the Web Risk Container App's **MOSS (Minimum Open Source Security)** compliance. It explains how to respond to vulnerability alerts and ensure our open-source dependencies are secure. + +For tracking and general documentation, see: +* **MOSS Dashboard:** [go/moss-dash](http://go/moss-dash) +* **Vulnerability Monitoring:** [go/vuln-monitoring](http://go/vuln-monitoring) + +## Alerting & Bug Routing + +Vulnerability scanning is configured for all repositories on the `webrisk` Gerrit host (configured in [CL 740788929](http://cl/740788929)). + +* **Alerts Route to:** [reCAPTCHA Interrupts (Component 561426)](https://buganizer.corp.google.com/savedsearches/6594123?q=componentid:561426) +* **CC:** `cloud-webrisk-team@google.com` + +--- + +## How to Update Vulnerable Dependencies + +When a vulnerability is detected (or during routine maintenance), you must update the dependency. + +Because of internal `google3/...` import paths in Piper, **you cannot run `go get` or `go mod tidy` directly in your CitC workspace.** You must perform the update externally and copy the files back. + +### Step-by-Step Instructions + +1. **Clone/Sync Externally:** + Go to a local directory (outside CitC) and clone the public repository: + ```bash + git clone https://github.com/google/webrisk + cd webrisk + ``` + +2. **Update the Dependency:** + In your local clone, run the Go tools to update the specific vulnerable package (e.g., `golang.org/x/net`): + ```bash + # Update to latest: + go get -u golang.org/x/net@latest + + # Clean up go.mod and go.sum: + go mod tidy + ``` + +3. **Verify Externally:** + Run the Go tests in your local clone to ensure no breaking changes: + ```bash + go test ./... + ``` + +4. **Copy Back to CitC:** + Copy the updated `go.mod` and `go.sum` (and any modified `.go` files) from your local clone back into your google3 CitC workspace under `google3/third_party/webrisk/`. + +5. **Verify in google3:** + In your CitC workspace, run the Blaze tests to ensure google3 compatibility: + ```bash + SKYBUILD=1 blaze test //third_party/webrisk:webrisk_test + ``` + +6. **Submit with Attestation:** + Create a CL and add the following tag to your CL description: + ``` + DEPS_CHECKED=true + ``` + *This tag is required by a presubmit check to confirm you have followed this playbook and verified the updates.* + +--- + +## Detailed Development Workflow +For a complete guide on developing and making non-dependency changes to the container app, see [DEVELOPMENT.md](file:///google/src/cloud/interweb/prodx-fixit-share-260608150135/google3/third_party/webrisk/DEVELOPMENT.md).