# Model and credential providers

Operator connects Attack Harness to its model provider and authenticates requests
on the host. The Harness receives the permitted model interface, not provider
credentials. Interceptor separately configures model access for the target agent.

## Choose a model provider

Set `provider`, `codec_id`, and `model` in a private JSON model profile. The codec
selects the native conversation and tool-call format. Use a model that supports
the selected API and tool use.

| `provider` | `codec_id` | `endpoint` or routing fields |
| --- | --- | --- |
| `openai-chat` | `openai-chat-text-tools-v1` | `https://api.openai.com/v1/chat/completions` |
| `openai-responses` | `openai-responses-text-tools-v1` | `https://api.openai.com/v1/responses` |
| `anthropic-messages` | `anthropic-messages-text-tools-v1` | `https://api.anthropic.com/v1/messages`; also set `anthropic_version` to the provider's required API header value in `YYYY-MM-DD` form. |
| `gemini-api` | `gemini-text-tools-v1` | `https://generativelanguage.googleapis.com/v1beta/models/YOUR_MODEL:generateContent` |
| `vertex-gemini` | `gemini-text-tools-v1` | `https://YOUR_LOCATION-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/YOUR_LOCATION/publishers/google/models/YOUR_MODEL:generateContent`, or the applicable express-mode endpoint. |
| `azure-openai` | Chat or Responses codec above | Your resource's complete operation URL, such as `https://YOUR_RESOURCE.openai.azure.com/openai/v1/chat/completions` or `/openai/v1/responses`. |
| `litellm` | Chat or Responses codec above | Your gateway's complete HTTPS operation URL ending in `/chat/completions` or `/responses`. |
| `bedrock-converse` | `bedrock-converse-text-tools-v1` | Set `region`; omit `endpoint`. Operator uses the regional AWS endpoint. |

Replace placeholders with the endpoint and model or deployment identifier available
to your account. HTTP profiles take the **complete operation URL**, not a base URL.
Gemini URLs must contain the same model as `model`. Only Azure permits a query
string, with exactly one `api-version` parameter when required by the chosen route.
Do not put keys in URLs. Generation is non-streaming and Operator does not retry
model requests automatically.

## Configure the model profile

Save the following as a private host file, for example `/absolute/private/model.json`,
and replace `YOUR_MODEL`. The token and response bounds are illustrative; choose
allowances supported by the model and your campaign budget.

```json
{
  "api_version": "operator.dev/model-provider-profile/v1alpha1",
  "id": "campaign-model",
  "provider": "openai-chat",
  "codec_id": "openai-chat-text-tools-v1",
  "model": "YOUR_MODEL",
  "endpoint": "https://api.openai.com/v1/chat/completions",
  "authentication": "secret-store",
  "credential_id": "model-key",
  "maximum_prompt_tokens": 32768,
  "maximum_completion_tokens": 4096,
  "maximum_response_bytes": 1048576,
  "codec_options": {"instruction_role": "developer"}
}
```

Merge these fields into the installed Operator configuration, using actual absolute
paths. Preserve its existing image, contract, target, limits, and Docker settings:

```yaml
model:
  profile_file: /absolute/private/model.json
credentials:
  file: /absolute/private/credentials.yaml
```

`maximum_prompt_tokens` includes message and tool framing and is used to reserve
campaign tokens. Both token bounds must be positive; `maximum_response_bytes` must
be positive and at most 4 MiB. Oversized reservations can prevent work within the
campaign's remaining budget. Optional `context_warning_percent` is 1–99, default 80.
For a private TLS service, `ca_certificates_pem` can add trusted PEM certificates
without disabling certificate or hostname checks.

| Codec | Optional `codec_options` |
| --- | --- |
| Chat | `instruction_role`: `developer` (default) or `system`. |
| Responses | Native `reasoning` object. |
| Anthropic | Native `thinking` and `output_config` objects, including `output_config.effort`. |
| Gemini | Native `thinking_config` object. |
| Bedrock | Use an empty object. |

Choose options supported by the selected model. These settings are private to
Operator; the Harness cannot choose authentication, endpoints, or credentials.

## Select model authentication

Set `authentication` in the model profile. Secret-store login is a separate choice
in the credential configuration described below.

| `authentication` | Model providers | Additional profile fields |
| --- | --- | --- |
| `secret-store` or `api-key` | All HTTP providers above | `credential_id`; resolve the model API key from a configured store. |
| `api-key-env` | All HTTP providers above | `api_key_env` naming a host variable; omit `credential_id`. |
| `workload-token` | Anthropic | `credential_id` for a stored bearer token; the administrator manages its issuance and renewal. |
| `workload-identity` | Bedrock, Azure OpenAI, Vertex | No key fields; use the host's configured cloud workload identity. Bedrock also needs `region`. |
| `aws-profile` | Bedrock | `region` and `aws_profile`; omit key fields. |
| `aws-environment` | Bedrock | `region`; the host supplies the AWS access-key pair and optional session token. |
| `google-adc` | Vertex | No key fields; explicitly use Google Application Default Credentials. |
| `azure-cli` | Azure OpenAI | No key fields; use the existing Azure CLI login. |
| `azure-client-secret` | Azure OpenAI | No key fields; use the host's Azure service-principal variables. |
| `none` | LiteLLM | Omit credential fields; use only for an intentionally unauthenticated gateway. |

