fix(model_armor): restore reference attachments via skip_unscannable_attachments and remove the attachment count cap

[devin-ai-integration]

Relevant issues

Fixes #33535

Linear ticket

Resolves LIT-4490

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Screenshots / Proof of Fix

Live proxy, both runs at commit d66392662a, guardrail mode: pre_call, default_on: true. The request carries a single gs:// attachment reference with no inline bytes (the pattern Vertex AI docs recommend).

Before (skip_unscannable_attachments: false, the v1.92.0 default), the guardrail fails closed:

$ curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
  -d '{"model":"demo-model","messages":[{"role":"user","content":[{"type":"file","file":{"file_data":"gs://my-bucket/report.pdf","filename":"report.pdf"}}]}]}'
HTTP 400
# body: Model Armor could not scan an attachment and blocked the request: 1 attachment(s)
#       reference a document with no inline bytes (file_id or remote URL) that Model Armor cannot scan

After (skip_unscannable_attachments: true), the same request clears the guardrail and reaches the provider; the 400 now comes from Anthropic (it cannot fetch a gs:// url), not from Model Armor, which is proof the guardrail let the reference through:

$ curl ... (identical request)
HTTP 400
# body: litellm.BadRequestError: AnthropicException - Image url not in expected format ...
#       Received Messages=[{'role': 'user', 'content': [{'type': 'file', 'file': {'file_data': 'gs://my-bucket/report.pdf', ...}}]}]

Real Model Armor API errors (network, quota, bad template) still fail closed under the default fail_on_error: true when skip_unscannable_attachments is on; the flag only affects attachments there is nothing to send. This is covered by test_skip_unscannable_still_fails_closed_on_api_error, which cannot be reproduced against a live proxy here without Google Cloud Model Armor credentials.

The attachment-cap removal is covered by the regression test below; every attachment now goes straight to the byte scan, so a live capture needs a reachable Model Armor template.

Type

🐛 Bug Fix

Changes

v1.92.0 (#31655) added attachment scanning to the Model Armor guardrail. It fails closed on anything it cannot scan, which turned three request shapes that worked on v1.91.x into HTTP 400s: reference-only attachments (file_id, gs://, http(s)://), documents over the 4 MB byte limit, and requests carrying more than 10 attachments. The only workaround was fail_on_error: false, which also fails open on genuine Model Armor API errors; a different policy than "let these specific unscannable cases through".

This PR handles the reference case, removes the attachment cap, and deliberately leaves oversize fail-closed.

First, skip_unscannable_attachments (default false, so behavior is unchanged unless opted in). When enabled, attachments with no inline bytes for Model Armor to scan (references, and inline base64 that will not decode) pass through unscanned instead of blocking, while fail_on_error keeps governing real API errors:

skip_unscannable = bool(self.optional_params.get("skip_unscannable_attachments", False))
unscannable_references = 0 if skip_unscannable else plan.unscannable_count
if not attachments and unscannable_references == 0:
    return

Second, the per-request attachment count cap is removed entirely. It was introduced in this same feature (#31655), not pre-existing, and it was never a scannability limit; every attachment past the old limit of 10 was individually scannable, so blocking (or, under fail_on_error: false, silently truncating to the first 10 and dropping the rest) was an arbitrary fan-out bound that turned a legitimate 12-document request into a 400 or a scanning bypass. Now every attachment is scanned, with no count ceiling:

for attachment in attachments:
    ...  # scan every attachment; no count cap

skip_unscannable_attachments is threaded through LitellmParams and initialize_guardrail:

guardrails:
  - guardrail_name: "model-armor"
    litellm_params:
      guardrail: model_armor
      mode: "pre_call"
      template_id: "..."
      skip_unscannable_attachments: true

Oversize documents (over 4 MB) stay fail-closed by default and are not covered by skip_unscannable_attachments: unlike a reference, an oversize document carries real bytes you likely want blocked rather than forwarded unscanned. Operators who want it through still have fail_on_error: false.

Docs updated in a companion PR on BerriAI/litellm-docs.

New regression test in tests/test_litellm/proxy/guardrails/guardrail_hooks/test_model_armor.py:

• test_pre_call_scans_every_attachment_without_a_count_cap - a batch of 25 attachments is fully scanned, with every attachment submitted to Model Armor and none dropped

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

Link to Devin session: https://app.devin.ai/sessions/2a1e5e4797394ff79c4d8d6a9513d2f0
Requested by: @yucheng-berri

---

Note

Medium Risk
Opt-in skip_unscannable_attachments lets unscanned attachment references reach the model, which is a deliberate security tradeoff; removing the attachment cap increases per-request Model Armor fan-out and latency.

Overview
Restores workflows that send reference-only attachments (file_id, gs://, http(s)://) without inline bytes, which the Model Armor guardrail started blocking after attachment scanning landed.

Adds skip_unscannable_attachments (default false) on LitellmParams, wired through initialize_guardrail into _scan_request_files. When enabled, unscannable references (and bad base64) pass through instead of failing closed; fail_on_error still applies to real Model Armor API failures.

Removes the per-request MAX_FILE_ATTACHMENTS_PER_REQUEST (10) cap so every scannable inline attachment is submitted—no block or silent truncation at 10.

Oversize files (>4 MB) and default blocking behavior for unscannable refs are unchanged unless operators opt in via the new flag or fail_on_error: false.

^{Reviewed by Cursor Bugbot for commit 043f990. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[greptile-apps]

Greptile Summary

This PR fixes two regressions introduced by the Model Armor file-scanning feature in v1.92.0: reference-only attachments (file_id, gs://, http(s)://) were unconditionally blocked even though they carry no bytes for Model Armor to inspect, and a hard 10-attachment-per-request cap was silently truncating or blocking otherwise-valid requests.

• Adds skip_unscannable_attachments (default false, opt-in) to BaseLitellmParams and threads it through initialize_guardrail into ModelArmorGuardrail.optional_params; when enabled, reference-only attachments pass through while fail_on_error continues to govern real API errors.
• Removes MAX_FILE_ATTACHMENTS_PER_REQUEST entirely — every scannable attachment is now submitted to Model Armor, with no count ceiling; oversize (>4 MB) attachments remain fail-closed by default.
• Six new mocked unit tests cover the passthrough path, the secure-by-default path, the mixed-content path (text still scanned alongside reference files), API errors still failing closed under skip_unscannable_attachments=true, and full 25-attachment scanning.

Confidence Score: 5/5

Safe to merge — the new flag defaults to false so existing deployments are unaffected, and removing the attachment cap only expands what was previously blocked or silently truncated.

The logic change is well-contained inside _scan_request_files. The skip_unscannable_attachments flag is read from optional_params consistently with how fail_on_error is already read, the default is the secure (blocking) value, and the mixed scannable/unscannable case correctly scans what it can while allowing references through. The cap removal is straightforward: sequential per-attachment scans with no artificial ceiling, error isolation per attachment already in place. All six new tests are fully mocked and cover the meaningful edge cases.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/types/guardrails.py	Adds skip_unscannable_attachments: Optional[bool] to BaseLitellmParams with a secure default of False; field is inherited by LitellmParams via existing MRO.
litellm/proxy/guardrails/guardrail_hooks/model_armor/init.py	Threads skip_unscannable_attachments from LitellmParams into ModelArmorGuardrail constructor; plumbing is correct and mirrors how fail_on_error is already passed.
litellm/proxy/guardrails/guardrail_hooks/model_armor/file_scanning.py	Removes MAX_FILE_ATTACHMENTS_PER_REQUEST constant; no other logic changes — the constant was only consumed by model_armor.py.
litellm/proxy/guardrails/guardrail_hooks/model_armor/model_armor.py	Implements skip_unscannable_attachments logic in _scan_request_files and removes the 10-attachment cap; edge cases (mixed scannable/unscannable, API errors still failing closed) are handled correctly.
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_model_armor.py	Replaces the old cap-enforcement test with six new mocked tests covering: file_id passthrough, gs:// passthrough, config threading defaults, API-error still failing closed, and 25-attachment uncapped scan; all tests use mocks only.

_{Reviews (2): Last reviewed commit: "fix(model_armor): remove the per-request..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_model_armor_skip_unscannable (67ce1b3) with litellm_internal_staging (fba7ac4)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (03e7dc4) during the generation of this report, so fba7ac4 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[CLAassistant]

All committers have signed the CLA.

[devin-ai-integration]

Live proxy test — configurable max_file_attachments cap

Ran a local proxy with three model_armor guardrails differing only in max_file_attachments, selected per request via the guardrails body field, sending inline-PDF attachment batches with curl. No GCP credentials needed: the over-cap block path raises before Model Armor is contacted. Commit 7fd76e5ac4.

Config: ma-cap2 -> max_file_attachments: 2, ma-cap5 -> 5, ma-default -> unset (default 10)

Test 1 - lowered cap (2) blocks 3 attachments; message reflects the configured value

$ curl .../v1/chat/completions -d '{"model":"demo-model","guardrails":["ma-cap2"],"messages":[{"role":"user","content":[<3 inline PDFs>]}]}'
HTTP 400
{"error":{"message":"Model Armor could not scan an attachment and blocked the request: 3 attachments exceed the per-request scan limit of 2", ... "guardrail_name":"ma-cap2"}}

Test 2 - raised cap (5) lets the same 3 attachments past the cap gate (500 ADC = reached scan stage, not dropped)

$ curl ... "guardrails":["ma-cap5"] , 3 attachments
HTTP 500
{"error":{"message":"Your default credentials were not found. To set up Application Default Credentials ..."}}

Test 3 - default cap is 10: 11 attachments block with "of 10" (not the old silent truncate-and-scan)

$ curl ... "guardrails":["ma-default"] , 11 attachments
HTTP 400
{"error":{"message":"Model Armor could not scan an attachment and blocked the request: 11 attachments exceed the per-request scan limit of 10", ... "guardrail_name":"ma-default"}}

Test 4 - 3 attachments under the default cap pass the gate (500 ADC)

$ curl ... "guardrails":["ma-default"] , 3 attachments
HTTP 500
{"error":{"message":"Your default credentials were not found. To set up Application Default Credentials ..."}}

The cap value in the block message tracks config (2 vs 10) and the same attachment count flips between block and pass as the cap changes, so a hardcoded cap or the old silent-truncate path would produce visibly different output.

Not covered live: the fail_on_error: false "scan every overflow attachment instead of dropping" path needs a reachable Model Armor template; it is covered by test_over_cap_scans_all_attachments_when_fail_open.

Devin session: https://app.devin.ai/sessions/2a1e5e4797394ff79c4d8d6a9513d2f0

[devin-ai-integration]

Update after review discussion: the earlier max_file_attachments approach was dropped. The 10-attachment cap was itself introduced in #31655 (not pre-existing) and was never a scannability limit, so rather than making it configurable this PR removes the cap entirely; every attachment is now scanned, with no count ceiling. The live-cap test comment above is therefore historical. Latest commit: 043f990.

@greptileai please re-review.

[yucheng-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 043f990. Configure here.}

[devin-ai-integration]

Live verification (real Model Armor + real Gemini)

Adding end-to-end proof captured after merge, on branch head 67ce1b3934, against a real Model Armor template (RAI filters at HIGH plus PI/jailbreak) and a real gemini/gemini-2.5-flash deployment; no mocks. Two guardrails on the same template: ma-default (fail_on_error: true) and ma-skip (fail_on_error: true, skip_unscannable_attachments: true).

Reference regression and fix. A request whose only attachment is a document reference with no inline bytes (a real public https:// PDF here; gs:// and file_id behave identically) is blocked by default and passes once the flag is on, reaching the real provider:

# ma-default (v1.92.0 default): reference blocked
$ curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
  -d '{"model":"demo-model","metadata":{"guardrails":["ma-default"]},
       "messages":[{"role":"user","content":[
         {"type":"text","text":"In one sentence, what is this document?"},
         {"type":"file","file":{"file_id":"https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf","format":"application/pdf"}}]}]}'
HTTP 400
# body: Model Armor could not scan an attachment and blocked the request: 1 attachment(s)
#       reference a document with no inline bytes (file_id or remote URL) that Model Armor cannot scan

# ma-skip (identical request, skip_unscannable_attachments: true): reference passes, real Gemini answers
$ curl ...  metadata.guardrails=["ma-skip"] ... (identical body otherwise)
HTTP 200
# body: {"choices":[{"message":{"content":"This document is a placeholder PDF file, as indicated by its content \"Dummy PDF file.\""}}], ...}
# proxy log: Model Armor: allowing 1 unscannable attachment(s) through because skip_unscannable_attachments is enabled

Inline content is still scanned by the real Model Armor API. A benign inline PDF passes and reaches the model; an inline PDF whose text asks for bomb-making instructions is blocked, and it stays blocked even with skip_unscannable_attachments: true, so the flag only affects references with no bytes and never weakens scanning of real content:

# ma-default + inline benign PDF -> scanned, passes
HTTP 200  {"choices":[{"message":{"content":"This quarterly sales report indicates a 10% revenue growth ..."}}], ...}

# ma-default + inline harmful PDF -> blocked by real Model Armor
HTTP 400  {"error":{"message":"Content blocked by Model Armor","model_armor_response":{"sanitizationResult":{"filterMatchState":"MATCH_FOUND","filterResults":{"rai":{"raiFilterResult":{"raiFilterTypeResults":{"dangerous":{"confidenceLevel":"HIGH","matchState":"MATCH_FOUND"}}}}}}}}}

# ma-skip + inline harmful PDF -> still blocked (flag does not bypass real scanning)
HTTP 400  {"error":{"message":"Content blocked by Model Armor", ... "dangerous":{"confidenceLevel":"HIGH","matchState":"MATCH_FOUND"} ...}}

Genuine Model Armor API errors still fail closed when the flag is on. Pointing a skip_unscannable_attachments: true guardrail at a nonexistent template makes the real API return an error, and an inline (scannable) PDF is blocked rather than forwarded, so the flag decouples reference handling from fail_on_error without opening real errors:

# ma-skip pointed at a missing template + inline benign PDF
HTTP 400
# body: The template named 'projects/.../locations/us-west1/templates/does-not-exist-template' was not found ... INVALID_ARGUMENT

Oversize documents stay fail-closed and are not covered by the flag. A 5 MB inline PDF (over Model Armor's 4 MB byte limit) is blocked on both guardrails:

# ma-default + 5MB PDF   -> HTTP 400  attachment of 5243489 bytes exceeds Model Armor's 4194304 byte scan limit
# ma-skip    + 5MB PDF   -> HTTP 400  (same; skip_unscannable_attachments does not cover oversize)

Non-PDF document types go through the same real scan. A harmful .docx is blocked on both ma-default and ma-skip with dangerous: HIGH, MATCH_FOUND. The attachment-cap removal is covered by test_pre_call_scans_every_attachment_without_a_count_cap, and the full unit suite is green (80 passed)