2026-10-24 04:38:50 +02:00
# Armor - Specification
Owned directory: `src/google/armor/` . Namespace `molo::google::armor` .
Depends on the foundation in `src/google/` (`GoogleClient` , `Service` ,
`GoogleError` , `CloudContext` , `endpoints::custom` , `LanguageModel` ). No other
module.
## 1. Scope
- Model Armor: templates (create, get, list, patch, delete), floor settings
(get, update; project, folder, organization), locations (list, get),
`sanitizeUserPrompt` , `sanitizeModelResponse` with typed filter results
(prompt injection and jailbreak, sensitive data, malicious URIs,
responsible AI, CSAM, virus scan).
- Agent Threat Detection and Agent Anomaly Detection: they have NO API of
their own. They publish findings to Security Command Center. Read-only
access here is `SecurityFindings` over Security Command Center v2
(`findings.list` , `findings:group` , `sources.list` , `sources.get` ). The
Finding resource carries typed `agent` , `agentAnomaly` , `agentSessions` ,
`agentDataAccessEvents` , `aiModel` and `vulnerability` members, which are
read into `Finding` .
2026-10-24 05:43:13 +02:00
- Security Command Center administration, `SecurityAdmin` (every v2 method
except the attack exposure engine): mute configs, notification configs and
BigQuery exports (list, get, create, patch, delete), finding state, mute,
patch, security marks, create, external systems, bulk mute, findings export,
sources create/patch and source IAM, asset security marks, organization
operations (get, list, cancel, delete). Attack paths, valued resources,
simulations and resource value configs are excluded on purpose: they are
cloud posture risk scoring, not agent security (`EXCLUDED_RE` in
`tools/check_discovery.py` ).
- Agent Threat Detection categories: `AgentCategories` holds the documented
category strings (runtime detectors and control plane detectors) with module
names. Agent Anomaly Detection has no documented category string: its
findings are the ones with the typed `agentAnomaly` member.
2026-10-24 04:38:50 +02:00
- Agent Security dashboard: a console product with no dashboard API.
`AgentSecurityDashboard` is a LOCAL abstraction that aggregates listed
findings (counts by severity, category, class, state, per-asset worst
severity). Agent assets are matched by the resource name fragment
`reasoningEngines` (local convention, see Unverified).
- Asset discovery: Security Command Center v2 has no assets list method
(Discovery: only `assets.updateSecurityMarks` ). `discovered_assets()` is
local: distinct resources that carry findings.
- `GuardedModel : LanguageModel` : sanitizes the prompt before and the response
after any wrapped `LanguageModel` ; throws `BlockedError` .
Authentication: Model Armor and Security Command Center REQUIRE an OAuth2
access token (`GOOGLE_ACCESS_TOKEN` , scope `cloud-platform` ). API keys,
including express keys, are refused (see Verified live). Required project
env: `GOOGLE_CLOUD_PROJECT` , optional `GOOGLE_CLOUD_LOCATION` .
## 2. Module map
| File | Concern |
|---|---|
| `caps.h` | Static ceilings (`ArmorCaps` ) |
2026-10-24 05:43:13 +02:00
| `calls.h/.cpp` | The ONE table of declared calls (144 rows: rpc, verb, path, query, request schema, allowed body fields), schemas, enums; path matcher |
| `scc_name.h/.cpp` | `SccName` : a validated SCC resource name; derives the table row (scope, `locations` , `sources` ) from the name |
| `security_admin.h/.cpp` | `SecurityAdmin : Service` : every SCC v2 administration method, `SccList` , `SccAvailability` probe |
| `agent_categories.h/.cpp` | `AgentCategories` : documented Agent Platform Threat Detection categories and module names |
2026-10-24 04:38:50 +02:00
| `tools/check_discovery.py` | Fails when `calls.h` and Google's Discovery documents disagree |
| `armor_types.h/.cpp` | `SanitizationResult` , `FilterOutcome` , enums |
| `template.h/.cpp` | `Template` , `FilterConfig` , `TemplateMetadata` , `FloorSetting` , rule sets |
| `model_armor.h/.cpp` | `ModelArmor : Service` , `DataItem` , `LanguageHint` |
| `armor_util.h/.cpp` | `query_escape` , `join_update_mask` , `valid_scope` , `valid_request_id` |
| `findings.h/.cpp` | `SecurityFindings : Service` , `Finding` , `FindingQuery` |
| `dashboard.h/.cpp` | `AgentSecurityDashboard` (local aggregation) |
| `guarded_model.h/.cpp` | `Sanitizer` seam, `ModelArmorSanitizer` , `GuardedModel` , `BlockedError` |
## 3. Static caps (see caps.h)
| Knob | Value |
|---|---|
| Text per sanitize call | 100000 characters |
| File bytes per sanitize call | 5 MiB (our ceiling) |
| Stream buffer (guarded) | 200000 characters, 4096 chunks |
| Template page size / pages followed | 100 / 10 |
| Rai filters, rule sets, rules per set, words per rule, regex | 4, 16, 64, 1000, 1024 chars |
| Labels per template | 64 (63 chars each) |
| Update mask paths | 16 |
| Detail strings per filter result | 50 |
2026-10-24 05:43:13 +02:00
| Findings page size (Google max) / pages / results | 1000 / 10 / 5000; config and operation lists use 100 / 10 / 5000 and report `truncated` |
| Categories in a filter | 100 (all documented agent categories fit) |
2026-10-24 04:38:50 +02:00
| Dashboard distinct assets | 500 |
## 4. Contracts
- Every id, scope, mask, filter value, order_by, enum string and size is
validated before any network traffic (`GoogleError::invalid` , HTTP 400
`INVALID_ARGUMENT` ). No credential: `NotConfiguredError` (503) before the
network.
- Hosts: `https://modelarmor.{location}.rep.googleapis.com/v1` for templates,
sanitize and floor settings; floor settings and locations also accept
`global` (`https://modelarmor.googleapis.com/v1` ); templates and sanitize
reject `global` . Security Command Center: `https://securitycenter.googleapis.com/v2` .
- Destructive: `delete_template` is an explicit method; the demo route also
2026-10-24 05:43:13 +02:00
requires `confirm=delete` . `SecurityAdmin` mutations are explicit methods
(`delete_config` , `bulk_mute` , `set_finding_state` , ...), each checked
against its table row (query parameters, top-level body fields, update mask
roots) before traffic. `bulk_mute` refuses an empty filter and only mutes or
un-mutes (`MUTED` , `UNDEFINED` ); its demo route needs `confirm=bulk-mute` .
`cancel_operation` / `delete_operation` read the operation first. Floor
settings are read and written at location `global` on the global host only
(found live, see 6).
- Lists never truncate silently: findings (`FindingPage::truncated` ), config
and operation lists (`SccList::truncated` with `next_page_token` ).
- Not activated is a state, not a crash: `SecurityAdmin::availability` maps
403 API disabled, 404 on `sources` and 400 `FAILED_PRECONDITION` (SCC enabled
but not activated for the project) to `SccAvailability` .
2026-10-24 04:38:50 +02:00
- `retry ids` : `requestId` is accepted on create, patch and delete as a
non-zero UUID.
- Sanitization results are typed; an unknown or missing `invocationResult`
never counts as clean (`fully_executed()` is false).
- `GuardedModel` fails closed: a matched filter blocks (`incomplete() ==
false`); a PARTIAL or FAILURE run, or any skipped filter, also blocks
(` incomplete() == true`) unless ` GuardOptions::allow_partial`. An
unreachable sanitizer propagates its error and the model is not called
(prompt stage) or the response is not returned (response stage). Requests
with no text (only files) are counted in ` skipped_empty`, not checked.
Streaming buffers the whole stream, sanitizes the full text once, then
replays the chunks; a blocked stream delivers nothing.
- Findings: ` FindingQuery` builds an AIP-160 filter from typed fields only
(` category`, ` state`, ` severity`, ` resourceName` substring). ` findingClass`
is filtered locally because Discovery lists it for ` orderBy` only.
## 5. Verified against discovery
2026-10-24 05:43:13 +02:00
` python3 -I src/google/armor/tools/check_discovery.py` (coverage: every method of both Discovery documents is a table row except the excluded attack exposure engine) fetches
2026-10-24 04:38:50 +02:00
` https://modelarmor.googleapis.com/$discovery/rest?version=v1` and
` https://securitycenter.googleapis.com/$discovery/rest?version=v2` and checks
2026-10-24 05:43:13 +02:00
every row of ` calls.h`: 144 calls (rpc id, HTTP method, path, query
parameters, request schema, request fields), 71 schemas (every field this
module reads or writes) and 17 enum value sets. Result on 2026-10-24: ` OK:
144 calls, 71 schemas, 17 enums checked, 0 problems`. Unit tests additionally prove that every request the
2026-10-24 04:38:50 +02:00
client puts on the wire matches a declared call and only uses declared query
parameters, and that every key of every request body built here is a field of
its Discovery schema (nested schemas included).
Discovery facts that differ from the prose docs and are implemented as
Discovery states them: ` inspectOnly` and ` inspectAndBlock` on floor settings
are booleans; ` FloorSetting.googleMcpServerFloorSetting` exists; the CSAM
result member is spelled ` csamFilterFilterResult`; templates carry
` filterRuleSettings` (exclusion dictionaries and regex), custom error codes
and messages, ` filterVersionSelector`, ` modalities`, ` dataResidencyCompliant`;
` ListTemplatesResponse.unreachable` exists; create, patch and delete accept
` requestId`; the Discovery root URL lists ` us-central1` as the sample region.
## 6. Verified live
Date 2026-10-24, project from ` GOOGLE_CLOUD_PROJECT`, no resource created,
updated or deleted.
2026-10-24 05:43:13 +02:00
**Re-run after the owner enabled Model Armor and Security Command Center
(service-account token, read-only):**
| Call | Result |
|---|---|
| Model Armor ` GET https://modelarmor.us-central1.rep.googleapis.com/v1/projects/P/locations/us-central1/templates` | 200 ` {}` (no template exists) |
| ` GET https://modelarmor.googleapis.com/v1/projects/P/locations/global/floorSetting` | 200 ` {name, createTime, updateTime}` (no filterConfig: enforcement off) |
| ` GET .../locations/us-central1/floorSetting` on the regional host | 400 INVALID_ARGUMENT "Malformed name" (floor settings exist only at ` global`) |
| ` GET https://modelarmor.googleapis.com/v1/projects/P/locations?pageSize=5` | 200, a list of locations (` name`, ` locationId`) |
| ` GET https://modelarmor.us-central1.rep.googleapis.com/v1/projects/P/locations` | 403 "Read access to project denied" (list is global-host only) |
| ` GET .../locations/us-central1` on the regional host / ` .../locations/global` on the global host | 200 ` {name, locationId}` |
| ` GET .../locations/us-central1` on the global host | 403 |
| ` sanitizeUserPrompt` against an absent template id | 400 INVALID_ARGUMENT "The template named '...' was not found" (request shape accepted; absent template is 400, not 404) |
| SCC v2 ` GET projects/P/sources`, ` sources/-/findings`, ` sources/-/locations/global/findings` (also v1 sources) | 404 NOT_FOUND "Requested entity was not found." |
| SCC v2 ` GET projects/P/muteConfigs`, ` .../locations/global/muteConfigs`, ` .../locations/global/notificationConfigs`, ` .../locations/global/bigQueryExports` | 400 FAILED_PRECONDITION "Precondition check failed." |
| Cloud Resource Manager ` GET v3/projects/P` | 403 API not enabled (so the project's organization could not be read) |
Reading: the API is enabled but Security Command Center is not activated for
this project (no organization or SCC tier reachable): sources do not resolve
and every config call fails its precondition. Findings, groups, mute configs,
notification configs, exports and every ` SecurityAdmin` happy path are
therefore NOT seen live; they stay Discovery-verified. ` SecurityAdmin::availability`
reports ` not_activated` for exactly this state, and the opt-in test
` google_live_armor.oauth_token_reads_templates_and_findings` prints it.
Model Armor code fixed from these runs: floor settings now use location
` global` on the global host, ` list_locations` uses the global host,
` get_location` the location's own host.
2026-10-24 04:38:50 +02:00
| Call | Credential | Result |
|---|---|---|
| Model Armor ` templates.list` | express key (` AQ.`) | 401 UNAUTHENTICATED (API keys are not supported); ` google_live_armor.express_key_is_refused` |
| Model Armor ` templates.list` | service account OAuth token | 403 PERMISSION_DENIED: "Model Armor API has not been used in project before or it is disabled" |
| Security Command Center v2 ` findings.list` | service account OAuth token | 403 PERMISSION_DENIED: API not enabled |
| Security Command Center v2 ` sources` | express key | 401 (reported by the coordinator) |
So authentication and routing to both services work with an OAuth token; the
request shapes beyond the 403 gate, and every response parser, are NOT yet
exercised against a real reply. The opt-in test
` google_live_armor.oauth_token_reads_templates_and_findings` (` MOLO_LIVE_NET=1`,
` GOOGLE_ACCESS_TOKEN`, ` GOOGLE_CLOUD_PROJECT`; loud SKIP otherwise) is read-only
(list templates, get floor setting, list project findings, and
` sanitizeUserPrompt` only when a template already exists) and reports a
disabled API loudly. Run it once the APIs are enabled.
## 7. Sources
- Discovery documents above (authoritative for paths, methods, fields, enums).
- https://docs.cloud.google.com/security-command-center/docs/reference/model-armor/rest
- https://docs.cloud.google.com/model-armor/reference/rest/v1/ (Template,
FloorSetting, SanitizationResult, DataItem, templates.* method pages)
- https://docs.cloud.google.com/security-command-center/docs/reference/rest/v2/organizations.sources.findings/list
- https://docs.cloud.google.com/security-command-center/docs/reference/rest/v2/ListFindingsResponse
- https://docs.cloud.google.com/gemini-enterprise-agent-platform/agent-anomalies-overview
(anomaly findings are surfaced in Security Command Center)
- https://docs.cloud.google.com/security-command-center/docs/overview-threats
(Agent Platform threat findings)
## 8. Unverified
Nothing neither Discovery nor docs state:
2026-10-24 05:43:13 +02:00
- Agent Anomaly Detection category strings: neither the anomaly overview page
nor the threat pages name one. Settled by documentation reading
(2026-10-24): Agent Platform Threat Detection (runtime, Preview) and the AI
agent control plane detectors publish the category strings in
` agent_categories.cpp` (module names ` AGENT_ENGINE_*`); anomaly findings are
recognised by the typed ` agentAnomaly` member, not by category. The pages
disagree on a few spellings (CloudSQL / Cloud SQL, "Evidence of Port
Scanning from AI Agent" / "AI Agent Evidence of Port Scanning", "Remove Bulk
Data From Disk" / "from Disk", "cryptocurrency" / "crypto", "Abuse of Sudo" /
"Attempt to Abuse Sudo"): both are listed and filtered. No finding was ever
seen live, so which spelling Google emits is unverified.
- ` SecurityAdmin` response bodies (configs, operations, marks) are returned as
raw Json and were never seen; request fields are checked against Discovery
only. Notification configs and BigQuery exports exist only under
` locations` in v2 (Discovery), mute configs with and without.
- Whether ` findings:bulkMute` accepts ` UNMUTED` (Discovery's enum for
` BulkMuteFindingsRequest.muteState` is ` MUTED`, ` UNDEFINED`): only those are sent.
- Sanitize against a floor setting without a template: not possible (a
template name is required); no default template exists.
2026-10-24 04:38:50 +02:00
- That agent assets always contain ` reasoningEngines` in ` resourceName`
(dashboard default filter; override with ` resource_contains`).
- Server-side behavior of the ` resourceName:"x"` substring operator (AIP-160
` :` is documented generally, not for this field).
- Real response bodies: parsers follow Discovery schemas and are tested with
documents built from schema field names, not with recorded Google replies.
The FilterResult map keys (` rai`, ` pi_and_jailbreak`, ...) are not relied
upon; filters are identified by their member name.
- Google's byte limit for file items in sanitize calls.
- Whether ` sources.get` exists for folders and projects (Discovery: only
organizations; ` get_source` accepts only organizations).
- Gemini ` promptFeedback` and ` safetyRatings` were not live-checked; the guard
does not use them.
## 9. Gaps
- ` findings:group` is wired; the dashboard still aggregates locally (owner:
` dashboard.cpp`). Server-side counting is the cheaper path for large sets.
- Streaming sanitize (` streamingMode`, gRPC ` StreamSanitize*`) is not
implemented; ` GuardedModel` buffers instead.
- No asset inventory (Cloud Asset Inventory is a different API).
2026-10-24 05:43:13 +02:00
- Attack exposure engine (attack paths, valued resources, simulations,
resource value configs) is excluded on purpose (posture risk scoring).
- Security Command Center is not activated for the test project, so no
findings, group, config or admin response was ever seen. Owner: whoever
activates SCC at the organization; tests ` google_live_armor.*`.
2026-10-24 04:38:50 +02:00
- Token refresh is the caller's job (foundation gap).