# 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](security-findings.md); the shared scope table is in [Security scope](security-scope.md).

## 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](approvals.md)), 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](ingest-outcomes.md)) 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.

## Related

- [Security findings](security-findings.md), including the daily [security sweep](security-findings.md#security-sweep)
- [Security scope](security-scope.md)
- [Ingest outcomes](ingest-outcomes.md)
- [Governed actions](actions.md), the registry that lists `block_rule.enable` as human-only
- [MCP tools](mcp-tools.md), for the scope and toolset of each tool named here
