DICT: token bucket against Pix key scanning

01 · CONTEXT

When querying is the attack

The DICT, the Directory of Transactional Account Identifiers, is the base of Pix keys. The Central Bank is the maintainer of the database, and the participants, with direct or indirect access, are the requesters of the queries.

1. The diagram shows the user, the participant's app, and the DICT.

2. Participants query the DICT as requesters, while the Central Bank maintains the database.

3. A scan attack can come from a user or from an intruder using the participant's infrastructure.

The regulation defines a scan attack as the capture of existing links in the DICT for purposes other than making payments. It can be fast and intense, within a few hours, or slow, over days or months.

To contain this abuse, the DICT limits Pix key queries based on two indicators: queries without a payment order and invalid queries, that is, queries made for keys not registered in the DICT.

02 · THE TOKEN BUCKET

How the DICT counts queries

The limiting mechanism uses the Token Bucket algorithm. To count, the participant states in the PI-PayerId header who originates the query, and all queries from the same end user through that participant carry the same identifier. This way, the DICT controls queries both per end user and per participant.

1. The DICT controls queries per end user and per participant, each with its own bucket.

2. Each valid key query takes one token from the bucket.

3. Each invalid query, to an unregistered key, takes twenty tokens from the user's bucket.

4. For the participant, a valid query takes one token and an invalid one takes three.

5. After the SPI receives the payment order, the bucket gets tokens back per key query.

6. With an empty bucket, the query gets a rate-limit error, HTTP code 429, and is blocked until tokens are replenished.

03 · PUBLISHED PARAMETERS

Individual, legal entity, and participant

For the individual, the bucket for queries by mobile phone or e-mail has a maximum size of one hundred tokens, and the bucket size for queries by CPF, CNPJ, or random key is defined separately. In each bucket, a valid query takes one token and an invalid one takes twenty.

For the participant, the maximum bucket size and the per-minute increment depend on the category. The Central Bank places each participant in one of the categories, from A to H. Each valid query takes one token from the participant's bucket and each invalid one takes three.

04 · THE REGULATION'S EXAMPLE

When an invalid query creates debt

When the bucket is already empty, the requester receives the rate-limit error, with HTTP code 429, and cannot query until tokens are replenished. The manual itself includes a worked example for the individual.

1. The individual in the example has only five tokens in the bucket and makes one query.

2. The queried key is not registered: the DICT responds NOT FOUND, HTTP code 404, with a penalty of twenty tokens.

3. The bucket now has a debt balance of fifteen tokens.

4. New queries will only succeed after eight minutes, with replenishment of two tokens per minute.

The example makes the cost asymmetry visible: a valid query costs one token and an invalid one costs twenty.

05 · DEFENSE IN LAYERS

What the participant does before the DICT says no

The regulation requires that each participant have an internal query-limiting policy equal to or stricter than the DICT's Token Bucket. This policy is an earlier layer of protection, which limits excessive sending of requests, and the control can sit in the application or in the infrastructure.

1. The diagram shows the query path at the participant: internal limiting, cache, checkKeys, DICT, and monitoring.

2. The participant's internal policy is equal to or stricter than the DICT's bucket.

3. The participant does not forward to the DICT a query that would exceed the user's or the participant's limit, which prevents the rate-limit error.

4. Queries to legal-entity keys may have the response cached, for at most one hundred eighty seconds, to reduce the load on the DICT.

5. It is suggested to use checkKeys to confirm that keys exist before the requests, which avoids large numbers of invalid queries.

6. Monitoring tracks users' requests, and once well-founded suspicion of misuse is verified, the participant must block the user immediately.

Monitoring has two ratios. The first compares queries to the DICT with orders sent to the SPI: a value slightly above one is expected, and values close to two or greater are typically indicative of an anomaly, although the threshold may vary. The second compares unregistered keys with found keys, and the regulation notes that this relationship is affected by the user journey and behavior.

The regulation usually gives references for suspicion: percentages of unregistered keys above seven percent for the participant and above twenty percent for users who have made at least one hundred queries in the last twenty-four hours.

06 · READINGS FOR THE DESIGN

What to take into an interview

Three ideas sum up the case. The cost of a query depends on its result, since an invalid one costs much more than a valid one. The token credit depends on payment, since the order received by the SPI returns tokens to the bucket. And the defense has layers, because the participant limits before the DICT does.