docs/security/shepherd.md
Security Shepherding is a rotation for security bug triage. The Shepherding rotation is made up of people actively working on security in Chrome. At any given time there are two shepherds on shift. The shifts are during work hours only, so you are not "on call" while shepherding.
[TOC]
Your overarching goal is to get security bugs in Chrome to people or machines which can fix them, which means ensuring that valid, actionable reports enter the process.
Remember that you are triaging bugs. There are usually many bug reports, far too many for you to actually investigate all of them in detail. You are deciding how to allocate your own time, and the time of other engineers, in the way that produces the best security results for users. You are not fully investigating every element of every report.
It makes sense to focus your attention first on:
If you are the shepherd, your PRIMARY DIRECTIVE is to tackle all the red cells on the security bug dashboard. You do that by filling in missing fields on the bugs and assigning them to engineers who will fix them.
If you are chrome-security-shepherds-1: you are responsible for all the
bugs in the Shepherd 1 tab. If you are chrome-security-shepherds-2, you are
responsible for the Shepherd 2 tab.
To actually triage a report, you go through several steps. On a new bug report:
Skim the bug to see if it looks plausible: is this likely to be a real bug, in Chrome, with security consequences for Chrome users?
Prefer to quickly WontFix bugs with a reason at this stage. Reporters can and will open a new issue if they have further information to provide.
If it could plausibly be a security bug, does it come with the evidence we need to reproduce it? Ask this before attempting to reproduce or understand the issue:
If evidence for the issue is not attached to the issue, close it noting what is missing. Do not use Needs-Feedback at this stage.
Do not be shy about asking for clear evidence. The burden of proof at this point is primarily on the reporter - they need to convince you that the bug exists and could plausibly be exploited. These things aren't enough evidence:
If the PoC looks sketchy, ask the reporter to fix it or minimize it - don't spend your own time trying to minimize it or read through half a megabyte of wasm bytecode to figure out what's going on. Use WontFix and do not use Needs-Feedback.
At this stage, you should lean towards marking bugs as WontFix if you are in doubt. Unfortunately, most incoming bug reports are not valid security bugs, and time spent triaging those reports in detail is time not spent triaging bugs which are valid. As a rule:
Vulnerability to Privacy IssueLimited Visibility + GooglersNow, before reproducing or deeply understanding the issue, move on to...
Have a look at the severity guidelines, which contain lots of examples of bugs of different severities and detailed writeups of the various factors. The severity is based on your judgment of the consequences of exploitation of the bug, not on the reporter's assessment in the bug report.
If the report requires you to enable a specific feature or pass a specific command-line argument, and that feature isn't default-enabled for any Chrome users, then add the bug to the Security_Impact-None (hotlistid:5433277) hotlist at this stage, which exempts it from the usual severity-based fix SLOs. Note that features can be enabled by Finch studies or origin trials, so don't just base your decision on the default state of the feature. The Finch state dashboard may be helpful.
If you're in doubt about severity, ask for help in the Shepherd chat. This step benefits a lot from judgment and experience!
ClusterFuzz is far quicker than manual reproduction, and will automatically do bisection and set Found In for you, so you should use ClusterFuzz if at all possible. If you have to manually reproduce a bug instead:
At this point, you need the ability to know if a specific OS + version combination (up to the oldest active branch) is affected by the bug, so you need to either:
In all cases, Found In should contain the oldest milestone number which is still active and has the bug. This should be based on your investigation and the evidence in the bug, not on what versions the reporter reported the bug against - those are often just what the reporter happens to be testing on.
It's ok if the OS field is a guess. There is no need to manually test every OS + version combination, but please do remember to set this field.
Now, it's time to assign the bug:
git blame if in doubtAs you work through the queue each day, please manage your time and ensure you have addressed all red rows and cells in the sheet to the best of your ability. Do your best to ensure there are no red cells at the top of your sheet before the end of your shift.
Please fill out the Shepherding Handoff Log to communicate issues from your shift that may be helpful to the oncoming shift.
Security bug triage is hard. We receive hundreds of bug reports per week on average. If you are ever stuck or in doubt, please ask for help from the Chrome Security Shepherds chat or the Chrome Security Chat. During some shifts, there are just too many incoming bugs. It’s okay to ask for help, please do!
You may also like the classic HOWTO: Be a Security Shepherd deck
Here are some of the important references and resources you need or may need during your shepherding shift:
What do I do here?
You are not responsible for handling merges or approving a fix for backmerge.
If the issue is resolved and there is a landed CL, please ensure the bug is
closed as Fixed. Please also make sure the bug has a severity and Found In set.
This will allow the bot (Sheriffbot) to add the appropriately update the Merge
custom field with the appropriate request-MMM or review-MMM labels, where MMM =
the milestones for backmerge consideration (based on rules driven by severity
(and Security_Impact, derived from Found In). See
security merge triage
for more information.
That issue will be visible to the security merge review queue. There are designated members of the security team who have the hefty responsibility of reviewing security issues for backmerge. Merge approvals will be handled by them after at least the fix has had sufficient bake time on Canary.
(e.g. how and when does a VRP bug get to the Chrome VRP Panel?) See Life of a Security Issue.
Chrome VRP policies and rewards page and Chrome VRP News and FAQs. You can also reach out directly to the Chrome VRP TL or ask questions in the Chrome Security Shepherds chat, all VRP Panel members are also members of that chat.
For cases of PII, simply delete the attachment or comment that contains PII
within the issue tracker. If PII is contained in the text of the original
description of the report, simply choose the Edit description option and
remove any PII.
For cases in which we are just delaying public disclosure (such as when a
security issue impacts other products or vendors), please add the
SecurityEmbargo hotlist (hotlistID: 5432549) and set a date in the Next Action field so that disclosure can be re-evaluated at that time.
Many researchers report security issues under a pseudonym and from a specific email address pertaining to that pseudonym. Please do not refer to the researcher by the email username directly in any comments of the report. When reports are publicly disclosed, that becomes visible to all and we have to delete those comments to protect that information. To direct a comment at an external security researcher, please use “OP”, “reporter”, or "researcher”.
You may come across some reports in the security bug triage queue with a red
banner, "The issue has been deleted. Reason: ABUSE," this is generally due to
the overactive spam filtering in the issue tracker. Just click Undelete in the
right side of the banner, and triage the report as you normally would.