# 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`. - 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. - 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`) | | `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 | | `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 | | 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) | | 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 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`. - `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 `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 `https://modelarmor.googleapis.com/$discovery/rest?version=v1` and `https://securitycenter.googleapis.com/$discovery/rest?version=v2` and checks 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 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. **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. | 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: - 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. - 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). - 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.*`. - Token refresh is the caller's job (foundation gap). ## Required APIs Enable these on the project (placeholder project `example-214512124`; full list and a one-line `gcloud` command in `src/google/APIS.md`). A disabled API answers 403 `SERVICE_DISABLED`. - `modelarmor.googleapis.com`: https://console.developers.google.com/apis/api/modelarmor.googleapis.com/overview?project=example-214512124 - `securitycenter.googleapis.com`: https://console.developers.google.com/apis/api/securitycenter.googleapis.com/overview?project=example-214512124 (also needs Security Command Center activated for the organization: https://console.cloud.google.com/security/command-center)