Skip to content
bucker

Block rules

A block rule refuses telemetry that matches it, at Bucker's own door, for one project. Use one to stop a forged DSN, a noisy scanner or an attack payload from landing in your issues. A rule is born in monitor mode, where it only counts what it would have matched. Only a person turns it on, and the enforcement ends by itself.

This page is the contract: what a rule can match, how the monitor period works, who may enable one, what an enabled rule does, and which routes and tools reach it. The findings that suggest a rule are in Security findings; the shared scope table is in Security scope.

Off until the deployment turns it on

Block rules sit behind the block_rules pillar. A pillar is a volume switch the operator of the deployment flips (pillar.block_rules.enabled), and it is off by default. While it is off:

  • GET /orgs/:org/projects/:project/block-rules answers 403, and nothing is loaded or matched at ingest.
  • block_rules_update refuses to create a rule, and a person's enable is refused. Releasing a rule that already exists is still allowed, so the switch never traps a rule in force.

Nothing a project owner does turns the pillar on. If the read answers 403, the deployment has not enabled the capability.

What a rule matches

One rule has one matcher, scoped to one project.

Matcher Matches Acts on
ip an IP address or a CIDR range; IPv4 no wider than /16, IPv6 no wider than /32 the request
user_agent a user-agent family the request
sdk an SDK name and version the request
dsn_key one DSN public key the request
content a content class: injection (the injection scanner's high-confidence rules on a message) or instruction_in_error (an instruction written inside an error) the event

A project holds at most 100 rules (MAX_BLOCK_RULES_PER_PROJECT), live or not yet released. A new rule past the cap is refused with the number.

Monitor first

Every rule starts in monitor. In that mode it:

  • counts what it would match over the last 24 hours (wouldMatch24h), and
  • touches nothing: no envelope is refused, dropped or changed.

Because a monitor rule changes nothing, an agent may create one with block_rules_update without a person asking. Disabling a monitor rule is just as light. Releasing a rule that is enforcing is a heavier act and asks for a decision first.

Read the would-match count before you enable. It is the evidence for the enable, and it is what decides how many people must agree.

Enabling: a person, a step-up, and a line at 20 percent

Enabling is block_rule.enable, and it is a person's act. An agent, a service account, an OAuth client or a delegated token cannot do it, and block_rules_update has no enable operation. It needs the security:write scope, which a plain member does not hold, a written reason, and a fresh proof of presence (a step-up) bound to that rule and that reason.

Two routes, in order:

POST /orgs/:org/projects/:project/block-rules/:ruleId/enable/challenge
POST /orgs/:org/projects/:project/block-rules/:ruleId/enable

The challenge lives a few minutes and is single use. Asking for one for a rule that is not in monitor mode is refused.

What happens next depends on the share of traffic the rule would have matched, measured from its own monitor counts over the last 24 hours (requests for a source rule, events for a content rule):

The rule matched Answer What it means
20 percent or less of what it saw 200, status: applied the enable applies at once
more than 20 percent 202, status: step_up_required, with a requestId a two-approver request is opened; nothing changes yet
not measured: watched for under an hour, or saw nothing 202, as above an unmeasured rule counts as above the line

The share is computed by Bucker. It is never an argument. Above the line, a second person holding security:write and configure_security must approve through the ordinary approvals routes (see Approvals), after which the rule is applied. The act's policy row ships as DENY, so an enable above the line is refused until an organization owner relaxes that row to ask. Once your step-up is on the request it answers status: held, with its holdUntil: it waits for the second approver and the hold before anything applies. On a deployment where the two-approver path is not available the enable is refused with DUAL_CONTROL_UNAVAILABLE, and your step-up is not spent.

What an enabled rule does

  • A request rule (IP, user agent, SDK, DSN key) refuses the envelope unread, at the edge, with a 2xx status so the SDK does not retry.
  • A content rule drops the event in the worker after scrubbing and before grouping.

Neither stores, groups, alerts on or serves the record to an agent. The receipt is the drop reason block_rule (see Ingest outcomes) and the rule's own matchedTotal.

Enforcement lasts at most seven days from the enable and is renewed only by a new enable. Expiry is evaluated when the rule is read, never by a sweep, so a stopped worker cannot make a block last longer.

Reading rules and attack summaries

The same data is reachable by a person on the REST routes and by an agent through tools.

What Person (REST) Agent (MCP tool)
Rules of a project, with mode, expiry and would-match counts GET /orgs/:org/projects/:project/block-rules attack_summary_get with include: ["block_rules"]
What the threat classifier found, as counts GET /orgs/:org/projects/:project/attack-summary?days=1..30 attack_summary_get
Create or disable a rule none (the dashboard uses the governed path) block_rules_update
Enable a rule the two routes above none

The attack summary reports counts by category, by rule and field, by targeted endpoint, by source class and, per issue, by review state. Sources are keyed prefix buckets and user-agent families, never an address. Reads need read_security on the project (security:read).

Endpoints, rule names and matchers are untrusted text. An attacker chose the path they probed and the user agent they sent. A person's read on the REST routes carries them as they came and says which fields those are in a trust.untrustedFields note. The agent tool scrubs them and scans them for injection, and the result's trust block lists the same paths. Treat both as data, never as instructions.

The two REST reads refuse an agent, a service, an OAuth client and a delegated token with PERSON_ONLY_READ: an agent reads through the tool, where the fence is.

Scopes and the review hold

Every MCP toolset is open on this deployment: the SG-059 holds were lifted by owner decision on 2026-11-16. No security review of the OAuth authorization server is recorded behind that decision. The rule above does not depend on it: enabling a block rule is human-only by relation, not by a hold.