rubber-stamper/

README

Rubber-Stamper

go/rubber-stamper-user-guide

Rubber-Stamper provides a security-sensitive bot which can provide timely second-eyes code review by verifying the safety of CLs that it is asked to review.

See go/chops-rubber-stamp-bot-design for design plans.

Rubber Stamper User Guide

Have Rubber-Stamper review your CLs

For every CL that requires Rubber-Stamper's review, add Rubber Stamper (rubber-stamper@appspot.gserviceaccount.com) as a reviewer. Rubber-Stamper will respond in ~1 min. It will either add a Bot-Commit +1 label or leave a comment providing the reason why this CL does not meet the configured rules and also remove itself as reviewer. The Bot-Commit +1 label is not sticky, which means additional patchsets will need to be reviewed.

If you set the Auto-Submit label, Rubber Stamper will also set Commit-Queue +2 if it approves the CL.

If a CL does not pass, you can upload a new patchset that addresses the comments and re-add Rubber-Stamper as a reviewer.

Expected CL types & intended usage

Currently, our expected CL patterns can be generally divided into two types:

• Changes to benign files (translation, whitespace, test expectation files, directories that contain no code)
• Clean reverts/cherry-picks

Rubber Stamper never provides OWNERS approval, by design. It's intended to be used by those who have owners in the directory modified or who are sheriffs. If it provided both code review and OWNERS approval, that would be an abuse vector: that would allow anyone who can create a revert or cherry-pick to land it without any other person being involved and that would allow the insertion of nonsense into benign files. E.g. the silent revert of security patches.

If you need to add/change pattern configs, go to the first section "Configure your patterns"; if a pattern is already configured, and you need to use Rubber-Stamper as a reviewer for CLs, go to the second section "Have Rubber-Stamper review your CLs".

Configure your patterns

1. Add a config for your patterns in config.cfg. To edit this config file, clone the service configurations for LUCI repo. Config definitions can be found in config.proto.
2. Send a review request to chops-security-oncallers@google.com. Once the config change is submitted, the config will be pushed to Rubber-Stamper via luci-config.

Examples of benign file patterns

When you need Rubber-Stamper to treat your files as benign files, you need to add the path to the files/directories in the config.

The list of filepaths that follow .gitignore style ignore patterns, is configured on a per-repo basis. Here is a sample repo_config that allows all .xtb filepaths in chromium/src, and a few subpaths for.txt files.

repo_configs {
  key: "chromium/src"
  value: {
    benign_file_pattern {
      paths: "*.xtb"
      paths: "a/b.txt"
      paths: "a/*/c.txt"
      paths: "z/*"
    }
  }
}

We use the same rule as in .gitignore files to parse these paths. Here, each element of paths is treated as a line in a .gitignore file. Syntax of .gitignore can be found in gitignore. To be noticed, in a .gitignore file, the last matching pattern decides the outcome. We also follow this rule here. For example, with the following repo_config, file test/a/1.txt would be valid, while file test/a/b/2.txt would not be allowed.

repo_configs {
  key: "chromium/src"
  value: {
    benign_file_pattern {
      paths: "test/a/**",
      paths: "!test/a/b/*",
    }
  }
}

Note: when a revert/cherry-pick cannot pass the clean_revert_pattern/ clean_cherry_pick_pattern check, but can pass the benign_file_pattern check, we will still approve the CL because benign_file_pattern is used as a fallback in our design.

Examples of clean revert patterns

A revert will be approved if the Gerrit API marks it as a pure revert, it is within the configured time_window in the config, and none of the modified files is in the excluded_paths.

A time_window represents a length of time in <int><unit> form. Reverts need to be within this time_window to be valid. Valid units are s, m, h, d, meaning "seconds", "minutes", "hours", "days" respectively. By default, Rubber-Stamper has a global default_time_window of 7d, which allows reverts that are reverted no later than 7 days. You can override this value at a host-level (by modifying clean_revert_time_window in host_configs) or repo-level (by modifying time_window in clean_revert_pattern of repo_configs). It is always the more granular level that is applied. For example, in the following config, the global 7d, host-level 1h will all be overriden by repo-level 5m.

default_time_window: "7d"

host_configs {
  key: "chromium"
  value: {
    clean_revert_time_window: "1h"
    repo_configs {
      key: "infra/experimental"
      value: {
        clean_revert_pattern {
          time_window: "5m"
        }
      }
    }
  }
}

excluded_paths defines files/directories that always require a human to review. If a revert modifies any file that is contained in excluded_paths, the revert will not be approved by Rubber-Stamper. The syntax of excluded_paths is the same as that of .gitignore files. Gitignore file syntax is documented in gitignore. In the following sample config, any revert that changes a/b.md or any files ending in .go will not be approved.

clean_revert_pattern {
  excluded_paths: "a/b.md"
  excluded_paths: "*.go"
}

Examples of clean cherry-pick patterns

A cherry-pick will be approved if:

1. The current revision doesn't make any file changes compared with the initial revision;
2. It is within the configured time_window in the config;
3. It is cherry-picked after the original CL has been merged;
4. None of the modified files is in the excluded_paths;
5. It is marked as mergeable by the Gerrit API GetMergeable.

The format of time_window is the same as that for clean revert patterns, which you can find in the section above. Similarly, a host-level value (clean_cherry_pick_time_window in host_configs) can override the global value (default_time_window), while a repo-level value (time_window in clean_cherry_pick_pattern of repo_configs) can override the host-level value.

The format of excluded_paths is also the same as that for clean revert patterns.

Here is an example of a clean cherry-pick pattern. Any cherry-pick that is cherry-picked more than 3 hours ago or modifies any files ending in .md will not be approved.

clean_cherry_pick_pattern {
  time_window: "3h"
  excluded_paths: "*.md"
}

Bypass File Check

We also provide a way to bypass file check in clean cherry-pick patterns, that is, all the cherry-pick rules still apply except "The current revision doesn't make any file changes compared with the initial revision".

The cherry-pick needs to meet the following requirements:

1. The file changes between the initial revision and current revision will only be in configured included_paths.
2. The CL should have a configured hashtag.
3. The CL owner has to be one of allowed_owners.

Here is an example of clean cherry-pick pattern with a bypassFileCheck rule.

clean_cherry_pick_pattern {
  time_window: "3h"
  excluded_paths: "*.md"

  file_check_bypass_rule {
    included_paths: "dir/*.md"
    hashtag: "Example-Hashtag"
    allowed_owners: "user@example.com"
  }
}

Found a bug?

Please file a bug at go/peepsec-bug for support.