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>
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,sanitizeModelResponsewith 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
SecurityFindingsover Security Command Center v2 (findings.list,findings:group,sources.list,sources.get). The Finding resource carries typedagent,agentAnomaly,agentSessions,agentDataAccessEvents,aiModelandvulnerabilitymembers, which are read intoFinding. - 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_REintools/check_discovery.py). - Agent Threat Detection categories:
AgentCategoriesholds 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 typedagentAnomalymember. - Agent Security dashboard: a console product with no dashboard API.
AgentSecurityDashboardis 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 fragmentreasoningEngines(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 wrappedLanguageModel; throwsBlockedError.
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 400INVALID_ARGUMENT). No credential:NotConfiguredError(503) before the network. - Hosts:
https://modelarmor.{location}.rep.googleapis.com/v1for templates, sanitize and floor settings; floor settings and locations also acceptglobal(https://modelarmor.googleapis.com/v1); templates and sanitize rejectglobal. Security Command Center:https://securitycenter.googleapis.com/v2. - Destructive:
delete_templateis an explicit method; the demo route also requiresconfirm=delete.SecurityAdminmutations 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_muterefuses an empty filter and only mutes or un-mutes (MUTED,UNDEFINED); its demo route needsconfirm=bulk-mute.cancel_operation/delete_operationread the operation first. Floor settings are read and written at locationglobalon the global host only (found live, see 6). - Lists never truncate silently: findings (
FindingPage::truncated), config and operation lists (SccList::truncatedwithnext_page_token). - Not activated is a state, not a crash:
SecurityAdmin::availabilitymaps 403 API disabled, 404 onsourcesand 400FAILED_PRECONDITION(SCC enabled but not activated for the project) toSccAvailability. retry ids:requestIdis accepted on create, patch and delete as a non-zero UUID.- Sanitization results are typed; an unknown or missing
invocationResultnever counts as clean (fully_executed()is false). GuardedModelfails closed: a matched filter blocks (incomplete() == false); a PARTIAL or FAILURE run, or any skipped filter, also blocks (incomplete() == true) unlessGuardOptions::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 inskipped_empty, not checked. Streaming buffers the whole stream, sanitizes the full text once, then replays the chunks; a blocked stream delivers nothing.- Findings:
FindingQuerybuilds an AIP-160 filter from typed fields only (category,state,severity,resourceNamesubstring).findingClassis filtered locally because Discovery lists it fororderByonly.
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 namesAGENT_ENGINE_*); anomaly findings are recognised by the typedagentAnomalymember, 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. SecurityAdminresponse 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 underlocationsin v2 (Discovery), mute configs with and without.- Whether
findings:bulkMuteacceptsUNMUTED(Discovery's enum forBulkMuteFindingsRequest.muteStateisMUTED,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
reasoningEnginesinresourceName(dashboard default filter; override withresource_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.getexists for folders and projects (Discovery: only organizations;get_sourceaccepts only organizations). - Gemini
promptFeedbackandsafetyRatingswere not live-checked; the guard does not use them.
9. Gaps
findings:groupis wired; the dashboard still aggregates locally (owner:dashboard.cpp). Server-side counting is the cheaper path for large sets.- Streaming sanitize (
streamingMode, gRPCStreamSanitize*) is not implemented;GuardedModelbuffers 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-214512124securitycenter.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)