In Rails 8.1, how do config.filter_parameters and filter_attributes keep a card number out of the logs, and what still leaks?
answer
- filter_parameter_logging.rb initializer
- case-insensitive partial match
- card_number is not in the default list
- Base.filter_attributes, inspect, SQL binds
- your own interpolated log lines
basics
~20 sAdd the key to config.filter_parameters, for example :card_number, which the default list does not cover. Rails then logs [FILTERED] in the Parameters line, the query string, record inspect output and SQL binds. Values you interpolate into your own log lines still leak.
solid answer
~30 sThe generated `config/initializers/filter_parameter_logging.rb` adds `:passw, :email, :secret, :token, :_key, :crypt, :salt, :certificate, :otp, :ssn, :cvv, :cvc` to `config.filter_parameters`. Symbols and strings match **any key containing them**, case-insensitively, so `:passw` also catches `password_confirmation`. Nothing there matches `card_number`, so you add it. Rails applies the list to the `Parameters:` line, to query strings in `Started`, and through `ActiveRecord::Base.filter_attributes` to `#inspect` and to SQL bind values. In 8.1, `self.filter_attributes += [:card_number]` on `Order` also adds `"order.card_number"` to `filter_parameters`. What still leaks: strings you build yourself, such as `logger.info("charging #{params[:card_number]}")`, exception messages, values interpolated into SQL text, and job arguments unless `log_arguments` is false.
go deeper
Recall the initializer, the [FILTERED] marker, and that you must add your own sensitive keys such as card_number.
Explain substring versus Regexp matching, the four places Rails applies the filter, and how filter_attributes ties records and SQL binds in.
Audit every path a secret can take into logs, including your own interpolations, exceptions, SQL text and job arguments, and back it with a test.
Decide whether raw secrets should ever reach the app, for example tokenised payments, so log filtering is defence in depth, not the control.
## The list and how it matches `config.filter_parameters` is an array of filters that Rails compiles into an **`ActiveSupport::ParameterFilter`**. Any value whose key matches is replaced with `"[FILTERED]"`. A new Rails 8.1 app writes this initializer: ```ruby # config/initializers/filter_parameter_logging.rb (generated) Rails.application.config.filter_parameters += [ :passw, :email, :secret, :token, :_key, :crypt, :salt, :certificate, :otp, :ssn, :cvv, :cvc ] ``` Four kinds of filter are accepted: | Filter | Matches | Example | |---|---|---| | Symbol or String | Any key **containing** it, case-insensitive | `:token` filters `payment_token` | | Regexp | Keys the pattern matches, case-sensitive unless `/i` | `/\Acard_number\z/` filters only that key | | Dotted string | A nested key path containing it | `"order.card_number"` | | Proc | Called with each key and value. It may mutate the value | mask all but the last four digits | Partial matching is generous on purpose: `:passw` catches `password` and `password_confirmation`. It also over-filters. `:otp` matches `footprint`, and `:_key` matches every `*_key` field. Use a Regexp when you need an exact key. For an electronics store, the trap is the list itself. `:cvv` and `:cvc` are there, but **nothing matches `card_number`**. A checkout posting `order[card_number]` writes the full number into the `Parameters:` line until you add `:card_number`, or a pattern such as `/card_?num/`. ## Where Rails applies it 1. **`Parameters:` line.** Action Controller logs `request.filtered_parameters`, never the raw params. 2. **`Started` line.** It logs `request.filtered_path`, so a matching GET parameter shows as `?token=[FILTERED]`. 3. **Record inspection.** The Active Record railtie runs `ActiveRecord::Base.filter_attributes += config.filter_parameters`, so `order.inspect` shows `card_number: [FILTERED]`. This matters in consoles, error pages and exception messages that inspect records. 4. **SQL binds at debug level.** When Active Record logs a statement, it passes each bind value through `ActiveRecord::Base`'s inspection filter, so a bound value whose column name matches the list prints as `[FILTERED]`. A model can add its own: `self.filter_attributes += [:card_number]` on `Order` masks that column in `Order#inspect`. **New in Rails 8.1.0**, such per-model declarations are also added to `config.filter_parameters` in the dotted form `"order.card_number"`, so the nested request param is filtered too. Before 8.1, a model's own `filter_attributes` never flowed into `filter_parameters`. Neither version feeds it into SQL bind logging, which uses `ActiveRecord::Base`'s list, so the global initializer remains the safer place for a key. ## What still leaks The filter works on **keys** in hashes Rails knows about. It cannot see: - **Strings you build.** `Rails.logger.info("charging #{params[:order][:card_number]}")` writes the number. The filter never sees a key. - **SQL text.** A value interpolated into a SQL fragment is part of the statement, not a bind, so nothing masks it. - **Exception messages.** A gateway error such as `"card 4111... declined"` is logged with its message intact. - **Job arguments.** Active Job logs a job's arguments on enqueue and perform unless the job sets `self.log_arguments = false`. `filter_parameters` does not apply there. - **Other clients.** An HTTP library that logs request bodies writes them with its own logger, unfiltered. Filtering also does nothing for storage. The number still reaches your database if you save it. Most stores never accept a raw card number at all: the payment provider's form returns a token, and a key such as `payment_token` is already caught by `:token`. ## Configuring it well - **Keep additions in the initializer.** Rails reads `config.filter_parameters` when it builds the request environment at boot and, with `precompile_filter_parameters` (on since `load_defaults 7.1`), compiles it into a few regexps. Appending to it from a controller at runtime does nothing. - **Name your own fields.** Audit your forms and API payloads for card, bank, address or identity fields and add each key, or an anchored Regexp, that the defaults miss. - **Mind redirects.** The `Redirected to` line uses a separate list, `config.filter_redirect`. A matching URL is replaced with `[FILTERED]` as a whole. Otherwise only its query parameters go through `filter_parameters`. - **Test it.** A filter list is configuration, so a regression test is the only thing that notices when someone renames `card_number` to `pan`. ## Checking that it works ```ruby # test/integration/checkout_logging_test.rb test "card number never reaches the log" do io = StringIO.new Rails.logger.broadcast_to(sink = ActiveSupport::Logger.new(io)) post checkouts_path, params: { order: { card_number: "4111111111111111" } } assert_no_match "4111111111111111", io.string ensure Rails.logger.stop_broadcasting_to(sink) end ``` ## Takeaway Treat `filter_parameters` as a list you own, not a finished default. Add every sensitive key your forms use, prefer exact Regexps where substrings over-filter, and remember that it masks keys in Rails' own output only. A secret you interpolate into a message is logged in full.
- Why might `config.filter_parameters += [:otp]` hide a field called `carbon_footprint`?Symbol and string filters are compiled into case-insensitive substring matches, and `footprint` contains `otp`. Rails replaces the value with `[FILTERED]` even though it is harmless. Over-filtering costs only diagnosability, but when it matters, use an anchored Regexp such as `/\Aotp\z/` or `/\Aotp_/`.
- A job receives the order's card number as an argument. Does filter_parameters hide it in the job logs?No. Active Job logs arguments through its own log subscriber, and `filter_parameters` is not applied there. Set `self.log_arguments = false` in that job class, or `config.active_job.log_arguments = false` app-wide. Better, pass the `Order` record, which is logged as its GlobalID, and never put the number in a job at all.
- Why does `Order.first.inspect` show card_number: [FILTERED] in a console?At load, the Active Record railtie appends `config.filter_parameters` to `ActiveRecord::Base.filter_attributes`, and `#inspect` masks those attributes. A model's own `self.filter_attributes += [...]` adds to that list. In Rails 8.1 that per-model list is also added to `filter_parameters` as `model.attribute`.
- The default filter list already covers card numbers through :cvv and :cvc.
- A symbol in filter_parameters matches only a key with exactly that name.
- filter_parameters also masks values interpolated into Rails.logger.info strings.
- Filtered parameters are also masked before Active Record writes them to the database.
- filter_attributes encrypts the column, so it replaces the encrypts macro.
- Active Job arguments are filtered by filter_parameters like controller params.
Assumes Rails 8.1: since 8.1.0 a model's own filter_attributes entries are also added to config.filter_parameters as model.attribute; earlier versions did not copy them there.