> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bucket A: HTTPS API migration
> Zero-plaintext cutover for applications that call cloud secret store APIs directly. The agent intercepts, rewrites auth, and serves secrets from KnoxCall — no code changes required.
# Bucket A: HTTPS API migration
Bucket A handles migrations where your applications call a cloud secret store API (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, AWS SSM) directly over HTTPS. The KnoxCall agent intercepts these calls before they leave the host, rewrites the authentication header, and returns the secret from KnoxCall instead.
**Your application code does not change.**
## How it works
```text theme={"dark"}
Application
↓ HTTPS call to secretsmanager.us-east-1.amazonaws.com
KnoxCall agent (intercept mode)
↓ Validates app identity (SO_PEERCRED or process UID)
↓ Rewrites auth header: AWS SigV4 → KnoxCall Bearer token
↓ Forwards to KnoxCall proxy
KnoxCall proxy
↓ Injects real secret value
↓ Returns response in AWS SM wire format
Application receives response — identical to a real AWS SM response
```
The agent acts as a transparent MITM on the loopback interface. The application's AWS SDK believes it's talking to AWS Secrets Manager; the agent translates the call to KnoxCall's API and returns a response in the expected format.
No plaintext secret value ever touches disk. The agent holds secrets in memory only for the duration of the intercept.
## Supported capture surfaces
| Surface | How interception works |
| -------------------------------------- | ----------------------------------------------------------------------------------- |
| **K8s CSI volume driver** | Agent sidecar intercepts filesystem reads from the CSI mount |
| **External Secrets Operator (ESO)** | Agent intercepts ESO's API calls to the provider |
| **ECS / Lambda environment injection** | Agent intercepts metadata endpoint calls at runtime |
| **Cloud sidecar agents** | Agent intercepts AWS AppConfig, Azure App Configuration, GCP Config Connector calls |
| **TLS interception** | Agent proxies all outbound TLS on configured ports; matches secret store hostnames |
## Setting up intercept rules
Intercept rules tell the agent which outbound requests to intercept and how to rewrite them.
### Via admin UI
1. Go to **Infrastructure → Secret Store Migrations**
2. Open the migration → click the **Intercept Rules** tab
3. Click **Add rule**
4. Configure:
* **Match host**: e.g. `secretsmanager.us-east-1.amazonaws.com`
* **Match path prefix**: e.g. `/`
* **Rewrite**: select the KnoxCall secret to substitute
5. Save — the agent picks up new rules within 30 seconds
### Example rule (AWS SM → KnoxCall)
```json theme={"dark"}
{
"match_host": "secretsmanager.us-east-1.amazonaws.com",
"match_path_prefix": "/",
"rewrite_secret_id": "sec_01abc...",
"response_format": "aws_secrets_manager"
}
```
The `response_format` field tells the agent to return the value in the format the application expects (AWS SM JSON envelope, plain value, Azure KV JSON, etc.).
## Zero-plaintext guarantee
* The secret value is never written to disk, logged, or stored in the `migration_intercept_rules` table
* The agent holds the value in memory only for the lifespan of a single request
* If the agent process crashes mid-intercept, the application receives a connection error — not a partial or logged secret
## Monitoring migration progress
The `secret_consumers` table tracks discovered workloads that are consuming each migrated secret:
```bash theme={"dark"}
curl https://api.knoxcall.com/admin/migrations/mgr_01abc.../verification-events \
-H "Authorization: Bearer $KC_ADMIN_JWT"
```
The admin UI shows a consumer count per secret, and highlights any consumers not yet seen through the intercept path.
## Migration status progression
| Status | What it means |
| ----------------- | ------------------------------------------------------- |
| `pending` | Migration created; discovery not yet started |
| `discovering` | Agent scanning workloads; no interception active yet |
| `awaiting_review` | Discovery complete; items queued for reviewer decisions |
| `completed` | All approved items committed to KnoxCall secrets |
## Cutover
When the verification dashboard shows all consumers green and all items have been approved:
1. In the admin UI, click **Commit migration** (or call `POST /admin/migrations/:id/commit`)
2. Wait for the `completed` status
3. You can now safely revoke cloud store credentials and remove secrets from the source provider
Do not revoke the cloud store credentials until you have confirmed all application instances are routing through KnoxCall. Intercept rules route live traffic — removing them before cutover confirmation will break applications.
## Cancelling a Bucket A migration
You can cancel a migration in `pending`, `discovering`, or `awaiting_review` state:
```bash theme={"dark"}
curl -X POST https://api.knoxcall.com/admin/migrations/mgr_01abc.../cancel \
-H "Authorization: Bearer $KC_ADMIN_JWT"
```
This removes all intercept rules. Applications revert to direct cloud store access immediately.
For database credentials
DNS/TLS probes and safe-to-delete confirmation
Intercept rules and migration endpoints
Back to overview