Entity List Filter

entity-list-filter blocks requests that name a party from your own list, such as a denied or sanctioned company. You supply the full names and any aliases that must also match.

The gateway does not download or update a restricted-party database. With an empty list, the control blocks nothing.

Configuration

policy-config.yaml

pack:
  name: entity-list-filter-example
  version: 1.0.0
  enabled: true
policies:
  chain:
    - entity-list-filter
policy:
  entity-list-filter:
    blocked_entities:
      - Example Restricted Entity
      - Northwind Export Group
      - Contoso Research Holdings
    fuzzy_matching: false

These names are fictional. Replace them with your organization's approved list before rollout.

Verify your list

Add a test for a listed name and one for a normal prompt:

Add to policy-config.yaml

testing:
  suites:
    - name: entity-list-filter
      cases:
        - name: blocks-listed-name
          input: {messages: [{role: user, content: "Summarize Example Restricted Entity"}]}
          expected: {verdict: block, reason_code: entity_list.triggered}
        - name: allows-unlisted-prompt
          input: {messages: [{role: user, content: "Summarize our supplier onboarding guide"}]}
          expected: {verdict: allow, reason_code: ok}

Run verdictan policy test --json. Both pass. Before you turn on fuzzy matching, add tests with spelling variations and ordinary words that look like your names. Through a gateway, the matched name is in the nested result of the runtime event.

Fields

Field	Type	Default	Description
blocked_entities	list of strings	[]	Names to match. Empty or missing allows every request.
action	block	block	Lint accepts only block. The runtime ignores the field and always blocks a match.
fuzzy_matching	boolean	false	Also matches word windows within max_distance edits of a name
max_distance	integer	1	Maximum Levenshtein distance, from 0 to 8

How it works

1. The gateway joins the request messages into one lowercase string.
2. With an empty list, the control allows with entity_list.no_entities_configured and a warning in the details.
3. Each name must match a whole word or phrase. Case does not matter.
4. If none matched and fuzzy_matching is on, each name is compared with word windows of the same length, within max_distance.
5. A match blocks with entity_list.triggered. Otherwise, the request is allowed with entity_list.clean.

The details contain matched (the first matching name), fuzzy_matching, and max_distance.

Phase and verdicts

Item	Value
Phase	input, plus an output check on streamed and buffered responses
Request families	Chat Completions, Completions, Responses, Messages
Verdicts	allow, block
Reason codes	entity_list.clean, entity_list.triggered, entity_list.no_entities_configured

Examples

With the two export control term filters:

policy-config.yaml

pack:
  name: export-control
  version: 1.0.0
  enabled: true
policies:
  chain:
    - entity-list-filter
    - dual-use-filter
    - itar-ear-filter
policy:
  entity-list-filter:
    blocked_entities:
      - replace-with-denied-party-name
  dual-use-filter: {}
  itar-ear-filter: {}

Limits and failure behavior

• A block returns HTTP 400 with error code content_policy_violation, and the provider never gets the request.
• With an empty list, every request passes with entity_list.no_entities_configured. Search decision events for this code to find chains without a list.
• The gateway also checks the response on Chat Completions, Responses, and Messages, with exact matching only, and blocks on a match. A buffered block returns HTTP 400. A streamed block ends the stream with an error event.
• A streamed response is not buffered. The gateway sends the text while it arrives. With gateway 0.1.26 or later, it holds back the text that can be the start of a listed name. Thus no part of a matched name gets to the client. See Output blocks in a stream.
• With max_distance: 2, a short name matches many unrelated words. Use full names and start with 1.
• Aliases, transliterations, and registration numbers match only if you list them.
• The runtime event records the match. Trail records configuration changes. audit-logger only adds a marker.

Next steps

• Dual-Use Filter: dual-use terms.
• ITAR/EAR Filter: export control terms.
• Investigate a Blocked Request: find the matched name.