Files
moloapp/src/google/armor/SPEC.md
T

184 lines
10 KiB
Markdown
Raw Normal View History

# 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`.
- 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, schemas, enums; path matcher |
| `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 |
| Categories in a filter | 20 |
| 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`. Nothing here creates, updates or deletes
findings, sources or any Security Command Center resource.
- `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` 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`: 31 calls (rpc id, HTTP method, path, query
parameters), 66 schemas (every field this module reads or writes) and 13 enum
value sets. Result on 2026-10-24: `OK: 31 calls, 66 schemas, 13 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.
| 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:
- Finding `category` strings for Agent Threat Detection and Agent Anomaly
Detection: not read; callers pass categories they see in the console.
- 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).
- Findings mutation (mute, state), notification configs, BigQuery exports,
mute configs and attack paths are out of scope (read-only module).
- Token refresh is the caller's job (foundation gap).