For environment-key authentication, replace the example's `authentication` and
`credential_id` with the following fragment. Provision the variable's value through
your host's credential mechanism; the JSON contains only its name:

```json
{"authentication": "api-key-env", "api_key_env": "CAMPAIGN_MODEL_KEY"}
```

For Bedrock, a complete model-profile example is:

```json
{
  "api_version": "operator.dev/model-provider-profile/v1alpha1",
  "id": "campaign-bedrock",
  "provider": "bedrock-converse",
  "codec_id": "bedrock-converse-text-tools-v1",
  "model": "YOUR_BEDROCK_MODEL_OR_INFERENCE_PROFILE",
  "region": "us-east-1",
  "authentication": "aws-profile",
  "aws_profile": "YOUR_AWS_PROFILE",
  "maximum_prompt_tokens": 32768,
  "maximum_completion_tokens": 4096,
  "maximum_response_bytes": 1048576,
  "codec_options": {}
}
```

See [host identity setup](#configure-host-identities) for login prerequisites.

## Configure credential providers

Operator supports AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager,
HashiCorp Vault KV v2, and 1Password. A **profile** selects a store and its permitted
secret locations; a **credential reference** gives a stored value a stable ID used
by the model profile. The model provider and secret store can be in different clouds.

Create `/absolute/private/credentials.yaml` with the following structure. This
example reads a plain-text API key from AWS Secrets Manager through an explicit
host AWS profile. Replace the region, profile name, and secret location:

```yaml
profiles:
  - api_version: operator.dev/secret-store-profile/v1alpha1
    kind: SecretStoreProfile
    id: model-secrets
    backend_kind: aws-secrets-manager
    authentication: aws-profile
    aws_profile: YOUR_AWS_PROFILE
    region: us-east-1
    allowed_locator_prefixes: [aws://us-east-1/simulation/model-key]
    timeout_seconds: 10
    max_value_bytes: 65536
    max_cache_ttl_seconds: 300
credentials:
  - api_version: operator.dev/host-credential-ref/v1alpha1
    kind: HostCredentialRef
    credential_id: model-key
    store_profile_id: model-secrets
    locator:
      backend_kind: aws-secrets-manager
      region: us-east-1
      secret_id: simulation/model-key
      version_stage: AWSCURRENT
    value: {format: utf8}
    cache_ttl_seconds: 30
```

This file contains references, never the API key itself. Protect it and the model
profile with mode `0600`; use regular files owned by the execution account or root,
without symlinks. Operator accepts a single YAML document or JSON with the same
structure, at most 1 MiB; YAML aliases and anchors are not supported.

### Backend fields and secret locations

To select another backend, retain the common schema, kind, IDs, limits, and value
selection above. Replace `backend_kind` in both the profile and locator, remove
fields belonging to the previous backend, and supply these fields:

| Backend | Profile fields | `locator` fields | Example allowed prefix |
| --- | --- | --- | --- |
| `aws-secrets-manager` | `region`; `authentication`: `workload-identity`, `aws-profile`, or `aws-environment`; `aws_profile` only for named-profile access. | Matching `region`, `secret_id`; optional `version_id` or `version_stage`. | `aws://us-east-1/simulation/` |
| `azure-key-vault` | HTTPS `vault_url`; `authentication`: `workload-identity`, `azure-cli`, or `azure-client-secret`. | Matching `vault_url`, `secret_name`; optional `version`. | `https://YOUR_VAULT.vault.azure.net/secrets/simulation-` |
| `gcp-secret-manager` | `authentication`: `workload-identity` or `google-adc`. | `project`, `secret_name`, `version` such as `latest`. | `gcp://projects/YOUR_PROJECT/secrets/simulation-` |
| `hashicorp-vault` | HTTPS `vault_url`; exactly one of `vault_token_file` or `vault_proxy: true`; optional `vault_namespace`, `vault_ca_certificate`. | `mount`, `path`; optional `version` as a positive integer encoded as a string. | `vault://secret/simulation/` |
| `onepassword` | `authentication`: `onepassword-desktop` with `onepassword_account`, or `onepassword-service-account` without the account field. | `secret_reference`: `op://vault/item/[section/]field`. | `op://simulation/` |

Cloud-store authentication defaults to workload identity, except that an explicit
`aws_profile` selects that profile when `authentication` is omitted. The locator
must match the backend and the configured AWS region or Azure vault. Allowlist
prefixes restrict selection; they do not grant access at the remote store.

For example, these are the replacement profile fields and locator for Google
Secret Manager, merged into the same two records above:

```yaml
# Fields in profiles[0]; remove region and aws_profile.
backend_kind: gcp-secret-manager
authentication: google-adc
allowed_locator_prefixes: [gcp://projects/YOUR_PROJECT/secrets/simulation-]
```

```yaml
# Replace credentials[0].locator.
backend_kind: gcp-secret-manager
project: YOUR_PROJECT
secret_name: simulation-model-key
version: latest
```

### Values, caching, and store access

Use `value: {format: utf8}` when the selected secret is the key itself. For a JSON
secret, select one top-level string with
`value: {format: json-string-field, field: api_key}`. Vault KV v2 requires this
explicit field selection. Binary values, empty keys, NUL, and line breaks in the
selected credential are rejected. The resolver reads secrets; it does not create,
rotate, list, or delete them.

`timeout_seconds` defaults to 10 and permits 1–60. `max_value_bytes` defaults to
65536 and permits at most 1048576. `max_cache_ttl_seconds` defaults to 300 and permits
up to 3600. A reference's `cache_ttl_seconds` defaults to zero (no caching) and cannot
exceed its profile's ceiling. A failed refresh does not fall back to a stale value.

Grant the chosen host identity only the access it needs:

| Store | Access and setup |
| --- | --- |
| AWS Secrets Manager | `secretsmanager:GetSecretValue` on the secret; customer-managed encryption keys may also require `kms:Decrypt` and an allowing key policy. |
| Azure Key Vault | Key Vault Secrets User, or secret Get under legacy access policies. Key Vault Reader alone cannot read values. |
| Google Secret Manager | Secret Manager Secret Accessor on the selected secret, an enabled Secret Manager API, and an enabled secret version. |
| Vault KV v2 | Read access to `MOUNT/data/PATH` through an already authenticated Agent or Proxy. |
| 1Password | Read access to the selected vault/item for the desktop account or service account. |

For Vault, `vault_token_file` names an absolute private token-sink file; it is reread
on uncached resolution. Alternatively, use an authenticating Proxy with
`vault_proxy: true`. The product does not perform Vault login. Keep TLS verification
enabled; `vault_ca_certificate` supplies a trusted certificate file when needed.

For 1Password desktop access, run as the signed-in desktop user, enable
**Settings → Developer → Integrate with 1Password SDKs**, and set
`onepassword_account` to the account name or UUID. For automation, select
`onepassword-service-account` and supply `OP_SERVICE_ACCOUNT_TOKEN` only to the host
process. No `op` CLI is required. References select one field; names or IDs are
accepted, and allowed prefixes must end on a component boundary with `/`.

## Configure host identities

Run authentication setup as the account that will execute Operator. Model access
and permission to read a secret are separate grants.

| Selection | Host prerequisites |
| --- | --- |
| AWS `workload-identity` | Web-identity token file and role, container role, or instance role. Shared AWS files are excluded. |
| AWS `aws-profile` | Explicit profile name; for SSO, run `aws sso login --profile YOUR_AWS_PROFILE`. |
| AWS `aws-environment` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN` in the host process. Shared profiles are ignored. |
| Azure `workload-identity` | Federated token file with `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`, or managed identity. |
| Azure `azure-cli` | Existing `az login` session and `az` available on the process PATH. |
| Azure `azure-client-secret` | Host `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET`. |
| Google `workload-identity` | Attached identity or external-account federation, including a configured `GOOGLE_APPLICATION_CREDENTIALS` file. |
| Google `google-adc` | Explicit Application Default Credentials; local setup uses `gcloud auth application-default login`, separately from `gcloud auth login`. |

AWS workload and named-profile modes reject static AWS credential environment
variables; choose `aws-environment` when using an exported access-key session.
For direct model access, grant Bedrock `InvokeModel`, Azure Cognitive Services
OpenAI User, or Vertex AI User/inference permission for the selected resource.
Google quota-project use can also require Service Usage Consumer.

In CI, AWS credential actions that export temporary keys use `aws-environment`;
Azure CLI login uses `azure-cli`; Google's federated credential file uses
`workload-identity` or `google-adc`. Keep the authenticated environment and files
available for the process lifetime. A detached service needs its own configured
account and environment and does not automatically inherit a terminal login.

## Check the configuration

After saving private files and wiring them into the installed configuration, run:

```sh
operatorctl config check --config /absolute/private/config.yaml
operatorctl doctor --offline --config /absolute/private/config.yaml
```

Configuration checks do not retrieve secrets or prove model access. Inspect
diagnostics for profile, identity, and permission errors, then use your chosen
campaign to verify model access. Secret resolution during a campaign is audited
without recording the value or locator. For failures, check the selected host
account, credential ID, allowlist, store permissions, and model permissions.

Continue with [campaign preparation](campaigns.md). Upstream references provide
additional detail on [model profiles](https://github.com/intrusiveai/operator_sandbox/blob/v0.1.5/docs/MODEL_PROVIDERS.md)
and [credential stores](https://github.com/intrusiveai/operator_sandbox/blob/v0.1.5/docs/CREDENTIALS.md);
choose the source tag matching your installed release.
