Internal documentation updates.

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.

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).