Files
moloapp/src/google/armor/SPEC.md
T
retoorandClaude Sonnet 5.5 438e737ffb docs(clients): document the activation page of every Google API and each vendor key page
Adds molo::google::apis (api_catalog) as the code source of truth,
src/google/APIS.md, a Required APIs section per module SPEC, and the
vendor key consoles in src/llm/SPEC.md. Placeholder project example-214512124.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-25 08:02:50 +01:00

17 KiB

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

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.